Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
docs		docs
isaac_ros_apriltag		isaac_ros_apriltag
resources		resources
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md

Repository files navigation

Isaac ROS Apriltag

Overview

Isaac ROS AprilTag contains a ROS 2 package for detection of AprilTags, a type of fiducial marker that provides a point of reference or measure. AprilTag detections are GPU-accelerated for high performance.

A common graph of nodes connects from an input camera through rectify and resize to AprilTag. Rectify warps the input camera image into a rectified, undistorted output image; this node may not be necessary if the camera driver provides rectified camera images. Resize is often used to downscale higher resolution cameras into the desired resolution for AprilTags if needed. The input resolution to AprilTag is selected by the required detection distance for the application, as a minimum number of pixels are required to perform an AprilTag detection and classification. For example, an 8mp input image of 3840×2160 may be much larger than necessary and a 4:1 downscale to 1920x1080 could make more efficienct use of compute resources and satisfy the required detection distance of the application. Each of the green nodes in the above diagram is GPU accelerated, allowing for a high-performance compute graph from Argus Camera to ApriTag. For USB and Ethernet cameras, the graph is accelerated from Rectify through AprilTag

visual of AprilTag output message information

As illustrated above, detections are provided in an output array for the number of AprilTag detections in the input image. Each entry in the array contains the ID (two-dimensional bar code) for the AprilTag, the four corners ((x0, y0), (x1, y1), (x2, y2), (x3, y3)) and center (x, y) of the input image, and the pose of the AprilTag.

Note: This package is a GPU-accelerated drop-in replacement for the CPU version of ROS Apriltag

Note: For more information, including the paper and the reference CPU implementation, refer to the AprilTag page

Isaac ROS NITROS Acceleration

This package is powered by NVIDIA Isaac Transport for ROS (NITROS), which leverages type adaptation and negotiation to optimize message formats and dramatically accelerate communication between participating nodes.

Performance

The following table summarizes the per-platform performance statistics of sample graphs that use this package, with links included to the full benchmark output. These benchmark configurations are taken from the Isaac ROS Benchmark collection, based on the ros2_benchmark framework.

Sample Graph	Input Size	AGX Orin	Orin NX	Orin Nano 8GB	x86_64 w/ RTX 4060 Ti
AprilTag Node	720p	110 fps 15 ms	69.6 fps 18 ms	50.1 fps 25 ms	262 fps 9.3 ms
AprilTag Graph	720p	143 fps 16 ms	82.9 fps 22 ms	58.0 fps 31 ms	349 fps 11 ms

Latest Update

Update 2023-05-25: Performance improvements.

Supported Platforms

This package is designed and tested to be compatible with ROS 2 Humble running on Jetson or an x86_64 system with an NVIDIA GPU.

Note: Versions of ROS 2 earlier than Humble are not supported. This package depends on specific ROS 2 implementation features that were only introduced beginning with the Humble release.

Platform	Hardware	Software	Notes
Jetson	Jetson Orin Jetson Xavier	JetPack 5.1.1	For best performance, ensure that power settings are configured appropriately.
x86_64	NVIDIA GPU	Ubuntu 20.04+ CUDA 11.8+

Docker

To simplify development, we strongly recommend leveraging the Isaac ROS Dev Docker images by following these steps. This will streamline your development environment setup with the correct versions of dependencies on both Jetson and x86_64 platforms.

Note: All Isaac ROS Quickstarts, tutorials, and examples have been designed with the Isaac ROS Docker images as a prerequisite.

Quickstart

Set up your development environment by following the instructions here.

Clone this repository and its dependencies under ~/workspaces/isaac_ros-dev/src.

cd ~/workspaces/isaac_ros-dev/src

git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common

git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_nitros

git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_apriltag

git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_image_pipeline

Pull down a ROS Bag of sample data:

cd ~/workspaces/isaac_ros-dev/src/isaac_ros_apriltag && \ 
  git lfs pull -X "" -I "resources/rosbags/quickstart.bag"

Launch the Docker container using the run_dev.sh script:

cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
  ./scripts/run_dev.sh

Inside the container, build and source the workspace:

cd /workspaces/isaac_ros-dev && \
  colcon build --symlink-install && \
  source install/setup.bash

(Optional) Run tests to verify complete and correct installation:
```
colcon test --executor sequential
```
Run the following launch files to spin up a demo of this package:
```
ros2 launch isaac_ros_apriltag isaac_ros_apriltag.launch.py
```

Open a second terminal inside the docker container:

cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
  ./scripts/run_dev.sh

Run the rosbag file to simulate an image stream:

ros2 bag play --loop src/isaac_ros_apriltag/resources/rosbags/quickstart.bag

Open a third terminal inside the docker container:

cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
  ./scripts/run_dev.sh

Observe the AprilTag detection output /tag_detections on a separate terminal with the command:
```
source install/setup.bash && \
ros2 topic echo /tag_detections
```

Configuration

You will need to calibrate the intrinsics of your camera if you want the node to determine 3D poses for tags instead of just detection and corners as 2D pixel coordinates. See here for more details.

Next Steps

Try More Examples

To continue your exploration, check out the following suggested examples:

Try NITROS-Accelerated Graph with Argus

If you have an Argus-compatible camera, you can launch the NITROS-accelerated graph by following the tutorial.

Customize your Dev Environment

To customize your development environment, reference this guide.

Replacing `apriltag_ros` with `isaac_ros_apriltag`

Add a dependency on isaac_ros_apriltag to your_package/package.xml and your_package/CMakeLists.txt. The original apriltag_ros dependency may be removed entirely.
Change the package and plugin names in any *.launch.py launch files to use isaac_ros_apriltag and nvidia::isaac_ros::apriltag::AprilTagNode, respectively.

Supported Packages

At this time, the packages under the standard apriltag_ros have the following support:

Existing Package	Isaac ROS Alternative
`apriltag_ros`	See `isaac_ros_apriltag`
`image_pipeline`	See `isaac_ros_image_pipeline`

Package Reference