@lumy-pack/scene-sieve 0.2.0 → 0.2.1

package/dist/constants/package-version.d.ts

@@ -0,0 +1,2 @@
+/** Runtime manifest version shared by CLI responses and metadata documents. */
+export declare const PACKAGE_VERSION: string;

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

@@ -11,3 +11,23 @@ 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;
+/** Default maximum contact sheet columns. */
+export declare const DEFAULT_SHEET_COLUMNS = 4;
+/** Default contact sheet tile width in pixels. */
+export declare const DEFAULT_SHEET_TILE_WIDTH = 320;
+/** Default maximum contact sheet tiles. */
+export declare const DEFAULT_SHEET_MAX_TILES = 40;
+/** Enable timestamp labels on contact sheet tiles by default. */
+export declare const DEFAULT_SHEET_LABEL = true;
+/** White contact sheet margin and gap in pixels. */
+export declare const SHEET_TILE_GAP = 4;
+/** Tile-height fraction used for label font size. */
+export declare const SHEET_LABEL_HEIGHT_RATIO = 0.07;
+/** Maximum distinct regions retained per selected-frame span. */
+export declare const CHANGE_REGION_LIMIT = 5;
+/** Metadata schema discriminator. */
+export declare const METADATA_VERSION = 2;
+/** Fixed contact sheet output name. */
+export declare const SHEET_FILE_NAME = "sheet.jpg";
+/** Fixed metadata document output name. */
+export declare const METADATA_FILE_NAME = ".metadata.json";

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
 export { runPipeline, runPipelineInWorker } from './orchestrator/index.js';
+export type { AnimationMetadata, VideoMetadata, FrameMetadata, FrameChange, ToolMetadata, ToolParams, SheetMetadata, SheetOptions, SieveMetadata, EdgeMetadata, EdgeChange, } from '../types/index.js';
 export { analyzeFrames, computeIoU, computeInformationGain, dbscan, } from './analyzer/index.js';
 export type { Point2D } from './analyzer/index.js';
 export { extractFrames } from './extractor/index.js';

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

@@ -1,2 +1,8 @@
 import type { SieveOptions, SieveResult } from '../../types/index.js';
+/**
+ * Run the five pipeline stages, delegating segmented inputs to the segmenter.
+ * @param options - Mode-specific input and optional pipeline settings.
+ * @returns Selected outputs with v2 frame metadata and zero-based API animations.
+ * @throws Propagates stage failures after cleaning the workspace unless debug is enabled.
+ */
 export declare function runPipeline(options: SieveOptions): Promise<SieveResult>;

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

@@ -0,0 +1,11 @@
+import type { EdgeMetadata, ScoreEdge } from '../../../types/index.js';
+/**
+ * Serialize raw candidate edges in graph order.
+ * @param graph - Adjacent-pair edges, optionally carrying tracker partitions.
+ * @param analysisResolution - Analysis dimensions used for both area fractions.
+ * @returns One-based IDs with six-decimal scores and four-decimal clamped ratios.
+ */
+export declare function buildEdgeMetadata(graph: ScoreEdge[], analysisResolution: {
+    width: number;
+    height: number;
+}): EdgeMetadata[];

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

@@ -0,0 +1,20 @@
+import type { FrameMetadata, FrameNode, ScoreEdge } from '../../../types/index.js';
+/**
+ * Describe selected frames using candidate adjacency rather than synthetic pruning edges.
+ * @param input - Chronological candidates and selections, raw graph and output dimensions.
+ * @returns One-based frame summaries with rounded timestamps and nonnegative holds.
+ */
+export declare function buildFrameMetadata(input: {
+    frames: FrameNode[];
+    graph: ScoreEdge[];
+    selected: FrameNode[];
+    originalDurationMs: number;
+    analysisResolution: {
+        width: number;
+        height: number;
+    };
+    outputResolution: {
+        width: number;
+        height: number;
+    };
+}): FrameMetadata[];

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

@@ -0,0 +1,14 @@
+import type { AnimationMetadata, FrameNode, ProcessContext, SheetMetadata, SieveMetadata, VideoMetadata } from '../../../types/index.js';
+/**
+ * Assemble the complete v2 document without I/O or mutation.
+ * @param input - Pipeline state, selections, output-space video and zero-based animations.
+ * @returns Contract-ordered metadata, omitting unrequested optional keys entirely.
+ */
+export declare function buildSieveMetadata(input: {
+    ctx: ProcessContext;
+    selected: FrameNode[];
+    video: VideoMetadata;
+    animations: AnimationMetadata[];
+    version: string;
+    sheet?: SheetMetadata;
+}): SieveMetadata;

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

