/badge.svg){kind=icon}
/badge.svg){kind=icon}
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 moduletest: unit tests for each modulefrontend: the command-line frontenddemos: a collection of GUI applications serving as a demonstration of various parts of the algorithms implemented
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.
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
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-jsonThe 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.cppandsrc/ipelib/ipebitmap_win.cpp, add an#include <string>; - in
src/ipelib/ipeplatform.cpp, inPlatform::runLatex(), replacewcmd.data()by&wcmd[0]; - in
src/ipelib/ipeplatform.cpp, inString::w(), replaceresult.data()by&result[0].
Then, to compile:
cd src make IPEPREFIX=/usr/local ipelibThe compiled library
ipe.dllends up inmingw64/bin. - in
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-devThe 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.
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 buildWindows (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 buildLinux
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -S . -B build
cmake --build build
cmake --install buildwhere <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.)
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.jsonCopyright (c) 2019-2023 Netherlands eScience Center and TU Eindhoven Licensed under the GPLv3.0 license. See LICENSE for details.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent