@lumy-pack/scene-sieve 0.0.10 → 0.0.12

package/dist/pipeline-worker.mjs

@@ -3,6 +3,7 @@ import { parentPort, workerData } from "worker_threads";
 
 // src/core/orchestrator.ts
 import { randomUUID as randomUUID2 } from "crypto";
+import { filter as filter6 } from "@winglet/common-utils";
 
 // src/utils/logger.ts
 import pc from "picocolors";
@@ -36,6 +37,7 @@ ${pc.green("done")} ${message}`);
 
 // src/core/analyzer.ts
 import { createRequire } from "module";
+import { filter, map } from "@winglet/common-utils";
 import sharp from "sharp";
 
 // src/constants.ts
@@ -252,7 +254,8 @@ var IoUTracker = class {
         this.collectAnimation(region);
       }
     }
-    this.regions = this.regions.filter(
+    this.regions = filter(
+      this.regions,
       (r, i) => r.weight > 0.01 || matched.has(i)
     );
     return animationIndices;
@@ -433,7 +436,7 @@ function computeInformationGain(clusters, clusterPoints, imageArea, animationInd
 async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
   const edges = [];
   const preprocessed = await Promise.all(
-    frames.map((f) => preprocessFrame(f.extractPath, scale))
+    map(frames, (f) => preprocessFrame(f.extractPath, scale))
   );
   const imageWidth = preprocessed[0]?.width ?? scale;
   const imageHeight = preprocessed[0]?.height ?? Math.round(scale * 9 / 16);
@@ -475,7 +478,8 @@ async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
         }
       }
       const animationIndices = tracker.update(clusters, pairIndex);
-      const animationWeights = clusters.map(
+      const animationWeights = map(
+        clusters,
         (_, ci) => animationIndices.has(ci) ? tracker.getAnimationWeight(ci, clusters) : 0
       );
       const score = computeInformationGain(
@@ -540,6 +544,7 @@ async function analyzeFrames(ctx) {
 import { readdir } from "fs/promises";
 import { join as join2 } from "path";
 import { path as ffprobePath } from "@ffprobe-installer/ffprobe";
+import { filter as filter2, map as map2 } from "@winglet/common-utils";
 import { execa } from "execa";
 import ffmpegPath from "ffmpeg-static";
 
@@ -651,11 +656,11 @@ async function getVideoMetadata(inputPath) {
 }
 async function buildFrameList(framesDir, duration) {
   const files = await readdir(framesDir);
-  const jpgFiles = files.filter((f) => f.endsWith(".jpg")).sort();
+  const jpgFiles = filter2(files, (f) => f.endsWith(".jpg")).sort();
   if (jpgFiles.length === 0) {
     return [];
   }
-  return jpgFiles.map((file, index) => ({
+  return map2(jpgFiles, (file, index) => ({
     id: index,
     timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,
     extractPath: join2(framesDir, file)
@@ -685,6 +690,7 @@ import { join as join4 } from "path";
 // src/core/workspace.ts
 import { readdir as readdir2, rename, rm, stat as stat2, writeFile } from "fs/promises";
 import { join as join3 } from "path";
+import { map as map3 } from "@winglet/common-utils";
 import sharp2 from "sharp";
 async function createWorkspace(sessionId) {
   const workspacePath = getTempWorkspaceDir(sessionId);
@@ -725,7 +731,7 @@ async function finalizeOutput(ctx, selectedFrames) {
       }
     },
     frames: framesMetadata,
-    animations: (ctx.animations || []).map((anim) => ({
+    animations: map3(ctx.animations || [], (anim) => ({
       ...anim,
       startFrameId: anim.startFrameId + 1,
       endFrameId: anim.endFrameId + 1,
@@ -778,7 +784,8 @@ async function writeInputFrames(frames, workspacePath) {
 }
 async function readFramesAsBuffers(frameNodes, quality) {
   return Promise.all(
-    frameNodes.map(
+    map3(
+      frameNodes,
       (f) => sharp2(f.extractPath).jpeg({ quality, mozjpeg: true }).toBuffer()
     )
   );
@@ -835,39 +842,46 @@ async function resolveInput(options2, workspacePath) {
   throw new Error(`Unsupported input mode: ${options2.mode}`);
 }
 
+// src/core/pruner.ts
+import { filter as filter4, map as map5 } from "@winglet/common-utils";
+
 // src/utils/math.ts
+import { filter as filter3, map as map4 } from "@winglet/common-utils";
 function normalizeScores(items) {
   if (items.length === 0) return [];
-  const safeScores = items.map(
+  const safeScores = map4(
+    items,
     (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
   );
-  const positiveScores = safeScores.filter((s) => s > 0);
+  const positiveScores = filter3(safeScores, (s) => s > 0);
   if (positiveScores.length === 0) return safeScores;
   const sorted = [...positiveScores].sort((a, b) => a - b);
   if (positiveScores.length <= NORMALIZATION_MIN_SAMPLE_SIZE) {
     const min = sorted[0];
     const max = sorted[sorted.length - 1];
-    if (max === min) return safeScores.map((s) => s > 0 ? 1 : 0);
-    return safeScores.map(
+    if (max === min) return map4(safeScores, (s) => s > 0 ? 1 : 0);
+    return map4(
+      safeScores,
       (s) => s <= 0 ? 0 : Math.max(0, Math.min((s - min) / (max - min), 1))
     );
   }
   const median = sorted[Math.floor(sorted.length / 2)];
-  const absoluteDiffs = positiveScores.map((v) => Math.abs(v - median));
+  const absoluteDiffs = map4(positiveScores, (v) => Math.abs(v - median));
   const mad = [...absoluteDiffs].sort((a, b) => a - b)[Math.floor(absoluteDiffs.length / 2)];
   const scale = mad === 0 ? median : mad * NORMALIZATION_MAD_COEFFICIENT;
-  const logisticZ = safeScores.map((s) => {
+  const logisticZ = map4(safeScores, (s) => {
     if (s <= 0) return 0;
     if (scale === 0) return 1;
     const z = (s - median) / scale;
     return 1 / (1 + Math.exp(-NORMALIZATION_LOGISTIC_K * z));
   });
-  const cdf = safeScores.map((s) => {
+  const cdf = map4(safeScores, (s) => {
     if (s <= 0) return 0;
     const rank = sorted.findIndex((v) => v >= s);
     return rank / sorted.length;
   });
-  return logisticZ.map(
+  return map4(
+    logisticZ,
     (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
   );
 }
@@ -919,7 +933,7 @@ var MinHeap = class {
 // src/core/pruner.ts
 function pruneTo(graph, frames, targetCount) {
   if (frames.length <= targetCount) {
-    return new Set(frames.map((f) => f.id));
+    return new Set(map5(frames, (f) => f.id));
   }
   const prev = /* @__PURE__ */ new Map();
   const next = /* @__PURE__ */ new Map();
@@ -937,7 +951,7 @@ function pruneTo(graph, frames, targetCount) {
       tgtId: edge.targetId
     });
   }
-  const surviving = new Set(frames.map((f) => f.id));
+  const surviving = new Set(map5(frames, (f) => f.id));
   const firstId = frames[0].id;
   const lastId = frames[frames.length - 1].id;
   while (surviving.size > targetCount && heap.size > 0) {
@@ -1030,7 +1044,7 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
   if (thresholdSurvivors.size <= maxCount) {
     return thresholdSurvivors;
   }
-  const survivingFrames = frames.filter((f) => thresholdSurvivors.has(f.id));
+  const survivingFrames = filter4(frames, (f) => thresholdSurvivors.has(f.id));
   const idToOrigIdx = /* @__PURE__ */ new Map();
   for (let i = 0; i < frames.length; i++) {
     idToOrigIdx.set(frames[i].id, i);
@@ -1066,6 +1080,7 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
 // src/core/segmenter.ts
 import { randomUUID } from "crypto";
 import { join as join5 } from "path";
+import { filter as filter5, map as map6 } from "@winglet/common-utils";
 
 // src/utils/concurrency.ts
 function concurrencyLimit(limit) {
@@ -1204,18 +1219,30 @@ function remapEdges(segmentResults, globalIdMap) {
   const edgeMap = /* @__PURE__ */ new Map();
   for (const result of segmentResults) {
     for (const edge of result.edges) {
-      const newSourceId = globalIdMap.get(`${result.segment.index}:${edge.sourceId}`);
-      const newTargetId = globalIdMap.get(`${result.segment.index}:${edge.targetId}`);
+      const newSourceId = globalIdMap.get(
+        `${result.segment.index}:${edge.sourceId}`
+      );
+      const newTargetId = globalIdMap.get(
+        `${result.segment.index}:${edge.targetId}`
+      );
       if (newSourceId === void 0 || newTargetId === void 0) continue;
       const edgeKey = `${newSourceId}-${newTargetId}`;
       const existingIdx = edgeMap.get(edgeKey);
       if (existingIdx !== void 0) {
         if (edges[existingIdx].score < edge.score) {
-          edges[existingIdx] = { sourceId: newSourceId, targetId: newTargetId, score: edge.score };
+          edges[existingIdx] = {
+            sourceId: newSourceId,
+            targetId: newTargetId,
+            score: edge.score
+          };
         }
       } else {
         edgeMap.set(edgeKey, edges.length);
-        edges.push({ sourceId: newSourceId, targetId: newTargetId, score: edge.score });
+        edges.push({
+          sourceId: newSourceId,
+          targetId: newTargetId,
+          score: edge.score
+        });
       }
     }
   }
@@ -1225,10 +1252,18 @@ function remapAnimations(segmentResults, globalIdMap) {
   const animations = [];
   for (const result of segmentResults) {
     for (const anim of result.animations) {
-      const newStartId = globalIdMap.get(`${result.segment.index}:${anim.startFrameId}`);
-      const newEndId = globalIdMap.get(`${result.segment.index}:${anim.endFrameId}`);
+      const newStartId = globalIdMap.get(
+        `${result.segment.index}:${anim.startFrameId}`
+      );
+      const newEndId = globalIdMap.get(
+        `${result.segment.index}:${anim.endFrameId}`
+      );
       if (newStartId === void 0 || newEndId === void 0) continue;
-      animations.push({ ...anim, startFrameId: newStartId, endFrameId: newEndId });
+      animations.push({
+        ...anim,
+        startFrameId: newStartId,
+        endFrameId: newEndId
+      });
     }
   }
   return animations;
@@ -1309,7 +1344,7 @@ async function runSegmentedPipeline(options2, resolvedOptions) {
     logger.debug(`Segment plan: ${segments.length} segments`);
     const limit = concurrencyLimit(resolvedOptions.concurrency);
     const segmentProgresses = new Array(segments.length).fill(0);
-    const weights = segments.map((s) => s.duration / totalDuration);
+    const weights = map6(segments, (s) => s.duration / totalDuration);
     const emitOverallProgress = (phase) => {
       if (!options2.onProgress) return;
       const overall = weights.reduce(
@@ -1320,7 +1355,8 @@ async function runSegmentedPipeline(options2, resolvedOptions) {
     };
     options2.onProgress?.("EXTRACTING", 0);
     const results = await Promise.all(
-      segments.map(
+      map6(
+        segments,
         (segment) => limit(async () => {
           const segWorkspace = await createSegmentWorkspace(
             mainWorkspace,
@@ -1352,7 +1388,7 @@ async function runSegmentedPipeline(options2, resolvedOptions) {
       resolvedOptions.threshold,
       resolvedOptions.count
     );
-    const prunedFrames = frames.filter((f) => survivingIds.has(f.id));
+    const prunedFrames = filter5(frames, (f) => survivingIds.has(f.id));
     options2.onProgress?.("PRUNING", 100);
     options2.onProgress?.("FINALIZING", 0);
     const ctx = {
@@ -1462,7 +1498,7 @@ async function runPipeline(options2) {
       resolvedOptions.threshold,
       resolvedOptions.count
     );
-    const prunedFrames = ctx.frames.filter((f) => survivingIds.has(f.id));
+    const prunedFrames = filter6(ctx.frames, (f) => survivingIds.has(f.id));
     ctx.emitProgress(100);
     ctx.status = "FINALIZING";
     let outputFiles = [];

package/dist/types/index.d.ts

@@ -0,0 +1,129 @@
+export type ProgressPhase = 'EXTRACTING' | 'ANALYZING' | 'PRUNING' | 'FINALIZING';
+export type SieveInput = {
+    mode: 'file';
+    inputPath: string;
+} | {
+    mode: 'buffer';
+    inputBuffer: Buffer;
+} | {
+    mode: 'frames';
+    inputFrames: Buffer[];
+};
+export interface SieveOptionsBase {
+    count?: number;
+    threshold?: number;
+    outputPath?: string;
+    fps?: number;
+    maxFrames?: number;
+    scale?: number;
+    quality?: number;
+    iouThreshold?: number;
+    animationThreshold?: number;
+    debug?: boolean;
+    onProgress?: (phase: ProgressPhase, percent: number) => void;
+    maxSegmentDuration?: number;
+    concurrency?: number;
+}
+export type SieveOptions = SieveOptionsBase & SieveInput;
+export interface ResolvedOptions {
+    mode: 'file' | 'buffer' | 'frames';
+    inputPath?: string;
+    count: number;
+    threshold: number;
+    pruneMode: 'threshold-with-cap';
+    outputPath: string;
+    fps: number;
+    maxFrames: number;
+    scale: number;
+    quality: number;
+    iouThreshold: number;
+    animationThreshold: number;
+    debug: boolean;
+    maxSegmentDuration: number;
+    concurrency: number;
+}
+export interface SieveResult {
+    success: boolean;
+    originalFramesCount: number;
+    prunedFramesCount: number;
+    outputFiles: string[];
+    outputBuffers?: Buffer[];
+    animations?: AnimationMetadata[];
+    video?: VideoMetadata;
+    executionTimeMs: number;
+}
+export interface AnimationMetadata {
+    type: string;
+    boundingBox: BoundingBox;
+    startFrameId: number;
+    endFrameId: number;
+    durationMs: number;
+}
+export interface VideoMetadata {
+    originalDurationMs: number;
+    fps: number;
+    resolution: {
+        width: number;
+        height: number;
+    };
+}
+export interface FrameNode {
+    id: number;
+    timestamp: number;
+    extractPath: string;
+}
+export interface ScoreEdge {
+    sourceId: number;
+    targetId: number;
+    /**
+     * Information gain score (G(t)) between adjacent frames.
+     * Higher values = greater visual change (state transition) = should be preserved.
+     * Lower values = similar frames (little change) = candidates for pruning.
+     *
+     * Pruner removes frames with the LOWEST scores first (greedy ascending).
+     * Maps directly to G(t) from the vision analysis pipeline.
+     */
+    score: number;
+}
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface DBSCANResult {
+    labels: number[];
+    boundingBoxes: BoundingBox[];
+}
+export interface ProcessContext {
+    options: ResolvedOptions;
+    workspacePath: string;
+    frames: FrameNode[];
+    graph: ScoreEdge[];
+    animations?: AnimationMetadata[];
+    status: 'INIT' | ProgressPhase | 'SUCCESS' | 'FAILED';
+    emitProgress: (percent: number) => void;
+    error?: Error;
+}
+export interface AnalysisResult {
+    edges: ScoreEdge[];
+    animations: AnimationMetadata[];
+}
+export interface SegmentPlan {
+    index: number;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    allocatedFrames: number;
+    effectiveFps: number;
+    overlapBefore: number;
+    overlapAfter: number;
+    extractStartTime: number;
+    extractDuration: number;
+}
+export interface SegmentResult {
+    segment: SegmentPlan;
+    frames: FrameNode[];
+    edges: ScoreEdge[];
+    animations: AnimationMetadata[];
+}

package/dist/utils/command-registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Central command registry for scene-sieve CLI.
+ * Single source of truth for command metadata, used by --describe and --help.
+ */
+export interface CommandOption {
+    flag: string;
+    description: string;
+    type?: 'boolean' | 'string' | 'number';
+    default?: string;
+}
+export interface CommandArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface CommandInfo {
+    name: string;
+    description: string;
+    usage: string;
+    arguments?: CommandArgument[];
+    options?: CommandOption[];
+    examples?: string[];
+}
+export declare const SIEVE_COMMAND: CommandInfo;

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Creates a concurrency limiter that runs at most `limit` tasks in parallel.
+ * Lightweight replacement for p-limit to avoid external dependency.
+ */
+export declare function concurrencyLimit(limit: number): <T>(fn: () => Promise<T>) => Promise<T>;

package/dist/utils/logger.d.ts

@@ -0,0 +1,8 @@
+export declare function setDebugMode(enabled: boolean): void;
+export declare const logger: {
+    info(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+};

package/dist/utils/math.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Interface for objects that have a numeric score.
+ */
+export interface ScoredItem {
+    score: number;
+}
+/**
+ * Normalize raw scores to [0, 1] range via Robust Hybrid Normalization.
+ *
+ * This model combines two mathematical approaches to provide a stable "relative" threshold:
+ *
+ * 1. Logistic-Robust-Z (Intensity):
+ *    Calculates Z-scores using Median and Median Absolute Deviation (MAD).
+ *    Maps these to a sigmoid (logistic) curve. This suppresses noise (scores near median)
+ *    and highlights significant signals (outliers) without letting extreme outliers
+ *    crush other meaningful transitions.
+ *
+ * 2. CDF / Percentile Rank (Relative Position):
+ *    Maps each score to its percentile rank in the sequence. This ensures that 't'
+ *    always has a consistent meaning as a "relative rank" regardless of absolute values.
+ *
+ * The final score is a weighted sum (NORMALIZATION_ALPHA) of both.
+ *
+ * @param items - Array of items with scores to normalize
+ * @returns normalized scores array (same length as input)
+ */
+export declare function normalizeScores<T extends ScoredItem>(items: T[]): number[];

package/dist/utils/min-heap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generic binary min-heap.
+ *
+ * Elements are ordered by a numeric `score` field.
+ * push/pop: O(log N), size: O(1).
+ */
+export declare class MinHeap<T extends {
+    score: number;
+}> {
+    private readonly h;
+    get size(): number;
+    push(entry: T): void;
+    pop(): T | undefined;
+    private siftUp;
+    private siftDown;
+}

package/dist/utils/parse-options.d.ts

@@ -0,0 +1,21 @@
+import type { SieveOptionsBase } from '../types/index.js';
+/**
+ * Common pipeline options parsed from CLI opts (Commander string values → typed values).
+ * Does NOT include mode-specific fields (mode, inputPath, onProgress).
+ */
+export type ParsedPipelineOptions = Pick<Required<SieveOptionsBase>, 'fps' | 'maxFrames' | 'scale' | 'quality' | 'debug'> & Pick<SieveOptionsBase, 'count' | 'threshold' | 'outputPath' | 'iouThreshold' | 'animationThreshold' | 'maxSegmentDuration' | 'concurrency'>;
+export interface RawCliOptions {
+    count?: string;
+    threshold?: string;
+    output?: string;
+    fps: string;
+    maxFrames: string;
+    scale: string;
+    quality: string;
+    iouThreshold?: string;
+    animThreshold?: string;
+    maxSegmentDuration?: string;
+    concurrency?: string;
+    debug?: boolean;
+}
+export declare function parsePipelineOptions(opts: RawCliOptions): ParsedPipelineOptions;

package/dist/utils/paths.d.ts

@@ -0,0 +1,18 @@
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Expand leading ~ to homedir. Node's path.resolve() does not expand ~,
+ * so paths like ~/Desktop/foo depend on process.cwd() and can produce
+ * different results when run from different directories.
+ */
+export declare function expandTilde(p: string): string;
+/**
+ * Resolve path to absolute. Expands ~ to homedir first so that the result
+ * does not depend on process.cwd().
+ */
+export declare function resolveAbsolute(p: string): string;
+/**
+ * Derive default output directory name from input file path.
+ * e.g., /path/to/video.mp4 -> /path/to/video_scenes
+ */
+export declare function deriveOutputPath(inputPath: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/scene-sieve",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "CLI tool for extracting key frames from video and GIF files",
   "keywords": [
     "cli",
@@ -55,8 +55,9 @@
   },
   "dependencies": {
     "@ffprobe-installer/ffprobe": "^1.4.1",
-    "@lumy-pack/shared": "0.0.1",
     "@techstark/opencv-js": "4.12.0-release.1",
+    "@winglet/common-utils": "^0.11.2",
+    "@winglet/react-utils": "^0.11.2",
     "commander": "^12.1.0",
     "execa": "^9.5.0",
     "ffmpeg-static": "^5.2.0",
@@ -67,6 +68,7 @@
     "sharp": "^0.33.0"
   },
   "devDependencies": {
+    "@lumy-pack/shared": "0.0.1",
     "@types/node": "^20.11.0",
     "@types/react": "^18.0.0",
     "@vitest/coverage-v8": "^3.2.4"