new v0.9.0 release

[kalwalt]

This pull request releases PureCV 0.9.0. It brings calc_optical_flow_pyramid_lk (pyramidal Lucas-Kanade) to OpenCV parity and moves npm publishing to trusted publishing. 32 commits, 13 files changed (+1142 / −146); the full list is in the new CHANGELOG.md entry.

⚠️ Merge with "Create a merge commit", not "Rebase and merge" or "Squash and merge". Rebasing would give dev's commits new SHAs on main and make the branches diverge (see CLAUDE.md, v0.7.1 / #95).

---

Lucas-Kanade optical flow: OpenCV parity (src/video/optical_flow.rs)

• LK pyramid uses Sobel instead of Scharr gradients (undocumented divergence from OpenCV) #130: Scharr derivatives instead of Sobel, in both build_optical_flow_pyramid and calc_optical_flow_pyramid_lk.
• calc_optical_flow_pyramid_lk's min_eigen_threshold is not on OpenCV's scale (missing FLT_SCALE=2^-20 normalization) #138: minimum-eigenvalue scale now matches OpenCV (FLT_SCALE and window-area normalisation), so OpenCV's 1e-4 default carries over directly. Breaking: thresholds tuned on older builds need retuning (the docs give the factor).
• LK iteration lacks OpenCV's oscillation half-step fallback #131: OpenCV's oscillation half-step fallback; the Newton loop was extracted into lk_iterate so it can be unit-tested.
• lk_single_level's det.abs() < f64::EPSILON degeneracy guard is on the wrong scale after #130/#138 #142 (fix(video): scale the LK determinant guard to match OpenCV #146): the determinant degeneracy guard uses OpenCV's scaled, signed D < FLT_EPSILON test (LK_DET_EPSILON = 2^17).
• calc_optical_flow_pyramid_lk aborts the whole pyramid on any level's degeneracy, OpenCV only at level 0 #145 (fix(video): only lose an LK point when level 0 is degenerate #147): a degenerate window only loses the point at pyramid level 0. Coarser levels are skipped, and the propagated flow carries on to the next level.
• LK tracking window sampling diverges from OpenCV for even win_size (integer half-window truncation) #144 (fix(video): sample exactly win_size pixels in the LK window, like OpenCV #148): the tracking window samples exactly win_size pixels using OpenCV's (n−1)/2 half-window, so even sizes work correctly. win_size smaller than 3×3 now returns an error.
• LK Newton step is 1/32 of the full step: It is not scaled to match the Scharr-scaled gradients #149 (fix(video): scale LK's temporal difference to the Scharr gain #150): Newton steps are now the full Gauss-Newton step. They were 1/32 of it, so flow estimates came out about 30% short (a 1 px shift tracked as ≈0.70 px with OpenCV defaults).

These change tracking results for existing callers, which is why this is a minor version bump. Each fix has regression tests with hand-derived expected values; 359 unit tests in total.

CI and release process

• publish-npm job authenticates via npm config set + NPM_TOKEN; switch to OIDC trusted publishing #129 (fix(ci): publish to npm via trusted publishing (OIDC) instead of NPM_TOKEN #151): publish-npm now uses npm trusted publishing (OIDC) with provenance instead of NPM_TOKEN. That token path made v0.8.0's npm publish fail with EOTP. The Trusted Publisher for @webarkit/purecv-wasm is configured on npmjs.com. The v0.9.0 tag will be this path's first real run. If publish-npm fails, use Re-run failed jobs rather than re-tagging.

