🔌 Target Detection API¶

Target Detector API¶

To interact with the Target Detection module, you can refer to the following ROS 2 API:

Actions	Topics
/detect_target	/target_detector/goal
	/target_detector_server/image
	/updated_goal

The target_detector_server implements the main Target Detection functionalities.

To configure it you can refer to the following table containing the target_detector_server’s parameters and their explanation:

Parameter	Description
`detector_frequency`	Frequency at which the detection algorithm is run. Higher frequencies increase responsiveness but require more computational resources.
`action_server_result_timeout`	Timeout for action server results, ensuring that detection attempts do not run indefinitely.
`detector_plugins`	List of plugin names for target detectors to be loaded and used for detection tasks.
`goal_topic`	The topic on which detected poses are published, allowing other components or systems to utilize the detection results.
`detection_time_tolerance`	Tolerance for the time difference between the current time and the time a target was detected, ensuring relevance of detection data.
`accuracy_threshold`	Minimum required accuracy for a detection to be considered successful. Helps filter out false positives or uncertain detections.
`truncate_distance`	Distance used to adjust the target position by shortening the position in a straight line between the reference and the target.
`static_transform`	Homogeneuos transform to be applied on the transform between the reference and the target.
`use_realtime_priority`	Specifies whether the action server should operate with real-time priority, which can be essential for time-sensitive applications but requires appropriate system permissions.

Note

To configure the target_detector_server, you can create your own parameter file and follow the guide in 📔 Navigation Configuration Guide section:

mkdir -p ~/.pal/config
touch ~/.pal/config/99_my_target_detector_server_params.yaml
vi ~/.pal/config/99_my_target_detector_server_params.yaml

Finally, here is a table with the available Target Detection plugins:

Provided Plugin	Package	Description
`simple_target_detector`	Name of the package to which the plugin belongs (`pal_nav2_target_detector`).	Name of the plugin to load (`pal_nav2_target_detector::SimpleTargetDetector`).
`aruco_target_detector`	Name of the package to which the plugin belongs (`pal_nav2_aruco_target_detector`).	Name of the plugin to load (`pal_nav2_aruco_target_detector::ArucoTargetDetector`).
`apriltag_target_detector`	Name of the package to which the plugin belongs (`pal_nav2_apriltag_target_detector`).	Name of the plugin to load (`pal_nav2_apriltag_target_detector::AprilTagTargetDetector`).
`laser_target_detector`	Name of the package to which the plugin belongs (`pal_nav2_laser_target_detector`).	Name of the plugin to load (`pal_nav2_laser_target_detector::LaserTargetDetector`).

In the following sections you can find more information about their confiugration and their own APIs.

Laser Detector API¶

The pal_nav2_laser_target_detector::LaserTargetDetector plugin provides the Laser Target Detection functionalities.

It implements the pal_nav2_core::TargetDetector interface, but it also uses methods coming from the PatternMarcher class, to identify the presence and location of the target pattern within the generated image, based on comparison with a predefined pattern image.

To configure the Laser Target Detection plugin you can refer to the following table containing the LaserTargetDetector’s parameters and their explanation:

Parameter	Description
`patterns_folder`	Directory containing image patterns and the pattern registry for identification purposes.
`detection_threshold`	Threshold for considering a detection successful, based on the accuracy of pattern matching.
`max_laser_range`	Maximum range considered for detection within the laser scan data.
`resolution`	Resolution of the image generated from laser scan data, affecting the precision and performance of detection.

Note

To configure the LaserTargetDetector, you can create your own parameter file and follow the guide in 📔 Navigation Configuration Guide section:

mkdir -p ~/.pal/config
touch ~/.pal/config/99_my_target_detector_server_params.yaml
vi ~/.pal/config/99_my_target_detector_server_params.yaml

And modify the relative section:

/target_detector_server:
  ros__parameters:
    #Other target_detetor_server parameters
    detector_plugins: ["laser_target_detector"]
    laser_target_detector:
      plugin: "pal_nav2_laser_target_detector::LaserTargetDetector"
      base_frame_id: "base_footprint"
      max_laser_range: 2.0
      detection_threshold: 0.5
      #Other laser_target_detector parameters

    #Other detector plugins

ArUco Detector API¶

The pal_nav2_aruco_target_detector::ArucoTargetDetector plugin provides the ArUco Target Detection functionalities.

It implements the pal_nav2_core::TargetDetector interface, but it also uses methods coming from the ArucoDetector class and the ImageFilter class.

To configure the ArUco Target Detection plugin you can refer to the following table containing the ArucoTargetDetector’s parameters and their explanation:

