Skip to content
 
 

Latest commit

 

History

26 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SLAM para Câmara RealSense

0. Instalação do ROS 2 Humble (Ubuntu 22.04 LTS)

Esta secção é um pré-requisito e deve ser feita antes de tudo o resto. O wrapper ROS2 deste projecto foi testado com ROS 2 Humble Hawksbill em Ubuntu 22.04 LTS — não usar Jazzy nem outra distro, pois algumas das correcções abaixo assumem Humble.

0.1 Configurar o locale (UTF-8)

locale  # confirmar que já existe suporte UTF-8
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

0.2 Adicionar o repositório apt do ROS 2

sudo apt install -y software-properties-common curl
sudo add-apt-repository universe

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

0.3 Instalar o ROS 2 Humble

sudo apt update
sudo apt upgrade -y

# Instalação completa (inclui RViz, demos, tutoriais) — recomendado se houver GUI
sudo apt install -y ros-humble-desktop

# Alternativa sem componentes gráficos (ex: dentro de um container sem X11)
# sudo apt install -y ros-humble-ros-base

# Ferramentas de desenvolvimento (colcon, rosdep, vcstool, etc.)
sudo apt install -y ros-dev-tools

0.4 Instalar dependências adicionais necessárias ao wrapper

Estas não vêm com ros-humble-desktop e são necessárias para compilar este projecto:

sudo apt install -y python3-ament-package
sudo apt install -y ros-humble-cv-bridge ros-humble-vision-opencv ros-humble-message-filters

0.5 Fazer o source automaticamente em cada shell

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

0.6 Verificar a instalação

ros2 doctor --report

1. Instalação do ORB-SLAM3 e Wrapper ROS2 para Ubuntu 24.04 / Ubuntu 22.04

Este documento descreve a sequência de instalação do ORB-SLAM3 e do seu wrapper ROS2.

1.1 Passo 1: Clonar e Instalar ORB-SLAM3

Clonar o repositório ORB-SLAM3 e seguir as instruções presentes em:

Repositório: https://github.com/AeroTec-ATLAS/ORB-SLAM3-STEREO-FIXED-for-ubuntu-24.04-LTS

cd ~
mkdir -p orb-slam3-root && cd orb-slam3-root

export ORB_SLAM3_ROOT_PATH=~/orb-slam3-root
echo "export ORB_SLAM3_ROOT_PATH=~/orb-slam3-root" >> ~/.bashrc

git clone https://github.com/AeroTec-ATLAS/ORB-SLAM3-STEREO-FIXED-for-ubuntu-24.04-LTS ORB-SLAM3
cd ORB-SLAM3

chmod +x build.sh
./build.sh

Antes de correr ./build.sh, verificar a versão do OpenCV instalada:

pkg-config --modversion opencv4

O CMakeLists.txt deste repositório e o do Thirdparty/DBoW2 fixam a versão 4.6 do OpenCV (find_package(OpenCV 4.6)). Se a versão instalada for diferente (ex: 4.5.4, comum em Ubuntu 22.04), o find_package falha silenciosamente e o CMake devolve OpenCV > 3.0 not found ou um erro semelhante. Corrigir editando essa linha em ambos os ficheiros para a versão real instalada (ex: find_package(OpenCV 4.5 ...)), ou remover o número de versão para aceitar qualquer 4.x.

Dependências adicionais que podem faltar durante ./build.sh:

sudo apt install -y libssl-dev              # erro: "Could NOT find OpenSSL"
sudo apt install -y libboost-serialization-dev  # erro: "boost/serialization/serialization.hpp: No such file or directory"

1.2 Passo 2: Instalação Global do Sophus

Importante: Este passo é obrigatório para a integração com ROS2 e não está documentado no repositório anterior.

cd $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Thirdparty/Sophus/build
sudo make install

Para remover posteriormente, caso necessário:

