isaac_ros_apriltag

Source code available on GitHub.

Quickstart

Set Up Development Environment

1. Set up your development environment by following the instructions in getting started.

2. (Optional) Install dependencies for any sensors you want to use by following the sensor-specific guides.

   Note

   We strongly recommend installing all sensor dependencies before starting any quickstarts. Some sensor dependencies require restarting the development environment during installation, which will interrupt the quickstart process.

Download Quickstart Assets

1. Download quickstart data from NGC:

   Make sure required libraries are installed.

   sudo apt-get install -y curl jq tar
   

   Then, run these commands to download the asset from NGC:

   NGC_ORG="nvidia"
   NGC_TEAM="isaac"
   PACKAGE_NAME="isaac_ros_apriltag"
   NGC_RESOURCE="isaac_ros_apriltag_assets"
   NGC_FILENAME="quickstart.tar.gz"
   MAJOR_VERSION=4
   MINOR_VERSION=0
   VERSION_REQ_URL="https://catalog.ngc.nvidia.com/api/resources/versions?orgName=$NGC_ORG&teamName=$NGC_TEAM&name=$NGC_RESOURCE&isPublic=true&pageNumber=0&pageSize=100&sortOrder=CREATED_DATE_DESC"
   AVAILABLE_VERSIONS=$(curl -s \
       -H "Accept: application/json" "$VERSION_REQ_URL")
   LATEST_VERSION_ID=$(echo $AVAILABLE_VERSIONS | jq -r "
       .recipeVersions[]
       | .versionId as \$v
       | \$v | select(test(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+$\"))
       | split(\".\") | {major: .[0]|tonumber, minor: .[1]|tonumber, patch: .[2]|tonumber}
       | select(.major == $MAJOR_VERSION and .minor <= $MINOR_VERSION)
       | \$v
       " | sort -V | tail -n 1
   )
   if [ -z "$LATEST_VERSION_ID" ]; then
       echo "No corresponding version found for Isaac ROS $MAJOR_VERSION.$MINOR_VERSION"
       echo "Found versions:"
       echo $AVAILABLE_VERSIONS | jq -r '.recipeVersions[].versionId'
   else
       mkdir -p ${ISAAC_ROS_WS}/isaac_ros_assets && \
       FILE_REQ_URL="https://api.ngc.nvidia.com/v2/resources/$NGC_ORG/$NGC_TEAM/$NGC_RESOURCE/\
   versions/$LATEST_VERSION_ID/files/$NGC_FILENAME" && \
       curl -LO --request GET "${FILE_REQ_URL}" && \
       tar -xf ${NGC_FILENAME} -C ${ISAAC_ROS_WS}/isaac_ros_assets && \
       rm ${NGC_FILENAME}
   fi
   

Setup Jetson device

Setting up Jetson for using VPI. See here

Build isaac_ros_apriltag

Binary PackageBuild from Source

1. Activate the Isaac ROS environment:

   isaac-ros activate
   

2. Install the prebuilt Debian package:

   sudo apt-get update
   

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

Run Launch File

RosbagRealSense CameraZED Camera

1. Continuing inside the Isaac ROS environment, install the following dependencies:

   sudo apt-get update
   

   sudo apt-get install -y ros-jazzy-isaac-ros-examples
   

2. Run the following launch file to spin up a demo of this package using the quickstart rosbag:

   ros2 launch isaac_ros_examples isaac_ros_examples.launch.py launch_fragments:=apriltag interface_specs_file:=${ISAAC_ROS_WS}/isaac_ros_assets/isaac_ros_apriltag/quickstart_interface_specs.json
   

3. Open a second terminal and activate the Isaac ROS environment:

   isaac-ros activate
   

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

   ros2 bag play -l ${ISAAC_ROS_WS}/isaac_ros_assets/isaac_ros_apriltag/quickstart.bag --remap image:=image_rect camera_info:=camera_info_rect
   

Visualize Results

1. Open a new terminal and activate the Isaac ROS environment:

   isaac-ros activate
   

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

   ros2 topic echo /tag_detections
   

Note

You must 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 calibration 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

Troubleshooting

Isaac ROS Troubleshooting

For solutions to problems with Isaac ROS, see troubleshooting.

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

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. For example, 0.22
max_tags	int	64	The maximum number of tags to be detected. For example, 64
tile_size	uint	4	Tile/window size used for adaptive thresholding in pixels. For example, 4
tag_family	string	tag36h11	Tag family to detect. CUDA backend only supports tag36h11. CPU and PVA backends support tag36h11, tag16h5, tag25h9, tag36h10, tag36h11, circle21h7, circle49h12, custom48h12, standard41h12, standard52h13
backends	string	CUDA	Backend to perform detection with. Options include CPU, CUDA, PVA

ROS Topics Subscribed

ROS Topic	Interface	Description
image	sensor_msgs/Image	Input image.
camera_info	sensor_msgs/CameraInfo	CameraInfo for input image.

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.