Vision troubleshooting

When vision fails, change one thing at a time. Check that the camera opens and the processor receives an image before tuning detection. That order makes it easier to find the step that is failing.

Camera opening failures

Check the hardware before editing image-processing code:

1. In the Robot Controller configuration, confirm the webcam is present and its name matches the code exactly, including spaces and capitalization.
2. Reseat the USB cable and try the webcam on its own. Multiple USB devices or a weak connection can make camera startup unreliable.
3. Start the OpMode and read the Robot Controller log for the first camera error. A blank preview by itself does not tell you whether the name, connection, or camera startup failed.
4. If using VisionPortal, temporarily remove extra processors and start with one. If using EasyOpenCV, wait for the asynchronous open callback before calling startStreaming.

For VisionPortal, this is the smallest useful camera setup. webcamName must come from the configured name in the first step.

VisionPortal portal = new VisionPortal.Builder()
    .setCamera(webcamName)
    .build();

val portal = VisionPortal.Builder()
    .setCamera(webcamName)
    .build()

After that camera-only test, close it and rebuild the portal with a processor supplied to its Builder. Use the VisionPortal setup guide for the full lifecycle and shutdown steps.

Missing preview

Ask these questions in order:

1. Did the camera open? Check the log or the EasyOpenCV open callback. If it did not, return to the previous section.
2. Is the preview enabled? VisionPortal live view can be disabled in its builder. EasyOpenCV’s local Robot Controller preview needs a monitor view; the Driver Station Camera Stream is separate.
3. Is the camera pointed at a lit scene? Covering the lens or pointing it into darkness can look like a software failure.
4. Does a simple pass-through pipeline or empty processor work? If it does, the camera path is sound and the problem is in later processing.

Avoid changing camera resolution, exposure, and detection thresholds at the same time. Otherwise, you will not know which change helped.

Missing detections

Start with a target that is large, close, and easy to distinguish. Then inspect each stage:

1. Can you see the target in the preview? Fix framing and lighting first.
2. Is the processor enabled? VisionPortal processors can be enabled or disabled while the portal runs.
3. Does the color mask contain pixels? In a custom OpenCV pipeline, show the mask or report the percentage of nonzero pixels. Remember that the expected channel order depends on the input frame; FTC EasyOpenCV commonly supplies RGBA frames, so do not label it RGB without checking.
4. Is the region of interest over the target? Temporarily use the whole frame to check. Reintroduce a smaller region after detection works.
5. Are filters excluding it? Temporarily remove area, density, and aspect-ratio limits. Add them back one at a time after you can see candidate detections.
6. Are the color limits based on the robot camera? Tune them from the actual camera under the expected field lighting. A screenshot or simulator image may have different exposure and color response.

For the FTC SDK ColorBlobLocatorProcessor, area and density filters take a minimum and a maximum followed by the blob list:

ColorBlobLocatorProcessor.Util.filterByArea(minArea, maxArea, blobs);
ColorBlobLocatorProcessor.Util.filterByDensity(minDensity, maxDensity, blobs);

ColorBlobLocatorProcessor.Util.filterByArea(minArea, maxArea, blobs)
ColorBlobLocatorProcessor.Util.filterByDensity(minDensity, maxDensity, blobs)

Use values measured from your own preview. A density value is a ratio from 0 to 1; it is not a guarantee that the object is the right game element.

Intermittent detections

Small changes in lighting, camera movement, or object position can move a target across a threshold. Before adding code to smooth the result:

• secure the camera mount and use steady lighting;
• make sure the target is not right at the edge of the frame or region of interest;
• record the reported center and size for several seconds;
• widen a threshold slightly only if the extra detections are still safe to reject.

If the robot should act only after several matching frames, add a simple confirmation counter. Reset it when detection is lost, and keep the robot stopped until the count reaches the chosen threshold. This is temporal confirmation, not a replacement for correct calibration.

Incorrect AprilTag pose

First separate which target was detected from how its pose is interpreted:

1. Check the official season tag layout and confirm that your code handles the detection type used by that game. Some seasons use AprilTag clusters; a cluster is not the same object as an individually identified tag.
2. Confirm the physical tag size and units match the processor setup.
3. Check the camera mounting direction and the coordinate axes shown by the FTC SDK. Do not swap camera-relative pose values with field coordinates: localization requires a known camera pose on the robot and a known target pose on the field.
4. Test from a short distance with the camera close to facing the target. Move farther away or add angled views only after the basic result makes sense.
5. Treat the pose as an estimate. Blur, oblique views, calibration, and distance all affect accuracy.

For this season’s target type and pose details, use the AprilTag guide.

Processing load

Keep camera work away from the drive-control loop where possible. Try these changes one at a time:

1. Disable processors the OpMode does not need.
2. Lower the camera resolution and compare the frame rate.
3. Reduce expensive per-frame operations; reuse OpenCV Mat objects instead of allocating new ones for every frame.
4. Measure processing time before and after a change. Do not skip frames until you know processing load is the cause.

For custom EasyOpenCV code, release any Mat you create or obtain with submat() when you are done with it. Do not release the camera-owned input frame. For VisionPortal, prefer the SDK processor examples and their lifecycle rather than mixing EasyOpenCV callbacks into a VisionPortal processor.

Debugging checklist

• The configured camera name matches the code.
• The camera opens without a logged error.
• The preview shows a bright, stable image.
• A simple processor or pass-through pipeline works.
• The target is visible and inside the region of interest.
• Thresholds and filters are checked one at a time.
• Detection results are observed before they control robot motion.
• The OpMode stops the robot safely when a target is not found.

Next, work through Vision Basics, the VisionPortal guide, or EasyOpenCV pipelines depending on which system your project uses.