sudo rm -rf /usr/local/include/sophus
sudo rm -rf /usr/local/share/sophus

1.3 Passo 3: Clonar e Instalar Wrapper ROS2

Repositório: https://github.com/AeroTec-ATLAS/ORB_SLAM3_ROS2

cd ~
git clone https://github.com/AeroTec-ATLAS/ORB_SLAM3_ROS2
cd ORB_SLAM3_ROS2

Verificar CMakeLists.txt (linha ~28): este repositório também fixa find_package(OpenCV 4.6 REQUIRED), independentemente da correcção já feita no ORB-SLAM3 (são projectos CMake separados). Ajustar novamente para a versão instalada:

grep -n "find_package(OpenCV" CMakeLists.txt

e editar o número de versão para corresponder ao resultado de pkg-config --modversion opencv4.

Verificar CMakeModules/FindORB_SLAM3.cmake: este ficheiro já lê o caminho a partir da variável de ambiente ORB_SLAM3_ROOT_PATH:

set(ORB_SLAM3_ROOT_DIR "$ENV{ORB_SLAM3_ROOT_PATH}/ORB-SLAM3")

Isto só funciona se ORB_SLAM3_ROOT_PATH estiver definida na mesma shell onde se corre colcon build. Confirmar antes de compilar:

echo $ORB_SLAM3_ROOT_PATH
ls $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/lib
ls $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Thirdparty/DBoW2/lib
ls $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Thirdparty/g2o/lib

Se echo não devolver nada, correr source ~/.bashrc de novo nesta shell (o export pode não ter sido persistido, ou está a usar-se um terminal/sessão distrobox novo que ainda não carregou o .bashrc).

Erro cv_bridge/cv_bridge.hpp: No such file or directory: o pacote ros-humble-cv-bridge instalado por apt pode não incluir o cabeçalho .hpp (apenas o .h mais antigo). Confirmar:

dpkg -L ros-humble-cv-bridge | grep cv_bridge

Se só aparecer cv_bridge.h, substituir todas as inclusões no código-fonte:

grep -rl "cv_bridge/cv_bridge.hpp" src/ | xargs sed -i 's/cv_bridge\/cv_bridge.hpp/cv_bridge\/cv_bridge.h/'
colcon build --symlink-install
source install/setup.bash

Erro de cache do CMake após mover a pasta do workspace (CMake Error: The current CMakeCache.txt directory ... is different than the directory ... where CMakeCache.txt was created): acontece se a pasta ORB_SLAM3_ROS2 foi clonada, compilada, e depois movida/copiada para outro caminho. Resolver limpando a cache antiga:

rm -rf build install log
colcon build --symlink-install

1.4 Passo 4: Configuração Adicional de Variáveis de Ambiente

Adicionar as seguintes linhas ao ficheiro ~/.bashrc (substituindo o bloco antigo, se existir):

# Carregar ambiente ROS2 Humble
source /opt/ros/humble/setup.bash

# Carregar workspace ORB-SLAM3 ROS2
if [ -f "$HOME/ORB_SLAM3_ROS2/install/setup.bash" ]; then
    source "$HOME/ORB_SLAM3_ROS2/install/setup.bash"
fi

# Configurar caminhos das bibliotecas dinâmicas
export LD_LIBRARY_PATH="$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/lib:$LD_LIBRARY_PATH"
export LD_LIBRARY_PATH="$ORB_SLAM3_ROOT_PATH/Pangolin/build:$LD_LIBRARY_PATH"

Atenção: o bloco original referia /opt/ros/jazzy/setup.bash e $ORB_SLAM3_ROOT_PATH/ROS2_ORB_SLAM3/install/setup.bash — nenhum dos dois corresponde à instalação real (ROS 2 Humble, não Jazzy; a pasta chama-se ORB_SLAM3_ROS2 e fica directamente em ~, não dentro de $ORB_SLAM3_ROOT_PATH). Confirmar o caminho correcto antes de gravar:

