web-sdk-pp-detection 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,617 @@
+type Backend = "wasm" | "webgpu";
+type BackendPreference = Backend | "auto";
+type ExecutionMode = "main" | "worker";
+type Precision = "fp32" | "fp16" | "int8" | "int4" | "fp8";
+type ModelSourceKind = "git-lfs" | "huggingface" | "modelscope" | "custom";
+interface ModelIdentity {
+    readonly id: string;
+    readonly version: string;
+}
+interface ModelSource {
+    readonly kind: ModelSourceKind;
+    readonly repository: string;
+    readonly revision: string;
+    readonly path: string;
+    readonly downloadUrl: string;
+    readonly bytes: number;
+    readonly sha256: string;
+}
+interface ModelVariant {
+    readonly id: string;
+    readonly precision: Precision;
+    readonly quantization?: string | null;
+    readonly backends: readonly Backend[];
+    readonly status?: "stable" | "labs" | "blocked";
+}
+interface DetectionModelVariant extends ModelVariant {
+    readonly opset: number;
+    readonly bytes: number;
+    readonly parameterCount: number | null;
+    readonly sources: readonly ModelSource[];
+}
+interface TensorContract {
+    readonly name: string;
+    readonly shape: readonly number[];
+    readonly dtype: string;
+}
+interface DetectionPreprocessing {
+    readonly size: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly rescaleFactor: number;
+    readonly resizeMode?: "letterbox" | "stretch";
+    readonly interpolation?: "bilinear" | "bicubic";
+    readonly mean?: readonly number[];
+    readonly std?: readonly number[];
+    readonly doResize?: boolean;
+    readonly doRescale?: boolean;
+    readonly doNormalize?: boolean;
+}
+interface DetectionPostprocessing {
+    readonly type: "nms";
+    readonly scoreThreshold: number;
+    readonly iouThreshold: number;
+    readonly matrixCoordinates?: "pixels" | "normalized";
+    readonly queryCoordinates?: "pixels" | "normalized";
+    readonly queryBoxFormat?: "cxcywh" | "xyxy";
+}
+interface RuntimeDetectionManifest {
+    readonly schemaVersion: 1;
+    readonly model: ModelIdentity;
+    readonly input: TensorContract;
+    readonly outputs: readonly TensorContract[];
+    readonly preprocessing: DetectionPreprocessing;
+    readonly postprocessing: DetectionPostprocessing;
+    readonly labels: readonly string[];
+    readonly variants: readonly DetectionModelVariant[];
+}
+interface DetectionManifest {
+    readonly id: string;
+    readonly version: string;
+    readonly variants?: readonly ModelVariant[];
+}
+type ModelBackend = Backend;
+type ModelPrecision = Precision;
+interface ModelManifestMetadata {
+    readonly architecture: string;
+    readonly id: string;
+    readonly modelType: string;
+    readonly parameterCount: number | null;
+    readonly version: string;
+}
+interface ModelManifestSource {
+    readonly files: Readonly<Record<string, string>>;
+    readonly license: string;
+    readonly name: string;
+    readonly url: string;
+}
+interface ModelManifestVariant {
+    readonly backendCompatibility: readonly ModelBackend[];
+    readonly bytes: number;
+    readonly filename: string;
+    readonly id: string;
+    readonly opset: number;
+    readonly precision: ModelPrecision;
+    readonly quantization: string | null;
+    readonly sha256: string;
+    readonly url: string;
+    readonly validation: Readonly<{
+        included: boolean;
+        pass: boolean;
+        report: string;
+    }>;
+}
+interface ModelManifest {
+    readonly input: TensorContract;
+    readonly labels: readonly string[];
+    readonly minSdkVersion: string;
+    readonly model: ModelManifestMetadata;
+    readonly outputs: readonly TensorContract[];
+    readonly preprocessing: Readonly<{
+        doNormalize: boolean;
+        doRescale: boolean;
+        doResize: boolean;
+        readonly resizeMode?: "letterbox" | "stretch";
+        readonly interpolation?: "bilinear" | "bicubic";
+        imageMean: readonly [number, number, number];
+        imageStd: readonly [number, number, number];
+        resample: 2 | 3;
+        rescaleFactor: number;
+        size: Readonly<{
+            height: number;
+            width: number;
+        }>;
+    }>;
+    readonly schemaVersion: 1;
+    readonly source: ModelManifestSource;
+    readonly variantPriority: readonly string[];
+    readonly variants: readonly ModelManifestVariant[];
+}
+type PPDetectionModel = string | RuntimeDetectionManifest | ModelManifest | Readonly<{
+    data: ArrayBuffer;
+    manifest: RuntimeDetectionManifest | ModelManifest;
+}>;
+type PPDetectionProgressPhase = "capabilities" | "manifest" | "model" | "session" | "fallback" | "ready" | "preprocess" | "inference" | "postprocess";
+interface PPDetectionProgressEvent {
+    readonly phase: PPDetectionProgressPhase;
+    readonly status: "start" | "progress" | "complete";
+    readonly loadedBytes?: number;
+    readonly totalBytes?: number;
+    readonly fallback?: PPDetectionFallback;
+}
+interface CreatePPDetectionOptions {
+    readonly allowFallback?: boolean;
+    readonly backend?: BackendPreference;
+    readonly cache?: boolean | "memory" | "indexeddb";
+    readonly executionMode?: ExecutionMode;
+    readonly manifest?: RuntimeDetectionManifest;
+    readonly model?: PPDetectionModel;
+    readonly onProgress?: (event: PPDetectionProgressEvent) => void;
+    readonly ort?: Readonly<{
+        module?: unknown;
+        wasm?: Readonly<{
+            paths?: string;
+            numThreads?: number;
+        }>;
+    }>;
+    readonly precision?: Precision | "auto";
+    readonly signal?: AbortSignal;
+    readonly source?: ModelSourceKind | "auto";
+}
+interface DetectionCapabilities {
+    readonly webgpu: boolean;
+    readonly worker: boolean;
+    readonly offscreenCanvas: boolean;
+    readonly wasmSimd: boolean;
+    readonly wasmThreads: boolean;
+}
+interface RuntimeInfo {
+    readonly requestedBackend: BackendPreference;
+    readonly actualBackend: Backend;
+    readonly requestedPrecision: Precision;
+    readonly actualPrecision: Precision;
+    readonly executionMode: ExecutionMode;
+}
+interface TimingBreakdown {
+    readonly modelDownloadMs?: number;
+    readonly modelCacheReadMs?: number;
+    readonly integrityMs?: number;
+    readonly sessionMs?: number;
+    readonly inferenceMs?: number;
+    readonly totalMs?: number;
+}
+interface DetectionTimings {
+    readonly decodeMs: number;
+    readonly preprocessMs: number;
+    readonly inferenceMs: number;
+    readonly postprocessMs: number;
+    readonly totalMs: number;
+}
+interface DetectionBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly xMin: number;
+    readonly yMin: number;
+    readonly xMax: number;
+    readonly yMax: number;
+}
+interface DetectionPoint {
+    readonly x: number;
+    readonly y: number;
+}
+interface Detection {
+    readonly index: number;
+    readonly classId: number;
+    readonly labelId: number;
+    readonly label: string;
+    readonly score: number;
+    readonly box: DetectionBox;
+    readonly polygon: readonly DetectionPoint[];
+}
+interface DetectOptions {
+    readonly threshold?: number;
+    readonly classThresholds?: Readonly<Record<string, number>>;
+    readonly signal?: AbortSignal;
+    readonly timestampMs?: number;
+    readonly metadata?: unknown;
+}
+interface PPDetectionFallback {
+    readonly cause: unknown;
+    readonly code: string;
+    readonly message: string;
+    readonly precision: Precision;
+    readonly provider: Backend;
+    readonly stage: string;
+    readonly variantId: string;
+}
+interface PPDetectionRuntimeInfo {
+    readonly requestedBackend: BackendPreference;
+    readonly backend: Backend;
+    readonly precision: Precision;
+    readonly mode: ExecutionMode;
+    readonly fallbacks: readonly PPDetectionFallback[];
+    readonly capabilities: DetectionCapabilities;
+}
+interface PPDetectionModelInfo {
+    readonly id: string;
+    readonly version: string;
+    readonly variantId: string;
+    readonly precision: Precision;
+    readonly bytes: number;
+    readonly parameterCount: number | null;
+    readonly opset: number;
+    readonly source: PPDetectionModelSourceInfo;
+}
+interface PPDetectionModelSourceInfo {
+    readonly kind: ModelSourceKind;
+    readonly revision: string;
+    readonly bytes: number;
+    readonly sha256: string;
+}
+interface PPDetectionLoadTimings {
+    readonly modelDownloadMs?: number;
+    readonly modelCacheReadMs?: number;
+    readonly integrityMs?: number;
+    readonly sessionMs: number;
+    readonly totalMs: number;
+}
+interface PPDetectionResult {
+    readonly detections: readonly Detection[];
+    readonly image: Readonly<{
+        input: Readonly<{
+            width: number;
+            height: number;
+        }>;
+        original: Readonly<{
+            width: number;
+            height: number;
+        }>;
+    }>;
+    readonly model: PPDetectionModelInfo;
+    readonly runtime: PPDetectionRuntimeInfo;
+    readonly timings: DetectionTimings;
+    readonly frame?: Readonly<{
+        timestampMs?: number;
+        metadata?: unknown;
+    }>;
+}
+interface ModelInfo {
+    readonly id: string;
+    readonly version: string;
+    readonly variantId: string;
+    readonly precision: Precision;
+    readonly bytes?: number;
+    readonly parameterCount?: number | null;
+}
+
+interface CapabilityProbeOptions {
+    readonly global?: typeof globalThis;
+}
+declare function probeCapabilities(options?: CapabilityProbeOptions): DetectionCapabilities;
+
+interface ImageRaster {
+    readonly width: number;
+    readonly height: number;
+    readonly rgba: Uint8ClampedArray;
+}
+type ImageSource = Blob | File | ImageBitmap | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | OffscreenCanvas | ImageData | VideoFrame | ImageRaster;
+interface DecodedImage extends ImageRaster {
+    readonly decodeMs: number;
+}
+
+interface DrawableImage {
+    readonly width?: number;
+    readonly height?: number;
+    readonly naturalWidth?: number;
+    readonly naturalHeight?: number;
+    readonly videoWidth?: number;
+    readonly videoHeight?: number;
+    readonly displayWidth?: number;
+    readonly displayHeight?: number;
+    close?(): void;
+}
+interface RasterContext {
+    drawImage(source: unknown, dx: number, dy: number): void;
+    getImageData(x: number, y: number, width: number, height: number): {
+        data: Uint8ClampedArray;
+    };
+}
+interface RasterCanvas {
+    getContext(type: "2d", options?: CanvasRenderingContext2DSettings): RasterContext | null;
+}
+interface DecodeImageEnvironment {
+    readonly createCanvas?: (width: number, height: number) => RasterCanvas;
+    readonly createImageBitmap?: (source: Blob) => Promise<DrawableImage>;
+    readonly signal?: AbortSignal;
+    readonly now?: () => number;
+}
+
+interface InferenceInput {
+    readonly inputName: string;
+    readonly data: Float32Array;
+    readonly dims: readonly number[];
+}
+interface DetectionExecutor {
+    run(input: InferenceInput, signal?: AbortSignal): Promise<unknown>;
+    dispose(): Promise<void>;
+}
+interface PPDetectionDetectorOptions {
+    readonly capabilities: DetectionCapabilities;
+    readonly manifest: RuntimeDetectionManifest;
+    readonly model: PPDetectionModelInfo;
+    readonly runtime: PPDetectionRuntimeInfo;
+    readonly loadTimings: PPDetectionLoadTimings;
+    readonly loadExecutor: (signal?: AbortSignal) => Promise<DetectionExecutor>;
+    readonly decodeEnvironment?: Omit<DecodeImageEnvironment, "signal">;
+    readonly now?: () => number;
+    readonly onProgress?: (event: PPDetectionProgressEvent) => void;
+    readonly clearCurrentModelCache?: () => Promise<void>;
+    readonly clearAllCache?: () => Promise<void>;
+    readonly getCacheEstimate?: () => Promise<{
+        bytes: number;
+        entries: number;
+    }>;
+    readonly disposeResources?: () => Promise<void> | void;
+}
+declare class PPDetectionDetectorImplementation {
+    private readonly options;
+    readonly capabilities: DetectionCapabilities;
+    readonly manifest: RuntimeDetectionManifest;
+    readonly model: PPDetectionModelInfo;
+    readonly runtime: PPDetectionRuntimeInfo;
+    readonly loadTimings: PPDetectionLoadTimings;
+    private readonly clock;
+    private executor?;
+    private loadPromise?;
+    private disposePromise?;
+    private queue;
+    private disposed;
+    constructor(options: PPDetectionDetectorOptions);
+    load(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    detect(input: ImageSource, options?: DetectOptions): Promise<PPDetectionResult>;
+    getCacheEstimate(): Promise<{
+        bytes: number;
+        entries: number;
+    }>;
+    clearCurrentModelCache(): Promise<void>;
+    clearAllCache(): Promise<void>;
+    clearModelCache(): Promise<void>;
+    dispose(): Promise<void>;
+    private detectOnce;
+}
+type PPDetectionDetector = PPDetectionDetectorImplementation;
+
+type PPDetectionErrorCode = "CAPABILITY_UNSUPPORTED" | "INVALID_INPUT" | "INVALID_MANIFEST" | "MODEL_INCOMPATIBLE" | "MODEL_SOURCE_UNAVAILABLE" | "MODEL_DOWNLOAD_FAILED" | "MODEL_INTEGRITY_FAILED" | "SESSION_CREATE_FAILED" | "INFERENCE_FAILED" | "OUT_OF_MEMORY" | "ABORTED" | "DISPOSED";
+declare class PPDetectionError extends Error {
+    readonly code: PPDetectionErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: PPDetectionErrorCode, message: string, details?: Readonly<Record<string, unknown>>, options?: ErrorOptions);
+}
+
+interface SelectExecutionOptions {
+    readonly backend?: BackendPreference;
+    readonly precision?: Precision;
+    readonly executionMode?: ExecutionMode;
+    readonly allowFallback?: boolean;
+}
+interface ExecutionCandidate {
+    readonly variantId: string;
+    readonly backend: Backend;
+    readonly precision: Precision;
+    readonly executionMode: ExecutionMode;
+}
+type ExecutionPlan = RuntimeInfo & {
+    readonly variantId: string;
+    readonly candidates: readonly ExecutionCandidate[];
+};
+declare function selectExecutionPlan(options: SelectExecutionOptions, capabilities: DetectionCapabilities, manifest: DetectionManifest): ExecutionPlan;
+
+interface OrtInferenceSession {
+    run(feeds: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+    release?(): Promise<void> | void;
+}
+interface OrtModule {
+    readonly env: {
+        readonly wasm?: Record<string, unknown>;
+    };
+    readonly InferenceSession: {
+        create(model: ArrayBuffer, options: Record<string, unknown>): Promise<OrtInferenceSession>;
+    };
+    readonly Tensor?: new (type: string, data: unknown, dims: readonly number[]) => unknown;
+}
+interface OrtSessionHandle {
+    readonly plan: ExecutionPlan;
+    readonly sessionMs: number;
+    run(feeds: Record<string, unknown>, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<unknown>;
+    dispose(): Promise<void>;
+}
+interface CreateOrtSessionOptions {
+    readonly ort?: OrtModule;
+    readonly loadOrt?: () => Promise<OrtModule>;
+    readonly wasmPaths?: string;
+    readonly numThreads?: number;
+    readonly sessionOptions?: Readonly<Record<string, unknown>>;
+}
+declare function createOrtSession(modelBytes: ArrayBuffer, plan: ExecutionPlan, options?: CreateOrtSessionOptions): Promise<OrtSessionHandle>;
+
+interface WorkerOrtOptions {
+    readonly wasmPaths?: string;
+    readonly numThreads?: number;
+}
+type WorkerRequest = {
+    readonly id: string;
+    readonly type: "load";
+    readonly modelBytes: ArrayBuffer;
+    readonly plan: ExecutionPlan;
+    readonly ort?: WorkerOrtOptions;
+} | {
+    readonly id: string;
+    readonly type: "run";
+    readonly input: unknown;
+} | {
+    readonly id: string;
+    readonly type: "cancel";
+    readonly requestId: string;
+} | {
+    readonly id: string;
+    readonly type: "dispose";
+};
+type WorkerResponse = {
+    readonly id: string;
+    readonly type: "progress";
+    readonly phase: string;
+    readonly status: string;
+    readonly loadedBytes?: number;
+    readonly totalBytes?: number;
+} | {
+    readonly id: string;
+    readonly type: "result";
+    readonly result: unknown;
+} | {
+    readonly id: string;
+    readonly type: "error";
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details?: Record<string, unknown>;
+    };
+};
+
+declare function parseDetectionManifest(value: unknown): RuntimeDetectionManifest;
+
+declare function parseModelManifest(value: unknown): ModelManifest;
+declare function adaptModelManifest(manifest: ModelManifest): RuntimeDetectionManifest;
+
+type ModelSourceSelection = ModelSourceKind | "auto";
+interface ResolveModelAssetSelection {
+    readonly variantId?: string;
+    readonly sourceKind?: ModelSourceSelection;
+}
+interface ResolvedModelAsset {
+    readonly model: ModelIdentity;
+    readonly variant: DetectionModelVariant;
+    readonly source: ModelSource;
+}
+declare function resolveModelAsset(selection: ResolveModelAssetSelection, manifest: RuntimeDetectionManifest): ResolvedModelAsset;
+
+type ModelFetcher = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+interface ModelDownloadProgress {
+    readonly loadedBytes: number;
+    readonly totalBytes?: number;
+}
+interface LoadModelAssetOptions {
+    readonly fetcher?: ModelFetcher;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: ModelDownloadProgress) => void;
+}
+interface ModelBytes {
+    readonly bytes: ArrayBuffer;
+    readonly timings: Pick<TimingBreakdown, "modelDownloadMs" | "integrityMs">;
+}
+declare function loadModelAsset(asset: ResolvedModelAsset, options?: LoadModelAssetOptions): Promise<ModelBytes>;
+
+interface CacheEstimate {
+    readonly bytes: number;
+    readonly entries: number;
+}
+interface ModelCache {
+    get(key: string): Promise<ArrayBuffer | undefined>;
+    put(key: string, bytes: ArrayBuffer): Promise<void>;
+    clearCurrent(key: string): Promise<void>;
+    clearAll(): Promise<void>;
+    estimate(): Promise<CacheEstimate>;
+    close?(): Promise<void> | void;
+}
+
+interface ModelManagerOptions {
+    readonly fetcher?: ModelFetcher;
+    readonly cache?: "memory" | "indexeddb" | false | ModelCache;
+}
+interface LoadManagedModelOptions {
+    readonly manifest: unknown;
+    readonly variantId?: string;
+    readonly sourceKind?: ModelSourceSelection;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: ModelDownloadProgress) => void;
+}
+interface ModelSourceFailure {
+    readonly kind: ModelSourceKind;
+    readonly code: string;
+    readonly message: string;
+}
+interface LoadedManagedModel {
+    readonly bytes: ArrayBuffer;
+    readonly manifest: RuntimeDetectionManifest;
+    readonly variant: DetectionModelVariant;
+    readonly source: ModelSource;
+    readonly cacheKey: string;
+    readonly fromCache: boolean;
+    readonly failures: readonly ModelSourceFailure[];
+    readonly timings: TimingBreakdown;
+}
+declare class ModelManager {
+    private readonly fetcher?;
+    private readonly cache;
+    private readonly lifecycle;
+    private readonly activeLoads;
+    private currentKey?;
+    private disposed;
+    private disposePromise?;
+    constructor(options?: ModelManagerOptions);
+    cacheKey(variant: DetectionModelVariant, source: ModelSource, model?: ModelIdentity): string;
+    load(options: LoadManagedModelOptions): Promise<LoadedManagedModel>;
+    private loadActive;
+    estimate(): Promise<CacheEstimate>;
+    getCacheEstimate(): Promise<CacheEstimate>;
+    clearCurrentModelCache(): Promise<void>;
+    clearAllCache(): Promise<void>;
+    dispose(): Promise<void>;
+}
+
+declare class MemoryModelCache implements ModelCache {
+    private readonly entries;
+    get(key: string): Promise<ArrayBuffer | undefined>;
+    put(key: string, bytes: ArrayBuffer): Promise<void>;
+    clearCurrent(key: string): Promise<void>;
+    clearAll(): Promise<void>;
+    estimate(): Promise<CacheEstimate>;
+    close(): Promise<void>;
+}
+
+interface IndexedDBModelCacheOptions {
+    readonly indexedDB?: IDBFactory;
+    readonly databaseName?: string;
+}
+declare class IndexedDBModelCache implements ModelCache {
+    private readonly factory;
+    private readonly databaseName;
+    private database?;
+    constructor(options?: IndexedDBModelCacheOptions);
+    get(key: string): Promise<ArrayBuffer | undefined>;
+    put(key: string, bytes: ArrayBuffer): Promise<void>;
+    clearCurrent(key: string): Promise<void>;
+    clearAll(): Promise<void>;
+    estimate(): Promise<CacheEstimate>;
+    close(): Promise<void>;
+    private open;
+    private request;
+}
+
+declare global {
+    var __PPDETECTION_SCRIPT_URL__: string | undefined;
+}
+declare const CURRENT_SDK_VERSION = "0.1.0";
+
+declare function probePPDetectionCapabilities(options?: CapabilityProbeOptions): DetectionCapabilities;
+
+declare function createPPDetection(options?: CreatePPDetectionOptions): Promise<PPDetectionDetectorImplementation>;
+declare function clearModelCache(): Promise<void>;
+
+export { type Backend, type BackendPreference, CURRENT_SDK_VERSION, type CacheEstimate, type CapabilityProbeOptions, type CreateOrtSessionOptions, type CreatePPDetectionOptions, type DecodedImage, type DetectOptions, type Detection, type DetectionBox, type DetectionCapabilities, type DetectionManifest, type DetectionModelVariant, type DetectionPoint, type DetectionPostprocessing, type DetectionPreprocessing, type DetectionTimings, type ExecutionCandidate, type ExecutionMode, type ExecutionPlan, type ImageRaster, type ImageSource, IndexedDBModelCache, type IndexedDBModelCacheOptions, type LoadManagedModelOptions, type LoadModelAssetOptions, type LoadedManagedModel, MemoryModelCache, type ModelBackend, type ModelBytes, type ModelCache, type ModelDownloadProgress, type ModelFetcher, type ModelInfo, ModelManager, type ModelManagerOptions, type ModelManifest, type ModelManifestMetadata, type ModelManifestSource, type ModelManifestVariant, type ModelPrecision, type ModelSource, type ModelSourceFailure, type ModelSourceKind, type ModelSourceSelection, type ModelVariant, type OrtModule, type OrtSessionHandle, type PPDetectionDetector, PPDetectionError, type PPDetectionErrorCode, type PPDetectionFallback, type PPDetectionLoadTimings, type PPDetectionModel, type PPDetectionModelInfo, type PPDetectionModelSourceInfo, type PPDetectionProgressEvent, type PPDetectionResult, type PPDetectionRuntimeInfo, type Precision, type ResolveModelAssetSelection, type ResolvedModelAsset, type RuntimeDetectionManifest, type RuntimeInfo, type SelectExecutionOptions, type TensorContract, type TimingBreakdown, type WorkerOrtOptions, type WorkerRequest, type WorkerResponse, adaptModelManifest, clearModelCache, createOrtSession, createPPDetection, loadModelAsset, parseDetectionManifest, parseModelManifest, probeCapabilities, probePPDetectionCapabilities, resolveModelAsset, selectExecutionPlan };