AprilTag detection

An AprilTag is a high-contrast printed marker with a machine-readable pattern. The FTC SDK can identify tags and estimate their pose relative to a camera. That estimate can help localization, but it is still a measurement: a blurry tag, a wrong tag size, poor camera calibration, or confusing the camera pose with the robot pose can lead to a bad decision.

SDK version

The code that reads detections changed in FTC SDK 12.0. This matters especially for the current BIOBUZZ season: the official FTC documentation says BIOBUZZ has four AprilTag clusters and no standalone tags.

In SDK 12.0 and later, getDetections() can return either:

• AprilTagSingleDetection, which has an id field; or
• AprilTagClusterDetection, which has cluster metadata and a cluster name, but no .id field.

The common parent type is AprilTagDetection. Pose fields such as ftcPose are on that parent and can be read for either type. Do not copy older code that reads detection.id directly from every result.

Processor setup

Make the processor before building VisionPortal. This convenience method uses the FTC SDK defaults:

AprilTagProcessor aprilTag = AprilTagProcessor.easyCreateWithDefaults();

val aprilTag = AprilTagProcessor.easyCreateWithDefaults()

The default game library is supplied by the FTC SDK. If you need custom tags or processor settings, use the current FTC sample and Builder documentation rather than adding old-season IDs by hand.

Camera setup

VisionPortal portal = new VisionPortal.Builder()
    .setCamera(hardwareMap.get(WebcamName.class, "Webcam 1"))
    .addProcessor(aprilTag)
    .build();

val portal = VisionPortal.Builder()
    .setCamera(hardwareMap.get(WebcamName::class.java, "Webcam 1"))
    .addProcessor(aprilTag)
    .build()

As with any VisionPortal setup, Webcam 1 must match the configured hardware name. Keep the preview open during INIT so you can see whether a marker is being detected before the robot moves.

Detection types

The Driver Hub preview below shows the processor finding BIOBUZZ AprilTag clusters in a real camera image. The colored boxes and labels are the detections overlaid on the frame. In the next step, you will read each detection from code.

This is a real FTC camera preview with the detected BIOBUZZ clusters labeled. The labels show recognition; the telemetry example below shows how your OpMode reads the measurements. Use your own live preview to verify detections before the robot acts.

Reading detections

The SDK gives you a list because the camera can see more than one detection at a time. In SDK 12, check whether each result is a single tag or a cluster before reading type-specific information:

List<AprilTagDetection> detections = aprilTag.getDetections();

for (AprilTagDetection detection : detections) {
    if (detection instanceof AprilTagSingleDetection) {
        AprilTagSingleDetection single = (AprilTagSingleDetection) detection;
        telemetry.addData("Single tag ID", single.id);
        if (single.metadata != null) {
            telemetry.addData("Tag name", single.metadata.name);
        }
    } else if (detection instanceof AprilTagClusterDetection) {
        AprilTagClusterDetection cluster = (AprilTagClusterDetection) detection;
        telemetry.addData("Cluster", cluster.metadata.name);
        telemetry.addData("Visible cluster", "%d%%", cluster.percentClusterFound);
    }

    if (detection.ftcPose != null) {
        telemetry.addData("XYZ (in)", "%.1f, %.1f, %.1f",
            detection.ftcPose.x, detection.ftcPose.y, detection.ftcPose.z);
        telemetry.addData("Pitch / Roll / Yaw (deg)", "%.1f / %.1f / %.1f",
            detection.ftcPose.pitch, detection.ftcPose.roll, detection.ftcPose.yaw);
        telemetry.addData("Range (in)", "%.1f", detection.ftcPose.range);
        telemetry.addData("Bearing (deg)", "%.1f", detection.ftcPose.bearing);
        telemetry.addData("Elevation (deg)", "%.1f", detection.ftcPose.elevation);
    }
}

val detections: List<AprilTagDetection> = aprilTag.detections

for (detection in detections) {
    when (detection) {
        is AprilTagSingleDetection -> {
            telemetry.addData("Single tag ID", detection.id)
            detection.metadata?.let { telemetry.addData("Tag name", it.name) }
        }
        is AprilTagClusterDetection -> {
            telemetry.addData("Cluster", detection.metadata.name)
            telemetry.addData("Visible cluster", "%d%%", detection.percentClusterFound)
        }
    }

    detection.ftcPose?.let { pose ->
        telemetry.addData("XYZ (in)", "%.1f, %.1f, %.1f", pose.x, pose.y, pose.z)
        telemetry.addData("Pitch / Roll / Yaw (deg)", "%.1f / %.1f / %.1f",
            pose.pitch, pose.roll, pose.yaw)
        telemetry.addData("Range (in)", "%.1f", pose.range)
        telemetry.addData("Bearing (deg)", "%.1f", pose.bearing)
        telemetry.addData("Elevation (deg)", "%.1f", pose.elevation)
    }
}

Add these imports when using the example in a Java OpMode:

import java.util.List;
import org.firstinspires.ftc.vision.apriltag.AprilTagDetection;
import org.firstinspires.ftc.vision.apriltag.AprilTagSingleDetection;
import org.firstinspires.ftc.vision.apriltag.AprilTagClusterDetection;

import org.firstinspires.ftc.vision.apriltag.AprilTagDetection
import org.firstinspires.ftc.vision.apriltag.AprilTagSingleDetection
import org.firstinspires.ftc.vision.apriltag.AprilTagClusterDetection

The code has a reason for each check:

1. getDetections() obtains the processor's current list.
2. instanceof tells Java which kind of detection it is handling.
3. A single-tag ID is read only after casting to AprilTagSingleDetection.
4. Cluster name and visibility are read only after casting to AprilTagClusterDetection.
5. Pose is read from the parent result type because both kinds of detection can have ftcPose.

If your project uses SDK 11 or earlier, this code will not compile because the cluster classes do not exist in that version. Use the samples and API docs that match your project's FTC SDK version.

Pose coordinates

ftcPose describes the detected target relative to the camera lens. In the FTC frame, Y points forward out of the lens, X points right, and Z points up. If a tag is left of the camera centerline, its X value is negative. Those translations and range use the processor's configured output distance unit (inches by default), independently of the tag metadata's units. AprilTagProcessor.Builder.setOutputUnits() configures distance and angle units; the default angle unit is degrees (normally inches for FTC field tags). The rotations are in degrees with the processor's default settings; their signs follow the FTC axes and right-hand rule.

The names are easy to mix up, so connect each value to a question:

Pitch, roll, and yaw names are the FTC SDK's mapping to its camera axes; do not assume another robotics library uses the same frame or angle naming. Bearing answers “which way should I turn to point at the center?” Yaw answers “how is the tag face rotated?” A tag can have near-zero bearing but nonzero yaw when it is centered in the image but turned sideways.

A cluster can report a target point placed somewhere useful in its group layout, rather than at the center of any printed marker. The official BIOBUZZ cluster guidance explains that the HIVE CELL cluster pose is designed to point toward the CELL opening. Do not substitute the center of one visible tag for the cluster pose.

Pose quality depends on the tag size and camera calibration. Check the current field tag layout and game manual before assuming a location or meaning. Do not use a stale detection after the camera no longer sees the target.

Detection testing

1. Put the robot on blocks or leave the drivetrain disabled.
2. Run the SDK's ConceptAprilTag sample that matches your SDK version.
3. Keep the OpMode in INIT and open Camera Stream.
4. Move a printed tag or cluster through the image and watch the detection name, range, and bearing.
5. Hide the target. Confirm your program handles an empty detection list.
6. Test the actual robot camera placement and real field lighting before using measurements for localization.

Common mistakes