What an AprilTag Is

An AprilTag is a specific type of fiducial marker — a printed pattern designed to be uniquely and reliably detected by a camera. The name comes from the University of Michigan team that developed the detection algorithm ("April" was the team's internal project name). The technology is used across robotics, augmented reality, and industrial automation, and FIRST adopted it for FRC starting in the 2023 season.

Unlike a QR code (which stores arbitrary data) or a color target (which requires specific lighting to distinguish), an AprilTag is optimized for one purpose: letting a camera answer two questions simultaneously — "which tag is this?" and "where is this tag relative to my camera?" The design decisions behind every aspect of the tag — the border, the bit matrix, the minimum cell size — flow directly from that dual goal.

Physically, an AprilTag is a printed black-and-white square. In FRC, they're printed at a standard size (6.5 inches for the 36h11 family used in most FRC games) and mounted at known field positions. The field layout file published by FIRST before each season lists the exact 3D pose of every tag on the field. Your robot's code downloads this layout, detects the tags with its camera, and uses the known physical positions to determine where the robot must be on the field to see the tags at those apparent angles and sizes.

AprilTag Anatomy: What Each Zone Does

Every AprilTag has a precise structure. Each zone serves a specific role in the detection pipeline. Click each zone to understand what it contributes and why it must be the way it is.

What a Camera Can Extract from a Single Tag

When a camera detects an AprilTag successfully, the detection pipeline produces more than just an ID number. The four pieces of information below are what make vision-based localization possible.

The Pose Estimation Pipeline

From a raw camera frame to a robot field position, the pipeline passes through five distinct steps. Each one is a potential source of error — and each has different failure modes.

AprilTag Families and the FRC Standard

AprilTags come in several "families" — different grid sizes and encoding schemes that make different tradeoffs between detection range, unique ID count, and error correction. Understanding which family FRC uses and why prevents a class of configuration mistakes.

FRC uses 36h11 as the standard family. The "36" means the full tag including border is 8×8 cells (6×6 data + 1-cell border on each side). The "h11" means a Hamming distance of at least 11 between any two valid IDs — if up to 5 bits in the read bit pattern are corrupted, the algorithm can still identify the tag correctly. This makes it robust to the partial occlusions, lighting variation, and motion blur typical of an FRC match environment.

What Limits Detection in Competition

AprilTag detection is not equally reliable in all conditions. The following factors reduce detection quality, and understanding them informs both camera placement decisions (hardware) and measurement trust decisions (software, covered in Lesson 7).

• Distance. As the robot moves farther from a tag, the tag subtends fewer pixels. Below approximately 10–15 pixels per tag cell, corner detection accuracy degrades significantly. At typical FRC competition distances (2–8 meters), a 6.5-inch tag fills between 10 and 80 pixels per side depending on camera resolution and focal length. Detection is reliable at 3–5 meters, increasingly unreliable beyond 7 meters.
• Angle. A tag viewed at a steep angle (more than ~60° off-normal) appears highly foreshortened. The corner pixel coordinates are compressed along one axis, reducing solvePnP accuracy. A pose estimated from a tag viewed at 75° may have 5–10× more error than the same tag viewed straight-on.
• Motion blur. At a camera exposure of 20 ms and a robot velocity of 3 m/s, the tag moves 6 cm during a single frame — several pixels at competition distances. This smears corner positions and reduces detection confidence. Short exposures (2–5 ms) prevent blur but require brighter illumination or a more sensitive camera.
• Lighting. FRC fields have inconsistent lighting: venue ceiling lights, flashing LEDs from other robots, sunlight through venue skylights, and team-specific robot illumination. High contrast between the tag's black and white cells is required for binary thresholding to work correctly. Very low ambient light or strong directional lighting that washes out contrast both degrade detection.
• Occlusion. If another robot, field element, or the robot's own mechanism partially covers the tag, the detection may fail or produce incorrect corner coordinates. Partial occlusion with fewer than 4 visible corners will fail entirely since solvePnP requires all 4.
• Camera calibration quality. solvePnP uses the camera's intrinsic calibration (focal length, principal point, distortion coefficients) to map pixels to angles. A poorly calibrated camera produces systematically biased pose estimates — the tag appears closer or at a wrong angle regardless of detection quality. Calibration is covered in Lesson 3.

A First Look at the Data Structures

You won't write vision integration code until Lessons 3–6, but understanding the WPILib data types involved now prevents conceptual confusion later. These classes will be referenced throughout the unit.

// The field layout — loaded once, used throughout the match
// AprilTagFieldLayout stores the 3D Pose3d of every tag on the 2025 field
AprilTagFieldLayout fieldLayout =
    AprilTagFields.k2025ReefScapeV2.loadAprilTagLayoutField();

// Get a specific tag's field pose by ID
Optional<Pose3d> tagPose = fieldLayout.getTagPose(5);
// Returns Optional.empty() if that ID isn't in the layout

// A single AprilTag detection result (from PhotonVision, Lesson 3)
PhotonTrackedTarget target;
int    tagId    = target.getFiducialId();          // which tag (1–587)
Transform3d camToTag = target.getBestCameraToTarget(); // camera → tag transform
double ambiguity = target.getPoseAmbiguity();        // 0.0–1.0, lower = more ambiguous

// Transform3d contains both translation and rotation
// Translation3d: distance in each axis (meters)
// Rotation3d: orientation as roll/pitch/yaw (radians)
Translation3d camToTagTranslation = camToTag.getTranslation();
double distanceMeters = camToTagTranslation.getNorm();  // total 3D distance to tag

// Chaining transforms manually (PhotonPoseEstimator does this for you in Lesson 4):
// robotPose = fieldTagPose × tagToCamera × cameraToRobot
Pose3d robotPose = new Pose3d()
    .plus(fieldTagPose.minus(new Pose3d(camToTag)))
    .plus(robotToCameraTransform.inverse());

🔌 System Check

Knowledge Check