@melite/models-h3 0.1.5-pre-alpha → 0.2.2-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,15 @@
1
+ import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
2
+ import type { H3Facts } from './actions.js';
3
+ /** The repair renderer: validates the bound entry, then composes the
4
+ * masked second-pass chain. Like the swap, the film path never
5
+ * reaches here (the card branches on a non-empty repair bag, refuses
6
+ * a bag under an armed reshoot or replace — one door per doc), and
7
+ * the emission ends in MiniMaxH3ChainAssemble.
8
+ * @param entry the repair mod's single bound entry
9
+ * @param p the walked doc params (the lora mod bag + SLA/shift knobs
10
+ * — the family plane this repair renders under)
11
+ * @param facts the family's lane facts (unet off the DECL row)
12
+ * @param g the run's graph builder
13
+ * @param runId the run tree's id (the assemble filename rides it) */
14
+ export declare function renderH3Repair(entry: Record<string, unknown>, p: Record<string, unknown>, facts: H3Facts, g: GraphBuilder, runId: string): void;
15
+ //# sourceMappingURL=repair.d.ts.map
package/lib/repair.js ADDED
@@ -0,0 +1,164 @@
1
+ import { loadVideo, renderMaskedEditChain } from './chainEdit.js';
2
+ import { assertGridLength } from './timelineContract.js';
3
+ /** The SAM3 checkpoint the mask family declares + hash-pins
4
+ * (packages/models/mask/src/index.ts — auto-provisioned; the track
5
+ * card's own SAM3_CKPT constant is the same file). */
6
+ const SAM3_CKPT = 'sam3.1_multiplex_fp16.safetensors';
7
+ /** The repair entry's required seats (the reshoot idiom: an armed
8
+ * doc with an empty seat refuses loud naming the seat). Two of the
9
+ * three are text, not staged media — the loop still speaks the one
10
+ * spelling so the refusal names the seat the same way the swap's
11
+ * does. */
12
+ const REQUIRED_SEATS = [
13
+ ['source_clip', 'the clip whose region is repaired — ONE staged leaf: the VHS window loader + the core LoadVideo read it by staged name, and the timeline reads it back off the native VIDEO wire'],
14
+ ['repair_prompt', 'the repair action text — what the masked region should become (the R2V prompt seat; agent-composed, user-confirmed)'],
15
+ ['region_prompt', 'the free-text SAM3 detection target naming the region — "hands", "a person", "a face" are param VALUES, never card kinds (the region-agnostic law)'],
16
+ ];
17
+ const num = (p, k, d) => typeof p[k] === 'number' ? p[k] : d;
18
+ const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
19
+ /** The repair renderer: validates the bound entry, then composes the
20
+ * masked second-pass chain. Like the swap, the film path never
21
+ * reaches here (the card branches on a non-empty repair bag, refuses
22
+ * a bag under an armed reshoot or replace — one door per doc), and
23
+ * the emission ends in MiniMaxH3ChainAssemble.
24
+ * @param entry the repair mod's single bound entry
25
+ * @param p the walked doc params (the lora mod bag + SLA/shift knobs
26
+ * — the family plane this repair renders under)
27
+ * @param facts the family's lane facts (unet off the DECL row)
28
+ * @param g the run's graph builder
29
+ * @param runId the run tree's id (the assemble filename rides it) */
30
+ export function renderH3Repair(entry, p, facts, g, runId) {
31
+ for (const [seat, what] of REQUIRED_SEATS) {
32
+ const v = entry[seat];
33
+ if (typeof v !== 'string' || v.trim() === '') {
34
+ throw new Error(`h3-timeline repair: '${seat}' names no media — ${what}; a repair needs all three seats bound (source_clip, repair_prompt, region_prompt)`);
35
+ }
36
+ }
37
+ const denoise = num(entry, 'denoise', 0.32);
38
+ if (denoise >= 1) {
39
+ throw new Error(`h3-timeline repair: denoise ${denoise} >= 1 — a masked second pass is a refine, never a re-render (the partial-denoise window is 0.05–0.50; denoise 1 would boil the held region into a new take — that is a reshoot, and the reshoot door exists)`);
40
+ }
41
+ const seed = num(entry, 'seed', 0);
42
+ const steps = num(entry, 'steps', 6);
43
+ const clipSeconds = num(entry, 'clip_seconds', 6);
44
+ const resolution = str(entry, 'resolution') || '736p';
45
+ const windowStart = num(entry, 'window_start', 0);
46
+ const windowLength = num(entry, 'window_length', 0);
47
+ // No silent clamps (the no-silent-repair law): a negative window
48
+ // is a caller bug — refuse loud, never round it into a render.
49
+
50
+ // geometry is 22+17k frames, and the mask tracks the WINDOW the
51
+ // loader cuts. An off-grid window length makes the tracked mask
52
+ // stack disagree with the plan's own intervals — the operator's
53
+ // trial-and-error burn — so a STATED length refuses at the compose
54
+ // door naming the nearest legal grid point, never engine-side.
55
+ if (windowLength > 0)
56
+ assertGridLength(Math.round(windowLength), 'h3-timeline repair window_length');
57
+ if (windowStart < 0 || windowLength < 0) {
58
+ throw new Error(`h3-timeline repair: window_start ${windowStart} / window_length ${windowLength} — a window seat never goes negative (frames at the film clock, 24 fps; 0/0 is the whole clip)`);
59
+ }
60
+ // ── the staged media: the WINDOW loader (cap + skip on the same
61
+ // VHS seat, so frames and audio stay in sync) and the inline
62
+ // per-frame SAM3 mask that replaces the swap's staged PNG ──
63
+ const [srcFrames, srcAudio] = loadVideo(g, str(entry, 'source_clip'), Math.round(windowLength), Math.round(windowStart));
64
+ const scaled = g.node('ImageScaleToMaxDimension', {
65
+ image: srcFrames, upscale_method: 'area', largest_size: 1008,
66
+ }).out(0);
67
+ const sam = g.node('CheckpointLoaderSimple', { ckpt_name: SAM3_CKPT });
68
+ const regionCond = g.node('CLIPTextEncode', {
69
+ text: str(entry, 'region_prompt'), clip: sam.out(1),
70
+ }).out(0);
71
+ const track = g.node('SAM3_VideoTrack', {
72
+ images: scaled, model: sam.out(0), conditioning: regionCond,
73
+ detection_threshold: num(entry, 'detection_threshold', 0.5),
74
+ max_objects: 0, detect_interval: 1,
75
+ }).out(0);
76
+ const regionMasks = g.node('SAM3_TrackToMask', {
77
+ track_data: track, object_indices: '',
78
+ }).out(0);
79
+ // picture_1 for the plan head: the window's own first frame. The
80
+ // plan node REQUIRES a picture (its describer vocabulary); the
81
+ // repair's "replacement" is the source's own person, so the
82
+ // window's lead frame is the truthful anchor — and the geometry
83
+ // law (grid snap + tier scaling off source_frames) stays
84
+ // engine-owned either way.
85
+ const anchorFrame = g.node('ImageFromBatch', {
86
+ image: srcFrames, batch_index: 0, length: 1,
87
+ }).out(0);
88
+ renderMaskedEditChain(g, {
89
+ p, facts,
90
+ clipSeconds,
91
+ overlapFrames: num(entry, 'overlap_frames', 39),
92
+ resolution, seed, steps,
93
+ roles: '',
94
+ sourceClip: str(entry, 'source_clip'),
95
+ windowStart,
96
+ picture1: anchorFrame,
97
+ srcFrames, srcAudio,
98
+ // the ignored literal fallback — the plan node's WINDOW-RE-SLICED
99
+ // shots ride plan_json_input (the repair's geometry law)
100
+ planJson: JSON.stringify({ shots: [{ id: 'repair', prompt: str(entry, 'repair_prompt') }] }),
101
+ planFromSource: true,
102
+ denoise,
103
+ assemble: {
104
+ // a repair is a VISUAL second pass: the soundtrack is the
105
+ // source's own, always (audio_source 'source' — the swap's
106
+ // keep_audio switch has no repair pole to flip)
107
+ audioSource: 'source',
108
+ filename: `${runId}/repair`,
109
+ },
110
+ body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio }) => {
111
+
112
+ // parity. The plan head segments the window engine-side (the
113
+ // swap's own choreography — planFromSource rides the same
114
+ // seat); the loop drives the scenes; ChainAssemble stitches.
115
+ // The one wire that never segmented was THE MASK: the tracked
116
+ // stack (the whole window's timeline) fed every scene whole,
117
+ // so a multi-scene repair saw rows it did not own (the F7
118
+ // burn: one oversized shot, the mask leg loop-posture-only).
119
+ // MiniMaxH3ContexLoopMaskSlice selects the current scene's
120
+ // interval off the loop state — the tracked mask stack sliced
121
+ // to each scene's frame range, BEFORE the grow (the
122
+ // extension's own posture: slice, then Grow Mask). A
123
+ // single-scene window slices its own whole interval — the
124
+ // cure is posture-uniform, never a branch. ──
125
+ const sceneMask = g.node('MiniMaxH3ContexLoopMaskSlice', {
126
+ state: cur.out(0), mask: regionMasks, source_fps: 24,
127
+ });
128
+ const grown = g.node('GrowMaskWithBlur', {
129
+ mask: sceneMask.out(0), expand: Math.round(num(entry, 'mask_grow', 16)),
130
+ tapered_corners: true, blur_radius: 0,
131
+ }).out(0);
132
+ // ── the masked second-pass body: NO still, NO mannequin — the
133
+ // source clip rides its own ref_video seat (the identity
134
+ // anchor of a repair is the person already in the frame — the
135
+ // zero-new-pixels law) ──
136
+ const r2v = g.node('MiniMaxH3ReferenceToVideo', {
137
+ prompt: str(entry, 'repair_prompt'),
138
+ width: cur.out(8), height: cur.out(9), length: cur.out(6),
139
+ ref_image_size: 'match',
140
+ clip, vae: vaeVideo, audio_vae: vaeAudio,
141
+ 'ref_videos.ref_video_0': srcFrames,
142
+ 'ref_video_audios.ref_video_audio_0': mutedChainAudio,
143
+ });
144
+ const slice = g.node('H3SourceSlice', {
145
+ source_fps: 24, crop: 'center',
146
+ state: cur.out(0), latent: r2v.out(1),
147
+ audio_vae: vaeAudio, source_frames: srcFrames, source_audio: sliceAudio,
148
+ });
149
+ const edit = g.node('MiniMaxH3FantasticVideoEditLatent', {
150
+ grow: 0, keep_audio: true, megapixels: 0,
151
+ vae: vaeVideo, images: slice.out(0), mask: grown,
152
+ audio_vae: vaeAudio, audio: slice.out(1),
153
+ }).out(0);
154
+ const target = g.node('MiniMaxH3ContexMaskedTarget', {
155
+ mask_meaning: 'white = generate',
156
+ audio_mode: 'preserve source audio',
157
+ mask_conversion: 'H3 exact (causal/token max)',
158
+ target_latent: edit, mask: grown,
159
+ }).out(0);
160
+ return { conditioning: r2v.out(0), targetLatent: target };
161
+ },
162
+ });
163
+ }
164
+ //# sourceMappingURL=repair.js.map
@@ -0,0 +1,201 @@
1
+ import type { OutputHandle } from '@melite/comfyui-card-kit/graph';
2
+ import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
3
+ /** The pack's clip-normalization node (the official chain's first
4
+ * stage — resamples to 24 fps, snaps the frame count to H3's 17k+5
5
+ * grid, centre-crops to the requested aspect at the pixel budget).
6
+ * The F13d grid-match burn this node kills at the source: the old
7
+ * chain resized VDA depth onto full-size frames by hand. */
8
+ export declare const CROSSVIEW_PREPARE_NODE = "CrossViewPrepareClip";
9
+ /** The pack's reprojection node (the one class the pack always
10
+ * carried; the official graph wires moge_geometry, the metric
11
+ * input — never the legacy brightness-depth seat). */
12
+ export declare const CROSSVIEW_WARP_NODE = "CrossViewWarp";
13
+ /** Core MoGe nodes (engine comfy_extras/nodes_moge.py — v0.37+,
14
+ * no pack provision rides them). */
15
+ export declare const MOGE_LOAD_NODE = "LoadMoGeModel";
16
+ export declare const MOGE_INFER_NODE = "MoGeInference";
17
+ /** The prepare node's own clock (it resamples every clip to 24 fps
18
+ * before the warp sees it) — the unit the guide duration is stated
19
+ * in. */
20
+ export declare const CROSSVIEW_PREP_FPS = 24;
21
+ /** The shortest window a re-shoot will guide: one second of prepared
22
+ * motion. Below this the warp carries no usable parallax and the
23
+ * guide outlives the window it is pinned into. */
24
+ export declare const CROSSVIEW_MIN_GUIDE_FRAMES = 24;
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+
41
+ export declare function crossviewGuideSeconds(windowFrames: number): number;
42
+ /** MoGe-2 ViTL normal fp16 — the official workflow's one geometry
43
+ * checkpoint (Comfy-Org/MoGe on HF), already on the engine's
44
+ * geometry_estimation shelf. */
45
+ export declare const MOGE_MODEL = "moge_2_vitl_normal_fp16.safetensors";
46
+ /** The CrossView LoRA (Cseti/MiniMax-H3_Ref2VA-LoRA-CrossView-Warp_v1
47
+ * on HF, the _3500 step file comfy-reshoot pins): trained against
48
+ * the warp guide, it is what makes H3 FOLLOW the moved camera.
49
+ * Arm-functional, not a Modifiers row — the Fun ControlNet patch
50
+ * precedent (a per-arm model file provisioned by the family, never
51
+ * a user-picked distill seat; the catalog is for adapters a user
52
+ * stacks freely, and this one is meaningless outside a reshoot). */
53
+ export declare const CROSSVIEW_LORA = "h3/MiniMax-H3_Ref2VA-LoRA-CrossView-Warp_v1_3500.safetensors";
54
+ /** The LoRA's trigger word (the pack's own docs + the official
55
+ * graph's prompt is exactly `crossview.`) — rides the r2v prompt
56
+ * when the arm is armed, or the LoRA does not fire. */
57
+ export declare const CROSSVIEW_TRIGGER = "crossview";
58
+ /** The pose + conditioning knobs the chain reads (the RESHOOT_MOD
59
+ * bag entry's own wire names — the card's field rows own the
60
+ * bounds, these are the names on the wire). */
61
+ export interface ReshootKnobs {
62
+ readonly orbit: number;
63
+ readonly tilt: number;
64
+ readonly dolly: number;
65
+ readonly zoom: number;
66
+ readonly pan: number;
67
+ readonly strength: number;
68
+ readonly depthRatio: number;
69
+ readonly smoothDepth: boolean;
70
+ readonly invertDepth: boolean;
71
+ }
72
+ /** The dial bands — MIRRORED from the card's RESHOOT_MOD field rows
73
+ * (the UI's own bounds; the wall judges the two homes in 1:1
74
+ * agreement). A bag entry rides the compose door as a loose dict,
75
+ * so the READER owns the refusal — out-of-domain dials refuse LOUD
76
+ * here, ahead of the engine, never as a ComfyUI widget 400. */
77
+ /** The app's default camera move (see {@link readReshootKnobs}). */
78
+ export declare const RESHOOT_DEFAULT_POSE: Readonly<{
79
+ orbit: number;
80
+ tilt: number;
81
+ }>;
82
+ /** The smallest pose the CrossView LoRA accepts as a camera MOVE. The
83
+ * pack's README: "Avoid near-zero angles — the LoRA misbehaves when
84
+ * the warp is almost identical to the source." Below this both-angle
85
+ * floor the warp is the input clip plus hole noise, and the guide
86
+ * prior contradicts the source prior instead of extending it. */
87
+ export declare const RESHOOT_MIN_POSE_DEGREES = 5;
88
+ export declare const RESHOOT_DIAL_BOUNDS: Readonly<Record<string, readonly [number, number]>>;
89
+ /** THE OFFICIAL APP'S POSE (Comfy-Org/comfy-reshoot,
90
+ * workflows/generate.api.json node 5: azimuth -30, elevation 20, the
91
+ * app's own slider defaults) — never the identity camera. The pack's
92
+ * README names the failure mode verbatim: "Avoid near-zero angles —
93
+ * the LoRA misbehaves when the warp is almost identical to the
94
+ * source." The identity default shipped a warp indistinguishable from
95
+ * the input, fed it to a camera LoRA as the geometric prior, and
96
+ * round 5 measured the result (a second subject at a second scale).
97
+ * The neutral pose is therefore the app's DEFAULT camera move: orbit
98
+ * -30°, tilt +20° (inside the green training zone), the source
99
+ * distance, a normal 50° lens, no framing shift. The
100
+ * strength default is the official 0.8 (the LoRA's own tested
101
+ * band is 0.5–1, served default 0.8). */
102
+ export declare function readReshootKnobs(p: Record<string, unknown>): ReshootKnobs;
103
+ /** The arm predicate: BAG PRESENCE — the same law as the replace/
104
+ * repair/extend arms (the fourth-mod-bag unification: a commission
105
+ * is armed when its bag is a NON-EMPTY ARRAY, whatever its entry's
106
+ * shape). A non-object entry and a bag whose entry names no source
107
+ * clip both stay ARMED and refuse loud at the chain build (the
108
+ * compose's missing-required law) — neither quietly disarms the
109
+ * film. Absent or empty bag = the compose never sees the chain
110
+ * (byte-stable graphs). */
111
+ export declare function reshootArmed(p: Record<string, unknown>): boolean;
112
+ /** The r2v prompt seat under the arm: the trigger word leads (the
113
+ * official graph's prompt is exactly `crossview.` — the LoRA fires
114
+ * on the word's presence, the estate's own motion prose follows). */
115
+ export declare function reshootPrompt(prompt: string): string;
116
+ /** The run-level chain handles: built once per compose (film or
117
+ * single window), consumed by every window's two seats. */
118
+ export interface ReshootChain {
119
+ /** The prepared source frames — the appearance/identity
120
+ * reference (the official chain's ref_videos.ref_video_0). */
121
+ readonly refFrames: OutputHandle;
122
+ /** The warp — the geometric guide for the moved camera, HOLES
123
+ * INCLUDED (the official chain's MiniMaxH3AddGuide image seat;
124
+ * the magenta disocclusions are the LoRA's training signal). */
125
+ readonly warp: OutputHandle;
126
+ /** CrossViewPrepareClip's own width/height outputs (slots 1/2) —
127
+ * the shape the prepared clip was cropped to at the render
128
+ * target's pixel budget (aspect 'source', multiple 32). The
129
+ * official graph feeds these straight into
130
+ * MiniMaxH3ReferenceToVideo's width/height (node 20), so the
131
+ * reference frames and the rendered latent can never disagree
132
+ * about shape (a source whose aspect differs from the doc's
133
+ * literal would otherwise feed aspect-faithful refs into a
134
+ * differently-shaped latent — the soft-render class). */
135
+ readonly prepWidth: OutputHandle;
136
+ readonly prepHeight: OutputHandle;
137
+ /** CrossViewPrepareClip's frame-count output (slot 3) — the
138
+ * SHORTEST window's legal length. It is NOT wired into a film
139
+ * window's render length: one guide is shared by every window, so
140
+ * its own count would shorten longer windows (the documented
141
+ * divergence from node 20, beside duration). */
142
+ readonly prepLength: OutputHandle;
143
+ /** The ONE plate frame the guide pins (CrossViewWarp's frame 0),
144
+ * saved through `ImageFromBatch { batch_index: 0, length: 1 }` —
145
+ * never the whole warp clip (N PNGs for one still). The run
146
+ * delivers the exact image the guide reads, holes and all, without
147
+ * re-deriving it from the film. Saved under `<runId>/reshoot_warp`. */
148
+ readonly plateSave: OutputHandle;
149
+
150
+
151
+
152
+
153
+
154
+ readonly orbitSave: OutputHandle;
155
+ }
156
+ /**
157
+ * Build the re-shoot chain on the run's graph (once per compose).
158
+ *
159
+ * @param p the gated compose doc (the reshoot bag's entry carries
160
+ * source_clip + the camera knobs; reshootArmed gates the build)
161
+ * @param g the run's graph builder
162
+ * @param windowFrames the SHORTEST window this run renders (the guide
163
+ * is pinned into every window, so its duration derives from this —
164
+ * F28)
165
+ * @param runId the run's own id — scopes the two preview saves under
166
+ * the run's output folder so the artifact harvest lists them with
167
+ * the film (§8.7)
168
+ * @returns the shared handles for the per-window seats
169
+ */
170
+ export declare function buildH3Reshoot(p: Record<string, unknown>, g: GraphBuilder, windowFrames: number, runId: string): ReshootChain;
171
+ /**
172
+ * The per-window MODEL seat: the CrossView LoRA on the window's
173
+ * model, post sigma shift (the official order — the distill lora
174
+ * loads first, the shift + attention ride over it, the CrossView
175
+ * LoRA applies LAST so the camera-trained adapters win). Mounted
176
+ * ahead of the file-based picks chain — the camera spine; picks
177
+ * refine on top.
178
+ *
179
+ * @param g the window's (scoped) builder
180
+ * @param model the window's model so far (post sigma shift)
181
+ * @param p the gated doc (the strength dial rides, band 0.5–1)
182
+ * @returns the LoRA-loaded model handle for the scheduler chain
183
+ */
184
+ export declare function applyH3ReshootModel(g: GraphBuilder, model: OutputHandle, p: Record<string, unknown>): OutputHandle;
185
+ /**
186
+ * The per-window CONDITIONING seat: the warp pinned into the
187
+ * window's own AV latent at row 0 through MiniMaxH3AddGuide — the
188
+ * H3-native guide lane (the same node the estate's keyframe pins
189
+ * ride), the official chain's image seat verbatim. Mounts AFTER the
190
+ * arm's own guide pins (audio first, keyframes next, the camera
191
+ * spine last — the strongest structural prior closes the chain).
192
+ *
193
+ * @param g the window's (scoped) builder
194
+ * @param cond the window's positive conditioning so far
195
+ * @param latent the window's latent (the guide pins into it)
196
+ * @param vae the window's video VAE (the guide image encodes through it)
197
+ * @param chain the shared run-level handles
198
+ * @returns the guide-wrapped conditioning for the guider
199
+ */
200
+ export declare function applyH3ReshootCond(g: GraphBuilder, cond: OutputHandle, latent: OutputHandle, vae: OutputHandle, chain: ReshootChain): OutputHandle;
201
+ //# sourceMappingURL=reshoot.d.ts.map