Installation

Operating Systems

Currently, the main target operating systems are GNU/Linux distributions. There are, however, no platform-specific components in viren2d and all dependencies and build tools are available for Unix, Mac and Windows. Please let me know if you’ve set it up on any other platform, so I can update the installation instructions accordingly.

Important

Windows: There is no official CMake package configuration for Cairo and the one included with viren2d uses a hard-coded search path, i.e. ${CMAKE_CURRENT_LIST_DIR}/libs/cairo-windows. You will have to adjust this path or use your own FindCairo.cmake.

If you find a simple setup/build workflow for Windows, please drop me a line or consider creating a PR to update the installation instructions for future users.

Important

Ubuntu: If you run Ubuntu<=18.04, you need to install CMake via Kitware’s APT repository. The default software repository is stuck at CMake version 3.10.

From Ubuntu 20.04 on, everything works out-of-the-box. Note, however, that tests are only run on the LTS versions.

Requirements

Most internal dependencies are automatically set up by the library’s CMake-based build pipeline. Nevertheless, the basic build environment, Cairo and Eigen3 must be set up manually:

• A C++ compiler supporting at least C++17.

• CMake >= 3.15 and a compatible build tool, like Make, Ninja, etc. For example, on GNU/Linux distributions, you’d simply need:

  # Debian & derivatives (like Ubuntu)
  sudo apt install cmake build-essentials ninja-build
  
  # On Fedora & openSUSE distributions, you need to install the same
  # packages via your package manager, i.e. `yum` or `zypper`.
  

• The Cairo 2D graphics library.

  Currently, there are no viren2d packages - thus, you need the Cairo development packages (-dev or -devel) for your system. For example, on GNU/Linux distributions, you simply install Cairo via:

  # Debian & derivatives (like Ubuntu)
  sudo apt install libcairo2-dev
  
  # On Fedora & openSUSE distributions, the package name
  # is `cairo-devel`.
  

• The header-only Eigen linear algebra library.

  # Debian & derivatives
  sudo apt install libeigen3-dev
  
  # On Fedora & openSUSE distributions, the package name
  # is `eigen3-devel`.
  

• Additional requirements to build the optional Python bindings:

  • Python >= 3.6, along with its development library, i.e. system package python3-dev on Linux/macOS. On Windows, please follow the setup instructions of pybind11.

  • Python’s standard package installer pip >= 10.0.0.

  • The only runtime dependency is NumPy >= 1.7.0.

Python Setup

If all requirements are installed, the simplest way to install viren2d is to use the default package manager, pip, which supports installation directly from the github repository:

Set up a virtual environment with up-to-date pip.

python3 -m venv venv
source venv/bin/activate
python -m pip install -U pip

Install viren2d.

python -m pip install git+https://github.com/snototter/viren2d.git

Python Demo

To verify the installation, you can optionally run the following copy-pastable example. Note that this additionally requires Pillow package, which can be installed via:

python -m pip install Pillow

viren2d Hello World Example in Python.

import numpy as np
import viren2d
from PIL import Image

# Set up a white canvas:
width, height = 400, 50
painter = viren2d.Painter(width=width, height=height, color='#1a1c1d')

# Draw "Hello World":
text_style = viren2d.TextStyle(
    family='sans-serif', size=35, color='#c0bab1', bold=True)

bbox = painter.draw_text(
    text=['Hello World!'], position=(width/2, height/2),
    anchor='center', text_style=text_style)

# Draw markers to the left & right:
marker_style = viren2d.MarkerStyle(
    marker='5', size=30, filled=True, color='midnight-blue',
    bg_border=2, bg_color='ivory')

painter.draw_marker(
    position=(bbox.cx - bbox.width/2 - 35, height/2),
    marker_style=marker_style)
painter.draw_marker(
    position=(bbox.cx + bbox.width/2 + 35, height/2),
    marker_style=marker_style)

# Display the image:
shared_canvas_np = np.array(painter.canvas, copy=False)
image = Image.fromarray(shared_canvas_np)
image.show()

The resulting visualization.

C++ Setup

The recommended way of integrating viren2d in your application is via CMake’s FetchContent module, as shown below:

Exemplary CMakeLists.txt to integrate viren2d via CMake’s FetchContent module.

# viren2d requires at least C++14
set(CMAKE_CXX_STANDARD 14)

# Let CMake download and set up the viren2d dependency
include(FetchContent)
FetchContent_Declare(
  viren2d
  GIT_REPOSITORY https://github.com/snototter/viren2d.git
  GIT_TAG main)
FetchContent_MakeAvailable(viren2d)

# Create the demo executable
add_executable(hello-world
    ${CMAKE_CURRENT_LIST_DIR}/hello_world.cpp)

# Add the viren2d dependency (include paths will be set up automatically)
target_link_libraries(hello-world PRIVATE viren2d++::viren2d++)

C++ Demo

For the corresponding demo application, refer to the C++ hello world example. To build this standalone demo, only the C++ source file and the example’s CMakeLists.txt are needed. FetchContent will download and set up all dependencies as needed. For example, if these two files are placed in a hello-world-example folder, a classical CMake build would look like:

cd hello-world-example
mkdir && cd build
cmake ..
cmake --build .
./hello-world