viam-orb-slam3

(In)stability Notice

Warning This is an experimental feature. Stability is not guaranteed. Breaking changes are likely to occur, and occur often.

Overview

This repo wraps ORB_SLAM3 as a modular resource so it is easily usable with the rest of Viam's ecosystem. ORB_SLAM3 is a SLAM system for feature-based mapping using monocular, rgbd, and stereo camera setups.

Getting started

Install viam-orb-slam3:

Linux aarch64:

sudo curl -o /usr/local/bin/orb_grpc_server http://packages.viam.com/apps/slam-servers/orb_grpc_server-stable-aarch64.AppImage
sudo chmod a+rx /usr/local/bin/orb_grpc_server

Linux x86_64:

sudo curl -o /usr/local/bin/orb_grpc_server http://packages.viam.com/apps/slam-servers/orb_grpc_server-stable-x86_64.AppImage
sudo chmod a+rx /usr/local/bin/orb_grpc_server

Homebrew / Linuxbrew

brew tap viamrobotics/brews && brew install orb-grpc-server

For next steps, see the Run ORB-SLAM3 on your Robot with a Webcam Tutorial.

Development

Download

git clone --recurse-submodules https://github.com:viamrobotics/viam-orb-slam3

If you happened to use git clone only, you won't see the ORB_SLAM3 folder and will need to fetch it:

git submodule update --init

Setup, build, and run the binary

# Setup the gRPC files
make bufinstall buf 
# Install dependencies
make setup
# Build & install the binary
make build
sudo cp ./viam-orb-slam3/bin/orb_grpc_server /usr/local/bin
# Run the binary
orb_grpc_server

Alternative: Manual Dependency Install (x64 or arm64)

# Install & build Pangolin (includes eigen)
git clone --recursive https://github.com/stevenlovegrove/Pangolin.git
cd Pangolin 
./scripts/install_prerequisites.sh recommended
mkdir build && cd build
cmake ..
make -j4 
sudo make install
# Install openCV
sudo apt install libopencv-dev
# Install Eigen3
sudo apt install libeigen3-dev
# Other dependencies
sudo apt install libssl-dev 
sudo apt-get install libboost-all-dev

Linting

# Ubuntu:
sudo apt install clang-format
# macOS:
brew install clang-format
make format

Testing

make test

Working with submodules

Commit and push

Commit and push changes in the submodules first.
Commit and push changes in the slam library last.

Or, alternatively:

Commit changes in the submodules
Commit changes in the main repo
Push all changes by running git push --recurse-submodules=on-demand

Changing branches in a submodule

When changing branches in a submodule, update .gitmodules, e.g., changing to a branch called kk/fix-install:

...
[submodule "viam-orb-slam3/ORB_SLAM3"]
        path = viam-orb-slam3/ORB_SLAM3
        url = git@github.com:kkufieta/ORB_SLAM3.git
        branch=kk/fix-this-bug

Commit & push the changes.

When pulling those changes, run the following:

git pull
git submodule update --init --recursive

License

Apache 2.0 - See LICENSE file

Gifted-s/viam-orb-slam3