DOCSEARCHbyAlgolia
Submit Docs

Sophus Lie Groups

repository·main·Indexed 25 days ago

https://github.com/strasdat/sophus

C++ implementations of Lie groups (SO(2), SO(3), SE(2), SE(3)) for 2D and 3D geometric computations in robotics and computer vision. The library includes Python bindings via sophus-pybind, providing vectorized support for SO3 and SE3 operations, including initialization from quaternions, matrices, and rotation vectors, as well as interpolation and iterative mean calculations.

Tokens
2.7K
Snippets
6
Records
15
Agent score
82%

What's inside Sophus

  1. Overview of Sophus Lie Groups

    main

    Sophus is a C++ implementation of Lie groups used for 2D and 3D geometric problems in Computer Vision and Robotics.

    Key supported groups include:

    • SO(2) and SO(3): Special orthogonal groups for representing 2D and 3D rotations.
    • SE(2) and SE(3): Special Euclidean groups for representing isometries (rigid body transformations consisting of rotations and translations) in 2D and 3D.

  2. Project Status and Future Iterations

    main

    Sophus (v1) is currently in maintenance mode. Future updates are expected to be limited to bug fixes, small improvements, and toolchain updates.

    For more advanced geometric features, consider these upcoming/alternative versions:

    • sophus2: A complete C++ rewrite including unit vectors, splines, image classes, and camera models. It is currently hosted as part of the farm-ng-core repository.
    • sophus-rs: A Rust implementation that includes geometric concepts and an experimental non-linear least squares optimization library. Available on crates.io.

  3. Install Sophus via vcpkg

    main

    You can use the vcpkg dependency manager to build and install Sophus. Follow these steps to clone, bootstrap, and install the package:

    git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install sophus

  4. Build Sophus from source

    main

    To build Sophus from source, you need a C++17 compiler (though older versions can build with C++14).

    Platform Support:

    • Linux and macOS: Fully tested.
    • Windows: May require manual patches as there is currently no CI for Windows.

    Dependencies: There are no explicit comprehensive build instructions, but you can find information on required dependencies by inspecting the scripts/ directory or the .github/workflows/main.yml file in the repository.

  5. Features of the sophus-pybind module

    main

    The sophus-pybind module provides Python access to core Sophus features, with a user interface inspired by scipy.spatial.transform.Rotation.

    SO3 (3D Rotations)

    • Initialization: from_quat(), from_matrix(), exp()
    • Conversion: to_quat(), to_matrix(), log()
    • Operations: Multiplication with SO3 or 3D points, Inverse, copy, print, and len()
    • Indexing: Support for [] operator (index or slices)
    • Vectorization: Supports vectorized operations.

    SE3 (3D Rigid Body Motions)

    • Initialization: from_quat_and_translation(), from_matrix(), from_matrix3x4(), exp()
    • Conversion: to_quat_and_translation(), to_matrix(), to_matrix3x4(), log()
    • Operations: Multiplication with SE3 or 3D points, Inverse, copy, print, and len()
    • Indexing: Support for [] operator (index or slices)
    • Interpolation: Interpolate between two SE3 objects.
    • Mean: Iterative mean of a group of SE3 objects.
    • Vectorization: Supports vectorized operations.

  6. Passing single SO3/SE3 objects to C++ via Python bindings

    main

    The bindings include a custom caster that allows SO3Group or SE3Group objects to be implicitly converted to a single Sophus::SO3 or Sophus::SE3 object at C++ boundaries.

    This means you can pass a Python object containing exactly one SO3/SE3 element to a C++ function that expects a single object, simplifying the binding of the rest of the C++ codebase.

    Note: The implicit cast will fail if the Python object contains more than one element.

  7. How vectorization works in sophus-pybind

    main

    To achieve efficient numerical performance in Python, sophus-pybind exports Sophus::SO3 and Sophus::SE3 as vectors of objects. This is implemented by binding the C++ SO3Group and SE3Group classes, which inherit from std::vector.

    • SO3Group inherits from std::vector<Sophus::SO3<Scalar>>
    • SE3Group inherits from std::vector<Sophus::SE3<Scalar>>

    This approach allows users to work with arrays of transformations, similar to the pattern used in scipy.spatial.transform.Rotation.

  8. Install the sophus-pybind Python module

    main

    To use the Sophus Python bindings, create a virtual environment and install the package from the source repository. This ensures all dependencies are isolated.

    1. Create and activate a virtual environment.
    2. Clone the Sophus repository.
    3. Install the package using pip install . from the root directory.
    # Create virtual environment
python3 -m venv ~/sophus_venv
source ~/sophus_venv/bin/activate

# Install package
git clone <sophus-package>
cd Sophus
pip install .

  9. Generate .pyi stub files for type annotation

    main

    To enable type hinting and autocompletion in IDEs, you can generate .pyi stub files using pybind11-stubgen.

    Follow these steps:

    1. Install pybind11-stubgen via pip.
    2. Run the provided generate_stubs.py script (requires sophus-pybind to be already installed).
    3. Re-install the project to include the newly generated stub files.
    cd Sophus
# install pybind11-stubgen that will create stub file for a python module
pip3 install pybind11-stubgen

# Create stub files (Requires sophus-pybind to be installed in prior)
python3 generate_stubs.py

# Re-install the sophus-pybind project with the stub file
pip install .

  10. Run the Sophus Python quickstart tutorial

    main

    A Jupyter notebook tutorial is available to demonstrate usage. To ensure Jupyter uses the virtual environment where sophus-pybind is installed, run it using python3 -m jupyter.

    cd Sophus
python3 -m jupyter notebook sophus_pybind/examples/sophus_quickstart_tutorial.ipynb