CartoCrow - A framework for cartographic visualization algorithms

CartoCrow is a framework that simplifies the implementation of algorithms in cartographic visualization. It allows researchers to experiment with these algorithms and use them to generate maps. The framework behind CartoCrow can be used to run other cartography algorithms online. CartoCrow consists of a C++ library (this repository) which provides a set of command-line applications, and a web interface (see cartocrow-web) which allows end users to generate maps in a user-friendly way.

Warning

CartoCrow is still a work in progress and should not be considered stable yet.

This repository consists of the following subdirectories:

• cartocrow: the library itself, with subdirectories for each module
• test: unit tests for each module
• frontend: the command-line frontend
• demos: a collection of GUI applications serving as a demonstration of various parts of the algorithms implemented

Dependencies

CartoCrow depends on the following build tools:

• g++ (11.4.0, 12.3.0) / clang++ (14.0.0, 15.0.7) / MSVC (2019)
• CMake (3.15)

And it depends on the following libraries:

• CGAL (5.4, 5.5) – for implementations of computational geometry algorithms we need
• glog (0.5.0, 0.6.0) – for logging
• ipelib (7.2.26) – for Ipe input and SVG/Ipe output
• nlohmann-json (3.10.5, 3.11.2) – for JSON parsing
• Qt (5.15) – for the interactive GUI

The version numbers listed are the ones we're testing with. Newer (and possibly somewhat older) versions will most likely work as well.

Windows (MSVC)

Installing dependencies on Windows

On Windows systems, we recommend using vcpkg to install and manage dependencies. The following steps install everything necessary to build CartoCrow.

• MSVC. Download MSVC 2019 from Microsoft's website and install it.

• CMake. Download CMake from here and install it. (Note: If you have a version of CMake installed in Cygwin, this does not seem to play well with vcpkg. Please install a native version of CMake.)

• vcpkg. The standard procedure to setup vcpkg on Windows:

  git clone https://github.com/microsoft/vcpkg
  cd vcpkg
  .\bootstrap-vcpkg.bat

  In our experience, vcpkg may misbehave when installed in a directory with a long path name, or a path name containing exotic characters. vcpkg itself recommends C:\src\vcpkg.

  For more information on installing vcpkg, see here.

• Install dependencies. As described here:

  vcpkg install cgal:x64-windows
  vcpkg install qt5:x64-windows
  vcpkg install glog:x64-windows
  vcpkg install nlohmann-json:x64-windows

  This step can take a very long time, especially compiling CGAL (around 30 minutes) and Qt (around 2 hours).

• Ipelib. This library is not available in vcpkg, so we will have to build it ourselves. Unfortunately, the upstream version of ipelib does not compile cleanly with MSVC. We prepared a patched version (to do: link coming soon) that can be compiled and installed with

  cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>\scripts\buildsystems\vcpkg.cmake -S . -B build
  cmake --build build
  sudo cmake --install build

Windows (MSYS2 / MINGW64)

Installing dependencies on Windows (MSYS2 / MINGW64)

In case your machine does not have MSYS2 installed yet, you can download it from here.

Most dependencies can be obtained from the repository:

pacman -S base-devel mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja
pacman -S mingw-w64-x86_64-cgal mingw-w64-x86_64-glog mingw-w64-x86_64-qt5 mingw-w64-x86_64-nlohmann-json

The remaining dependencies need to be built manually.

• Ipelib. Download the source archive and unpack it. Instead of the instructions for Ubuntu given in install.txt, you can use the following to install the dependencies:

  pacman -S mingw-w64-x86_64-freetype mingw-w64-x86_64-cairo mingw-w64-x86_64-libjpeg-turbo
  pacman -S mingw-w64-x86_64-libpng mingw-w64-x86_64-lua mingw-w64-x86_64-zlib
  pacman -S mingw-w64-x86_64-libspiro mingw-w64-x86_64-gsl

  Then set the correct environment: in common.mak, set

  # line 158
  IPEDEPS       := /mingw64  # or /ucrt64 if you're building under UCRT64
  
  # line 167-168
  LUA_CFLAGS    := -I$(IPEDEPS)/lua54/include
  LUA_LIBS      := -L$(IPEDEPS)/lib -llua

  A few changes are necessary to make Ipelib compile correctly:

  • in src/ipelib/ipeplatform.cpp and src/ipelib/ipebitmap_win.cpp, add an #include <string>;
  • in src/ipelib/ipeplatform.cpp, in Platform::runLatex(), replace wcmd.data() by &wcmd[0];
  • in src/ipelib/ipeplatform.cpp, in String::w(), replace result.data() by &result[0].

  Then, to compile:

  cd src
  make IPEPREFIX=/usr/local ipelib

  The compiled library ipe.dll ends up in mingw64/bin.

Linux

Installing dependencies on Linux

On Ubuntu, most dependencies can be obtained from the repository:

sudo apt install build-essential cmake
sudo apt install libcgal-dev nlohmann-json3-dev qtbase5-dev

The remaining dependencies need to be built manually.

• glog. This dependency is built manually because Ubuntu's packaging apparently does not include the CMake files we need.

  git clone https://github.com/google/glog.git
  cd glog
  cmake -S . -B build
  cmake --build build
  sudo cmake --install build

• Ipelib. Download the source archive, unpack it, and compile and install it using the instructions given in install.txt.

Compiling

CartoCrow uses CMake as its build system and can therefore be built like any other CMake application, for example:

Windows (MSVC)

cmake.exe -DCMAKE_INSTALL_PREFIX=<install-directory> -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>\scripts\buildsystems\vcpkg.cmake -S . -B build
cmake.exe --build build --config Release
cmake.exe --install build

Windows (MSYS2 / MINGW64)

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -DIpelib_LIBRARY=<location-of-ipe.dll> -S . -B build
cmake --build build
cmake --install build

Linux

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -S . -B build
cmake --build build
cmake --install build

where <install-directory>/bin is the directory where the executables will be installed. Note that on Windows (MSVC), it is necessary to supply the CMAKE_TOOLCHAIN_FILE generated by vcpkg; see the vcpkg documentation for details. On Windows (MSYS2 / MINGW64) FindIpelib.cmake needs a little help finding out where our self-compiled Ipelib library is. Otherwise, there is no difference in compiling between the platforms.

If you want to use cartocrow-web, clone that repository to a separate directory, and use that directory as <install-directory>, so that the executables are installed in a location where the web application can find them. (See also the README in the cartocrow-web repository for details.)

Usage

CartoCrow provides a command-line application, simply called cartocrow, which can be used to generate maps. To use it, you need a JSON file describing the map to generate, which can then be passed to cartocrow:

build/frontend/cartocrow <json-file>

We provide some sample input data to generate a necklace map depicting the population of all countries in Europe:

build/frontend/cartocrow data/europe-population-necklace.json

License

Copyright (c) 2019-2023 Netherlands eScience Center and TU Eindhoven Licensed under the GPLv3.0 license. See LICENSE for details.