@lumy-pack/scene-sieve 0.1.0 → 0.2.0

package/dist/constants/pipeline-defaults.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Default values for scene-sieve pipeline options (frame count, threshold, extraction, segmentation).
+ */
+export declare const DEFAULT_COUNT = 20;
+export declare const DEFAULT_THRESHOLD = 0.5;
+export declare const DEFAULT_FPS = 5;
+export declare const DEFAULT_SCALE = 720;
+export declare const DEFAULT_QUALITY = 80;
+export declare const DEFAULT_MAX_FRAMES = 300;
+export declare const DEFAULT_MAX_SEGMENT_DURATION = 300;
+export declare const DEFAULT_SEGMENT_CONCURRENCY = 2;
+export declare const IOU_THRESHOLD = 0.9;
+export declare const ANIMATION_FRAME_THRESHOLD = 5;

package/dist/core/{analyzer.d.ts → analyzer/analyzer.d.ts}

@@ -1,5 +1,5 @@
-import type { AnalysisResult, AnimationMetadata, BoundingBox, ProcessContext } from '../types/index.js';
-import type { Point2D } from './dbscan.js';
+import type { AnalysisResult, AnimationMetadata, BoundingBox, ProcessContext } from '../../types/index.js';
+import type { Point2D } from './clustering/dbscan.js';
 type CvLib = typeof import('@techstark/opencv-js');
 export declare function preprocessFrame(framePath: string, scale: number): Promise<{
     data: Uint8Array;
@@ -19,10 +19,6 @@ export declare class IoUTracker {
     flushAndGetAnimations(): AnimationMetadata[];
     getAnimationWeight(boxIndex: number, boxes: BoundingBox[]): number;
 }
-export interface AKAZEResult {
-    sNew: Point2D[];
-    sLoss: Point2D[];
-}
 /**
  * Pixel-level difference fallback for AKAZE blind spots.
  *
@@ -37,6 +33,12 @@ export interface AKAZEResult {
  * 3. threshold → binary mask of significant changes
  * 4. findContours → bounding rects of changed regions
  * 5. Grid sampling within each bounding rect → Point2D[]
+ *
+ * @param cvLib - Initialized OpenCV runtime shared by the analyzer.
+ * @param frame1 - Previous grayscale frame, with the same dimensions as frame2.
+ * @param frame2 - Next grayscale frame, with the same dimensions as frame1.
+ * @returns Grid-sampled points from changed regions.
+ * @throws Propagates allocation or OpenCV errors after releasing acquired handles.
  */
 export declare function computePixelDiff(cvLib: CvLib, frame1: {
     data: Uint8Array;
@@ -57,6 +59,9 @@ export declare function computeInformationGain(clusters: BoundingBox[], clusterP
  * 2. DBSCAN Spatial Clustering
  * 3. Spatio-temporal IoU Tracking
  * 4. G(t) Information Gain Scoring
+ * @param ctx - Frames, analysis options, and the progress callback for this run.
+ * @returns Adjacent scores and tracked animations in analysis coordinates.
+ * @throws Propagates runtime errors and rejects total failure of two or more pairs after cleanup.
  */
 export declare function analyzeFrames(ctx: ProcessContext): Promise<AnalysisResult>;
 export {};

package/dist/core/{dbscan.d.ts → analyzer/clustering/dbscan.d.ts}

@@ -1,4 +1,4 @@
-import type { DBSCANResult } from '../types/index.js';
+import type { DBSCANResult } from '../../../types/index.js';
 export interface Point2D {
     x: number;
     y: number;

package/dist/core/analyzer/constants/vision-tuning.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tuning constants for the OpenCV-based vision analysis pipeline (DBSCAN, feature matching, pixel-diff fallback).
+ */
+export declare const OPENCV_BATCH_SIZE = 10;
+export declare const DBSCAN_ALPHA = 0.03;
+export declare const DBSCAN_MIN_PTS = 4;
+export declare const DECAY_LAMBDA = 0.95;
+export declare const MATCH_DISTANCE_THRESHOLD = 0.25;
+export declare const PIXELDIFF_GAUSSIAN_KERNEL = 3;
+export declare const PIXELDIFF_BINARY_THRESHOLD = 30;
+export declare const PIXELDIFF_CONTOUR_MIN_AREA = 100;
+export declare const PIXELDIFF_SAMPLE_SPACING = 8;

package/dist/core/analyzer/features/feature-diff.d.ts

@@ -0,0 +1,14 @@
+import type { Point2D } from '../clustering/dbscan.js';
+import type { FrameFeatures } from './frame-features.js';
+/** Initialized OpenCV runtime supplied by the analyzer. */
+type CvLib = typeof import('@techstark/opencv-js');
+/**
+ * Match prev to next with Hamming k=2, crossCheck=false and strict ratio 0.25.
+ * @param cvLib - Initialized OpenCV runtime.
+ * @param prev - Previous frame's live features, owned by the caller.
+ * @param next - Next frame's live features, owned by the caller.
+ * @returns Unmatched next-frame coordinates without changing input ownership.
+ * @throws Propagates matching errors after releasing temporary native handles.
+ */
+export declare function computeNewPoints(cvLib: CvLib, prev: FrameFeatures, next: FrameFeatures): Point2D[];
+export {};

package/dist/core/analyzer/features/frame-features.d.ts

@@ -0,0 +1,32 @@
+import type { AKAZE, KeyPointVector, Mat } from '@techstark/opencv-js';
+/** Initialized OpenCV runtime supplied by the analyzer. */
+type CvLib = typeof import('@techstark/opencv-js');
+/** Grayscale bytes whose length matches width times height. */
+type PreprocessedFrame = {
+    data: Uint8Array;
+    width: number;
+    height: number;
+};
+/** Caller-owned AKAZE features for one frame; delete releases both handles once. */
+export interface FrameFeatures {
+    /** Width of the analyzed grayscale image. */
+    readonly width: number;
+    /** Height of the analyzed grayscale image. */
+    readonly height: number;
+    /** Keypoints in descriptor row order. */
+    readonly keypoints: KeyPointVector;
+    /** Descriptor rows equal keypoints.size(). */
+    readonly descriptors: Mat;
+    /** Release both native handles; repeated calls have no effect. */
+    delete(): void;
+}
+/**
+ * Detect one frame's features without retaining its image or mask.
+ * @param cvLib - Initialized OpenCV runtime.
+ * @param akaze - Detector owned and released by the caller.
+ * @param frame - Grayscale bytes with matching width and height.
+ * @returns Feature handles that the caller must delete.
+ * @throws Propagates native errors after releasing partial allocations.
+ */
+export declare function computeFrameFeatures(cvLib: CvLib, akaze: AKAZE, frame: PreprocessedFrame): FrameFeatures;
+export {};

package/dist/core/analyzer/index.d.ts

@@ -0,0 +1,3 @@
+export { analyzeFrames, computeIoU, computeInformationGain } from './analyzer.js';
+export { dbscan } from './clustering/dbscan.js';
+export type { Point2D } from './clustering/dbscan.js';

package/dist/core/constants/workspace-layout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Temp workspace naming and frame file layout for pipeline runs.
+ */
+export declare const APP_NAME = "scene-sieve";
+export declare const WORKSPACE_PREFIX = "scene-sieve-";
+export declare const TEMP_BASE_DIR: string;
+export declare const FRAME_OUTPUT_EXTENSION = ".jpg";
+export declare const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
+export declare function getTempWorkspaceDir(sessionId: string): string;

package/dist/core/{extractor.d.ts → extractor/extractor.d.ts}

@@ -1,4 +1,4 @@
-import type { FrameNode, ProcessContext } from '../types/index.js';
+import type { FrameNode, ProcessContext } from '../../types/index.js';
 export interface FFprobeMetadata {
     format?: {
         format_name?: string;
@@ -10,8 +10,9 @@ export interface FFprobeMetadata {
 }
 /**
  * Extract frames from video/GIF using FFmpeg.
- * Always uses FPS-based extraction. For long videos, FPS is automatically
- * reduced to stay within maxFrames budget.
+ * @param ctx Pipeline context; records effectiveFps and sourceDurationSec for video input.
+ * @returns Extracted candidates, or the unchanged input array in frames mode.
+ * @throws When the input is missing, metadata has no video stream, or FFmpeg fails.
  */
 export declare function extractFrames(ctx: ProcessContext): Promise<FrameNode[]>;
 export declare function getVideoMetadata(inputPath: string): Promise<FFprobeMetadata>;
@@ -25,6 +26,7 @@ export declare function getVideoMetadata(inputPath: string): Promise<FFprobeMeta
  * @param scale - Height scale for vision analysis
  * @param startTime - Start time in seconds
  * @param duration - Duration in seconds to extract
+ * @param frameLimit - Positive output limit; defaults to the range's grid capacity
  * @returns Array of FrameNode with segment-local timestamps (starting from 0)
  */
-export declare function extractFramesForRange(inputPath: string, outputDir: string, fps: number, scale: number, startTime: number, duration: number): Promise<FrameNode[]>;
+export declare function extractFramesForRange(inputPath: string, outputDir: string, fps: number, scale: number, startTime: number, duration: number, frameLimit?: number): Promise<FrameNode[]>;

package/dist/core/extractor/index.d.ts

@@ -0,0 +1 @@
+export { extractFrames, extractFramesForRange, getVideoMetadata } from './extractor.js';

package/dist/core/index.d.ts

@@ -1,9 +1,8 @@
-export { runPipeline } from './orchestrator.js';
-export { analyzeFrames, computeIoU, computeInformationGain, } from './analyzer.js';
-export { extractFrames } from './extractor.js';
-export { pruneTo, pruneByThreshold, pruneByThresholdWithCap, suppressConsecutiveRuns, } from './pruner.js';
-export { dbscan } from './dbscan.js';
-export type { Point2D } from './dbscan.js';
-export { resolveInput, resolveOptions } from './input-resolver.js';
-export { shouldSegment, computeSegmentPlan, processSegment, mergeSegmentFrames, runSegmentedPipeline, } from './segmenter.js';
-export { createWorkspace, createSegmentWorkspace, cleanupWorkspace, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace.js';
+export { runPipeline, runPipelineInWorker } from './orchestrator/index.js';
+export { analyzeFrames, computeIoU, computeInformationGain, dbscan, } from './analyzer/index.js';
+export type { Point2D } from './analyzer/index.js';
+export { extractFrames } from './extractor/index.js';
+export { pruneTo, pruneByThreshold, pruneByThresholdWithCap, suppressConsecutiveRuns, } from './pruner/index.js';
+export { resolveInput, resolveOptions } from './input-resolver/index.js';
+export { shouldSegment, computeSegmentPlan, processSegment, mergeSegmentFrames, runSegmentedPipeline, } from './segmenter/index.js';
+export { createWorkspace, createSegmentWorkspace, cleanupWorkspace, cleanupStaleWorkspaces, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace/index.js';

package/dist/core/input-resolver/index.d.ts

@@ -0,0 +1 @@
+export { resolveInput, resolveOptions } from './input-resolver.js';

package/dist/core/{input-resolver.d.ts → input-resolver/input-resolver.d.ts}

@@ -1,4 +1,10 @@
-import type { FrameNode, ResolvedOptions, SieveOptions } from '../types/index.js';
+import type { FrameNode, ResolvedOptions, SieveOptions } from '../../types/index.js';
+/**
+ * Validate supplied options and resolve defaults and paths for the pipeline.
+ * @param options - Mode-specific input and optional numeric settings.
+ * @returns Complete pipeline settings with absolute file input paths.
+ * @throws An input error if a supplied numeric setting is invalid.
+ */
 export declare function resolveOptions(options: SieveOptions): ResolvedOptions;
 /**
  * Resolve the input source to a list of FrameNode[].
@@ -6,6 +12,10 @@ export declare function resolveOptions(options: SieveOptions): ResolvedOptions;
  * - 'file'   mode: validate file exists and delegate to extractor (caller's responsibility)
  * - 'buffer' mode: write buffer as temp video file, return path via FrameNode trick (empty list)
  * - 'frames' mode: write frame buffers as JPGs, return FrameNode[]
+ * @param options - Input source; encoded frames must have matching dimensions.
+ * @param workspacePath - Workspace receiving temporary input files.
+ * @returns Frame nodes or a resolved video path for extraction.
+ * @throws Propagates metadata or write errors and rejects mismatched frame sizes.
  */
 export declare function resolveInput(options: SieveOptions, workspacePath: string): Promise<{
     frames: FrameNode[];

package/dist/core/input-resolver/validation/validate-options.d.ts

@@ -0,0 +1,8 @@
+import type { SieveOptions } from '../../../types/index.js';
+/**
+ * Reject invalid numeric options before defaults or pipeline effects are applied.
+ * @param options - Supplied options; omitted numeric fields use pipeline defaults.
+ * @returns Nothing when all supplied numeric fields satisfy their contracts.
+ * @throws An input error naming the invalid option and its received value.
+ */
+export declare function validateOptions(options: SieveOptions): void;

package/dist/core/orchestrator/index.d.ts

@@ -0,0 +1,3 @@
+export { runPipeline } from './orchestrator.js';
+export { runPipelineInWorker } from './worker/run-in-worker.js';
+export type { SieveWorkerOptions } from './worker/run-in-worker.js';

package/dist/core/{orchestrator.d.ts → orchestrator/orchestrator.d.ts}

@@ -1,2 +1,2 @@
-import type { SieveOptions, SieveResult } from '../types/index.js';
+import type { SieveOptions, SieveResult } from '../../types/index.js';
 export declare function runPipeline(options: SieveOptions): Promise<SieveResult>;

package/dist/core/{run-in-worker.d.ts → orchestrator/worker/run-in-worker.d.ts}

@@ -1,9 +1,13 @@
-import type { ProgressPhase, SieveInput, SieveOptionsBase, SieveResult } from '../types/index.js';
+import type { ProgressPhase, SieveInput, SieveOptionsBase, SieveResult } from '../../../types/index.js';
 export type SieveWorkerOptions = Omit<SieveOptionsBase, 'onProgress'> & SieveInput;
 /**
  * Run the pipeline, choosing the best execution strategy:
  *
  * - Production (bundled .mjs): Worker thread — spinner never freezes
  * - Dev mode (tsx .ts): Main thread — simpler, spinner may stutter during CPU work
+ * @param options - Serializable input and pipeline settings for this run.
+ * @param onProgress - Receives worker progress updates.
+ * @returns The pipeline result; settlement is unchanged by later exit events.
+ * @throws Rejects worker errors or any worker exit before a result is received.
  */
 export declare function runPipelineInWorker(options: SieveWorkerOptions, onProgress: (phase: ProgressPhase, percent: number) => void): Promise<SieveResult>;

package/dist/core/pruner/index.d.ts

@@ -0,0 +1 @@
+export { pruneTo, pruneByThreshold, pruneByThresholdWithCap, suppressConsecutiveRuns, } from './pruner.js';

package/dist/core/{pruner.d.ts → pruner/pruner.d.ts}

@@ -1,4 +1,4 @@
-import type { FrameNode, ScoreEdge } from '../types/index.js';
+import type { FrameNode, ScoreEdge } from '../../types/index.js';
 /**
  * Edge-aware greedy merge with re-linking — O(N log N).
  *
@@ -35,7 +35,7 @@ export declare function pruneTo(graph: ScoreEdge[], frames: FrameNode[], targetC
  */
 export declare function suppressConsecutiveRuns(graph: ScoreEdge[], passingIndices: number[], normalizedScores: number[]): Set<number>;
 /**
- * Threshold-based pruning with NMS -- O(N).
+ * Threshold-based pruning with NMS -- including normalization, O(N log N).
  *
  * 1. Scores are normalized to [0, 1] via percentile normalization.
  * 2. Edges with normalized score >= threshold are collected.

package/dist/{utils/math.d.ts → core/pruner/scoring/normalize-scores.d.ts}

@@ -1,3 +1,7 @@
+export declare const NORMALIZATION_LOGISTIC_K = 3;
+export declare const NORMALIZATION_ALPHA = 0.4;
+export declare const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+export declare const NORMALIZATION_MIN_SAMPLE_SIZE = 10;
 /**
  * Interface for objects that have a numeric score.
  */

package/dist/core/segmenter/index.d.ts

@@ -0,0 +1 @@
+export { shouldSegment, computeSegmentPlan, processSegment, mergeSegmentFrames, runSegmentedPipeline, } from './segmenter.js';

package/dist/core/{segmenter.d.ts → segmenter/segmenter.d.ts}

@@ -1,4 +1,4 @@
-import type { AnimationMetadata, FrameNode, ResolvedOptions, ScoreEdge, SegmentPlan, SegmentResult, SieveOptions, SieveResult } from '../types/index.js';
+import type { AnimationMetadata, FrameNode, ResolvedOptions, ScoreEdge, SegmentPlan, SegmentResult, SieveOptions, SieveResult } from '../../types/index.js';
 /**
  * Determine whether segmentation should be used.
  * Returns false for frames mode and GIF files.
@@ -6,25 +6,25 @@ import type { AnimationMetadata, FrameNode, ResolvedOptions, ScoreEdge, SegmentP
  */
 export declare function shouldSegment(resolvedOptions: ResolvedOptions, originalOptions: SieveOptions): boolean;
 /**
- * Compute segment boundaries with overlap, frame allocation, and effectiveFps.
- * Pure function — no I/O.
- *
- * - effectiveFps is uniform across all segments
- * - Overlap: 1 frame at each internal boundary
- * - allocatedFrames total <= maxFrames (last segment adjusted if needed)
+ * Partition the global extraction grid into nonempty logical segments.
+ * @param totalDuration Positive source duration in seconds.
+ * @param maxSegmentDuration Positive logical segment width in seconds.
+ * @param maxFrames Candidate budget, defensively raised to at least two.
+ * @param fps Positive requested sampling frequency.
+ * @returns Contiguous plan indices with grid-aligned seeks and overlap-inclusive limits.
  */
 export declare function computeSegmentPlan(totalDuration: number, maxSegmentDuration: number, maxFrames: number, fps: number): SegmentPlan[];
 /**
  * Merge multiple segment results into a single unified frame/edge/animation set.
- * - Timestamps adjusted using extractStartTime (Section 18 note 1)
- * - Overlap frames deduplicated by threshold 1/(effectiveFps*2) (Section 18 note 5)
- * - Global IDs reassigned after dedup
- * - Duplicate edges keep higher score
+ * @param segmentResults Local frames, edges and tracker entries with distinct segment indices.
+ * @returns Global timestamp-ordered frames, aliased edges and animations without self loops.
+ * Duplicate edges keep the higher score; duplicate animations keep the first tracker entry.
  */
 export declare function mergeSegmentFrames(segmentResults: SegmentResult[]): {
     frames: FrameNode[];
     edges: ScoreEdge[];
     animations: AnimationMetadata[];
+    analysisResolution: SegmentResult['analysisResolution'];
 };
 /**
  * Extract frames for a single segment and analyze them.

package/dist/core/utils/metadata/build-video-metadata.d.ts

@@ -0,0 +1,14 @@
+import type { AnimationMetadata, FrameNode, ProcessContext, VideoMetadata } from '../../../types/index.js';
+/**
+ * Read output dimensions and build consistent video and animation metadata.
+ * JPEG finalization does not resize, so the source dimensions match the output.
+ * @param ctx Pipeline state with source duration, effective FPS and analysis-space animations.
+ * @param selected Selected frames in output order; the first candidate is the fallback.
+ * @param analysisResolution Analysis dimensions; absent or zero dimensions imply no scaling.
+ * @returns Video metadata and new output-space animations, retaining zero-based frame IDs.
+ * @throws If sharp cannot read the selected or fallback image. Empty input performs no image I/O.
+ */
+export declare function buildVideoMetadata(ctx: ProcessContext, selected: FrameNode[], analysisResolution: ProcessContext['analysisResolution']): Promise<{
+    video: VideoMetadata;
+    animations: AnimationMetadata[];
+}>;

package/dist/core/workspace/index.d.ts

@@ -0,0 +1 @@
+export { createWorkspace, createSegmentWorkspace, cleanupWorkspace, cleanupStaleWorkspaces, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace.js';

package/dist/core/{workspace.d.ts → workspace/workspace.d.ts}

@@ -1,4 +1,4 @@
-import type { FrameNode, ProcessContext } from '../types/index.js';
+import type { FrameNode, ProcessContext } from '../../types/index.js';
 export declare function createWorkspace(sessionId: string): Promise<string>;
 export declare function finalizeOutput(ctx: ProcessContext, selectedFrames: FrameNode[]): Promise<string[]>;
 export declare function createSegmentWorkspace(parentWorkspacePath: string, segmentIndex: number): Promise<string>;