Skip to main content

AprilTag Detection

The AprilTag Detection action identifies and reads AprilTag visual markers in video streams or images. This is commonly used for identifying authorized personnel, tracking assets, or verifying credentials.

Overview​

AprilTags are special square patterns that can be printed and attached to badges, equipment, or any surface. Each tag has a unique ID number that can be read by a camera. Think of them as advanced barcodes that are designed specifically for camera systems.

This action scans images for these tags and can determine:

  • Which tag IDs are present
  • Whether those IDs are on your "authorized" list
  • The distance and orientation of the tag (with proper calibration)

What It Does​

1. Scans for Tags​

The action examines the video frame or image looking for the distinctive AprilTag patterns. It can find multiple tags in a single image.

2. Reads Tag IDs​

Each AprilTag has a unique numerical ID (e.g., Tag #1, Tag #5, Tag #42). The action extracts this ID and makes it available for further processing.

3. Authorization Check​

If you've configured a list of "Authorized IDs," the action compares the detected tag against this list. This allows workflows to branch based on whether the person is authorized.

4. Region of Interest (Optional)​

When chained after a person detection action, AprilTag Detection can focus on a specific area—such as where a badge would typically be worn (chest area). This reduces false positives from tags in the background.

Configuration Options​

ParameterTypeRequiredDefaultDescription
Authorized IDsListNoNoneList of Tag IDs considered "authorized" (e.g., 1, 2, 5, 10)
Marker ID MinNumberNo0Minimum Tag ID to accept
Marker ID MaxNumberNo50Maximum Tag ID to accept
Camera MatrixTextNoNoneCamera intrinsic parameters for accurate pose estimation
Tag SizeNumberNoNonePhysical size of the tag in meters (required for distance calculation)

About Authorized IDs​

You can specify authorized IDs in two ways:

  • As a list: Enter multiple numbers separated by commas (e.g., 1, 5, 10, 15)
  • As a range: Use Marker ID Min and Max to accept all tags within a range

Understanding Results​

ResultMeaningTypical Next Step
success_authorizedA tag was found AND it IS in the authorized listEnd workflow (access granted) or log entry
success_unauthorizedA tag was found but it is NOT in the authorized listCreate violation, alert security
no_tag_foundNo AprilTags were detected in the imageCreate violation (no badge visible) or request manual check
failedAn error occurred during processingCheck configuration and image quality

Common Use Cases​

Access Control Verification​

  1. Run Object Detection to detect a person at a restricted entrance
  2. Run AprilTag Detection on the cropped person image
  3. If authorized → Log entry and allow access
  4. If unauthorized or no tag → Create violation and alert security

Asset Tracking​

  1. Configure cameras overlooking equipment storage
  2. Run AprilTag Detection to identify which assets are present
  3. Compare against expected inventory
  4. Flag missing or misplaced items

Visitor Identification​

  1. Issue temporary badges with unique AprilTag IDs to visitors
  2. Configure cameras at key checkpoints
  3. Track visitor movement through the facility
  4. Ensure visitors stay in permitted areas

Troubleshooting​

No Tags Detected When Tags Are Present​

  1. Check Image Resolution: AprilTags need sufficient resolution to be readable. If the tag appears small in the frame, consider zooming in or using a higher resolution camera.

  2. Verify Lighting: Tags need even lighting without harsh shadows or glare. Reflective badge holders can cause problems.

  3. Check Tag Quality: Ensure printed tags are clear and undamaged. Faded or wrinkled tags may not be readable.

  4. Verify Tag Family: ResEngine uses the standard AprilTag 36h11 family. Ensure your printed tags are from this family.

  5. Adjust ID Range: If using Marker ID Min/Max, ensure your tags fall within the configured range.

Wrong Tag IDs Detected​

  1. Check for Duplicate Tags: Ensure no two people/assets have the same tag ID.

  2. Verify Printing: Re-print tags if they appear distorted or have printing errors.

  3. Reduce Detection Range: Narrow the Marker ID Min/Max range to exclude unexpected IDs.

False Positives (Tags Detected Where None Exist)​

  1. Narrow ID Range: Reduce Marker ID Max to reject high-numbered false detections.

  2. Chain After Person Detection: Only run AprilTag detection on cropped person images, not full frames, to avoid detecting background patterns.

  3. Check Environment: Some geometric patterns (tiles, artwork) can be mistaken for tags. Adjust zones to exclude these areas.

Distance/Pose Estimation Not Working​

  1. Provide Camera Matrix: Accurate pose estimation requires camera calibration data (intrinsic parameters).

  2. Set Tag Size: Physical tag dimensions must be configured for distance calculations.

  3. Check Tag Orientation: Tags must be roughly facing the camera for reliable pose estimation.

Technical Notes​

  • Tag Family: ResEngine uses the AprilTag 36h11 family, which provides good error correction and a large number of unique IDs.

  • Processing Speed: AprilTag detection is computationally lightweight and can process frames quickly.

  • Multiple Tags: The action can detect and read multiple tags in a single image, returning all found IDs.

  • Robustness: AprilTags are designed to be readable even when partially obscured, rotated, or viewed at an angle.