docs: image-chapter audit round 2 -- accuracy, links, de-meta

Page-by-page audit continuing through pixel-math, thresholding,
filters, analysis, transforms, finding, decoding, matching, io,
and wrap-up. Accuracy fixes verified against firmware: morphology
threshold semantics (erode tolerates N background neighbours,
dilate needs more than N foreground), AprilTag error correction
(uniform 2-bit, per-family Hamming distance), line results are
attrtuples passed straight to draw_line, blob threshold auto-learn
via histogram percentiles, csi framesize tuples replace stale
sensor.B64X64 constants, ulab bridge is to_ndarray/Image(ndarray)
copies. Figures: frame-diff box widths aligned across panels,
convolution-kernel labels/centering fixed, morphology walkthrough
regenerated with exact 3x3 results. Dropped legacy Haar/keypoint
sections (ML chapter rewired), closing recaps, and forward
references; de-acronymed prose; fixed dead and missing cross
references. Library: note that PDF417 is not implemented by the
barcode decoder.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: kwagyeman

docs/library/omv.image.rst

@@ -735,7 +735,9 @@ returned by :meth:`Image.find_barcodes`.
 .. data:: PDF417
    :type: int
 
-   PDF417 2D stacked barcode.
+   PDF417 2D stacked barcode. The constant exists for completeness,
+   but the barcode decoder does not currently implement PDF417 --
+   `Image.find_barcodes()` will not return detections of this type.
 
 .. data:: CODE93
    :type: int

docs/openmvcam/tutorial/image/analysis/histograms-and-statistics.rst

@@ -1,23 +1,21 @@
 Histograms and statistics
 =========================
 
-The sections so far have all *operated* on
-images: filtering them, thresholding them,
-combining them with other images. The remaining
-family of operations does something different.
-It *measures* the image -- summarises the
-distribution of pixel values, returns the
-mean and median brightness, finds the optimal
-cutoff between dark and bright pixels, reports
-the spread of the colour channels. Those
-measurements feed back into the operating side
-in two ways: as inputs to the algorithm that
-decides what threshold to use, what gain to set,
-what the scene's tonal profile looks like; and as
-diagnostic signals -- "is the scene bright
-enough?" -- that the application can act on
-without making a decision about any particular
-pixel.
+Alongside the operations that change an
+image's pixels, the :class:`Image` class
+carries a family of methods that *measure*
+them -- summarise the distribution of pixel
+values, return the mean and median brightness,
+find the optimal cutoff between dark and
+bright pixels, report the spread of the colour
+channels. The measurements feed applications
+in two ways: as inputs to the code that
+decides what threshold to use, what gain to
+set, what the scene's tonal profile looks
+like; and as diagnostic signals -- "is the
+scene bright enough?" -- that an application
+can act on without making a decision about any
+particular pixel.
 
 The starting point for almost every measurement
 is the *histogram*.
@@ -171,8 +169,8 @@ Percentiles and CDF lookups
 ---------------------------
 
 The :class:`histogram` object exposes a
-``get_percentile`` method that turns a
-fraction into a pixel value -- the value
+:meth:`~image.histogram.get_percentile` method
+that turns a fraction into a pixel value -- the value
 below which the requested fraction of pixels
 lies. ``h.get_percentile(0.5)`` is the
 median; ``h.get_percentile(0.05)`` and
@@ -268,14 +266,3 @@ call to produce an image whose only purpose
 is to be measured. For a continuously
 running motion-detection script, the saving
 adds up.
-
-With histograms describing distributions,
-statistics summarising them, percentiles for
-robust range estimates, and Otsu's method
-for the optimal binary split, the
-measurement side of the toolkit is ready.
-The remaining tonal work is about *acting*
-on what the measurements say -- adjusting the
-image's contrast, brightness, or colour to
-correct for what the histogram revealed
-about it.

docs/openmvcam/tutorial/image/analysis/regression-and-similarity.rst

@@ -1,12 +1,11 @@
 Regression and similarity
 =========================
 
