Skip to content

Vision

Vision is an odometry measurement source, not a magic correction layer. The template accepts good AprilTag pose estimates, rejects suspicious ones, logs both, and never silently changes drive behavior because a camera is disconnected or an estimate was rejected.

Configure camera names

Camera names in VisionConstants must exactly match PhotonVision. Capitalization and spaces matter.

If PhotonVision says the camera is named front-left, the code should say front-left. Do not rename cameras casually after calibration; logs and dashboards become harder to compare.

Configure robot-to-camera transforms

Each camera transform is measured from the robot coordinate frame to the camera coordinate frame.

Measure:

  • X offset from robot center, meters
  • Y offset from robot center, meters
  • Z height, meters
  • roll
  • pitch
  • yaw

Use WPILib's coordinate convention. If the camera appears to localize the robot on the wrong side of a tag, check yaw and transform signs before changing estimator trust.

Camera calibration

Calibrate cameras in PhotonVision before trusting AprilTag localization. A rough calibration might find tags, but it will not produce reliable field poses.

A good calibration workflow:

  1. Mount the camera rigidly.
  2. Focus and expose it for the real field lighting.
  3. Calibrate in PhotonVision with the intended resolution.
  4. Confirm tag detections at realistic distances.
  5. Verify the robot pose in sim or on a marked field.
  6. Only then tune standard deviations.

If the camera mount moves, recalibrate or at least remeasure the transform.

Pose filtering

The vision subsystem logs all candidate robot poses, then splits them into accepted and rejected observations.

Rejection can happen because of conditions such as:

  • pose outside the field
  • impossible Z position
  • too few tags
  • high ambiguity
  • invalid tag layout result

Rejected observations are diagnostics. They should not block drive commands or trigger hidden navigation behavior.

Standard deviation tuning

The estimator trust is scaled by tag distance, tag count, observation type, and per-camera factors. Tune after:

  • odometry is sane
  • wheel radius is validated
  • camera transforms are measured
  • PhotonVision calibration is complete
  • tag layout is correct

Start with conservative trust. A noisy camera should not drag a good odometry estimate around the field.

Simulation

PhotonVision simulation is included so you can test:

  • camera plumbing
  • timestamped pose fusion
  • accepted/rejected pose logging
  • autonomous and navigation code that depends on robot pose
  • replay-safe behavior

Simulation is not a substitute for camera calibration. It proves that code paths work; it does not prove the real camera is mounted or exposed correctly.

Alerts and dashboard topics

Disconnected camera alerts are shown through WPILib alerts and logged through AdvantageKit.

Useful logged topics include:

  • Robot/Vision/Camera0/Connected
  • Robot/Vision/Camera1/Connected
  • Vision/Camera0/RobotPosesAccepted
  • Vision/Camera0/RobotPosesRejected
  • Vision/Summary/RobotPosesAccepted
  • Vision/Summary/RobotPosesRejected

Use AdvantageScope for detailed review. Use Elastic or another NT4 dashboard for quick driver-facing status.

Common vision mistakes

  • Trusting vision before drivetrain odometry is correct.
  • Measuring camera transforms from a bumper corner instead of robot center.
  • Changing camera resolution after calibration.
  • Treating camera disconnect as a reason to change drive behavior.
  • Hiding rejected estimates instead of logging them.
  • Using direct NetworkTables publishers for telemetry aliases instead of AdvantageKit outputs.