Installation

How to install Datoviz?

Note

Binary packages are still experimental. They are currently uploaded on GitHub releases, but not yet on PyPI. They will, once they have been sufficiently tested. In the meantime, please open an issue on GitHub if you have any problem.

Linux

1. If you don't already have a Python distribution, install one. For example, download the miniconda installer for Linux 64-bit and install it.
2. Open a terminal.

3. Type the following to install Datoviz:

   pip install http://dl.datoviz.org/v0.1.0-alpha.1/datoviz-0.1.0a1-cp38-cp38-manylinux_2_24_x86_64.whl
   

4. Type the following to test Datoviz:

   python -c "import datoviz; datoviz.demo()"
   

macOS

1. Install the Vulkan SDK for macOS (we'll try to remove this requirement in the near future)
2. If you don't already have a Python distribution, install one. For example, download the miniconda pkg installer for macOS and install it.
3. Open a terminal.

4. Type the following to install Datoviz:

   pip install http://dl.datoviz.org/v0.1.0-alpha.1/datoviz-0.1.0a1-cp38-cp38-macosx_10_14_x86_64.whl
   

5. Type the following to test Datoviz:

   python -c "import datoviz; datoviz.demo()"
   

Windows

1. If you don't already have a Python distribution, install one. For example, download the miniconda installer for Windows 64-bit and install it.
2. Open an Anaconda prompt.

3. Type the following to install Datoviz:

   pip install http://dl.datoviz.org/v0.1.0-alpha.1/datoviz-0.1.0a1-cp38-cp38-win_amd64.whl
   

4. Type the following to test Datoviz:

   python -c "import datoviz; datoviz.demo()"
   

How to build Datoviz from source?

Datoviz is made of:

• a C library (also called libdatoviz),
• a Python wrapper (written in Cython)

The philosophy of Datoviz is to implement all the logic and functionality in C, and provide minimal bindings in high-level languages. This will ensure that all wrappers share the same functionality.

Linux

Note

Only Ubuntu 20.04 has been tested so far.

1. Install the latest graphics drivers.

2. Install the build tools:

   sudo apt install build-essential cmake ninja-build \
       xcb libx11-xcb-dev libxcursor-dev libxi-dev patchelf
   

3. Install the optional dependencies:

   sudo apt install libpng-dev libavcodec-dev libavformat-dev \
       libavfilter-dev libavutil-dev libswresample-dev \
       libqt5opengl5-dev libfreetype6-dev
   

4. Install the latest Lunarg Vulkan SDK (tarball SDK), for example in ~/vulkan.

5. Export the Vulkan environment variables:

   source ~/vulkan/setup-env.sh
   

6. Add source ~/vulkan/setup-env.sh to your ~/.bashrc so that the $VULKAN_SDK environment variable and other variables are properly set in your terminal.

7. Copy the Vulkan headers and libraries to your system:

   sudo cp -r $VULKAN_SDK/include/vulkan/ /usr/local/include/
   sudo cp -P $VULKAN_SDK/lib/libvulkan.so* /usr/local/lib/
   sudo cp $VULKAN_SDK/lib/libVkLayer_*.so /usr/local/lib/
   sudo mkdir -p /usr/local/share/vulkan/explicit_layer.d
   sudo cp $VULKAN_SDK/etc/vulkan/explicit_layer.d/VkLayer_*.json /usr/local/share/vulkan/explicit_layer.d
   

8. Clone the Datoviz repository:

   git clone --recursive https://github.com/datoviz/datoviz.git
   cd datoviz
   

9. Build the C library:

   ./manage.sh build
   

10. Check that the compilation worked by running an example:

    ./manage.sh demo scatter
    

11. Once the C library is compiled, you need to compile the Cython module:

    ./manage.sh cython
    

12. Export the shared library path to your environment:

    source setup-env.sh
    

13. Try a Python example:

    python bindings/cython/examples/quickstart.py
    

macOS

1. Open a terminal.
2. Type git to install git.
3. Install Xcode.
4. Install Homebrew.

5. Install the build dependencies:

   brew install cmake ninja libpng
   

6. Download the latest Vulkan SDK.

7. Install it.

8. Clone the Datoviz repository:

   git clone --recursive https://github.com/datoviz/datoviz.git
   cd datoviz
   

9. Build the C library:

   ./manage.sh build
   

10. Check that the compilation worked by running an example:

    ./manage.sh demo scatter
    

11. Once the C library is compiled, you need to compile the Cython module:

    ./manage.sh cython
    

12. Export the shared library path to your environment:

    source setup-env.sh
    

13. Try a Python example:

    python bindings/cython/examples/quickstart.py
    

Windows 10

Warning

Only mingw-w64 is supported at the moment. Microsoft Visual C++ is not yet supported.

Note

Help needed to add more details to the install instructions below.

1. Install the latest graphics drivers for your system and hardware.
2. Install Winlibs, a Windows port of gcc, using mingw-w64.
3. Make sure the mingw executable is in the PATH.
4. Install CMake for Windows.
5. Install the Windows Universal C Runtime.
6. Install the latest Lunarg Vulkan SDK (.exe executable).
7. Install git for Windows and open a Git-aware Windows terminal.

8. Clone the Datoviz repository:

   git clone --recursive https://github.com/datoviz/datoviz.git
   cd datoviz
   

9. Build the C library:

   manage.bat build
   

10. Build the Cython module and create a wheel:

    manage.bat wheel
    

11. Try a Python example:

    python bindings\cython\examples\quickstart.py
    

How to update Datoviz when it was compiled from source?

git pull
./manage.sh build
./manage.sh parseheaders
./manage.sh cython

What are the dependencies of Datoviz?

Mandatory dependencies are required for compilation:

• LunarG Vulkan SDK 1.2.170+
• cmake 3.16+ (build)

Optional dependencies:

• ninja (build)
• freetype (font support)
• libpng (screenshot)
• ffmpeg (screencasts)
• Qt5 (upcoming Qt backend (work in progress)

Built-in dependencies:

• glfw3 3.3+: cross-platform windowing system
• cglm: basic types and math computations on vectors and matrices
• stb_image: image file input and output
• Dear ImGui: rich graphical user interfaces
• earcut.hpp: triangulation of polygons
• triangle: triangulation of complex polygons and planar straight-line graphs (PSLG)
• tiny_obj_loader: loading of .obj mesh files

CPU emulation with Swiftshader

Note

Swiftshader support is still experimental.

Software emulation of Vulkan is useful on computers with no GPUs or on continuous integration servers, for testing purposes. Datoviz has preliminary support for Swiftshader, an emulation library developed by Google.

1. Compile Datoviz with Swiftshader support.
2. Compile Swiftshader.

3. Temporarily override your native Vulkan driver with the SwiftShader one:

   • Linux: export LD_LIBRARY_PATH=/path/to/swiftshader/build/Linux/:$LD_LIBRARY_PATH

4. Run your Datoviz script or application.