Versioning and changelog (#152)

• Version bumped to 0.9.0 in Cargo.toml ([package] and [workspace.package]), package.json and crates/wasm/pkg/package.json; README install snippets updated to "0.9"; CHANGELOG.md entry generated with git-cliff.
• Checked before merging chore(release): prepare for v0.9.0 #152: cargo publish --dry-run -p purecv succeeds, and a local npm run build:wasm (std + SIMD) regenerates crates/wasm/pkg/package.json byte-identical to the committed file.

---

After merging

1. Tag v0.9.0 on the new main merge commit and push the tag. This publishes to crates.io and npm and can't be undone. The release workflow waits for the Build and Test, WASM, Benchmarks and both Miri checks before publishing.
2. Issues LK pyramid uses Sobel instead of Scharr gradients (undocumented divergence from OpenCV) #130, LK iteration lacks OpenCV's oscillation half-step fallback #131, calc_optical_flow_pyramid_lk's min_eigen_threshold is not on OpenCV's scale (missing FLT_SCALE=2^-20 normalization) #138, lk_single_level's det.abs() < f64::EPSILON degeneracy guard is on the wrong scale after #130/#138 #142, LK tracking window sampling diverges from OpenCV for even win_size (integer half-window truncation) #144, calc_optical_flow_pyramid_lk aborts the whole pyramid on any level's degeneracy, OpenCV only at level 0 #145, LK Newton step is 1/32 of the full step: It is not scaled to match the Scharr-scaled gradients #149 and publish-npm job authenticates via npm config set + NPM_TOKEN; switch to OIDC trusted publishing #129 can be closed once the release is out.

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Release PureCV 0.9.0 with corrected LK tracking and npm publishing

🐞 Bug fix 🧪 Tests ⚙️ Configuration changes 📝 Documentation 🕐 40+ Minutes

AI Description

• Align pyramidal Lucas–Kanade tracking with OpenCV, changing flow estimates and threshold behavior.
• Add regression tests for derivative scaling, window sampling, degeneracy, and convergence.
• Release version 0.9.0 and switch npm publishing to OIDC with provenance.

Diagram

graph TD
  A["Frame pairs"] --> B["Image pyramids"] --> C["Scharr gradients"] --> D["Window samples"] --> E{"Gradient valid?"}
  E -->|valid| F["LK refinement"] --> G["Flow and status"]
  E -->|coarse skip| D
  E -->|finest lost| G
  F -->|next level| D

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Replicate OpenCV fixed-point sampling

• ➕ Could provide closer numerical agreement with OpenCV's internal LK calculations.
• ➖ Adds substantial complexity to the existing floating-point scalar and SIMD paths.
• ➖ Requires a broader rewrite than the identified tracking corrections.

Recommendation: Keep the existing floating-point tracker and correct its Scharr, temporal-difference, and guard scales as this PR does. Consider fixed-point sampling only if future requirements call for closer numerical agreement than the regression tests establish.

Files changed (13) +1142 / -146

Bug fix (1) +277 / -111

optical_flow.rsCorrect pyramidal LK calculations and tracking decisions +277/-111

Correct pyramidal LK calculations and tracking decisions

• Uses Scharr derivatives, OpenCV-scaled eigenvalue and determinant checks, and exact-sized tracking windows. Restores full Gauss–Newton steps, adds an oscillation fallback, and lets points survive degenerate coarse levels while rejecting windows smaller than 3×3.

src/video/optical_flow.rs

Tests (1) +754 / -7

tests.rsPin LK behavior with numerical regression tests +754/-7

Pin LK behavior with numerical regression tests

• Adds closed-form and end-to-end tests for Scharr derivatives, eigenvalue scaling, determinant boundaries, coarse-level propagation, even and non-square windows, oscillation, and Newton-step accuracy. Tightens an existing translation-accuracy assertion.

src/video/tests.rs

Documentation (7) +85 / -22

MIRI_PLAN.mdReconcile Miri coverage notes with the Scharr tests +12/-8

Reconcile Miri coverage notes with the Scharr tests

• Updates the test-count and runtime rationale for Miri exclusions. Explains that retained Scharr tests cover the derivative fast path despite the slow pyramid test remaining excluded.

.agents/MIRI_PLAN.md

CHANGELOG.mdDocument the PureCV 0.9.0 release +48/-0

Document the PureCV 0.9.0 release

• Adds the 0.9.0 entry covering LK fixes, the threshold-scale breaking change, regression tests, documentation, and npm publishing.

CHANGELOG.md

README.mdRefresh installation examples and test count +6/-6

Refresh installation examples and test count

• Changes Rust dependency examples to version 0.9 and reports 359 unit tests.

README.md

benchmark_results.mdDescribe Scharr-based pyramid benchmark behavior +7/-4

Describe Scharr-based pyramid benchmark behavior

• Replaces stale Sobel references with Scharr and notes that both use the same derivative fast path.

benches/benchmark_results.md

video_bench.rsCorrect the pyramid benchmark description +1/-1

Correct the pyramid benchmark description

• Identifies the derivative work measured by the existing pyramid benchmark as Scharr rather than Sobel.

benches/video_bench.rs

lib.rsDocument WASM optical-flow derivative and threshold behavior +10/-2

Document WASM optical-flow derivative and threshold behavior

• Identifies pyramid derivatives as Scharr and documents the OpenCV-compatible minimum-eigenvalue scale and migration guidance for older thresholds.

crates/wasm/src/lib.rs

optical_flow.rsRefresh the optical-flow CSV example +1/-1

Refresh the optical-flow CSV example

• Adjusts the sample tracked coordinates and eigenvalue to reflect the corrected LK results.

examples/optical_flow.rs

Other (4) +26 / -6

release.ymlPublish npm package through trusted OIDC credentials +22/-2

Publish npm package through trusted OIDC credentials

• Grants the npm job OIDC permission, installs Node 24 and a verified npm version of at least 11.5.1, and publishes with provenance. Removes the long-lived NPM_TOKEN configuration.

.github/workflows/release.yml

Cargo.tomlBump Rust package and workspace versions to 0.9.0 +2/-2

Bump Rust package and workspace versions to 0.9.0

• Sets both the root package and shared workspace package version to 0.9.0.

Cargo.toml

package.jsonSet the publishable WASM package version to 0.9.0 +1/-1

Set the publishable WASM package version to 0.9.0

• Bumps the generated npm package manifest from 0.8.0 to 0.9.0.

crates/wasm/pkg/package.json

package.jsonBump the root npm package version to 0.9.0 +1/-1

Bump the root npm package version to 0.9.0

• Sets the private root package manifest version to 0.9.0.

package.json

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (2) 📎 Requirement gaps (1) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Large tracking windows panic on overflow 📘 Rule violation ≡ Correctness

Description

TrackingWindow::area multiplies two i32 window dimensions before converting the result to
usize, without checking for overflow. A non-empty tracking request with win_size of
1_073_741_824 by 3 passes the new minimum-size check but panics when the SIMD path sizes its
sample buffers in debug builds.

Code

src/video/optical_flow.rs[308]

+        (self.width * self.height) as usize

Evidence

The new validation rejects only dimensions below three, while the new area calculation multiplies
accepted dimensions as i32; the SIMD path calls it before sampling.

Rule 2965956: Library functions that can fail must return Result<T, PureCvError>
src/video/optical_flow.rs[747-753]
src/video/optical_flow.rs[306-309]
src/video/optical_flow.rs[391-405]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Accepted window dimensions can overflow the area calculation and panic during tracking.
## Fix Focus Areas
- src/video/optical_flow.rs[306-309]
- src/video/optical_flow.rs[747-753]
## Recommended Fix
Compute the area with checked arithmetic during input validation, return a `PureCvError` if it is not representable, and use the validated area throughout tracking.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. New solver silences a Clippy warning 📘 Rule violation ✧ Quality

Description

lk_iterate adds #[allow(clippy::too_many_arguments)] rather than changing the new helper's
argument structure. The suppression applies whenever the solver is linted, so changes to its growing
parameter list will not be checked by that lint.

Code

src/video/optical_flow.rs[563]

+#[allow(clippy::too_many_arguments)]

Evidence

The changed line introduces a Clippy allow attribute on the new solver, which the checklist
explicitly prohibits adding to silence a lint.

Rule 2965968: Do not introduce new Clippy warnings in Rust code
src/video/optical_flow.rs[563-574]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new solver suppresses a Clippy lint on its argument count.
## Fix Focus Areas
- src/video/optical_flow.rs[563-574]
## Recommended Fix
Group related solver parameters into small structs, update both callers and the direct test, and remove the new allow attribute.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. One-pixel tracking accuracy goes untested 📎 Requirement gap ≡ Correctness

Description

test_lk_recovers_subpixel_shift_with_opencv_defaults uses a (0.6, -0.4) shift and accepts error
below 0.02 pixels rather than checking a one-pixel shift to approximately 0.01 pixels. The
single-step bowl test checks the step separately, but this end-to-end test can pass without
establishing the specified one-pixel accuracy under the default tracking parameters.

Code

src/video/tests.rs[1115]

+        let (sx, sy) = (0.6f32, -0.4f32);

Evidence

The checklist calls for an end-to-end smooth-texture one-pixel accuracy check; the added test
instead supplies a 0.6-pixel horizontal shift and a 0.02-pixel tolerance.

Test LK step size and tracking accuracy
src/video/tests.rs[1108-1139]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The end-to-end regression test does not establish the specified one-pixel tracking accuracy.
## Fix Focus Areas
- src/video/tests.rs[1108-1139]
## Recommended Fix
Add a smooth-texture one-pixel shift case using the OpenCV default tracking parameters and assert accuracy of approximately 0.01 pixels. Keep the subpixel case if it provides separate coverage.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (1)

4. Edge features are marked lost with even windows 🐞 Bug ≡ Correctness

Description

TrackingWindow::offsets emits negative half-integer coordinates for even-sized windows, but
bilinear_interp clamps only the base pixel index, leaving weights that blend the border pixel with
an interior pixel instead of replicating the border. At the left or top edge, those samples affect
the gradient matrix, flow refinement, and tracking error; for a 4×4 window at (0, 0) on an x + y
image, they lower the minimum eigenvalue below the default 1e-4 threshold when border-replicated
sampling would keep it above.

Code

src/video/optical_flow.rs[R316-317]

+            let dy = ky as f32 - self.half_h;
+            (0..self.width).map(move |kx| (kx as f32 - self.half_w, dy))

Evidence

An even-sized window at an integer-valued corner produces offsets including -1.5 and -0.5. For
x = -0.5, the interpolator clamps the floor-derived base index to x0 = 0 but retains ax = 0.5
from the out-of-range coordinate, blending pixels 0 and 1 rather than returning pixel 0. The
sampling loops use these interpolated values in the derivative matrix used for minimum-eigenvalue
rejection, Newton mismatch accumulation, and final tracking error.

src/video/optical_flow.rs[295-318]
src/video/optical_flow.rs[325-347]
src/video/optical_flow.rs[413-457]
src/video/optical_flow.rs[615-626]
src/video/optical_flow.rs[281-318]
src/video/optical_flow.rs[325-346]
src/video/optical_flow.rs[399-404]
src/video/optical_flow.rs[496-504]
src/video/optical_flow.rs[621-626]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Even-sized LK windows generate negative half-integer sample coordinates near the top and left image borders. `bilinear_interp` clamps the base pixel index but derives interpolation weights from the out-of-range coordinate, causing border samples to blend with adjacent interior pixels and changing tracking decisions.
## Fix Focus Areas
- src/video/optical_flow.rs[315-318]
- src/video/optical_flow.rs[325-347]
- src/video/tests.rs[905-950]
## Recommended Fix
Clamp the floating-point `x` and `y` sampling coordinates to valid image bounds before computing their floor indices, neighboring indices, and interpolation weights. Add regression coverage for an even-sized window at the top-left image corner: verify that a negative half-integer sample uses the border pixel rather than blending with its interior neighbor, and check the resulting minimum eigenvalue or tracking status.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