Parameter	Description	Belonging Class
`dictionary`	ArUco marker dictionary selection for detection, tailoring the detector to specific marker sets.	`ArucoTargetDetector`
`image_topic`	ROS topic for image data reception, crucial for marker detection.	`ArucoTargetDetector`
`camera_info_topic`	ROS topic for camera calibration data, essential for accurate pose estimation.	`ArucoTargetDetector`
`image_filter_enable`	Enables/disables image preprocessing, potentially enhancing detection under various conditions.	`ImageFilter`
`threshold`	Binary thresholding value for image preprocessing, aiding in marker-background distinction.	`ImageFilter`
`roi_size`	Region of interest size, focusing detection on specific image areas to improve efficiency.	`ImageFilter`
`detection_mode`	ArUco marker detection mode, balancing detection speed and robustness.	`ArucoDetector`
`corner_refinement_method`	Corner refinement method for marker detection, affecting pose estimation accuracy.	`ArucoDetector`
`marker_size`	Physical marker size, crucial for precise pose estimation.	`ArucoDetector`
`detection_timeout`	Maximum time between detections for consistent tracking, managing marker visibility and stability.	`ArucoDetector`
`correct_fisheye`	Fisheye distortion correction flag, improving accuracy for fisheye lenses.	`ArucoDetector`
`lambda_accuracy`	Reprojection error sensitivity, tuning detection sensitivity and error tolerance.	`ArucoDetector`
`draw_result`	Flag for overlaying detected marker axes on the output image for visualization.	`ArucoDetector`

Note

To configure the ArucoTargetDetector, you can create your own parameter file and follow the guide in 📔 Navigation Configuration Guide section:

mkdir -p ~/.pal/config
touch ~/.pal/config/99_my_target_detector_server_params.yaml
vi ~/.pal/config/99_my_target_detector_server_params.yaml

And modify the relative section:

/target_detector_server:
  ros__parameters:
    #Other target_detetor_server parameters
    detector_plugins: ["aruco_target_detector"]
    aruco_target_detector:
      plugin: "pal_nav2_aruco_target_detector::ArucoTargetDetector"
      detector:
          marker_size: 0.25
      image_topic: "/roof_rgbd_camera/color/image_raw"
      camera_info_topic: "/roof_rgbd_camera/color/camera_info"
      #Other aruco_target_detector parameters

    #Other detector plugins

AprilTag Detector API¶

The pal_nav2_apriltag_target_detector::AprilTagTargetDetector plugin provides the AprilTag Target Detection functionalities.

It implements the pal_nav2_core::TargetDetector interface, but it also uses methods from the AprilTagDetector class and the ImageFilter class.

To configure the AprilTag Target Detection plugin you can refer to the following table containing the AprilTagTargetDetector’s parameters and their explanation:

Parameter	Description	Belonging Class
`image_topic`	ROS topic for image data reception, crucial for marker detection.	`AprilTagTargetDetector`
`camera_info_topic`	ROS topic for camera calibration data, essential for accurate pose estimation.	`AprilTagTargetDetector`
`detection_time_tolerance`	The maximum allowed time tolerance between detections.	`AprilTagTargetDetector`
`accuracy_threshold`	The minimum accuracy threshold for a valid detection.	`AprilTagTargetDetector`
`filter.enable`	Enables or disables image preprocessing.	`ImageFilter`
`filter.threshold`	Binary thresholding value for image preprocessing, aiding in marker-background distinction.	`ImageFilter`
`filter.roi_size.width`	The width of the region of interest (ROI) for image filtering.	`ImageFilter`
`filter.roi_size.height`	The height of the region of interest (ROI) for image filtering.	`ImageFilter`
`detector.family`	AprilTag marker family selection for detection.	`AprilTagDetector`
`detector.tag_size`	Distance between the detection corners in meters, crucial for precise pose estimation.	`AprilTagDetector`
`detector.detection_timeout`	Maximum time in seconds between detections for consistent tracking.	`AprilTagDetector`
`detector.lambda_accuracy`	Reprojection error sensitivity, tuning detection sensitivity and error tolerance.	`AprilTagDetector`
`detector.draw_result`	Flag for overlaying detected marker axes on the output image for visualization.	`AprilTagDetector`
`detector.threads`	Number of threads to use for detection.	`AprilTagDetector`
`detector.decimate`	Decimate value for the detector.	`AprilTagDetector`
`detector.blur`	Blur value for the detector.	`AprilTagDetector`
`detector.refine_edges`	Flag to enable or disable edge refinement.	`AprilTagDetector`
`detector.debug`	Flag to enable or disable debug mode.	`AprilTagDetector`

Note

To configure the AprilTagTargetDetector, you can create your own parameter file and follow the guide in 📔 Navigation Configuration Guide section:

mkdir -p ~/.pal/config
touch ~/.pal/config/99_my_target_detector_server_params.yaml
vi ~/.pal/config/99_my_target_detector_server_params.yaml

And modify the relative section:

/target_detector_server:
  ros__parameters:
    #Other target_detetor_server parameters
    detector_plugins: ["apriltag_target_detector"]
    apriltag_target_detector:
      plugin: "pal_nav2_apriltag_target_detector::AprilTagTargetDetector"
      detector:
          tag_size: 0.306
      image_topic: "/roof_rgbd_camera/color/image_raw"
      camera_info_topic: "/roof_rgbd_camera/color/camera_info"
      #Other apriltag_target_detector parameters

    #Other detector plugins

Simple Detector API¶

The pal_nav2_laser_target_detector::SimpleTargetDetector plugin provides a bridge between any kind of detector that you want to develop, or that you already have available, and the target_detector_server node.