@lumy-pack/scene-sieve 0.0.7 → 0.0.8

package/dist/cli.mjs

@@ -51,7 +51,7 @@ import { join } from "path";
 function getTempWorkspaceDir(sessionId) {
   return join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
 }
-var APP_NAME, DEFAULT_COUNT, DEFAULT_THRESHOLD, DEFAULT_FPS, DEFAULT_SCALE, DEFAULT_QUALITY, DEFAULT_MAX_FRAMES, NORMALIZATION_PERCENTILE, WORKSPACE_PREFIX, TEMP_BASE_DIR, FRAME_OUTPUT_EXTENSION, FRAME_FILENAME_PATTERN, OPENCV_BATCH_SIZE, DBSCAN_ALPHA, DBSCAN_MIN_PTS, IOU_THRESHOLD, DECAY_LAMBDA, ANIMATION_FRAME_THRESHOLD, MATCH_DISTANCE_THRESHOLD, PIXELDIFF_GAUSSIAN_KERNEL, PIXELDIFF_BINARY_THRESHOLD, PIXELDIFF_CONTOUR_MIN_AREA, PIXELDIFF_SAMPLE_SPACING;
+var APP_NAME, DEFAULT_COUNT, DEFAULT_THRESHOLD, DEFAULT_FPS, DEFAULT_SCALE, DEFAULT_QUALITY, DEFAULT_MAX_FRAMES, NORMALIZATION_LOGISTIC_K, NORMALIZATION_ALPHA, NORMALIZATION_MAD_COEFFICIENT, NORMALIZATION_MIN_SAMPLE_SIZE, WORKSPACE_PREFIX, TEMP_BASE_DIR, FRAME_OUTPUT_EXTENSION, FRAME_FILENAME_PATTERN, OPENCV_BATCH_SIZE, DBSCAN_ALPHA, DBSCAN_MIN_PTS, IOU_THRESHOLD, DECAY_LAMBDA, ANIMATION_FRAME_THRESHOLD, MATCH_DISTANCE_THRESHOLD, PIXELDIFF_GAUSSIAN_KERNEL, PIXELDIFF_BINARY_THRESHOLD, PIXELDIFF_CONTOUR_MIN_AREA, PIXELDIFF_SAMPLE_SPACING;
 var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
