depth_anything_v2_ros2

Overview

This package is a ROS2 wrapper for the depth_anything_v2 library. It provides a ROS2 node that subscribes to a camera topic and publishes the depth map of the scene.

RGB	Depth

The depth_anything_v2_ros2 package has been tested under [ROS2] jazzy on [Ubuntu] 22.04. This is research code, expect that it changes often and any fitness for a particular purpose is disclaimed.

Installation

Building from Source

Dependencies

• Robot Operating System (ROS) 2 (middleware for robotics),
• depth_anything_v2 (library for depth estimation),
• torch (deep learning framework),
• nav2_common (used by the launch file to rewrite the parameters YAML).

torch, torchvision, opencv-python and numpy are installed via pip (see Building); the rest are regular ROS 2 dependencies resolved by rosdep.

Building

To build from source, clone the latest version from the main repository into your colcon workspace and install the python dependencies by running the following commands:

cd colcon_workspace/src
git clone --recurse-submodules https://github.com/grupo-avispa/depth_anything_v2_ros2.git -b main
pip3 install -r requirements.txt

Before building, make sure to download the depth_anything_v2 model weights and place them in the models directory.

[!IMPORTANT] This node uses the metric depth model (depth_anything_v2.metric_depth), so you must download a metric checkpoint, not a relative one. A relative checkpoint loaded into the metric architecture produces mis-scaled, non-metric depth (objects appear too far away and bounding boxes become oversized). For indoor scenes use the Hypersim model; for outdoor scenes use the VKITTI model.

You can download the metric checkpoints here. For example, the indoor (Hypersim) small model:

cd colcon_workspace/src/depth_anything_v2_ros2/models
wget https://huggingface.co/depth-anything/Depth-Anything-V2-Metric-Hypersim-Small/resolve/main/depth_anything_v2_metric_hypersim_vits.pth

Remember to set max_depth to the value the checkpoint was trained with (20 m for Hypersim/indoor, 80 m for VKITTI/outdoor).

Then, install the ROS2 dependencies using rosdep and build the package using:

cd colcon_workspace
rosdep install -i --from-path src --rosdistro jazzy -y
colcon build --symlink-install

Updating the depth_anything_v2 submodule

The depth_anything_v2 submodule is pinned to a fixed commit (there are no upstream tags/releases to pin to instead), so git submodule update always checks out that exact commit and builds stay reproducible. To deliberately move to a newer upstream commit:

cd colcon_workspace/src/depth_anything_v2_ros2/depth_anything_v2
git fetch
git checkout <new-commit-sha>
cd ..
git add depth_anything_v2
git commit -m "build: update depth_anything_v2 submodule to <new-commit-sha>"

Rebuild and re-run the test suite afterwards, since upstream changes to dpt.py or the dinov2 backbone can break the DepthEstimator import.

Usage

With some RGB image source running, run the depth_anything_v2_ros2 node with:

ros2 launch depth_anything_v2_ros2 default.launch.py

depth_anything is a managed (lifecycle) node. With the default autostart:=true launch argument it configures (loads the model) and activates (creates the topics) itself on startup. To drive it manually instead, launch with autostart:=false and use:

ros2 lifecycle set /depth_anything configure
ros2 lifecycle set /depth_anything activate

A failed configure (e.g. an invalid encoder or a missing model_file) is reported as a clean lifecycle transition failure instead of crashing the process.

Nodes

depth_anything

This is a managed (lifecycle) node. It subscribes to a camera topic and publishes the depth map of the scene, alongside the matching CameraInfo so downstream nodes (e.g. depth_image_proc for point clouds) can pair both topics.

Subscribed Topics

• camera/color/image_raw ([sensor_msgs/Image])

  The RGB image topic.

• camera/color/camera_info ([sensor_msgs/CameraInfo])

  Camera info matching image_topic, republished alongside the depth image.

Published Topics

• depth ([sensor_msgs/Image])

File truncated at 100 lines see the full file

CHANGELOG

All notable changes to the depth_anything_v2_ros2 project will be documented in this file.

[1.1.0] - 25-07-2026

Added

• Added depth_anything_v2_ros2/depth_estimator.py with the pure depth estimation domain logic, extracted out of the ROS node so it can be unit tested without rclpy, a GPU or a checkpoint file:
  • select_encoder_config() maps an encoder name to its DepthAnythingV2 architecture kwargs and raises ValueError on an unsupported value.
  • resolve_device() falls back to CPU when CUDA is requested but unavailable.
  • postprocess_depth() clips a raw depth prediction to [0, max_depth] and casts it to float32.
  • DepthEstimator loads the model (raising FileNotFoundError/ValueError on a missing checkpoint or invalid encoder) and runs inference.
• Added test/test_depth_estimator.py with 8 pytest cases covering select_encoder_config(), resolve_device() and postprocess_depth().
• Migrated DepthAnythingROS from rclpy.node.Node to rclpy.lifecycle.LifecycleNode: the model is now loaded in on_configure (returning TransitionCallbackReturn.FAILURE on an invalid encoder or missing checkpoint instead of crashing with an opaque AttributeError), and the subscribers/publishers are created in on_activate and torn down in on_deactivate/on_cleanup.
• Added an autostart launch argument (default true) in launch/default.launch.py, passed to the launch_ros.actions.LifecycleNode action so it configures and activates depth_anything right after startup.
• Added camera_info_topic/depth_camera_info_topic parameters: the node now republishes the input CameraInfo alongside the depth image (timestamped with the image header), so downstream nodes such as depth_image_proc can pair both topics to build a point cloud.
• Added a MutuallyExclusiveCallbackGroup for image_callback and switched main() to a MultiThreadedExecutor, so a heavy inference no longer blocks lifecycle transitions and other callbacks.
• Documented the depth_anything_v2 submodule update procedure in README.md.

Changed

• package.xml: added python3-numpy, python3-opencv and nav2_common (already used by the launch file, previously undeclared) as exec_depend.
• requirements.txt: removed gradio, gradio_imageslider and huggingface_hub (unused, pulled in from the upstream Gradio demo).
• .github/workflows/build.yml: removed skip-tests: true so ament_flake8, ament_pep257, ament_copyright and the new pytest suite actually run in CI.
• torch.load() now uses weights_only=True and validates that model_file exists before loading, instead of deserializing an unrestricted pickle and failing with a low-level traceback on a missing file.
• max_depth is now validated to be strictly positive in get_params().
• Extracted the repeated declare/get/log parameter pattern into a _declare() helper.
• Fixed the image_callback docstring (it described "detections", copied from an unrelated node) and the misleading "Invert depth valies" comment.
• Replaced print(e) with self.get_logger().error(...) in the CvBridgeError handler for the outgoing publish, so failures show up in the ROS logs.
• Removed the duplicated start_time = time.time() call and the unnecessary self.current_image instance attribute (now a local variable).
• Removed trailing whitespace flagged by ament_flake8 (W293).

[1.0.0] - previous releases

See the git history prior to this file for changes up to the metric depth support.