Ouster Python SDK Development

Building ouster-sdk package

Building the Python SDK from source requires several dependencies:

The Python SDK source is available on the Ouster Github. You should clone the whole project.

Linux and macos

On supported Debian-based linux systems, you can install all build dependencies by running:

$ sudo apt install build-essential cmake \
                   libeigen3-dev libjsoncpp-dev libtins-dev libpcap-dev \
                   python3-dev python3-pip libcurl4-openssl-dev \
                   libglfw3-dev libglew-dev libspdlog-dev \
                   libpng-dev libflatbuffers-dev

On macos >= 10.13, using homebrew, you should be able to run:

$ brew install cmake eigen curl jsoncpp libtins python3 glfw glew spdlog libpng flatbuffers

After you have the system dependencies, you can build the SDK with:

# first, specify the path to the ouster_example repository
$ export OUSTER_SDK_PATH=<PATH TO OUSTER_EXAMPLE REPO>

# make sure you have an up-to-date version of pip installed
$ python3 -m pip install --user --upgrade pip

# install pybind11
$ python3 -m pip install pybind11

# then, build an installable "wheel" package
$ python3 -m pip wheel --no-deps $OUSTER_SDK_PATH/python

# or just install directly (virtualenv recommended)
$ python3 -m pip install $OUSTER_SDK_PATH/python

Note

We recommend to always use Virtual Environment for python development.

Windows 10

On Windows 10, you’ll have to install the Visual Studio 2017 Build Tools, Python and the vcpkg package manager and run:

PS > vcpkg install --triplet=x64-windows curl eigen3 jsoncpp libtins glfw3 glad[gl-api-33] spdlog libpng flatbuffers

The currently tested vcpkg tag is 2023.02.24. After that, using a developer powershell prompt:

# first, specify the path to the ouster_example repository
PS > $env:OUSTER_SDK_PATH="<PATH TO OUSTER_EXAMPLE>"

# point cmake to the location of vcpkg (make sure to use an absolute path)
PS > $env:CMAKE_TOOLCHAIN_FILE="<PATH TO VCPKG REPO>\scripts\buildsystems\vcpkg.cmake"

# set the correct vcpkg triplet
PS > $env:VCPKG_TARGET_TRIPLET="x64-windows"

# set build options related to the compiler
PS > $env:CMAKE_GENERATOR_PLATFORM="x64"
PS > $env:CMAKE_GENERATOR="Visual Studio 15 2017"

# install pybind11
PS > py -m pip install pybind11 ninja

# then, build an installable "wheel" package
PS > py -m pip wheel --no-deps "$env:OUSTER_SDK_PATH\python"

# or just install directly (virtualenv recommended)
PS > py -m pip install "$env:OUSTER_SDK_PATH\python"

See the top-level README in the Ouster Example repository for more details on setting up a development environment on Windows.

Developing

Install in editable mode with pip using pip install -e. For a faster development cycle, you can rebuild using python3 setup.py build_ext -i instead of reinstalling the package after every change. For a local debug build, you can also add the -g flag.

The Ouster SDK package includes configuration for flake8 and mypy. To run:

# install pybind11
$ python3 -m pip install pybind11

# install and run flake8 linter
$ python3 -m pip install flake8
$ cd ${OUSTER_SDK_PATH}/python
$ python3 -m flake8

# install and run mypy in an environment with
$ python3 -m pip install mypy
$ python3 -m mypy src/

Running Tests

To run tests while developing, install the pytest package and run it from the root of the Python SDK package:

$ cd ${OUSTER_SDK_PATH}/python
$ python3 -m pytest

To run interactive viz.PointViz tests, use --interactive argument:

$ cd ${OUSTER_SDK_PATH}/python
$ python3 -m pytest --interactive

To run tests against multiple Python versions simultaneously, use the tox package:

$ cd ${OUSTER_SDK_PATH}/python
$ python3 -m tox

This will take longer, since it will build the package from a source distribution for each supported Python version available.

Using Dockerfile

To simplify testing on multiple linux distros, a Dockerfile is included for running tox on a variety of Debian-based distros with all packaged Python versions pre-installed. To build a test image, run:

$ docker build ${OUSTER_SDK_PATH} -f ${OUSTER_SDK_PATH}/python/Dockerfile \
    --build-arg BASE=ubuntu:20.04 \
    -t ouster-sdk-tox

the BASE argument will default to ubuntu:20.04, but can also be set to other docker tags, e.g. ubuntu:22.04 or debian:11. Then, run the container to invoke tox:

$ docker run -it --rm ouster-sdk-tox