test(properties): math, detector and optical-flow invariants (refs #87)

[kalwalt]

Phase 3 of the #87 plan, completing category A (property/invariant tests). 47 new tests, 133 → 180 total. Tests only, no src/ changes.

Refs #87. Follows #106 (linalg + matmath) and #108 (imgproc).

Why these modules matter most

For the detectors the parity suite can only say "the same corners as jsfeat" — and for the detectors still to be ported (haar/bbf, #43/#44) there is no oracle at all. Invariants are the only correctness signal that survives either situation.

What is covered

math — Gaussian kernels are normalized, non-negative, symmetric, unimodal, monotonically decreasing away from the centre, and flatten as sigma grows. The U8 path sums to 256 within the per-tap rounding bound (size/2) and to exactly 256 on the fixed binomial path, where the weights are exact binary fractions. qsort is verified as a sorted permutation — idempotent, correct on already-sorted/reversed/all-equal input, honouring a custom comparator, and touching only the requested sub-range. median is pinned against a sorted copy across odd and even lengths, shown order-independent, and confirmed to return a value actually present in the input.

detectors — a structureless image yields nothing (always paired with a counter-case, so a detector that always returned nothing could not pass); results respect the requested border; detections are equivariant under translation and invariant under a global brightness offset. Both hold bit-exactly, so they are asserted as exact set equality rather than with a tolerance.

optical_flow_lk — zero motion between identical frames (bit-exact), convergence back to zero from a deliberately wrong seed, recovery of small known translations, rejection of every point in a textureless image, and non-mutation of the input coordinates.

To make translation meaningful, the new cornerScene() helper samples one generator at (x - dx, y - dy) — translating the background too, rather than sliding shapes over a static one — and caps intensities at 200 so the brightness offset cannot saturate and void the premise.

Two findings worth recording

1. ORB is exactly brightness-invariant only when the whole patch is inside the image. rectify_patch() warps with fill_value = 128, and that constant does not shift with image brightness, so patches crossing the edge flip a few bits. Measured: border 8 → 2 bits of 8960; border ≥ 16 → exactly 0. Both are asserted, the second as a documented caveat — callers needing exposure-robust descriptors want border >= 16. Paired with a distinctness check (different keypoints sit ≥ 47 bits apart, mean 108.8/256) so the invariance assertions cannot pass vacuously.

2. optical_flow_lk does not recover large displacements at these settings. Small shifts come back to ~0.01px, but a 5px shift of this scene at 2 levels with a 9px window is off by tens of pixels. That is a local gradient method behaving as designed, not a defect — so the accuracy assertions stay inside that regime and the limitation is documented in a comment rather than asserted as a failure.

FAST/yape06 count monotonicity is asserted as the issue asks, but flagged in a comment as a structural trend rather than a theorem: 3×3 non-maximum suppression could in principle let a suppressed corner survive once a stronger neighbour drops out.

Verification

Every behaviour was characterised against the library before being asserted; the ORB border effect was predicted from the fill value and then confirmed. Mutation testing proves the tests bite — all seven injected bugs are caught (1–4 failing tests each), with src/ restored and re-verified after each:

Injected bug	Result
fast_corners: drop the threshold clamp	caught (1)
math: skew the gaussian normalization	caught (1)
math: median returns the low element	caught (3)
math: flip the qsort insertion comparison	caught (4)
yape06: ignore the border on x	caught (1)
optical_flow_lk: bias tracked x by 0.02px	caught (2)
orb: describe every keypoint from corner 0	caught (1)

prettier clean · tsc --noEmit clean · npm test 180/180.

Remaining #87 scope

Category A is now complete. Still open: B edge/boundary inputs, C third-party ground-truth fixtures, D coverage gaps (data_type has no dedicated test). As discussed, the golden-fixture work in C is the natural point to revisit these and the earlier phases with tighter assertions.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds Phase 3 of issue #87’s property/invariant test plan, extending the Vitest suite with oracle-independent checks for core math, detectors/ORB, and Lucas–Kanade optical flow—without changing any src/ runtime code.

Changes:

• Added invariants for math (get_gaussian_kernel, qsort, median).
• Added detector/descriptor invariants for fast_corners, yape06, yape, and orb.describe.
• Added optical-flow invariants for optical_flow_lk.track, plus new shared property-test helpers (scene generator, hamming distance).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
tests/properties/optical_flow_lk.test.ts	New LK optical-flow invariant/property tests.
tests/properties/math.test.ts	New oracle-independent invariants for Gaussian kernels, sorting, and medians.
tests/properties/helpers.ts	Adds cornerScene, keypointPool, and hammingDistance for property tests.
tests/properties/detectors.test.ts	New invariants for detectors and ORB descriptor behavior (translation/brightness properties, borders, determinism).