feat(orb): expose ic_angle, the keypoint orientation step (#96)

[kalwalt]

Part of #96 — the jsfeatNext-side work item ("stream A": keep the modules adapter-ready). The CvBackend contract and the adapter itself live in webarkit/webarkit and are not part of this PR.

The audit

Four of the five primitives the adapter delegates to are already adapter-ready — public, neutral-mappable I/O, no hidden state:

contract method	jsfeatNext primitive	status
match	bfmatcher.match / knnMatch / ratio_test	ready (matrix_t in, match_t[] out)
estimateHomography	motion_estimator.ransac + homography2d	ready (mask is a matrix_t → Uint8Array)
poseFromHomography	pose_estimator.estimate	ready (matrix_t + Float64Array)
detect	fast_corners / yape / yape06	ready
describe	orb.describe	ready

Useful incidental finding for whoever writes the adapter: point_t and keypoint_t are structurally identical (x, y, score, level, angle), so a single pre-allocated pool can be passed to both fast_corners.detect (typed point_t[]) and orb.describe (typed keypoint_t[]).

The gap this PR closes

Keypoint orientation was missing from the library. ic_angle — the intensity-centroid measure that makes ORB descriptors rotation-invariant — existed only in the example pages, duplicated verbatim in sample_orb.html and sample_orb_pinball.html. Nothing under src/ ever assigned keypoint_t.angle.

This is the same shape of gap #133 closed for match_pattern.

Why it matters for #96: the contract's Keypoint type has an angle field and detect() is expected to return it populated. jsfeatNext's detectors never set it, so an out-of-repo adapter would have to reimplement the orientation itself — leaving PureCV's Rust port with no TypeScript oracle to cross-validate against, which is half the reason the jsfeatNext backend exists.

To be precise about severity: this is not a hard blocker. An adapter could pass angle = 0 and the code would run — it would just produce descriptors that are not rotation-invariant.

ic_angle now lives in orb as a public method, with the u_max table at module scope so the hot loop allocates nothing per call. Placement follows the ORB paper (the "o" in oFAST is that paper's own contribution) and OpenCV, which keeps IC_Angle in orb.cpp; bit_pattern_31 is the existing precedent for ORB-specific data living here.

Both examples now call the library method instead of carrying their own copy.

Documentation fix

examples/orb_test.html claimed angle = -1 lets ORB work out the patch orientation itself. That was never true: rectify_patch feeds the value straight into cos/sin, so -1 rotates the patch by −1 radian (≈ −57°) rather than leaving it upright. The page now fixes the angle at 0 — it only compares a patch against itself under a brightness change — and says why. describe's own docs now state that orientation is a required prior step, not an optional one.

Tests

10 new (295 → 305, all green).

• Parity against the examples' inline implementation — the only available oracle, since original jsfeat also kept ic_angle in its sample rather than the library. Same arrangement as tests/parity/bfmatcher.test.ts.
• Invariants: gradient direction (+x ramp → 0, +y ramp → π/2, diagonal → π/4), brightness invariance, atan2(0,0) returning 0 rather than NaN on a flat patch, and range.
• Rotation equivariance: turning the image a quarter turn turns the angle by exactly π/2 — to the last bit. This only holds on an odd-sized image, where the rotation's fixpoint lands on a pixel centre; an even size puts it on a half-pixel and the error grows to ~5°. Documented in the test.
• A closing test pins the point of the method: 11 bits apart with orientation versus 87 without, out of 256.

One note on that last test, since the numbers look suspiciously convenient: the first version used a pixel-noise image and failed at 131 vs 130. That was not a defect in ic_angle — ORB rectifies the patch by bilinear resampling, which does not preserve content at the Nyquist limit, so two views of a noise field give uncorrelated descriptors however well the orientation is recovered. The test now uses smooth structure, and the comment explains the constraint.

Verification

• npm test — 305 passed
• npm run typecheck — clean
• npm run format-check — clean
• node scripts/check-license-headers.mjs — 100 files OK
• Built locally and both webcam examples confirmed working by @kalwalt. dist/ and types/ are deliberately not committed — they are rebuilt at release time.

Not in this PR

• Folding the feat(cv_backend): descriptor selection & capability declaration #128 / feat(cv_backend): optional filterMatches step (GMS seam) #129 amendments into @webarkit/cv-backend-spec (that package is still at its pre-amendment version).
• The cv-backend-jsfeatnext adapter package itself.

Both are webarkit/webarkit work.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!