Merge branch 'main' into android

.github/workflows/link-check.yaml

@@ -22,12 +22,12 @@ jobs:
         run: pip install -r docs/requirements.txt
 
       - name: link-check
-        run: make -C docs/ linkcheck SPHINXOPTS="-W --keep-going -n -q"
+        run: make -C docs/ linkcheckdiff SPHINXOPTS="-W --keep-going -n -q"
 
       - name: Arhive Log
         if: ${{ failure() }}
         uses: actions/upload-artifact@v4
         with:
           name: LINKCHECK--1
-          path: docs/build/linkcheck/output.txt
+          path: docs/build/linkcheckdiff/output.json
           retention-days: 7

.github/workflows/pull-request.yaml

@@ -133,6 +133,7 @@ jobs:
           if unzip -t linkcheck.zip >/dev/null 2>&1; then
               unzip -q linkcheck.zip -d linkcheck_contents
               echo "Successfully downloaded and unzipped previous LINKCHECK artifact"
+              mv linkcheck_contents/output.json docs/main-output.json
           else
               echo "Downloaded file is not a valid zip. Skipping unzip."
               rm linkcheck.zip
@@ -141,38 +142,14 @@ jobs:
 
       - name: link-check
         run: |
-          make -C docs/ linkcheck SPHINXOPTS="-W --keep-going -n -q" || true
-        
-      - name: Compare outputs
-        run: |
-          echo "Archived Errors"
-          cat linkcheck_contents/output.txt
-          echo "PR Errors"
-          cat docs/build/linkcheck/output.txt
-
-          if [ -f linkcheck_contents/output.txt ]; then
-            sort linkcheck_contents/output.txt > old_sorted.txt
-            sort docs/build/linkcheck/output.txt > new_sorted.txt
-            new_errors=$(comm -13 old_sorted.txt new_sorted.txt)
-            if [ -n "$new_errors" ]; then
-              echo "New errors found:"
-              echo "$new_errors"
-              exit 1
-            else
-              echo "No new errors found."
-            fi
-          else
-            echo "No previous output.txt found. Treating all current errors as new."
-            cat docs/build/linkcheck/output.txt
-            [ -s docs/build/linkcheck/output.txt ] && exit 1 || exit 0
-          fi
+          make -C docs/ linkcheckdiff SPHINXOPTS="-W --keep-going -n -q"
 
       - name: Archive Log
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: LINKCHECK-PR-${{ github.event.number }}-${{ github.run_attempt }}
-          path: docs/build/linkcheck/output.txt
+          path: docs/build/linkcheckdiff/output.json
           retention-days: 7
 
   image-check:

docs/requirements.txt

@@ -10,3 +10,4 @@ sphinx-sitemap==2.3.0
 python-git-info==0.8.3
 sphinxcontrib-mermaid==0.9.2
 sphinxext-rediraffe==0.2.7
+git+https://github.com/FIRST-Tech-Challenge/ftcdocs-helper@main#subdirectory=linkcheckdiff

docs/source/color_processing/color-blob-concepts/color-blob-concepts.rst