@@ -62,7 +62,10 @@ var init_constants = __esm({
     DEFAULT_SCALE = 720;
     DEFAULT_QUALITY = 80;
     DEFAULT_MAX_FRAMES = 300;
-    NORMALIZATION_PERCENTILE = 0.9;
+    NORMALIZATION_LOGISTIC_K = 3;
+    NORMALIZATION_ALPHA = 0.4;
+    NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+    NORMALIZATION_MIN_SAMPLE_SIZE = 10;
     WORKSPACE_PREFIX = `${APP_NAME}-`;
     TEMP_BASE_DIR = tmpdir();
     FRAME_OUTPUT_EXTENSION = ".jpg";
@@ -873,6 +876,49 @@ var init_input_resolver = __esm({
   }
 });
 
+// src/utils/math.ts
+function normalizeScores(items) {
+  if (items.length === 0) return [];
+  const safeScores = items.map(
+    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
+  );
+  const positiveScores = safeScores.filter((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(
+      (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 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) => {
+    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) => {
+    if (s <= 0) return 0;
+    const rank = sorted.findIndex((v) => v >= s);
+    return rank / sorted.length;
+  });
+  return logisticZ.map(
+    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
+  );
+}
+var init_math = __esm({
+  "src/utils/math.ts"() {
+    "use strict";
+    init_constants();
+  }
+});
+
 // src/utils/min-heap.ts
 var MinHeap;
 var init_min_heap = __esm({
@@ -973,20 +1019,6 @@ function pruneTo(graph, frames, targetCount) {
   }
   return surviving;
 }
-function normalizeScores(graph) {
-  if (graph.length === 0) return [];
-  const safeScores = graph.map(
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
-  if (sorted.length === 0) return safeScores;
-  const pIdx = Math.min(
-    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
-    sorted.length - 1
-  );
-  const refScore = sorted[pIdx];
-  return safeScores.map((s) => Math.min(s / refScore, 1));
-}
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
   const result = /* @__PURE__ */ new Set();
   let runStart = 0;
@@ -1086,7 +1118,7 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
 var init_pruner = __esm({
   "src/core/pruner.ts"() {
     "use strict";
-    init_constants();
+    init_math();
     init_min_heap();
   }
 });

package/dist/constants.d.ts

@@ -5,7 +5,12 @@ 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 NORMALIZATION_PERCENTILE = 0.9;
+export declare const NORMALIZATION_MIN_PERCENTILE = 0.1;
+export declare const NORMALIZATION_MAX_PERCENTILE = 0.9;
+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;
 export declare const WORKSPACE_PREFIX = "scene-sieve-";
 export declare const TEMP_BASE_DIR: string;
 export declare const FRAME_OUTPUT_EXTENSION = ".jpg";

package/dist/index.cjs

@@ -85,7 +85,10 @@ var DEFAULT_FPS = 5;
 var DEFAULT_SCALE = 720;
 var DEFAULT_QUALITY = 80;
 var DEFAULT_MAX_FRAMES = 300;
-var NORMALIZATION_PERCENTILE = 0.9;
+var NORMALIZATION_LOGISTIC_K = 3;
+var NORMALIZATION_ALPHA = 0.4;
+var NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+var NORMALIZATION_MIN_SAMPLE_SIZE = 10;
 var WORKSPACE_PREFIX = `${APP_NAME}-`;
 var TEMP_BASE_DIR = (0, import_node_os.tmpdir)();
 var FRAME_OUTPUT_EXTENSION = ".jpg";
@@ -839,6 +842,43 @@ async function resolveInput(options, workspacePath) {
   throw new Error(`Unsupported input mode: ${options.mode}`);
 }
 
+// src/utils/math.ts
+function normalizeScores(items) {
+  if (items.length === 0) return [];
+  const safeScores = items.map(
+    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
+  );
+  const positiveScores = safeScores.filter((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(
+      (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 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) => {
+    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) => {
+    if (s <= 0) return 0;
+    const rank = sorted.findIndex((v) => v >= s);
+    return rank / sorted.length;
+  });
+  return logisticZ.map(
+    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
+  );
+}
+
 // src/utils/min-heap.ts
 var MinHeap = class {
   h = [];
@@ -933,20 +973,6 @@ function pruneTo(graph, frames, targetCount) {
   }
   return surviving;
 }
-function normalizeScores(graph) {
-  if (graph.length === 0) return [];
-  const safeScores = graph.map(
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
-  if (sorted.length === 0) return safeScores;
-  const pIdx = Math.min(
-    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
-    sorted.length - 1
-  );
-  const refScore = sorted[pIdx];
-  return safeScores.map((s) => Math.min(s / refScore, 1));
-}
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
   const result = /* @__PURE__ */ new Set();
   let runStart = 0;

package/dist/index.mjs

@@ -45,7 +45,10 @@ var DEFAULT_FPS = 5;
 var DEFAULT_SCALE = 720;
 var DEFAULT_QUALITY = 80;
 var DEFAULT_MAX_FRAMES = 300;
-var NORMALIZATION_PERCENTILE = 0.9;
+var NORMALIZATION_LOGISTIC_K = 3;
+var NORMALIZATION_ALPHA = 0.4;
+var NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+var NORMALIZATION_MIN_SAMPLE_SIZE = 10;
 var WORKSPACE_PREFIX = `${APP_NAME}-`;
 var TEMP_BASE_DIR = tmpdir();
 var FRAME_OUTPUT_EXTENSION = ".jpg";
@@ -799,6 +802,43 @@ async function resolveInput(options, workspacePath) {
   throw new Error(`Unsupported input mode: ${options.mode}`);
 }
 
+// src/utils/math.ts
+function normalizeScores(items) {
+  if (items.length === 0) return [];
+  const safeScores = items.map(
+    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
+  );
+  const positiveScores = safeScores.filter((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(
+      (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 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) => {
+    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) => {
+    if (s <= 0) return 0;
+    const rank = sorted.findIndex((v) => v >= s);
+    return rank / sorted.length;
+  });
+  return logisticZ.map(
+    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
+  );
+}
+
 // src/utils/min-heap.ts
 var MinHeap = class {
   h = [];
@@ -893,20 +933,6 @@ function pruneTo(graph, frames, targetCount) {
   }
   return surviving;
 }
-function normalizeScores(graph) {
-  if (graph.length === 0) return [];
-  const safeScores = graph.map(
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
-  if (sorted.length === 0) return safeScores;
-  const pIdx = Math.min(
-    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
-    sorted.length - 1
-  );
-  const refScore = sorted[pIdx];
-  return safeScores.map((s) => Math.min(s / refScore, 1));
-}
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
   const result = /* @__PURE__ */ new Set();
   let runStart = 0;

package/dist/pipeline-worker.mjs

@@ -48,7 +48,10 @@ var DEFAULT_FPS = 5;
 var DEFAULT_SCALE = 720;
 var DEFAULT_QUALITY = 80;
 var DEFAULT_MAX_FRAMES = 300;
-var NORMALIZATION_PERCENTILE = 0.9;
+var NORMALIZATION_LOGISTIC_K = 3;
+var NORMALIZATION_ALPHA = 0.4;
+var NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+var NORMALIZATION_MIN_SAMPLE_SIZE = 10;
 var WORKSPACE_PREFIX = `${APP_NAME}-`;
 var TEMP_BASE_DIR = tmpdir();
 var FRAME_OUTPUT_EXTENSION = ".jpg";
@@ -802,6 +805,43 @@ async function resolveInput(options2, workspacePath) {
   throw new Error(`Unsupported input mode: ${options2.mode}`);
 }
 
+// src/utils/math.ts
+function normalizeScores(items) {
+  if (items.length === 0) return [];
+  const safeScores = items.map(
+    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
+  );
+  const positiveScores = safeScores.filter((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(
+      (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 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) => {
+    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) => {
+    if (s <= 0) return 0;
+    const rank = sorted.findIndex((v) => v >= s);
+    return rank / sorted.length;
+  });
+  return logisticZ.map(
+    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
+  );
+}
+
 // src/utils/min-heap.ts
 var MinHeap = class {
   h = [];
@@ -896,20 +936,6 @@ function pruneTo(graph, frames, targetCount) {
   }
   return surviving;
 }
-function normalizeScores(graph) {
-  if (graph.length === 0) return [];
-  const safeScores = graph.map(
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
-  if (sorted.length === 0) return safeScores;
-  const pIdx = Math.min(
-    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
-    sorted.length - 1
-  );
-  const refScore = sorted[pIdx];
-  return safeScores.map((s) => Math.min(s / refScore, 1));
-}
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
   const result = /* @__PURE__ */ new Set();
   let runStart = 0;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/scene-sieve",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "CLI tool for extracting key frames from video and GIF files",
   "keywords": [
     "cli",