> For the complete documentation index, see [llms.txt](https://docs.raidrobotics.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raidrobotics.org/commands-v3-state-machine/guide/vision.md).

# Vision

The Limelights help the robot know where it is on the field. Every camera frame that shows AprilTags is an offer: "I think the robot is **here**". `subsystems/Vision.java` decides which offers to believe, and hands those to the CTRE drivetrain, which blends them with the wheels and the gyro into one position (`Drive/Pose`).

```mermaid
flowchart TD
    H[Drivetrain heading] --> L[Every Limelight]
    L --> F{FILTERS:<br/>believable?}
    F -- no --> R[Logged with the reason, then dropped]
    F -- yes --> T[TRUST: how much?]
    T --> D["drivetrain.addVisionMeasurement(pose, time, trust)"]
```

These are the 2026 robot's rules, carried over. In 2026 they were written out by hand; LimelightLib 2 now has the same checks built in, so each rule is one line of configuration and the library does the checking.

`Vision` isn't a `Mechanism`: it has no motors, so nothing ever needs to require it.

## The cameras

Each camera is listed in `Constants.Vision.CAMERAS` with its name and where it's mounted:

{% code title="Constants.java" %}

```java
public static final Camera[] CAMERAS = {
    new Camera("limelight-front",
        Inches.of(0.545), Inches.of(0), Inches.of(21.729),
        Degrees.of(0), Degrees.of(33), Degrees.of(0)),
    new Camera("limelight-rear",
        Inches.of(-11.6), Inches.of(0), Inches.of(6.6875),
        Degrees.of(0), Degrees.of(30), Degrees.of(180)),
};
```

{% endcode %}

| Field     | Meaning                                                                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | The camera's hostname (its web page › Settings › Hostname). Must start with `limelight`: RAIDLogs finds Limelights in the log by this name. |
| `forward` | How far the lens is toward the front of the robot (negative = toward the back)                                                              |
| `left`    | How far toward the robot's left (negative = right)                                                                                          |
| `up`      | How far above the floor                                                                                                                     |
| `roll`    | Tilt sideways, almost always 0                                                                                                              |
| `pitch`   | Tilt up from level (positive = looking up)                                                                                                  |
| `yaw`     | Which way it faces: 0 = forward, 90 = left, 180 = backward                                                                                  |

Mounting numbers are measured from the center of the robot at floor height, the same six boxes as the camera's web page (**Settings › Camera Pose in Robot Space**). Setting them in code overrides the web page, so a swapped-in spare camera is right as soon as it has its name.

To add or remove a camera, add or remove a line. Nothing else changes.

`Constants.Vision.TAG_IDS` limits which AprilTags the cameras may use. Empty means all of them. Use it to leave out tags that are unreliable on the season's field.

## MegaTag 1 and MegaTag 2

A Limelight can work out the robot's pose two ways. Pick one with `MODE` at the top of `Vision.java`:

| Mode                  | How                                 | Good                         | Bad                                                            |
| --------------------- | ----------------------------------- | ---------------------------- | -------------------------------------------------------------- |
| `MEGATAG_1` (default) | From the tags alone                 | Needs no help from the robot | One far-away tag can fool it                                   |
| `MEGATAG_2`           | From the tags plus our gyro heading | Steadier                     | Only as good as the gyro, and wrong while the robot spins fast |

Either way, the cameras' **heading** is never used. The gyro is better.

Every loop, `Vision` tells every camera which way the robot faces and how fast it's turning, with one call to `Limelight.setSharedRobotOrientation(...)`. MegaTag 2 needs this.

A Limelight 4 has its own gyro. The template puts it in `INTERNAL_MT1_ASSIST` mode: it uses its own gyro between frames and keeps correcting it from what MegaTag 1 sees. Cameras without a gyro ignore this.

## Filters: is it believable?

An estimate that fails any filter is dropped, and the reason is logged.

| Filter                                      | Value              | Drops estimates...                                       |
| ------------------------------------------- | ------------------ | -------------------------------------------------------- |
| `withMinAvgTagArea`                         | 0.08% of the image | where the tags are too small (too far) to read well      |
| `withMaxAvgTagDistance`                     | 5.0 m              | where the tags are too far away                          |
| `withFieldBounds` + `withFieldBoundsMargin` | field size + 0.5 m | that put the robot outside the field                     |
| MegaTag 1: `withMaxSingleTagAmbiguity`      | 0.2                | from a lone tag that could look the same from two places |
| MegaTag 2: `withMinTagCount`                | 2                  | that see fewer than two tags                             |
| MegaTag 2 only                              | 1 rotation/s       | while the robot spins faster than this                   |

## Trust: how much?

Trust is a **standard deviation** in meters: roughly how far off we expect the estimate to be. Bigger means believe it less. It grows with distance and shrinks with more tags in view:

```
trust = 0.7 × distance^1.2 ÷ tags      but never below 0.3 m or above 6 m

1 tag  at 2 m ─▶ 1.6 m (a nudge)       2 tags at 2 m ─▶ 0.8 m
1 tag  at 4 m ─▶ 3.7 m (barely)        2 tags at 4 m ─▶ 1.8 m
```

The library works out the trust for each frame, and `Vision` passes it straight to `drivetrain.addVisionMeasurement(...)`.

## Every frame counts

A camera can send several frames per robot loop. `Vision` reads every frame that arrived since last time (`readPoseEstimateQueue`), not just the newest, because each one that passes makes the pose better.

## Turning vision off

```java
public Command ignore()
```

`ignore()` is a [request](https://docs.raidrobotics.org/commands-v3-state-machine/concepts/requests.md): it stops believing the cameras for as long as it runs, and starts again when it ends. The robot then knows where it is from the wheels and gyro alone. The cameras keep running and keep being logged, so the log still shows what vision *would* have said.

It's used two ways:

* **The driver's View button** toggles it, for when a camera is clearly wrong in a match.
* **Autos** hold it for the whole autonomous period. See [Autonomous](https://docs.raidrobotics.org/commands-v3-state-machine/guide/autonomous.md#vision-in-autos).

`isTrusted()` says whether the cameras are being used right now.

## Logging

Each camera's raw data is already in the `.wpilog`: it lives in NetworkTables under the camera's name (`/limelight-front/...`), and RobotLog logs all of NetworkTables. What `Vision` logs is what **we** decided:

| Entry                                                            | Meaning                                        |
| ---------------------------------------------------------------- | ---------------------------------------------- |
| `Vision/Mode`                                                    | `MEGATAG_1` or `MEGATAG_2`                     |
| `Vision/Trusted`                                                 | `false` while `ignore()` is running            |
| `Vision/<camera>/Connected`                                      | Whether the camera is answering                |
| `Vision/<camera>/Used`                                           | Whether any frame was used this loop           |
| `Vision/<camera>/Rejection`                                      | Why the newest frame was dropped (`""` = used) |
| `Vision/<camera>/Pose`                                           | The camera's latest estimate                   |
| `Vision/<camera>/Tag Count`, `Avg Tag Distance (m)`, `Trust (m)` | Details of each frame                          |

Rejection reasons come from the library's filters (`TAG_AREA`, `TAG_DISTANCE|FIELD_BOUNDS`, ...) or from `Vision` itself: `no tags`, `turning too fast`, `vision ignored`, `no new frame`, `not connected`. When the robot mis-aims in a match, this is how to tell "vision was wrong" from "vision was ignored".

A dashboard alert, **Limelight not connected**, names any camera that isn't answering.

## Rules for this year's field

Field-specific rules go in `reasonToReject(...)` as more `if ... return "reason"` lines. 2026's was to ignore vision while crossing the bump, where the robot tilts and the cameras see the tags from the wrong angle:

```java
if (Field.inBumpZone(drivetrain.getState().Pose)) return "on the bump";
```

## Before the cameras work on the robot

{% stepper %}
{% step %}

## Name and place each camera

Give each camera its name on its web page, and list it with its mounting position in `Constants.Vision.CAMERAS`.
{% endstep %}

{% step %}

## Upload the field map

Upload the season's AprilTag field map to each camera.
{% endstep %}

{% step %}

## Check them against each other

Drive around with tags in view and compare `Vision/<camera>/Pose` with `Drive/Pose` in AdvantageScope. They should sit on top of each other. If one camera is off, its mounting numbers are wrong.
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.raidrobotics.org/commands-v3-state-machine/guide/vision.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
