@lumy-pack/scene-sieve 0.0.1

package/dist/constants.d.ts

@@ -0,0 +1,20 @@
+export declare const APP_NAME = "scene-sieve";
+export declare const DEFAULT_COUNT = 5;
+export declare const DEFAULT_FPS = 5;
+export declare const DEFAULT_SCALE = 720;
+export declare const DEFAULT_QUALITY = 80;
+export declare const WORKSPACE_PREFIX = "scene-sieve-";
+export declare const TEMP_BASE_DIR: string;
+export declare const SUPPORTED_VIDEO_EXTENSIONS: string[];
+export declare const SUPPORTED_GIF_EXTENSIONS: string[];
+export declare const FRAME_OUTPUT_EXTENSION = ".jpg";
+export declare const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
+export declare const OPENCV_BATCH_SIZE = 10;
+export declare const MIN_IFRAME_COUNT = 3;
+export declare const DBSCAN_ALPHA = 0.03;
+export declare const DBSCAN_MIN_PTS = 4;
+export declare const IOU_THRESHOLD = 0.9;
+export declare const DECAY_LAMBDA = 0.95;
+export declare const ANIMATION_FRAME_THRESHOLD = 5;
+export declare const MATCH_DISTANCE_THRESHOLD = 0.75;
+export declare function getTempWorkspaceDir(sessionId: string): string;

package/dist/core/analyzer.d.ts

@@ -0,0 +1,29 @@
+import type { BoundingBox, ProcessContext, ScoreEdge } from '../types/index.js';
+import type { Point2D } from './dbscan.js';
+export declare function preprocessFrame(framePath: string, scale: number): Promise<{
+    data: Uint8Array;
+    width: number;
+    height: number;
+}>;
+export declare function computeIoU(a: BoundingBox, b: BoundingBox): number;
+export declare class IoUTracker {
+    private regions;
+    update(boxes: BoundingBox[], pairIndex: number): Set<number>;
+    getAnimationWeight(boxIndex: number, boxes: BoundingBox[]): number;
+}
+export interface AKAZEResult {
+    sNew: Point2D[];
+    sLoss: Point2D[];
+}
+export declare function computeInformationGain(clusters: BoundingBox[], clusterPoints: number[], imageArea: number, animationIndices: Set<number>, animationWeights: number[]): number;
+/**
+ * Analyze adjacent frame pairs to compute information gain scores (G(t)).
+ * Processes frames in batches for memory efficiency.
+ *
+ * Pipeline:
+ * 1. AKAZE Feature Set Difference
+ * 2. DBSCAN Spatial Clustering
+ * 3. Spatio-temporal IoU Tracking
+ * 4. G(t) Information Gain Scoring
+ */
+export declare function analyzeFrames(ctx: ProcessContext): Promise<ScoreEdge[]>;

package/dist/core/dbscan.d.ts

@@ -0,0 +1,10 @@
+import type { DBSCANResult } from '../types/index.js';
+export interface Point2D {
+    x: number;
+    y: number;
+}
+/**
+ * DBSCAN clustering with resolution-independent eps.
+ * eps = alpha * sqrt(width^2 + height^2)
+ */
+export declare function dbscan(points: Point2D[], imageWidth: number, imageHeight: number, alpha?: number, minPts?: number): DBSCANResult;

package/dist/core/extractor.d.ts

@@ -0,0 +1,7 @@
+import type { FrameNode, ProcessContext } from '../types/index.js';
+/**
+ * Extract frames from video/GIF using FFmpeg.
+ * Attempts I-Frame extraction first; falls back to fixed FPS if insufficient.
+ * GIF inputs always use FPS fallback.
+ */
+export declare function extractFrames(ctx: ProcessContext): Promise<FrameNode[]>;

package/dist/core/index.d.ts