@@ -0,0 +1,147 @@
+Color Blob Concepts
+===================
+
+Color Blobs
+-----------
+
+An image can be evaluated by its **groupings of similar colors**.
+
+The smallest unit of any digital image is a **pixel**: a tiny square of one
+particular color.
+
+Each grouping or cluster of similar-colored pixels is called a **Blob**, which
+can be irregular in size and shape.
+
+Forming a Blob is done automatically by the software.  It seeks pixels of
+similar color that are **contiguous** -- touching each other along an edge, not
+just at a corner.  
+
+.. figure:: images/10-Blobs-formation.png
+   :width: 75%
+   :align: center
+   :alt: Blob Formation Visualization
+
+   Blob Formation Visualization
+
+There are 9 Blobs here, not 4.  Some are very small, just one pixel each.
+
+The 5 pixels at top right, for example, are not contiguous (edges joined), so
+they are not joined to form a larger Blob.
+
+The above simple example has only 2 colors: black and white.  For FTC, the
+definition of "similar" colors is a range specified by you.
+
+.. figure:: images/20-Blobs-red-chair.png
+   :width: 75%
+   :align: center
+   :alt: Defining Blobs from an image of a red chair
+
+   Blobs from a Red Chair image
+
+In the above example, the chair surfaces are not **exactly** the same shade of
+red.  But with a **target** definition "close to red" or "mostly red", the
+software can form reasonable Blobs for further processing.
+
+Color Processing
+----------------
+
+Now let's point the camera at an INTO THE DEEP game element called a
+**Sample**.
+
+.. figure:: images/30-Blobs-blue-basic.png
+   :width: 75%
+   :align: center
+   :alt: Detecting Blob from a Blue SAMPLE
+
+   Blob from a Blue SAMPLE
+
+Here the software was told to seek shades of blue.  The orange rectangle
+encloses a Blob of blue color.
+
+But why doesn't the rectangle enclose the entire game piece?  The software is
+processing only a certain **Region of Interest** or ROI.  That's the white
+rectangle; its size and location are specified by you.
+
+Anything outside the ROI will not be considered part of any Blob that is
+detected.  This can help you avoid detecting (unwanted) background objects.
+
+In the example above, the Blob was actually outlined in teal (blue-green
+color), very hard to see.  Let's try another image:
+
+.. figure:: images/40-Blobs-single.png
+   :width: 75%
+   :align: center
+   :alt: Finding Teal Outline
+
+   Teal Outline of Blue Blob
+
+Now the teal outline of the blue Blob can be seen.  Its shape is irregular,
+which can be difficult for your OpMode to evaluate.
+
+boxFit Rectangles
+-----------------
+
+The orange rectangle is drawn automatically by OpenCV, to give your OpMode a
+simpler geometric shape that represents the Blob.  It's not **exactly** like
+the actual Blob, but hopefully still useful.
+
+The orange rectangle, called the **boxFit**, fits tightly around the extreme
+edges of the Blob.  The boxFit is **not** required to stay inside the Region of
+Interest.  In the above case, the best-fitting rectangle happens to stay inside
+the ROI.
+
+But here's another case:
+
+.. figure:: images/50-Blobs-tilted.png
+   :width: 75%
+   :align: center
+   :alt: Showing Boxfit position
+
+   New boxFit position
+
+Look very closely for the teal outline of the Blob, with its very rough lower
+edge.
+
+Here, the best-fitting rectangle (boxFit) is **tilted**, and is not contained
+inside the ROI.
+
+OpenCV provides all data for the boxFit, including its corner points, size, and
+tilt angle.  It can even provide a fitted horizontal version of the boxFit
+rectangle, if you prefer not to handle a tilted boxFit.
+
+Now things get a bit more complicated:
+
+.. figure:: images/60-Blobs-two.png
+   :width: 75%
+   :align: center
+   :alt: Detecting two blobs
+
+   Detecting two blobs
+
+OpenCV detected **two Blobs**, each with a teal outline and each with a boxFit.
+
+Your OpMode will need to "decide" which boxFit is important and which to
+ignore.  Fortunately, OpenCV provides tools to **filter out** certain unwanted
+results.  After filtering, your OpMode can **sort** the remaining results, to
+focus on the highest priority.
+
+With these tools, your OpMode could handle even a "busy" result like this one:
+
+.. figure:: images/70-Blobs-many.png
+   :width: 75%
+   :align: center
+   :alt: Many blob detections
+
+   Many Blob Detections
+
+Your programming tasks will include:
+
+* determine which boxFit is most relevant,
+* evaluate its data, and
+* take robot action accordingly.
+
+Now try the Sample OpMode for the :doc:`Color Locator <../color-locator-discover/color-locator-discover>` processor.
+
+============
+
+*Questions, comments and corrections to [email protected]*