-Two measurements on the :class:`Image`
-surface do not fit the histogram / statistics
-framing of the previous pages, but come up
-often enough to deserve a dedicated section.
-Linear regression of thresholded pixels gives
-an application a *line* it can act on -- the
+Two more measurements on the :class:`Image`
+class summarise the image as something other
+than a distribution of pixel values. Linear
+regression of thresholded pixels gives an
+application a *line* it can act on -- the
 classical input to a line-following robot.
 Similarity measurement gives an application a
 single number describing how alike two images
@@ -197,12 +196,3 @@ reference image. It is the cheap way to
 build a tracker that searches a parameter
 space and reports which transform of the
 reference best matches the current frame.
-
-With linear regression for line extraction
-and SSIM for image comparison, the
-measurement side of the toolkit is complete.
-What follows turns to geometric work --
-scaling, flipping, cropping, correcting
-lens distortion, and re-projecting into
-the polar coordinate system the Foundations
-introduced.

docs/openmvcam/tutorial/image/analysis/tonal-corrections.rst

@@ -1,24 +1,24 @@
 Tonal corrections
 =================
 
-The previous page introduced the histogram as
-the *description* of how brightness is
-distributed in an image. This page is about the
-operations that *change* that distribution --
-the corrections an application applies when the
-captured image is too dark, too bright, too
-flat, or skewed toward the wrong colour.
+Tonal corrections change how brightness and
+colour are distributed in a captured image --
+the fixes an application applies when a frame
+is too dark, too bright, too flat, or skewed
+toward the wrong colour.
 
 The corrections belong to two families:
 brightness-and-contrast adjustments that