@@ -0,0 +1,8 @@
+import type { ResolvedOptions, ToolMetadata } from '../../../types/index.js';
+/**
+ * Record the tool and the nine selection and encoding settings in contract order.
+ * @param options - Validated pipeline settings; operational options are excluded.
+ * @param version - Runtime package version supplied by the I/O boundary.
+ * @returns Deterministic tool provenance without paths or execution details.
+ */
+export declare function buildToolMetadata(options: ResolvedOptions, version: string): ToolMetadata;

package/dist/core/utils/metadata/change/build-frame-change.d.ts

@@ -0,0 +1,20 @@
+import type { FrameChange, ScoreEdge } from '../../../../types/index.js';
+/**
+ * Aggregate adjacent-pair evidence across one selected-frame span.
+ * @param input - Ordered raw edges, one-based previous ID, skipped count and dimensions.
+ * @returns Rounded raw scores, analysis-space union ratio and output-space regions.
+ */
+export declare function buildFrameChange(input: {
+    spanEdges: ScoreEdge[];
+    fromFrameId: number;
+    skippedCandidates: number;
+    analysisResolution: {
+        width: number;
+        height: number;
+    };
+    outputResolution: {
+        width: number;
+        height: number;
+    };
+    regionLimit: number;
+}): FrameChange;

package/dist/core/utils/metadata/change/select-regions.d.ts

@@ -0,0 +1,8 @@
+import type { BoundingBox } from '../../../../types/index.js';
+/**
+ * Select distinct positive-area boxes with deterministic area and coordinate ties.
+ * @param boxes - Already scaled output rectangles; the input is not mutated.
+ * @param limit - Nonnegative maximum number of regions.
+ * @returns Largest boxes ordered by area descending, then y, x and width ascending.
+ */
+export declare function selectRegions(boxes: BoundingBox[], limit: number): BoundingBox[];

package/dist/core/utils/metadata/change/union-area/y-coverage-tree.d.ts

@@ -0,0 +1,26 @@
+/** Internal sweep helper retaining cover counts and lengths between sorted y bounds. */
+export declare class YCoverageTree {
+    private readonly bounds;
+    /** Number of whole-node covering intervals, independent of descendants. */
+    private readonly counts;
+    /** Covered geometric length for each node, including partially covered children. */
+    private readonly lengths;
+    /**
+     * Allocate linear storage for the elementary intervals between coordinates.
+     * @param bounds - At least two sorted unique finite y endpoints.
+     */
+    constructor(bounds: number[]);
+    /** Total active covered y length, in the input coordinate system. */
+    get coveredLength(): number;
+    /**
+     * Adjust a nonempty half-open interval and refresh its ancestors' lengths.
+     * @param start - Inclusive endpoint index; 0 <= start < end.
+     * @param end - Exclusive endpoint index; end < bounds.length.
+     * @param delta - One on entry, minus one for the matching departure.
+     * @param node - Internal tree slot; callers use the root default.
+     * @param left - Inclusive endpoint index of this node.
+     * @param right - Exclusive endpoint index of this node.
+     * @returns Nothing; mutates this tree's coverage in O(log n).
+     */
+    update(start: number, end: number, delta: number, node?: number, left?: number, right?: number): void;
+}

package/dist/core/utils/metadata/change/union-area.d.ts

@@ -0,0 +1,7 @@
+import type { BoundingBox } from '../../../../types/index.js';
+/**
+ * Measure rectangle union with an x sweep in O(n log n) time and O(n) space.
+ * @param boxes - Finite rectangles; nonpositive dimensions are ignored.
+ * @returns Covered area in the input coordinate system, or zero for empty input.
+ */
+export declare function unionArea(boxes: BoundingBox[]): number;

package/dist/core/utils/metadata/scale-bounding-box.d.ts

@@ -0,0 +1,11 @@
+import type { BoundingBox } from '../../../types/index.js';
+/**
+ * Convert an analysis box to clamped integer output pixels.
+ * @param box - Analysis-space rectangle; the input remains unchanged.
+ * @param sx - Horizontal output-to-analysis scale.
+ * @param sy - Vertical output-to-analysis scale.
+ * @param width - Nonnegative output image width.
+ * @param height - Nonnegative output image height.
+ * @returns A rectangle contained within the output dimensions.
+ */
+export declare function scaleBoundingBox(box: BoundingBox, sx: number, sy: number, width: number, height: number): BoundingBox;