ls ~/ORB_SLAM3_ROS2/install/setup.bash

Aplicar as alterações:

source ~/.bashrc

1.5 Verificação da Instalação

# Verificar se o pacote foi instalado
ros2 pkg list | grep orbslam3

# Listar executáveis disponíveis
ros2 pkg executables orbslam3

Deverá ver os seguintes executáveis disponíveis:

  • orbslam3 mono
  • orbslam3 rgbd
  • orbslam3 stereo
  • orbslam3 stereo-inertial

2. Exemplos de Utilização

2.1 Modo Monocular

ros2 run orbslam3 mono \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Monocular/TUM1.yaml

Tópicos subscritos:

  • /camera/image_raw (sensor_msgs/Image)

2.2 Modo Estéreo

ros2 run orbslam3 stereo \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Stereo/EuRoC.yaml \
    false

Tópicos subscritos:

  • /camera/left/image_raw (sensor_msgs/Image)
  • /camera/right/image_raw (sensor_msgs/Image)

2.3 Modo RGB-D

ros2 run orbslam3 rgbd \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/RGB-D/TUM1.yaml

Tópicos subscritos:

  • /camera/rgb/image_raw (sensor_msgs/Image)
  • /camera/depth_registered/image_raw (sensor_msgs/Image)

2.4 Modo Estéreo-Inercial

ros2 run orbslam3 stereo-inertial \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Stereo-Inertial/EuRoC.yaml \
    false

Tópicos subscritos:

  • /camera/left/image_raw (sensor_msgs/Image)
  • /camera/right/image_raw (sensor_msgs/Image)
  • /imu (sensor_msgs/Imu)

3. Exemplos Práticos

3.1 Exemplo com Intel RealSense D435

Terminal 1: Lançar o nó completo (câmara + SLAM)

ros2 launch orbslam3 stereo_realsense.launch.py

Este launch file inicia automaticamente:

  • O driver da RealSense (realsense2_camera_node)
  • O nó de SLAM estéreo (orbslam3_stereo)
  • Os transforms estáticos (base_linkcamera_link)

Terminal 2 (opcional): Lançar apenas a câmara separadamente

ros2 launch realsense2_camera rs_launch.py \
    enable_infra1:=true \
    enable_infra2:=true \
    enable_depth:=false \
    enable_color:=false \
    infra_width:=848 \
    infra_height:=480 \
    infra_fps:=30.0 \
    enable_sync:=true \
    emitter_enabled:=0

Terminal 3 (opcional): Lançar apenas o SLAM separadamente

ros2 run orbslam3 stereo \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
    /caminho/para/cameraParameters.yml \
    true \
    --ros-args \
    -r camera/left:=/camera/infra1/image_rect_raw \
    -r camera/right:=/camera/infra2/image_rect_raw

3.2 Teste com ROS2 Bag

Download de bag de teste:

cd $ORB_SLAM3_ROOT_PATH
pip install gdown --break-system-packages
gdown --folder https://drive.google.com/drive/folders/1NY4KEW2qpfKlzR-674E-DFNkUEfDkJsC

Terminal 1: Executar ORB-SLAM3

ros2 run orbslam3 mono \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Monocular/TUM1.yaml

Terminal 2: Reproduzir bag

ros2 bag play my_camera_bag

3.3 Teste com Webcam USB

sudo apt install ros-${ROS_DISTRO}-v4l2-camera
sudo apt install ros-${ROS_DISTRO}-rqt-image-view

Terminal 1: Lançar câmara

ros2 run v4l2_camera v4l2_camera_node \
    --ros-args -r /image_raw:=/camera

Terminal 2 (opcional): Visualizar imagem

ros2 run rqt_image_view rqt_image_view

Terminal 3: Executar SLAM

ros2 run orbslam3 mono \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
    $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Monocular/TUM1.yaml

