chore(release): bump version to 0.15.0 and rebuild dist

CHANGELOG.md

@@ -1,4 +1,52 @@
 
+## 0.15.0 - 2026-09-03
+
+### 🐛 Bug Fixes
+
+- Rename vitest.config.ts to .mts to silence the CJS/ESM warning (63e802b)
+
+- Match_t is original, not derived from jsfeat (11572e4)
+
+- Reject mismatched descriptor widths and export the new types (1f0e55d)
+
+- Compare effective row bytes, not cols, and require U8 (6d87c69)
+
+
+### 📚 Documentation
+
+- Record the agreed 1.0.0 milestone plan (dcfb524)
+
+- Restore the class description displaced by the ic_angle change (9c3d8b0)
+
+
+### 📦 Build
+
+- Bump actions/upload-artifact from 5 to 7 (7d28d72)
+
+- Bump vite from 8.2.1 to 8.2.2 (4ff82fc)
+
+
+### 🚀 Features
+
+- Brute-force Hamming matcher and match_t (f82d402)
+
+- Use bfmatcher in the ORB samples instead of inline match_pattern (4c48c50)
+
+- Closed-form planar pose from homography and intrinsics (c0ca5d5)
+
+- Expose ic_angle, the keypoint orientation step (#96) (3baaf09)
+
+
+### 🧪 Testing
+
+- Cover ratio_test edge cases and empty-train cross-check (5fb2402)
+
+- Perturbed-H orthonormalization case; document pose_t.t (eb54c61)
+
+- Cover setIntrinsics, the n2 guard, and the normalize zero-fallback (24a9c65)
+
+
+
 ## 0.14.0 - 2026-08-25
 
 ### ⚡ Performance

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webarkit/jsfeat-next",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Typescript version of jsfeat for WebARKit",
   "main": "dist/jsfeatNext.js",
   "module": "dist/jsfeatNext.mjs",

src/orb/orb.ts

@@ -48,16 +48,6 @@ import { imgproc } from "../imgproc/imgproc";
 import { bit_pattern_31 } from "./bit_pattern_31";
 import { rectify_patch } from "./rectify_patch";
 
-/**
- * ORB binary descriptor extractor (Oriented FAST and Rotated BRIEF): for
- * each keypoint a rotation-rectified 32×32 patch is sampled and 256
- * pixel-pair comparisons from the learned {@link bit_pattern_31} pattern are
- * packed into a 32-byte binary descriptor. Descriptors are matched with
- * Hamming distance.
- *
- * Mirrors `jsfeat.orb` from the original library.
- * (Moved out of the src/jsfeatNext.ts monolith in issue #47.)
- */
 /**
  * Per-row half-widths of the circular patch used by {@link orb.ic_angle},
  * indexed by `|v|` for `v` in `[-15, 15]`: row `v` spans `u ∈ [-u_max[v], u_max[v]]`.
@@ -68,6 +58,16 @@ import { rectify_patch } from "./rectify_patch";
  */
 const u_max = new Int32Array([15, 15, 15, 15, 14, 14, 14, 13, 13, 12, 11, 10, 9, 8, 6, 3, 0]);
 
+/**
+ * ORB binary descriptor extractor (Oriented FAST and Rotated BRIEF): for
+ * each keypoint a rotation-rectified 32×32 patch is sampled and 256
+ * pixel-pair comparisons from the learned {@link bit_pattern_31} pattern are
+ * packed into a 32-byte binary descriptor. Descriptors are matched with
+ * Hamming distance.
+ *
+ * Mirrors `jsfeat.orb` from the original library.
+ * (Moved out of the src/jsfeatNext.ts monolith in issue #47.)
+ */
 export class orb extends jsfeatNext {
     /** The learned 256-pair sampling pattern (flat `[x1,y1,x2,y2,…]`). */
     public bit_pattern_31_: Int32Array;
@@ -93,7 +93,7 @@ export class orb extends jsfeatNext {
      *
      * The angle points from the patch centre toward its intensity centroid,
      * computed from the first-order image moments `m01`/`m10` over a circular
-     * patch of radius 15 (see {@link u_max}), then `atan2(m01, m10)`.
+     * patch of radius 15 (see the module-level `u_max` table), then `atan2(m01, m10)`.
      *
      * @remarks
      * **This is a required step before {@link describe}, not an optional one.**

types/src/bfmatcher/bfmatcher.d.ts

@@ -0,0 +1,98 @@
+import { default as jsfeatNext } from '../core/core';
+import { matrix_t } from '../matrix_t/matrix_t';
+import { match_t } from './match_t';
+/**
+ * Brute-force Hamming matcher for binary descriptors (ORB today; TEBLID/FREAK
+ * once ported). Ported from the inline `match_pattern()`/`popcnt32()` helpers
+ * in `examples/sample_orb_pinball.html` — the only matcher jsfeatNext had
+ * before this module, duplicated across the ORB samples.
+ *
+ * The population-count routine is bit-identical to the sample's `popcnt32`,
+ * and descriptor rows are read the same way the sample does
+ * (`matrix_t.buffer.i32`, the full backing buffer reinterpreted as 32-bit
+ * words) — so this can serve as PureCV's numeric reference oracle the same
+ * way the rest of jsfeatNext does (see issue #96).
+ *
+ * Descriptor width must be a multiple of 4 bytes: 32 (ORB) and 64 (TEBLID
+ * p512) both qualify. Unlike `svd_invert`'s non-square guard (#102), this is
+ * not a jsfeat divergence — original jsfeat never shipped a matcher at all —
+ * so there is no parity obligation, only an explicit failure instead of a
+ * silently wrong read past the buffer's actual word count.
+ */
+export declare class bfmatcher extends jsfeatNext {
+    /** Distance norm in use. Only `JSFEAT_CONSTANTS.NORM_HAMMING` (exposed as `jsfeatNext.NORM_HAMMING`) is implemented. */
+    norm_type: number;
+    /** When true, {@link match} keeps only mutually-best (query, train) pairs. */
+    cross_check: boolean;
+    constructor(norm_type?: number, cross_check?: boolean);
+    /** SWAR population count — identical to the sample's `popcnt32`. */
+    private static popcnt32;
+    /**
+     * Physical width of one descriptor row, in bytes.
+     *
+     * NOT `cols`. `matrix_t.allocate` sizes its buffer as
+     * `cols * sizeof(type) * channel * rows`, so a row's storage depends on all
+     * three. Two matrices can share a `cols` and still have different row
+     * widths — a U8/C1 and a U8/C2 with `cols = 32` occupy 32 and 64 bytes —
+     * which is why the stride check below compares this rather than `cols`.
+     */
+    private static rowBytes;
+    /**
+     * Int32-word view over a descriptor matrix's full backing buffer, matching
+     * `matrix_t.buffer.i32` — the same access the original sample uses.
+     *
+     * @throws {Error} if the descriptors are not `U8`, or if a row is not a
+     *         whole number of 4-byte words.
+     */
+    private static words;
+    /**
+     * Int32 views over a query/train PAIR, plus the row stride in words.
+     *
+     * Both matrices are addressed with a single stride, so a width mismatch is
+     * not a mild inconsistency: `train` rows would be read at `ti * word_len`,
+     * an offset computed from the QUERY width. The reads walk across train row
+     * boundaries and, past the end, an out-of-range `Int32Array` index yields
+     * `undefined`, which XOR coerces to 0. The result is a full set of
+     * confident, silently wrong Hamming distances rather than any error — the
+     * matcher would report its best guess over garbage.
+     *
+     * Compares {@link rowBytes}, not `cols`, so a channel or element-type
+     * difference cannot slip past a matching column count.
+     *
+     * @throws {Error} if the row widths differ, or either matrix is rejected by
+     *         {@link words}.
+     */
+    private static pairWords;
+    private static hamming;
+    /**
+     * Nearest-neighbour match between two descriptor sets.
+     *
+     * With {@link cross_check} set, a pair is only kept when it is mutually
+     * best: `query[i]`'s nearest neighbour is `train[j]`, AND `train[j]`'s
+     * nearest neighbour (searched back over `query`) is `query[i]`.
+     *
+     * @param query        Query descriptors (U8, one row per descriptor).
+     * @param train        Train descriptors, same row width as `query`.
+     * @param max_distance Maximum Hamming distance to accept a pair.
+     */
+    match(query: matrix_t, train: matrix_t, max_distance?: number): match_t[];
+    /**
+     * k-nearest matches per query descriptor, each row sorted ascending by
+     * distance.
+     */
+    knnMatch(query: matrix_t, train: matrix_t, k?: number): match_t[][];
+    /**
+     * Lowe's ratio test over the output of `knnMatch(query, train, 2)`: keeps
+     * a query's best match only when it is meaningfully closer than the
+     * second-best (guards against ambiguous, repeated-texture matches).
+     *
+     * An instance method, not `static`, even though it reads no instance
+     * state: static methods are unreachable through a singleton instance
+     * (`jsfeatNext.bfmatcher.ratio_test(...)` — this repo's calling
+     * convention since 0.9.0 — would be `undefined` on a static declaration).
+     * Confirmed empirically before fixing: an earlier draft declared this
+     * `static`, following the #83 prototype literally, and the singleton
+     * simply had no such method at runtime.
+     */
+    ratio_test(knn: match_t[][], ratio?: number): match_t[];
+}

types/src/bfmatcher/match_t.d.ts

@@ -0,0 +1,19 @@
+/** Public shape of {@link match_t}. */
+export interface IMatch_T {
+    /** Index into the query descriptor set. */
+    queryIdx: number;
+    /** Index into the train descriptor set. */
+    trainIdx: number;
+    /** Hamming distance between the two descriptors. */
+    distance: number;
+}
+/**
+ * One descriptor correspondence — the equivalent of OpenCV's `cv::DMatch`.
+ * Produced by {@link bfmatcher.match} / {@link bfmatcher.knnMatch}.
+ */
+export declare class match_t implements IMatch_T {
+    queryIdx: number;
+    trainIdx: number;
+    distance: number;
+    constructor(queryIdx?: number, trainIdx?: number, distance?: number);
+}

types/src/constants/constants.d.ts

@@ -48,6 +48,8 @@ export declare const JSFEAT_CONSTANTS: {
     SVD_U_T: number;
     /** `linalg.svd_decompose` option: return V transposed. */
     SVD_V_T: number;
+    /** `bfmatcher`'s distance norm. Mirrors OpenCV's `cv::NORM_HAMMING` value; the only norm implemented. */
+    NORM_HAMMING: number;
     /** 8-bit unsigned, 1 channel (`U8_t | C1_t`) — grayscale images. */
     U8C1_t: number;
     /** 8-bit unsigned, 3 channels (`U8_t | C3_t`) — RGB images. */

types/src/core/core.d.ts

@@ -15,6 +15,9 @@ import { motion_estimator } from '../motion_estimator/motion_estimator';
 import { optical_flow_lk } from '../optical_flow_lk/optical_flow_lk';
 import { orb } from '../orb/orb';
 import { affine2d, homography2d } from '../motion_model/motion_model';
+import { bfmatcher } from '../bfmatcher/bfmatcher';
+import { match_t } from '../bfmatcher/match_t';
+import { pose_estimator, pose_t } from '../pose_estimator/pose_estimator';
 /**
  * The ONE shared scratch-buffer pool of the library (30 buffers of 2560
  * bytes, growable), matching original jsfeat's design where every module
@@ -60,6 +63,10 @@ export default class jsfeatNext {
     static motion_estimator: motion_estimator;
     static optical_flow_lk: optical_flow_lk;
     static orb: orb;
+    static bfmatcher: bfmatcher;
+    static match_t: typeof match_t;
+    static pose_estimator: typeof pose_estimator;
+    static pose_t: typeof pose_t;
     constructor();
     /** Library version, read from package.json at build time. */
     static VERSION: string;
@@ -81,6 +88,7 @@ export default class jsfeatNext {
     static BOX_BLUR_NOSCALE: number;
     static SVD_U_T: number;
     static SVD_V_T: number;
+    static NORM_HAMMING: number;
     static U8C1_t: number;
     static U8C3_t: number;
     static U8C4_t: number;

types/src/index.d.ts

@@ -31,5 +31,7 @@ export type { keypoint_t } from './keypoint_t/keypoint_t';
 export type { pyramid_t } from './pyramid_t/pyramid_t';
 export type { point_t, IPoint_t } from './point_t/point_t';
 export type { ransac_params_t } from './motion_estimator/ransac_params_t';
+export type { match_t, IMatch_T } from './bfmatcher/match_t';
+export type { pose_t, IPose_T } from './pose_estimator/pose_estimator';
 export type { ICache } from './cache/cache';
 export type { TypedArray, NumericArray, MotionKernel } from './types';

types/src/orb/orb.d.ts

@@ -22,6 +22,42 @@ export declare class orb extends jsfeatNext {
     /** Image-processing helper used for the affine patch warp. */
     imgproc: imgproc;
     constructor();
+    /**
+     * Dominant orientation of the patch around `(px, py)`, in radians — the
+     * "intensity centroid" measure ORB uses to make its descriptors
+     * rotation-invariant.
+     *
+     * The angle points from the patch centre toward its intensity centroid,
+     * computed from the first-order image moments `m01`/`m10` over a circular
+     * patch of radius 15 (see the module-level `u_max` table), then `atan2(m01, m10)`.
+     *
+     * @remarks
+     * **This is a required step before {@link describe}, not an optional one.**
+     * `describe` reads each keypoint's `angle` and rotates the sampling patch by
+     * it; it does *not* compute the orientation itself. A `keypoint_t` left at
+     * the default `angle = -1` is therefore described with the patch rotated by
+     * −1 **radian** (≈ −57°), not "unrotated" — so detectors, which never set
+     * `angle`, must be followed by a pass through this method:
+     *
+     * ```ts
+     * const count = jsfeatNext.yape06.detect(img, corners, 17);
+     * for (let i = 0; i < count; ++i) {
+     *     corners[i].angle = jsfeatNext.orb.ic_angle(img, corners[i].x, corners[i].y);
+     * }
+     * jsfeatNext.orb.describe(img, corners, count, descriptors);
+     * ```
+     *
+     * **Keep `(px, py)` at least 15 px from every image edge.** The patch is
+     * read directly from `src` with no bounds check (matching the original
+     * implementation, and mirroring {@link describe}'s own margin requirement —
+     * pass a detector `border` of ≥ 20 and both are satisfied at once).
+     *
+     * @param src Source grayscale image (single-channel `U8`).
+     * @param px  Keypoint X (column) coordinate, in pixels.
+     * @param py  Keypoint Y (row) coordinate, in pixels.
+     * @returns   Orientation in radians, in `(-π, π]`.
+     */
+    ic_angle(src: matrix_t, px: number, py: number): number;
     /**
      * Computes 256-bit (32-byte) binary descriptors for `count` keypoints.
      * Each keypoint's `angle` is used to rotation-rectify its patch, making