Color card detection polygon extending outside of ROI

[joshqsumner]

Describe the bug
When using pcv.transform.detect_color_card the roi argument is used to restrict where chips are found which I think implies that it restricts where the warped image will pull from, but that isn't always true.

• Color card detection happens in one of two helpers, each of which is only called inside of _rect_filter, which forces them to only use the section of the image inside of the ROI. It would seem like this means everything in those functions respects the ROI but it does not force the polygon to only exist in the ROI.
  • chip detection (_find_color_chip_like_objects) happens in the ROI exclusively, only normal problems there.
  • A bounding rectangle is fit to those chips and rotated to "robust pos=3", still only the section of the image in the ROI.
  • cv2.approxPolyN is used to fit a polygon to the corners. This does not have to respect the ROI since the polygon does not know the size of the image, it just takes some points and fits a polygon that can extend anywhere. If the shape is approximately a rectangle then all good, but if it is not then this can get very far off from what we'd expect.
  • I have a few ideas but I don't like any of them much:
    • We could do something like the long answer here and check if absolute value of any angle - 90 is greater than 5 or 10 then warn if it is. I don't think this would be all that helpful actually.
    • What I'd like is to coerce the shape to stay inside the rectangle so we could say that any corner outside of the ROI gets smashed onto the edge of the ROI. That would make the ROI extra useful for really hard detection problems where if we think no chips are going to be detected we could put the ROI just inside the border of the chips (assuming they are oriented about correctly with the camera and that I'm thinking about this correctly). It would probably be reasonable to find half of the angle of that vertex that is off of the image, make a vector in that direction pointed back at the image, then take the new corner to be where that intersects with the edge of the image.

To Reproduce
Steps to reproduce the behavior (including sample data and code really help):

1. Starting with very bad image call detect_color_card with an ROI
2. See error

# Note I am on a branch off of v5, no relevant edits to transform so v5 should demonstrate this well.
from plantcv import plantcv as pcv
img, path, filename = pcv.readimage(filename="mybadimage.jpg")
roi = pcv.roi.rectangle(img, 1175, 1950, 850, 600)
cc_mat = pcv.transform.detect_color_card(img, color_chip_size="passport")

What isn't shown in the debug image is that the polygon converges to a "spike" off screen (since it is constrained to be 4 sided) you can imaging what it looks like.

Expected behavior
Ideally I'd like to force cv2.approxPolyN to only allow a certain range of angles/to take the 4 sided polygon and squash it into frame.

Local environment (please complete the following information):

• OS: [Ubuntu]
• Environment [conda]
• PlantCV Version [e.g. 5.0.0]

Additional context
Add any other context about the problem here.

[Daniiiil1]

I traced this through the v5.0 implementation. The ROI is enforced while _rect_filter runs the detector on the cropped image, but _macbeth_card_detection later applies cv2.approxPolyN to the concatenated chip contours. Since that operation is unconstrained, a fitted corner can leave the crop even though every supporting chip contour is inside it.

I would avoid independently clamping x/y coordinates: that can collapse two vertices, change winding, create a non-convex quad, or produce a poorly conditioned perspective transform.

A safer approach is:

1. Compute an interior anchor from the detected chip centers (or the convex-hull centroid).
2. Preserve the fitted vertex order and project every out-of-ROI corner back along its ray from the anchor to the ROI boundary.
3. Apply a small inward epsilon, then verify four unique points, consistent winding, cv2.isContourConvex, minimum area, and a bounded homography condition.
4. Use the corrected source quad to derive the inner quad, rather than clipping both independently.
5. Add synthetic tests for one-corner and two-corner overflow, a rotated card, a non-zero ROI offset, and a deliberately degenerate fit.

A uniform radial scale of the whole quad would preserve shape most strongly, while per-corner ray clipping would preserve more of the detected card area. Which semantic is intended for ROI here: a hard geometric boundary that may shrink a partially inferred card, or should a card whose fitted quad leaves the ROI be rejected as unreliable? That choice determines whether I would implement projection or an explicit validation error.