jsfeatNext 🚀

A TypeScript port of jsfeat — a computer-vision library — for the WebARKit project. jsfeatNext is actively maintained: its algorithms are continuously checked for numeric/behavioral parity against the original jsfeat via an automated test suite, and its internals have been refactored into one real module per algorithm (no more duplicated implementations). It's still pre-1.0 and evolving — see "Known limitations" below for the honest list of gaps.

Quick start 🏁

npm install @webarkit/jsfeat-next

import jsfeatNext from "@webarkit/jsfeat-next";

// algorithm modules are singletons — call them directly, no `new` (since 0.9.0)
const src = new jsfeatNext.matrix_t(width, height, jsfeatNext.U8_t | jsfeatNext.C1_t);
jsfeatNext.imgproc.grayscale(rgbaPixelData, width, height, src);

In the browser (UMD build), the global is the namespace directly:

<script src="dist/jsfeatNext.js"></script>
<script>
    jsfeatNext.imgproc.grayscale(rgbaPixelData, width, height, src);
</script>

Upgrading from ≤ 0.8.x? The jsfeatNext.jsfeatNext double namespace and the new jsfeatNext.imgproc() calling convention were removed in 0.9.0 — see the migration guide.

List of features ✨

• TypeScript definitions, with full TSDoc on every public class/method (npm run docs to generate a browsable API reference locally)
• UMD (browser <script>) + ESM builds, built with Vite library mode
• npm package
• 250+ tests across 22 files: characterization tests asserting numeric/behavioral parity against the original jsfeat, plus property/invariant tests, ground-truth reference tests, and a registry of intentional divergences

Modules 📚

These classes are attached to the jsfeatNext namespace (jsfeatNext.<name>):

cache · fast_corners · homography2d · affine2d · imgproc · keypoint_t · linalg · math · matmath · matrix_t · motion_estimator · ransac_params_t · optical_flow_lk · orb · pyramid_t · transform · yape · yape06

Requirements & building 🛠️

• Node.js v24 (see .nvmrc; npm 11)
• Build (UMD + ESM + type declarations): npm install then npm run build-ts
  • Produces dist/jsfeatNext.js (UMD, browser global jsfeatNext), dist/jsfeatNext.mjs (ESM), and types/
  • Built with Vite library mode; webpack/babel are no longer used
• Watch mode: npm run dev-ts
• Tests: npm test (Vitest — characterization tests against the original jsfeat)
• API docs: npm run docs (TypeDoc, output to docs/api/, gitignored/local-only for now)
• Benchmarks: npm run bench (Vitest, A/B against the vendored original jsfeat) · npm run bench:ratios for the ratio summary alone

Benchmarks 📊

Every case runs both jsfeatNext and the vendored original jsfeat in the same process, and the number that matters is the ratio between them — absolute ops/s are not comparable across machines or even across runs on one machine.

The suite has already found and fixed several real slowdowns (#159, #165, #166), and it records the ones still open.

Read bench/README.md before interpreting any number — it documents the measured noise floor, how to take a clean measurement, and the current status of every finding.

CI runs a collection-only smoke check (npm run bench:smoke) that verifies the benchmarks still execute, without measuring anything. Actual measurement is manual: the Benchmarks workflow above is dispatch-only and never gates a build, because a shared runner is too noisy to draw conclusions from.

npm package 📦

npm install @webarkit/jsfeat-next

Known limitations 🔍

• Not every original jsfeat class is ported yet — haar and bbf (Haar-cascade / BBF object detection) are not implemented. Tracked in #43 and #44.
• The transform module takes matrix_t arguments where original jsfeat's (never-shipped) transform module used raw arrays — same math, slightly different calling convention (see the parity audit, Axis 2).

Examples 🧪

The examples folder demonstrates both ways of consuming the library. Build first (npm run build-ts), then open the examples in a browser.

ESM examples — import from dist/jsfeatNext.mjs

The camera demos use the modern ES-module entry point:

<script type="module">
    import jsfeatNext from '../dist/jsfeatNext.mjs';
    jsfeatNext.imgproc.grayscale(...);
</script>

⚠️ These must be served over HTTP — ES modules don't load from file://. Run a static server from the repo root, e.g. npx serve ., then browse to http://localhost:3000/examples/….

They share the helpers in examples/js/demo-utils.mjs (webcam setup and canvas drawing) instead of repeating that boilerplate in every file.

| Example | Demonstrates | |---|---| | grayscale.html | color → grayscale conversion | | sample_boxblur.html | box blur | | sample_gaussblur.html | gaussian blur | | sample_equalize_hist.html | histogram equalization | | sample_canny_edge.html | Canny edge detector | | sample_sobel.html / sample_sobel_edge.html | Sobel derivatives / edges | | sample_scharr.html | Scharr derivatives | | sample_pyrdown.html | image pyramid downsampling | | sample_fast_corners.html | FAST corner detector | | sample_yape.html / sample_yape06.html | YAPE / YAPE06 detectors | | sample_oflow_lk.html | Lucas–Kanade optical flow (click to add points) | | sample_orb.html | ORB descriptors + matching + homography | | sample_orb_pinball.html | ORB pattern tracking on a reference image | | sample_warp_affine.html / sample_warp_perspective.html | affine / perspective warps |

UMD examples — global <script> tag

These small API demos load the UMD bundle and use the jsfeatNext global. They need no server and open directly from the filesystem:

<script src="../dist/jsfeatNext.js"></script>
<script>
    const m = new jsfeatNext.matrix_t(320, 240, jsfeatNext.U8_t | jsfeatNext.C1_t);
</script>

| Example | Demonstrates | |---|---| | browser.html | version, constants, matrix_t, keypoint_t, the shared cache | | matrix_t_example.html | constructing a matrix_t | | mat_math_example.html | matmath (3×3 identity) | | linalg_example.html | linalg (SVD pseudo-inverse) | | orb_test.html | orb.describe |

TypeScript examples 📝

You can find some TypeScript examples in jsfeatNext-examples.

Documentation 📖

Every public class, interface, method and property has TSDoc comments. Run npm run docs to generate a full static HTML API reference locally (via TypeDoc) — hosting it publicly is tracked separately in webarkit/webarkit.github.io#49. You can also read the original jsfeat docs for background on the algorithms, though the calling convention differs (see "Known limitations" below).

Contributing 🤝

See AGENTS.md for the canonical contribution conventions (Conventional Commits, PRs target dev not main, numeric-parity expectations) and MAINTAINERS.md for the release process.

Dependencies and GitHub Actions are kept current by Dependabot, which opens its own PRs against dev — they go through the same CI and review as any other change.

Releases & changelog 📦

Releases are tagged X.Y.Z (never vX.Y.Z) and published automatically via GitHub Actions. Release notes (generated from Conventional Commits with git-cliff) live on the GitHub Releases page.

License 📄

LGPL-3.0-or-later