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.
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-8sudo 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/nullsudo 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-toolsEstas 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-filtersecho "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrcros2 doctor --reportEste documento descreve a sequência de instalação do ORB-SLAM3 e do seu wrapper ROS2.
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.shAntes de correr
./build.sh, verificar a versão do OpenCV instalada:pkg-config --modversion opencv4O
CMakeLists.txtdeste repositório e o doThirdparty/DBoW2fixam a versão4.6do OpenCV (find_package(OpenCV 4.6)). Se a versão instalada for diferente (ex:4.5.4, comum em Ubuntu 22.04), ofind_packagefalha silenciosamente e o CMake devolveOpenCV > 3.0 not foundou 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"
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 installPara remover posteriormente, caso necessário:
sudo rm -rf /usr/local/include/sophus
sudo rm -rf /usr/local/share/sophusRepositório: https://github.com/AeroTec-ATLAS/ORB_SLAM3_ROS2
cd ~
git clone https://github.com/AeroTec-ATLAS/ORB_SLAM3_ROS2
cd ORB_SLAM3_ROS2Verificar
CMakeLists.txt(linha ~28): este repositório também fixafind_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.txte 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 ambienteORB_SLAM3_ROOT_PATH:set(ORB_SLAM3_ROOT_DIR "$ENV{ORB_SLAM3_ROOT_PATH}/ORB-SLAM3")Isto só funciona se
ORB_SLAM3_ROOT_PATHestiver definida na mesma shell onde se correcolcon 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/libSe
echonão devolver nada, corrersource ~/.bashrcde 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 pacoteros-humble-cv-bridgeinstalado por apt pode não incluir o cabeçalho.hpp(apenas o.hmais antigo). Confirmar:dpkg -L ros-humble-cv-bridge | grep cv_bridgeSe 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.bashErro 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 pastaORB_SLAM3_ROS2foi clonada, compilada, e depois movida/copiada para outro caminho. Resolver limpando a cache antiga:rm -rf build install log colcon build --symlink-install
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.bashe$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-seORB_SLAM3_ROS2e 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# Verificar se o pacote foi instalado
ros2 pkg list | grep orbslam3
# Listar executáveis disponíveis
ros2 pkg executables orbslam3Deverá ver os seguintes executáveis disponíveis:
orbslam3 monoorbslam3 rgbdorbslam3 stereoorbslam3 stereo-inertial
ros2 run orbslam3 mono \
$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Monocular/TUM1.yamlTópicos subscritos:
/camera/image_raw(sensor_msgs/Image)
ros2 run orbslam3 stereo \
$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Stereo/EuRoC.yaml \
falseTópicos subscritos:
/camera/left/image_raw(sensor_msgs/Image)/camera/right/image_raw(sensor_msgs/Image)
ros2 run orbslam3 rgbd \
$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt \
$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/RGB-D/TUM1.yamlTópicos subscritos:
/camera/rgb/image_raw(sensor_msgs/Image)/camera/depth_registered/image_raw(sensor_msgs/Image)
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 \
falseTópicos subscritos:
/camera/left/image_raw(sensor_msgs/Image)/camera/right/image_raw(sensor_msgs/Image)/imu(sensor_msgs/Imu)
Terminal 1: Lançar o nó completo (câmara + SLAM)
ros2 launch orbslam3 stereo_realsense.launch.pyEste launch file inicia automaticamente:
- O driver da RealSense (
realsense2_camera_node) - O nó de SLAM estéreo (
orbslam3_stereo) - Os transforms estáticos (
base_link→camera_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:=0Terminal 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_rawDownload 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-DFNkUEfDkJsCTerminal 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.yamlTerminal 2: Reproduzir bag
ros2 bag play my_camera_bagsudo apt install ros-${ROS_DISTRO}-v4l2-camera
sudo apt install ros-${ROS_DISTRO}-rqt-image-viewTerminal 1: Lançar câmara
ros2 run v4l2_camera v4l2_camera_node \
--ros-args -r /image_raw:=/cameraTerminal 2 (opcional): Visualizar imagem
ros2 run rqt_image_view rqt_image_viewTerminal 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.yamlEsta secção descreve como verificar que os nós estão a funcionar correctamente após o arranque.
Após lançar o sistema, confirmar que todos os tópicos esperados estão activos:
ros2 topic list | grep orb_slam3Deverão aparecer os seguintes tópicos:
/orb_slam3/camera_pose
/orb_slam3/odometry
/orb_slam3/map_points
/orb_slam3/tracking_state
# 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.positionros2 topic echo /orb_slam3/tracking_stateMapeamento 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 |
# 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# 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-arrO 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
ros2 run rviz2 rviz2Configuração recomendada no RViz2:
- Definir
Fixed Frameparamap - Adicionar display
PoseStamped→ tópico/orb_slam3/camera_pose - Adicionar display
Odometry→ tópico/orb_slam3/odometry - Adicionar display
PointCloud2→ tópico/orb_slam3/map_points - Adicionar display
TFpara visualizar a árvore de transforms
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/TriggerResposta esperada:
response:
success: True
message: ORB-SLAM3 reset successfully
O nó publica automaticamente um resumo de diagnóstico no log a 1 Hz. Para visualizar:
ros2 topic echo /rosout | grep DiagOu 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 debugExemplo 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
# 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_ROS2echo $LD_LIBRARY_PATH
source ~/.bashrcA 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).
sudo apt install -y libboost-serialization-devsudo apt install -y python3-ament-packagesudo apt install -y ros-humble-cv-bridge ros-humble-vision-opencv ros-humble-message-filters
dpkg -L ros-humble-cv-bridge | grep cv_bridgeSe 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_PATHSe estiver vazia, correr source ~/.bashrc ou confirmar que o export foi mesmo gravado:
grep ORB_SLAM3_ROOT_PATH ~/.bashrc5.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-install5.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- 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_rawVerificar o estado de tracking:
ros2 topic echo /orb_slam3/tracking_stateSe 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# 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- 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
- ORB-SLAM3 Original: https://github.com/UZ-SLAMLab/ORB_SLAM3
- ORB-SLAM3 Ubuntu 24.04: https://github.com/AeroTec-ATLAS/ORB-SLAM3-STEREO-FIXED-for-ubuntu-24.04-LTS
- Wrapper ROS2: https://github.com/AeroTec-ATLAS/ORB_SLAM3_ROS2
- Documentação ROS2: https://docs.ros.org/
Última actualização: 30 de Agosto de 2026