README
moonbit-klt-tracker
Deterministic sparse KLT feature tracking for grayscale frame buffers.
computer-vision
klt
lucas-kanade
optical-flow
tracking
Author
Version
0.1.4
License
Apache-2.0
Repository
Last updated
2 months ago
Downloads
54
#moonbit-klt-tracker
moonbit-klt-tracker is a deterministic MoonBit library and CLI for sparse feature tracking on ordered grayscale frames. It combines checked image buffers, Shi-Tomasi features, pyramidal Lucas-Kanade tracking, trajectory lifecycle management, validation, reporting, and stable JSON/CSV/NDJSON contracts.
#Highlights
- deterministic integer-backed grayscale frames and image pyramids;
- finite-safe math, interpolation, filtering, normalization, tiling, and region analysis;
- Shi-Tomasi selection, pyramidal KLT tracking, forward-backward validation, and recovery diagnostics;
- immutable trajectory, motion-model, quality, segmentation, and event APIs;
- schema-aware table/stream contracts and analytics reports;
- a small native CLI with checked manifests and golden fixtures.
#Quick start
moon run src/cli -- detect --manifest tests/fixtures/translation-large/manifest.json
moon run src/cli -- inspect --manifest tests/fixtures/translation-large/manifest.json
moon run src/cli -- track --manifest tests/fixtures/translation-large/manifest.json --json trajectory.json --csv trajectory.csvThe manifest contains a frames array. Frames must share dimensions and contain byte-valued grayscale pixels. detect prints a count, inspect prints a deterministic report, and track writes only the requested JSON/CSV outputs. The checked-in translation fixture produces both active and lost observations, making the lifecycle result visible in a minimal end-to-end run. Duplicate flags, unknown flags, missing manifests, and invalid output combinations are rejected.
#Package map
| Package | Responsibility |
|---|---|
| math | vectors, matrices, statistics, geometry, intervals, and series utilities |
| image | frames, gradients, pyramids, interpolation, filters, normalization, tiles, and regions |
| features | Shi-Tomasi candidates, deterministic selection, spacing, and score summaries |
| klt | single-level and pyramidal Lucas-Kanade tracking |
| motion | translation/affine/projective models, robust losses, fitting, and residuals |
| validation | forward-backward checks, thresholds, typed diagnostics, and batch gates |
| tracking | lifecycle, health, recovery candidates, timelines, checkpoints, and sessions |
| trajectory | immutable samples, resampling, smoothing, metrics, windows, and segmentation |
| formats | JSON/CSV models plus table, stream, column, and schema contracts |
| analytics | aggregation, ranking, dashboards, filters, reports, and NDJSON contracts |
| cli_core / cli | target-independent commands and the native executable |
#Data and API contracts
The library APIs are pure where practical and return typed errors for invalid dimensions, non-finite values, insufficient samples, and incompatible schemas. analytics.analyze(document, config) produces deterministic per-track summaries, quality totals, and lifecycle events. analytics.export_ndjson(analysis) emits a newline-terminated stream with one header, summaries ordered by track ID, and events ordered by frame, track ID, and kind.
#Benchmarks
The checked-in benchmark uses a fixed 128 × 96 LCG-generated texture and a one-pixel horizontal translation. It measures detector and tracker paths separately. Captured output and reproduction details are in docs/performance.md; these numbers are fixture- and toolchain-specific, not universal performance claims.
#Development
node --test tools/verify-docs.test.mjs
node tools/verify-docs.mjs
moon fmt --check
moon check --target all --deny-warn
moon test --target wasm-gc --deny-warn
moon bench benchmarks --target wasm-gc --release --deny-warn
moon infoSee CONTRIBUTING.md, CHANGELOG.md, architecture notes, algorithm notes, performance evidence, references, and provenance.
#Scope and limitations
This is sparse, short-range point tracking, not a video runtime. Callers provide decoded grayscale frames. The default tracker assumes local brightness constancy and fixed source gradients. It does not provide dense flow, codecs, capture devices, calibration, rolling-shutter modeling, GPU execution, or a GUI.
#License
Apache-2.0. See LICENSE.
Source Files
Install
Download zipDeterministic sparse KLT feature tracking for grayscale frame buffers.
computer-visionkltlucas-kanadeoptical-flowtracking
Apache-2.0
Updated 2 months ago
54 downloads