package/dist/core/utils/output/finalize-selection.d.ts

@@ -0,0 +1,15 @@
+import type { AnimationMetadata, FrameNode, ProcessContext, SieveMetadata } from '../../../types/index.js';
+/**
+ * Read output dimensions once, render optional sheets and finalize the shared v2 document.
+ * @param ctx - Pipeline state owned by the orchestrator; this function does not mutate it.
+ * @param selected - Selected frames in temporal order.
+ * @returns Mode-specific output, the document and zero-based API animations.
+ * @throws Propagates image, rendering and output I/O errors to the orchestrator.
+ */
+export declare function finalizeSelection(ctx: ProcessContext, selected: FrameNode[]): Promise<{
+    outputFiles: string[];
+    outputBuffers?: Buffer[];
+    document: SieveMetadata;
+    animations: AnimationMetadata[];
+    sheetBuffer?: Buffer;
+}>;

package/dist/core/utils/sheet/build-tile-label-svg.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Build a tile-sized SVG overlay with a translucent badge and an explicit text baseline.
+ * @param text - A formatTileLabel result containing only digits, #, spaces, colons and periods.
+ * @param tileWidth - Positive tile canvas width in pixels.
+ * @param tileHeight - Positive tile canvas height in pixels.
+ * @returns Encoded SVG bytes for a top-left sharp composite overlay.
+ */
+export declare function buildTileLabelSvg(text: string, tileWidth: number, tileHeight: number): Buffer;

package/dist/core/utils/sheet/format-tile-label.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Format a contact sheet label without rounding into the next tenth of a second.
+ * @param frameId - One-based candidate frame ID.
+ * @param timestampMs - Nonnegative candidate time in milliseconds.
+ * @returns A label in the form "#<id> mm:ss.s", allowing minutes beyond two digits.
+ */
+export declare function formatTileLabel(frameId: number, timestampMs: number): string;

package/dist/core/utils/sheet/render-contact-sheet.d.ts

@@ -0,0 +1,19 @@
+import type { FrameNode, SheetMetadata, SheetOptions } from '../../../types/index.js';
+/**
+ * Read selected frame images and render a row-major contact sheet.
+ * @param input - Nonempty ordered selections, positive dimensions and validated sheet settings.
+ * @returns JPEG bytes and the effective tile layout with one-based frame IDs.
+ * @throws Propagates sharp image reading, compositing or encoding errors.
+ */
+export declare function renderContactSheet(input: {
+    selected: FrameNode[];
+    resolution: {
+        width: number;
+        height: number;
+    };
+    options: Required<SheetOptions>;
+    quality: number;
+}): Promise<{
+    buffer: Buffer;
+    metadata: SheetMetadata;
+}>;

package/dist/core/utils/sheet/sample-tile-frames.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sample a sequence uniformly while always retaining both endpoints.
+ * @param items - Items in temporal order.
+ * @param maxTiles - Validated integer limit of at least two.
+ * @returns The original sequence when within the limit, otherwise evenly sampled items.
+ */
+export declare function sampleTileFrames<T>(items: T[], maxTiles: number): {
+    items: T[];
+    sampled: boolean;
+};

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

@@ -1,6 +1,15 @@
-import type { FrameNode, ProcessContext } from '../../types/index.js';
+import type { FrameNode, ProcessContext, SieveMetadata } from '../../types/index.js';
 export declare function createWorkspace(sessionId: string): Promise<string>;
-export declare function finalizeOutput(ctx: ProcessContext, selectedFrames: FrameNode[]): Promise<string[]>;
+/**
+ * Write selected JPEGs and the supplied document before replacing the output directory.
+ * @param ctx - Workspace, quality and destination settings.
+ * @param selectedFrames - Frames paired by position with document.frames.
+ * @param document - Complete metadata, including the output file names.
+ * @param sheetBuffer - Optional JPEG contact sheet bytes to persist unchanged.
+ * @returns Selected JPEG paths, optional sheet path and finally the metadata path.
+ * @throws Rejects mismatched frame counts and propagates image or filesystem errors.
+ */
+export declare function finalizeOutput(ctx: ProcessContext, selectedFrames: FrameNode[], document: SieveMetadata, sheetBuffer?: Buffer): Promise<string[]>;
 export declare function createSegmentWorkspace(parentWorkspacePath: string, segmentIndex: number): Promise<string>;
 export declare function cleanupWorkspace(workspacePath: string): Promise<void>;
 /**