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.
- If you don't already have a Python distribution, install one. For example, download the miniconda installer for Linux 64-bit and install it.
- Open a terminal.
-
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
-
Type the following to test Datoviz:
python -c "import datoviz; datoviz.demo()"
- Install the Vulkan SDK for macOS (we'll try to remove this requirement in the near future)
- If you don't already have a Python distribution, install one. For example, download the miniconda pkg installer for macOS and install it.
- Open a terminal.
-
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
-
Type the following to test Datoviz:
python -c "import datoviz; datoviz.demo()"
- If you don't already have a Python distribution, install one. For example, download the miniconda installer for Windows 64-bit and install it.
- Open an Anaconda prompt.
-
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
-
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.
Note
Only Ubuntu 20.04 has been tested so far.
- Install the latest graphics drivers.
-
Install the build tools:
sudo apt install build-essential cmake ninja-build \ xcb libx11-xcb-dev libxcursor-dev libxi-dev patchelf
-
Install the optional dependencies:
sudo apt install libpng-dev libavcodec-dev libavformat-dev \ libavfilter-dev libavutil-dev libswresample-dev \ libqt5opengl5-dev libfreetype6-dev
-
Install the latest Lunarg Vulkan SDK (tarball SDK), for example in
~/vulkan
. -
Export the Vulkan environment variables:
source ~/vulkan/setup-env.sh
-
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. -
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
-
Clone the Datoviz repository:
git clone --recursive https://github.com/datoviz/datoviz.git cd datoviz
-
Build the C library:
./manage.sh build
-
Check that the compilation worked by running an example:
./manage.sh demo scatter
-
Once the C library is compiled, you need to compile the Cython module:
./manage.sh cython
-
Export the shared library path to your environment:
source setup-env.sh
-
Try a Python example:
python bindings/cython/examples/quickstart.py
- Open a terminal.
- Type
git
to install git. - Install Xcode.
- Install Homebrew.
-
Install the build dependencies:
brew install cmake ninja libpng
-
Download the latest Vulkan SDK.
- Install it.
-
Clone the Datoviz repository:
git clone --recursive https://github.com/datoviz/datoviz.git cd datoviz
-
Build the C library:
./manage.sh build
-
Check that the compilation worked by running an example:
./manage.sh demo scatter
-
Once the C library is compiled, you need to compile the Cython module:
./manage.sh cython
-
Export the shared library path to your environment:
source setup-env.sh
-
Try a Python example:
python bindings/cython/examples/quickstart.py
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.
- Install the latest graphics drivers for your system and hardware.
- Install Winlibs, a Windows port of gcc, using mingw-w64.
- Make sure the mingw executable is in the PATH.
- Install CMake for Windows.
- Install the Windows Universal C Runtime.
- Install the latest Lunarg Vulkan SDK (
.exe
executable). - Install git for Windows and open a Git-aware Windows terminal.
-
Clone the Datoviz repository:
git clone --recursive https://github.com/datoviz/datoviz.git cd datoviz
-
Build the C library:
manage.bat build
-
Build the Cython module and create a wheel:
manage.bat wheel
-
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.
- Compile Datoviz with Swiftshader support.
- Compile Swiftshader.
-
Temporarily override your native Vulkan driver with the SwiftShader one:
- Linux:
export LD_LIBRARY_PATH=/path/to/swiftshader/build/Linux/:$LD_LIBRARY_PATH
- Linux:
-
Run your Datoviz script or application.