-reshape the distribution of brightness, and
-colour adjustments that change which colour
-each pixel reads as. Both have analogues in
-the sensor's ISP that Vision Sensors covered;
-this page is about applying them to an
-already-captured :class:`Image`, after the
-fact, when the post-capture state needs more
-correction than the ISP already provided.
+redistribute brightness, and colour
+adjustments that change which colour each
+pixel reads as. Both have analogues in the
+sensor's :doc:`ISP
+</openmvcam/tutorial/vision/color/isp-pipeline>`,
+which corrects each frame on its way in; the
+methods here apply to an already-captured
+:class:`Image`, after the fact, for the cases
+where the frame needs more correction than the
+ISP provided.
 
 Histogram equalisation
 ----------------------
@@ -41,7 +41,7 @@ equalisation:
     img.histeq()
 
 The mechanic is direct. The cumulative
-distribution function of the source's
+distribution function (CDF) of the source's
 histogram is computed; each input pixel value
 is mapped to its position in the CDF, scaled
 to the output range. Where pixels were
@@ -238,36 +238,9 @@ Combined with a per-channel offset, the
 3-by-4 form lets the application also
 re-zero each channel.
 
-Vision Sensors covers the *why* of colour
-correction matrices in detail. The
-post-capture form on the :class:`Image` is
-just the same operation, applied after the
-fact.
-
-Where this leaves the application
----------------------------------
-
-With histogram equalisation and CLAHE for
-data-driven contrast adjustment, gamma /
-contrast / brightness for parameter-driven
-tone curves, auto white balance for the
-common colour correction, and the colour
-correction matrix for the more general case,
-the tonal toolkit covers the corrections that
-classical image processing applies *after*
-the capture is already done. Some of them
-overlap with what the ISP already did during
-capture, and the right place to make the
-correction depends on whether the captured
-frame is what needs the help or whether the
-capture itself needs to be different. When
-the answer is the latter, Vision Sensors'
-material is where the ISP-side knobs live;
-when the answer is the former, this page is
-where the post-capture knobs are.
-
-The remaining measurement-side operations are
-the ones that do not fit the histogram /
-statistics framing: linear regression of
-thresholded pixels, and image-to-image
-similarity comparison.
+The :doc:`ISP pipeline
+</openmvcam/tutorial/vision/color/isp-pipeline>`
+material covers the *why* of colour correction
+matrices. The post-capture form on the
+:class:`Image` is just the same operation,
+applied after the fact.

docs/openmvcam/tutorial/image/decoding/barcodes-and-datamatrix.rst

@@ -1,20 +1,22 @@
 Barcodes and Data Matrix codes
 ==============================
 
-QR codes and AprilTags are recent
-inventions, born in the era of dense
-two-dimensional symbols and cheap
-smartphone cameras. The codes printed on
-the side of a cereal box, the wrist band a
-hospital patient wears, the maker mark
-laser-etched onto a circuit board predate
-all of that. They are *one-dimensional*
-*barcodes* and small high-density
-*Data Matrix* codes, and the image module
-has dedicated decoders for both. The
-applications they fit are the industrial,
-retail, and inventory ones the consumer
-2D codes never quite covered.
+Two more code families round out the
+camera's decoders. *One-dimensional
+barcodes* -- the stripes on the side of a
+cereal box, a hospital wrist band, a
+shipping label -- are the oldest
+machine-readable symbols still in everyday
+use. *Data Matrix* codes are
+two-dimensional like QR codes, but denser
+at the same payload size and aimed at
+industrial marking -- the maker mark
+laser-etched onto a circuit board rather
+than the poster on a wall. The image module
+has a dedicated decoder for each, covering
+the industrial, retail, and inventory
+applications the consumer 2D codes never
+quite reached.
 
 1D barcodes
 -----------
@@ -71,9 +73,7 @@ libraries and blood banks),
 :data:`image.CODE39`, :data:`image.CODE93`,
 and :data:`image.CODE128` (variable-length
 alphanumeric symbologies for arbitrary
-text). The high-density two-row symbology
-:data:`image.PDF417` decodes too, and the
-shelf-edge family
+text). The shelf-edge family
 :data:`image.DATABAR` (RSS-14) and
 :data:`image.DATABAR_EXP` (RSS-Expanded)
 round out the list.
@@ -248,15 +248,3 @@ adds, so applications that do this
 typically narrow each pass with an
 appropriate ``roi`` rather than searching
 the full frame for every kind of code.
-
-With 1D barcodes, Data Matrix codes, QR
-codes, and AprilTags, the camera reads
-the four families of printed and etched
-symbols an application is likely to
-encounter. The remaining detectors do not
-decode symbols at all but instead measure
-similarity: how closely two patches of
-the same captured frame, or two frames at
-different times, line up with each other.
-That is the work of the matching methods,
-and they come next.

docs/openmvcam/tutorial/image/decoding/qr-apriltag.rst

@@ -53,8 +53,7 @@ objects:
 The detector takes a single optional ``roi``
 to restrict the search. It needs grayscale
 input -- a colour frame is converted
-internally before decoding -- and it works
-on every supported board except the M4.
+internally before decoding.
 
 Each detection carries the bounding box
 (``x``, ``y``, ``w``, ``h``, ``rect``), the
@@ -153,12 +152,25 @@ families are :data:`image.TAG16H5`,
 :data:`image.TAGCUSTOM48H12`,
 :data:`image.TAGSTANDARD41H12`, and
 :data:`image.TAGSTANDARD52H13`. Each family
-trades off ID count against
-error-correction strength: ``TAG16H5`` has
-30 IDs and 0 bit errors tolerated;
-``TAG25H9`` has 35 IDs and 3 bit errors;
+trades off ID count against robustness. The
+``H`` number in the name is the minimum
+*Hamming distance* between any two codes in
+the family -- how many bits must flip before
+one valid code turns into another --
+``TAG16H5`` has 30 IDs at distance 5,
+``TAG25H9`` has 35 IDs at distance 9, and
 ``TAG36H11`` (the default and the most
-common) has 587 IDs and 4 bit errors.
+common) has 587 IDs at distance 11. The
+detector corrects up to two bit errors no
+matter the family, so the distance decides
+how risky that correction is: a random
+pattern in a noisy frame only has to land
+within two bits of a valid code to decode as
+a false detection, and the higher-distance
+families spread their codes so much more
+sparsely that such collisions become rare --
+the reason ``TAG36H11`` is the recommended
+choice.
 Detection time scales with the number of
 enabled families, so an application enables
 only what it actually prints. The bitmask
@@ -282,13 +294,3 @@ The two detectors run independently on the
 same frame and the application correlates
 their bounding boxes to match each tag to
 its companion code.
-
-With QR codes for arbitrary payloads and
-AprilTags for IDs and pose, the cam can
-read the two most common 2D codes the
-camera will ever see. Older code families
-the camera also handles -- the 1D barcodes
-printed on consumer goods and the
-high-density Data Matrix codes printed on
-industrial parts -- have their own
-detectors, and those come next.