4. Teste e Monitorização dos Nós

Esta secção descreve como verificar que os nós estão a funcionar correctamente após o arranque.

4.1 Verificar Tópicos Publicados

Após lançar o sistema, confirmar que todos os tópicos esperados estão activos:

ros2 topic list | grep orb_slam3

Deverão aparecer os seguintes tópicos:

/orb_slam3/camera_pose
/orb_slam3/odometry
/orb_slam3/map_points
/orb_slam3/tracking_state

4.2 Monitorizar a Pose em Tempo Real

# Pose simples (PoseStamped)
ros2 topic echo /orb_slam3/camera_pose

# Odometria com covariância (Odometry)
ros2 topic echo /orb_slam3/odometry

# Apenas posição x, y, z
ros2 topic echo /orb_slam3/camera_pose --field pose.position

4.3 Monitorizar o Estado de Tracking

ros2 topic echo /orb_slam3/tracking_state

Mapeamento dos valores:

Valor Estado Descrição
0 NO_IMAGES_YET Nenhuma imagem recebida ainda
1 NOT_INITIALIZED A aguardar inicialização
2 OK Tracking a funcionar correctamente
3 RECENTLY_LOST Perdido recentemente, a usar modelo de movimento
4 LOST Tracking perdido

4.4 Verificar a Taxa de Publicação

# Taxa de publicação da pose (deve ser ~30 Hz)
ros2 topic hz /orb_slam3/camera_pose

# Taxa da odometria
ros2 topic hz /orb_slam3/odometry

# Taxa dos pontos do mapa
ros2 topic hz /orb_slam3/map_points

# Verificar latência (delay entre timestamp da mensagem e hora actual)
ros2 topic delay /orb_slam3/camera_pose

4.5 Verificar a Árvore de TF

# Ver todos os transforms activos
ros2 run tf2_tools view_frames

# Verificar transform específico map -> camera_link
ros2 run tf2_ros tf2_echo map camera_link

# Verificar se o transform está a ser publicado
ros2 topic echo /tf --no-arr

O comando view_frames gera um ficheiro frames.pdf com o diagrama completo da árvore de TF. A estrutura esperada é:

map
└── odom
    └── base_link
        └── camera_link

4.6 Visualização no RViz2

ros2 run rviz2 rviz2

Configuração recomendada no RViz2:

  1. Definir Fixed Frame para map
  2. Adicionar display PoseStamped → tópico /orb_slam3/camera_pose
  3. Adicionar display Odometry → tópico /orb_slam3/odometry
  4. Adicionar display PointCloud2 → tópico /orb_slam3/map_points
  5. Adicionar display TF para visualizar a árvore de transforms

4.7 Reset Manual do SLAM

Caso o tracking seja perdido e seja necessário reiniciar o ORB-SLAM3 sem reiniciar o nó:

ros2 service call /orb_slam3/reset std_srvs/srv/Trigger

Resposta esperada:

response:
  success: True
  message: ORB-SLAM3 reset successfully

4.8 Verificar os Diagnósticos do Nó

O nó publica automaticamente um resumo de diagnóstico no log a 1 Hz. Para visualizar:

ros2 topic echo /rosout | grep Diag

Ou directamente nos logs do nó:

# Ver logs em tempo real (substituir <node_name> pelo nome do nó)
ros2 node info /ORB_SLAM3_ROS2

# Ver logs com nível de detalhe
ros2 run orbslam3 stereo ... --ros-args --log-level debug

Exemplo de saída de diagnóstico esperada:

[INFO] [ORB_SLAM3_ROS2]: [Diag] State: OK | Frames: 450 total / 448 published | Map pts: 1203 | Lost streak: 0

4.9 Verificar Desempenho do Sistema

# Verificar carga do CPU e memória
htop

# Verificar estatísticas dos tópicos ROS2
ros2 topic bw /orb_slam3/map_points