@@ -0,0 +1,8 @@
+export { runPipeline } from './orchestrator.js';
+export { analyzeFrames, computeIoU, computeInformationGain } from './analyzer.js';
+export { extractFrames } from './extractor.js';
+export { pruneTo, pruneByThreshold, pruneByThresholdWithCap } from './pruner.js';
+export { dbscan } from './dbscan.js';
+export type { Point2D } from './dbscan.js';
+export { resolveInput, resolveOptions } from './input-resolver.js';
+export { createWorkspace, cleanupWorkspace, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace.js';

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

@@ -0,0 +1,13 @@
+import type { FrameNode, SieveOptions, ResolvedOptions } from '../types/index.js';
+export declare function resolveOptions(options: SieveOptions): ResolvedOptions;
+/**
+ * Resolve the input source to a list of FrameNode[].
+ *
+ * - '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[]
+ */
+export declare function resolveInput(options: SieveOptions, workspacePath: string): Promise<{
+    frames: FrameNode[];
+    resolvedInputPath?: string;
+}>;

package/dist/core/orchestrator.d.ts

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

package/dist/core/pruner.d.ts

@@ -0,0 +1,42 @@
+import type { FrameNode, ScoreEdge } from '../types/index.js';
+/**
+ * Edge-aware greedy merge with re-linking — O(N log N).
+ *
+ * 1. Build a doubly-linked list of frames
+ * 2. Insert all edges into a min-heap
+ * 3. Pop the lowest-score edge (most similar pair)
+ * 4. Remove the later frame (tgtId), re-link neighbors
+ * 5. Push synthetic edge with score = max(left, right)
+ * 6. Repeat until surviving count === targetCount
+ * 7. First and last frames are never removed (boundary preservation)
+ *
+ * Stale heap entries (involving removed frames) are lazily skipped on pop.
+ */
+export declare function pruneTo(graph: ScoreEdge[], frames: FrameNode[], targetCount: number): Set<number>;
+/**
+ * Threshold-based pruning — O(N).
+ *
+ * Scores are normalized to [0, 1] via max-normalization.
+ * threshold=0.5 means "keep frames where the change is at least 50%
+ * of the maximum change observed in this sequence".
+ *
+ * First and last frames are always preserved (boundary protection).
+ *
+ * Unlike pruneTo (which targets an exact count via greedy merge),
+ * this function has no count limit — every significant scene transition
+ * above the threshold is preserved.
+ */
+export declare function pruneByThreshold(graph: ScoreEdge[], frames: FrameNode[], threshold: number): Set<number>;
+/**
+ * Combined threshold + count pruning -- 2-stage pipeline.
+ *
+ * Stage 1: pruneByThreshold -- keep all frames with normalized score >= threshold
+ * Stage 2: if result exceeds maxCount, rebuild subgraph with synthetic edges
+ *          (min-score over each gap) and apply pruneTo on the surviving subset
+ *
+ * Edge reconstruction: for consecutive survivors A, B with removed frames
+ * [x1, x2, ...] between them, the synthetic edge score is:
+ *   min(score(A->x1), score(x1->x2), ..., score(xN->B))
+ * This preserves the "weakest link" semantics.
+ */
+export declare function pruneByThresholdWithCap(graph: ScoreEdge[], frames: FrameNode[], threshold: number, maxCount: number): Set<number>;

package/dist/core/workspace.d.ts

@@ -0,0 +1,19 @@
+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 cleanupWorkspace(workspacePath: string): Promise<void>;
+/**
+ * Write a video buffer to a temp file in the workspace and return the path.
+ * Used by 'buffer' input mode.
+ */
+export declare function writeInputBuffer(buffer: Buffer, workspacePath: string): Promise<string>;
+/**
+ * Write an array of frame Buffers as JPG files and return FrameNode[].
+ * Used by 'frames' input mode.
+ */
+export declare function writeInputFrames(frames: Buffer[], workspacePath: string): Promise<FrameNode[]>;
+/**
+ * Read selected FrameNode files as Buffers with JPEG compression.
+ * Used to return output buffers in 'buffer' and 'frames' modes.
+ */
+export declare function readFramesAsBuffers(frameNodes: FrameNode[], quality: number): Promise<Buffer[]>;