Attention

As of June 30, 2025, the Isaac ROS Buildfarm for Isaac ROS 2.1 on Ubuntu 20.04 Focal is no longer supported.

Due to an isolated infrastructure event, all ROS 2 Humble Debian packages that were previously built for Ubuntu 20.04 are no longer available in the Isaac Apt Repository. All artifacts for Isaac ROS 3.0 and later are built and maintained with a more robust pipeline.

Users are encouraged to migrate to the latest version of Isaac ROS. The source code for Isaac ROS 2.1 continues to be available on the release-2.1 branches of the Isaac ROS GitHub repositories.

The original documentation for Isaac ROS 2.1 is preserved below.

isaac_ros_apriltag

Source code on GitHub.

Quickstart

1. Set up your development environment by following the instructions here.

2. Clone isaac_ros_common and this repository under ${ISAAC_ROS_WS}/src.

   cd ${ISAAC_ROS_WS}/src
   

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

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

3. Pull down a ROS Bag of sample data:

   cd ${ISAAC_ROS_WS}/src/isaac_ros_apriltag && \
     git lfs pull -X "" -I "resources/rosbags/quickstart.bag"
   

4. Launch the Docker container using the run_dev.sh script:

   cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
     ./scripts/run_dev.sh
   

5. Install this package’s dependencies.

sudo apt-get install -y ros-humble-isaac-ros-apriltag

6. Run the following launch files to spin up a demo of this package:

   ros2 launch isaac_ros_apriltag isaac_ros_apriltag.launch.py
   

7. Open a second terminal inside the docker container:

   cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
     ./scripts/run_dev.sh
   

8. Run the rosbag file to simulate an image stream:

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

9. Open a third terminal inside the docker container:

   cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
     ./scripts/run_dev.sh
   

10. Observe the AprilTag detection output /tag_detections on a separate terminal with the command:

    ros2 topic echo /tag_detections
    

Note

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.

Try More Examples

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

• Tutorial with a USB camera
• Tutorial with Isaac Sim
• Tutorial with Argus Camera
• Tutorial with Zed Camera
• Tutorial with NITROS ROS 1 Bridge

Troubleshooting

Isaac ROS Troubleshooting

For solutions to problems with Isaac ROS, please check here.

API

Usage

ros2 launch isaac_ros_apriltag isaac_ros_apriltag.launch.py

Replacing apriltag_ros with isaac_ros_apriltag

1. 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.

2. 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

ROS Parameters

ROS Parameter	Type	Default	Description
size	double	0.22	The tag edge size in meters, assuming square markers. More details here. E.g. 0.22
max_tags	int	64	The maximum number of tags to be detected. E.g. 64
tile_size	uint	4	Tile/window size used for adaptive thresholding in pixels. E.g. 4

ROS Topics Subscribed

ROS Topic	Interface	Description
image	sensor_msgs/Image	The input camera stream.
camera_info	sensor_msgs/CameraInfo	The input camera intrinsics stream.

ROS Topics Published

ROS Topic	Type	Description
tag_detections	isaac_ros_apriltag_interfaces/AprilTagDetectionArray	The detection message array.
tf	tf2_msgs/TFMessage	Pose of all detected AprilTags (TagFamily:ID) w.r.t to the camera topic frame_id.