# Verificar informação do nó
ros2 node info /ORB_SLAM3_ROS2

5. Resolução de Problemas Comuns

5.1 Erro: "Library not found"

echo $LD_LIBRARY_PATH
source ~/.bashrc

5.2 CMake Error: OpenCV > 3.0 not found ou erro semelhante de OpenCV não encontrado

A versão fixa em find_package(OpenCV X.Y ...) não corresponde à versão instalada. Ver secções 1.1 e 1.3 acima para corrigir em ambos os repositórios (ORB-SLAM3 e wrapper ROS2 têm CMakeLists.txt independentes).

5.3 fatal error: boost/serialization/serialization.hpp: No such file or directory

sudo apt install -y libboost-serialization-dev

5.4 ModuleNotFoundError: No module named 'ament_package'

sudo apt install -y python3-ament-package

5.5 fatal error: cv_bridge/cv_bridge.hpp: No such file or directory

sudo apt install -y ros-humble-cv-bridge ros-humble-vision-opencv ros-humble-message-filters
dpkg -L ros-humble-cv-bridge | grep cv_bridge

Se apenas existir cv_bridge.h (sem .hpp), substituir as inclusões no código:

grep -rl "cv_bridge/cv_bridge.hpp" src/ | xargs sed -i 's/cv_bridge\/cv_bridge.hpp/cv_bridge\/cv_bridge.h/'

5.6 Could NOT find ORB_SLAM3 (missing: ORB_SLAM3_LIBRARY ORB_SLAM3_INCLUDE_DIR DBoW2_LIBRARY g2o_LIBRARY)

A variável ORB_SLAM3_ROOT_PATH não está definida na shell actual. Confirmar:

echo $ORB_SLAM3_ROOT_PATH

Se estiver vazia, correr source ~/.bashrc ou confirmar que o export foi mesmo gravado:

grep ORB_SLAM3_ROOT_PATH ~/.bashrc

5.7 CMake Error: The current CMakeCache.txt directory ... is different than the directory ... where CMakeCache.txt was created

A pasta do workspace foi movida/copiada depois de já ter sido compilada. Limpar e recompilar:

rm -rf build install log
colcon build --symlink-install

5.8 mkdir: cannot create directory 'build': File exists (durante a compilação do ORB-SLAM3 ou librealsense standalone)

Acontece ao repetir mkdir build && cd build quando build/ já existe de uma tentativa anterior — o mkdir falha e, por causa do &&, o cd build nunca chega a correr, fazendo com que todos os comandos seguintes actuem na pasta errada. Resolver com:

rm -rf build && mkdir build && cd build

5.9 ORB-SLAM3 não inicializa

  • Verificar se há movimento suficiente da câmara
  • Garantir que a cena tem textura adequada
  • Verificar se os tópicos estão a publicar dados:
ros2 topic list
ros2 topic echo /camera/infra1/image_rect_raw --no-arr
ros2 topic hz /camera/infra1/image_rect_raw

5.10 Tópico /orb_slam3/camera_pose não publica

Verificar o estado de tracking:

ros2 topic echo /orb_slam3/tracking_state

Se o valor for 4 (LOST) durante um período prolongado, o nó tenta o reset automático após 30 frames consecutivos perdidos. Pode também fazer reset manual:

ros2 service call /orb_slam3/reset std_srvs/srv/Trigger

5.11 TF não disponível

# Verificar se o transform está a ser publicado
ros2 run tf2_ros tf2_echo map camera_link

# Verificar a árvore completa
ros2 run tf2_tools view_frames

5.12 Performance baixa

  • Reduzir o número de features no ficheiro YAML:
    ORBextractor.nFeatures: 500
  • Verificar se o Pangolin não está a consumir demasiados recursos
  • Considerar desactivar o viewer do Pangolin

6. Referências


Última actualização: 30 de Agosto de 2026

About

ROS2 wrapping package for orbslam3 library

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages