![]() |
LibMultiSense
LibMultiSense Documentation
|
LibMultiSense is a C++ and Python library designed to simplify interaction with the MultiSense S family of stereo sensors developed by Carnegie Robotics. It provides a comprehensive, easy-to-use API for capturing and processing stereo sensor data an generating depth images, color images, and 3D point clouds.
Official product page: Carnegie Robotics MultiSense Products
Detailed documentation: LibMultiSense Documentation
LibMultiSense was recently refactored to have a new API. The following examples in the README all assume the user is using the new API. To build with the new API, the following CMake arguments should be set.
-DBUILD_LEGACY_API=0FF
The MultiSense comes preconfigured with a static 10.66.171.21 IP address with a /24 subnet. To connect to the MultiSense, a client machine must be updated with an IP address on the 10.66.171 subnet.
Please see the host network configuration for details on how to set a client machine's IP address and MTU.
Below are minimal examples demonstrating basic usage of LibMultiSense to capture rectified images from the sensor.
LibMultiSense optionally has OpenCV utility functions to make the LibMultiSense client API easier to integrate with existing systems. To build the OpenCV helpers the following CMake argument should be set
-DBUILD_OPENCV=ON
This will require a system installation of OpenCV, or an installation which can be pointed to with CMake's CMAKE_PREFIX_PATH
argument
LibMultiSense optionally uses nlohmann_json for serialization of base LibMultiSense types. To build the nlohmann_json serialization helpers the following CMake argument should be set
-DBUILD_JSON_SERIALIZATION=ON
This will require a system installation of nlohmann_json, or an installation which can be pointed to with CMake's CMAKE_PREFIX_PATH
argument
LibMultiSense optionally uses pybind11 to generate python bindings for the C++ API. To build the pybind11 python bindings the following CMake argument should be set
-DBUILD_PYTHON_BINDINGS=ON
This will require a system installation of pybind11, or an installation which can be pointed to with CMake's CMAKE_PREFIX_PATH
argument
LibMultiSense optionally uses googletest for unit testing the C+ API. To build the googletest unit tests the following CMake argument should be set
-DBUILD_TESTS=ON
This will require a system installation of googletest, or an installation which can be pointed to with CMake's CMAKE_PREFIX_PATH
argument
LibMultiSense uses pybind11 to generate python bindings for the base LibMultiSense API. These bindings can be installed via pip into a python virtual environment or a local python project.
To install the LibMultiSense python bindings
> sudo apt install build-essential pybind11-dev nlohmann-json3-dev > git clone https://github.com/carnegierobotics/LibMultiSense.git > cd LibMultiSense > pip install .
LibMultiSense uses CMake for its build system.
To build the standalone LibMultiSense library and demonstration applications.
# Note this only needs to be run once before building > sudo apt install build-essential nlohmann-json3-dev > git clone https://github.com/carnegierobotics/LibMultiSense.git > cd LibMultiSense > mkdir build > cd build && cmake -DBUILD_LEGACY_API=OFF -DBUILD_JSON_SERIALIZATION=ON -DCMAKE_INSTALL_PREFIX=../install .. > make install > cd ../install
To build the standalone LibMultiSense library without the demonstration applications, set the cmake variable -DMULTISENSE_BUILD_UTILITIES=OFF
LibMultiSense uses pybind11 to generate python bindings for the base LibMultiSense API. These bindings can be installed via pip into a python virtual environment or a local python project.
To install the LibMultiSense python bindings
> brew install pybind11 nlohmann-json > git clone https://github.com/carnegierobotics/LibMultiSense.git > cd LibMultiSense > pip install .
LibMultiSense uses CMake for its build system.
To build the standalone LibMultiSense library and demonstration applications.
# Note this only needs to be run once before building > brew install nlohmann-json > git clone https://github.com/carnegierobotics/LibMultiSense.git > cd LibMultiSense > mkdir build > cd build && cmake -DBUILD_LEGACY_API=OFF -DBUILD_JSON_SERIALIZATION=ON -DCMAKE_INSTALL_PREFIX=../install .. > make install > cd ../install
To build the standalone LibMultiSense library without the demonstration applications, set the cmake variable -DMULTISENSE_BUILD_UTILITIES=OFF
LibMultiSense uses pybind11 to generate python bindings for the base LibMultiSense API. These bindings can be installed via pip into a python virtual environment or a local python project. To ensure Windows has the proper build tools installed, please install Microsoft Visual Studio with the C++ and CMake extensions.
Note you will need to have a version of python installed on your Windows system. This was tested with python 3.9 installed via the Microsoft Store on Windows 11.
To install the LibMultiSense python bindings open a powershell terminal and execute the following commands
> git clone https://github.com/carnegierobotics/LibMultiSense.git > cd LibMultiSense > git clone https://github.com/microsoft/vcpkg.git > ./vcpkg/bootstrap-vcpkg.bat > $Env:VCPKG_ROOT = ./vcpkg > pip install .
LibMultiSense uses CMake and vcpkg to build the LibMultiSense library. To ensure Windows has the proper build tools installed, please install Microsoft Visual Studio with the C++ and CMake extensions.
Open a powershell terminal and execute the following commands:
> git clone https://github.com/carnegierobotics/LibMultiSense.git > cd LibMultiSense > git clone https://github.com/microsoft/vcpkg.git > ./vcpkg/bootstrap-vcpkg.bat > $Env:VCPKG_ROOT = ./vcpkg > cmake --build build --config Release --target install
Integrating LibMultiSense into an existing CMake project is easy. There are two primary methods for integration: a local install on your system, or a submodule clone within your repository
LibMultiSense is installed on your system (i.e. in a location like /opt/multisense)
find_package(MultiSense) target_link_libraries(<your-library-or-binary> MultiSense)
When running CMake, make sure to specify the location of the LibMultiSense install via -DCMAKE_PREFIX_PATH
Clone the LibMultiSense repository into the existing project's source tree. In the main CMakeLists.txt file of the project, add the following lines:
include_directories(LibMultiSense/source/LibMultiSense) add_subdirectory(LibMultiSense/source/LibMultiSense)
Documentation of high-level LibMutliSense concepts can be found here
Doxygen documentation can be built for LibMultisense by running the Doxygen configuration file located in the docs directory
> cd LibMultiSense/docs > doxygen Doxyfile
HTML and LaTex documentation will be generated in the docs directory.
Usage examples are included in the Doxygen documentation.
To report an issue with this library or request a new feature, please use the GitHub issues system
For product support, please see the support section of our website Individual support requests can be created in our support portal
Camera settings like resolution, exposure, FPS, gain, gamma, and white balance can be configured via the LibMultiSense image::Config
Disparity images can be converted to 3D point cloud images using the client API.
The following modified version of the Quickstart example, converts disparity images to 3D point clouds colorized using the left rectified image.
Disparity images can be converted to depth images using the client API
The following modified version of the Quickstart example, converts disparity images to openni depth images and saves them to disk using OpenCV.
Luma and Chroma Aux images can be converted to BGR color images using the client API
The following modified version of the Quickstart example, converts luma and chroma aux images to BGR images and saves them to disk using OpenCV.