@camstack/addon-vision 0.1.7 → 0.1.9

package/dist/index.d.ts

@@ -0,0 +1,183 @@
+import { BoundingBox, SpatialDetection, IInferenceEngine, DetectionRuntime, DetectionDevice, ModelCatalogEntry, IAddonModelManager, ModelFormat } from '@camstack/types';
+export { default as ObjectDetectionAddon } from './addons/object-detection/index.js';
+export { default as FaceDetectionAddon } from './addons/face-detection/index.js';
+export { default as FaceRecognitionAddon } from './addons/face-recognition/index.js';
+export { default as PlateDetectionAddon } from './addons/plate-detection/index.js';
+export { default as PlateRecognitionAddon } from './addons/plate-recognition/index.js';
+export { default as AudioClassificationAddon } from './addons/audio-classification/index.js';
+export { default as BirdGlobalClassifierAddon } from './addons/bird-global-classifier/index.js';
+export { default as BirdNABirdsClassifierAddon } from './addons/bird-nabirds-classifier/index.js';
+export { default as AnimalClassifierAddon } from './addons/animal-classifier/index.js';
+
+/** Decode JPEG to raw RGB pixels */
+declare function jpegToRgb(jpeg: Buffer): Promise<{
+    data: Buffer;
+    width: number;
+    height: number;
+}>;
+/** Crop a region from a JPEG buffer */
+declare function cropRegion(jpeg: Buffer, roi: BoundingBox): Promise<Buffer>;
+/** Letterbox resize for YOLO: resize preserving aspect ratio, pad to square */
+declare function letterbox(jpeg: Buffer, targetSize: number): Promise<{
+    data: Float32Array;
+    scale: number;
+    padX: number;
+    padY: number;
+    originalWidth: number;
+    originalHeight: number;
+}>;
+/** Resize and normalize to Float32Array */
+declare function resizeAndNormalize(jpeg: Buffer, targetWidth: number, targetHeight: number, normalization: 'zero-one' | 'imagenet' | 'none', layout: 'nchw' | 'nhwc'): Promise<Float32Array>;
+/** Convert raw RGB to grayscale Uint8Array */
+declare function rgbToGrayscale(rgb: Buffer, width: number, height: number): Uint8Array;
+
+interface YoloPostprocessOptions {
+    readonly confidence: number;
+    readonly iouThreshold: number;
+    readonly labels: readonly string[];
+    readonly scale: number;
+    readonly padX: number;
+    readonly padY: number;
+    readonly originalWidth: number;
+    readonly originalHeight: number;
+}
+/** Calculate IoU between two bounding boxes */
+declare function iou(a: BoundingBox, b: BoundingBox): number;
+/** Non-maximum suppression — returns indices of kept boxes (sorted by score desc) */
+declare function nms(boxes: ReadonlyArray<{
+    readonly bbox: BoundingBox;
+    readonly score: number;
+}>, iouThreshold: number): number[];
+/** Full YOLO v8/v9 postprocessing: filter → NMS → scale back to original coords */
+declare function yoloPostprocess(output: Float32Array, numClasses: number, numBoxes: number, options: YoloPostprocessOptions): SpatialDetection[];
+
+interface ScrfdRawOutputs {
+    readonly [key: string]: Float32Array;
+}
+declare function scrfdPostprocess(outputs: ScrfdRawOutputs, confidence: number, inputSize: number, originalWidth: number, originalHeight: number): SpatialDetection[];
+
+/** L2 normalize a vector in-place, returning a new Float32Array */
+declare function l2Normalize(vec: Float32Array): Float32Array;
+/** Cosine similarity between two embeddings (assumes they are already L2-normalized) */
+declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+
+/** Decode CTC output to text.
+ *
+ * Output shape: [1, seqLen, numChars]
+ * Algorithm: argmax per timestep → collapse consecutive duplicates → remove blank (index 0) → join
+ */
+declare function ctcDecode(output: Float32Array, seqLen: number, numChars: number, charset: readonly string[]): {
+    text: string;
+    confidence: number;
+};
+
+interface AudioClassification {
+    readonly className: string;
+    readonly score: number;
+}
+/** Average YAMNET scores across frames, return top classes above threshold */
+declare function yamnetPostprocess(output: Float32Array, numFrames: number, numClasses: number, classNames: readonly string[], minScore: number): AudioClassification[];
+
+declare class NodeInferenceEngine implements IInferenceEngine {
+    private readonly modelPath;
+    private readonly backend;
+    readonly runtime: DetectionRuntime;
+    readonly device: DetectionDevice;
+    private session;
+    constructor(modelPath: string, backend: string);
+    initialize(): Promise<void>;
+    run(input: Float32Array, inputShape: readonly number[]): Promise<Float32Array>;
+    runMultiOutput(input: Float32Array, inputShape: readonly number[]): Promise<Record<string, Float32Array>>;
+    dispose(): Promise<void>;
+}
+
+declare class PythonInferenceEngine implements IInferenceEngine {
+    private readonly pythonPath;
+    private readonly scriptPath;
+    private readonly modelPath;
+    private readonly extraArgs;
+    readonly runtime: DetectionRuntime;
+    readonly device: DetectionDevice;
+    private process;
+    private receiveBuffer;
+    private pendingResolve;
+    private pendingReject;
+    constructor(pythonPath: string, scriptPath: string, runtime: DetectionRuntime, modelPath: string, extraArgs?: readonly string[]);
+    initialize(): Promise<void>;
+    private _tryReceive;
+    /** Send JPEG buffer, receive JSON detection results */
+    runJpeg(jpeg: Buffer): Promise<Record<string, unknown>>;
+    /** IInferenceEngine.run — wraps runJpeg for compatibility */
+    run(_input: Float32Array, _inputShape: readonly number[]): Promise<Float32Array>;
+    /** IInferenceEngine.runMultiOutput — not supported by Python engine (operates on JPEG input) */
+    runMultiOutput(_input: Float32Array, _inputShape: readonly number[]): Promise<Record<string, Float32Array>>;
+    dispose(): Promise<void>;
+}
+
+interface EngineResolverOptions {
+    readonly runtime: DetectionRuntime | 'auto';
+    readonly backend: string;
+    readonly modelEntry: ModelCatalogEntry;
+    readonly modelsDir: string;
+    readonly pythonPath?: string;
+    /** Model service for downloading models. When provided, used instead of raw filesystem probing. */
+    readonly models?: IAddonModelManager;
+}
+interface ResolvedEngine {
+    readonly engine: IInferenceEngine;
+    readonly format: ModelFormat;
+    readonly modelPath: string;
+}
+declare function resolveEngine(options: EngineResolverOptions): Promise<ResolvedEngine>;
+/** Probe which ONNX execution providers are available on this system */
+declare function probeOnnxBackends(): Promise<string[]>;
+
+interface MotionRegion {
+    readonly bbox: BoundingBox;
+    readonly pixelCount: number;
+    readonly intensity: number;
+}
+/**
+ * Detect motion by frame differencing.
+ *
+ * @param current   - Grayscale pixel array for the current frame (Uint8Array, length = width * height)
+ * @param previous  - Grayscale pixel array for the previous frame
+ * @param width     - Frame width in pixels
+ * @param height    - Frame height in pixels
+ * @param threshold - Pixel diff threshold 0-255; differences below this are ignored
+ * @param minArea   - Minimum number of changed pixels for a region to be reported
+ */
+declare function detectMotion(current: Uint8Array, previous: Uint8Array, width: number, height: number, threshold: number, minArea: number): MotionRegion[];
+
+/** Standard files inside every .mlpackage directory bundle */
+declare const MLPACKAGE_FILES: readonly ["Manifest.json", "Data/com.apple.CoreML/model.mlmodel", "Data/com.apple.CoreML/weights/weight.bin"];
+declare const OBJECT_DETECTION_MODELS: readonly ModelCatalogEntry[];
+
+declare const FACE_DETECTION_MODELS: readonly ModelCatalogEntry[];
+
+declare const FACE_RECOGNITION_MODELS: readonly ModelCatalogEntry[];
+
+declare const PLATE_DETECTION_MODELS: readonly ModelCatalogEntry[];
+
+declare const PLATE_RECOGNITION_MODELS: readonly ModelCatalogEntry[];
+
+/**
+ * General-purpose OCR models for scene text recognition in camera feeds.
+ * These complement the plate-specific PaddleOCR models for broader text detection
+ * (signs, labels, addresses, etc.).
+ */
+declare const GENERAL_OCR_MODELS: readonly ModelCatalogEntry[];
+
+declare const AUDIO_CLASSIFICATION_MODELS: readonly ModelCatalogEntry[];
+
+declare const SEGMENTATION_MODELS: readonly ModelCatalogEntry[];
+
+declare const BIRD_SPECIES_MODELS: readonly ModelCatalogEntry[];
+declare const BIRD_NABIRDS_MODELS: readonly ModelCatalogEntry[];
+declare const ANIMAL_TYPE_MODELS: readonly ModelCatalogEntry[];
+
+declare const VEHICLE_TYPE_MODELS: readonly ModelCatalogEntry[];
+
+declare const SEGMENTATION_REFINER_MODELS: readonly ModelCatalogEntry[];
+
+export { ANIMAL_TYPE_MODELS, AUDIO_CLASSIFICATION_MODELS, BIRD_NABIRDS_MODELS, BIRD_SPECIES_MODELS, type EngineResolverOptions, FACE_DETECTION_MODELS, FACE_RECOGNITION_MODELS, GENERAL_OCR_MODELS, MLPACKAGE_FILES, type MotionRegion, NodeInferenceEngine, OBJECT_DETECTION_MODELS, PLATE_DETECTION_MODELS, PLATE_RECOGNITION_MODELS, PythonInferenceEngine, type ResolvedEngine, SEGMENTATION_MODELS, SEGMENTATION_REFINER_MODELS, VEHICLE_TYPE_MODELS, cosineSimilarity, cropRegion, ctcDecode, detectMotion, iou, jpegToRgb, l2Normalize, letterbox, nms, probeOnnxBackends, resizeAndNormalize, resolveEngine, rgbToGrayscale, scrfdPostprocess, yamnetPostprocess, yoloPostprocess };