CS Spatial Restore

CS Spatial Restore is the second half of the two-node trick that starts with CS Spatial Stabilize. That node stabilizes a moving subject into a fixed, equal-area crop so you can run a per-frame inpaint, face fix, or detail pass over something that isn't sliding around. But once you've edited the crop, you still face the other half: getting it back onto the original footage at the original positions, without a visible box or double-vision ghost.

That compositing job is exactly what this node does. Feed it the original frames, the processed stabilized crop, and the transform data from Stabilize, and it inverse-warps your edit onto each frame, blends it in, and hands back a full-resolution video batch. It's the "stitch" in crop-and-stitch - but the geometry is computed once, up front, rather than re-guessed per frame.

How it works

The source tells the story better than the README does. stable_data (the CS_SPATIAL_STABLE_DATA output from Stabilize) carries one forward and one inverse affine matrix per frame, plus the crop geometry. Restore:

1. Validates everything first. It checks that stable_data actually came from CS Spatial Stabilize and that the recorded frame count, source size, and crop size all match the tensors you've connected. Mismatches throw descriptive errors rather than silently compositing garbage.
2. Works out, per frame, the region of the source that the crop actually covers, so it only samples that region instead of reprojecting the whole frame.
3. Builds a composite alpha. If you connected the optional mask, that mask (in crop space, matching the stabilized frames) decides what gets replaced - and Soft Border is ignored. If you didn't, the whole crop is used, feathered along its four edges by Soft Border pixels so the boundary fades instead of forming a hard rectangle.
4. Samples the processed crop back into source coordinates (premultiplied by the alpha, bilinear), then blends: output = source × (1 − alpha) + edit × alpha.

That last bit matters more than it looks: outside the composite region the output is a straight clone of the source frames - byte-for-byte untouched pixels. That's the whole guarantee of this pattern: the only thing that changes is what you deliberately replaced.

The inputs that matter

• source_image - the same original frame batch you fed into CS Spatial Stabilize.
• stabilized_image - your processed crop batch. It must keep the exact frame count and crop dimensions Stabilize emitted. This is the trap: whatever you do in between (inpaint, restore, upscale) must not resize or drop/duplicate frames, or Restore will refuse or misalign.
• stable_data - the matching STABLE_DATA output. If you tweak Stabilize's settings or trim the clip, rerun it and reconnect the fresh data.
• mask (optional) - wire Stabilize's MASK output here and only the masked subject is replaced, keeping everything around it pristine. Skip it when your processing legitimately changed the whole crop and you want the full feathered paste.
• Soft Border (crop px) (default 32, in crop-space pixels) - only used when no mask is connected. 0 turns feathering off, which you'll regret unless the crop edge already sits somewhere invisible.

The single output is IMAGE: the restored frames, same size and count as the source, ready to feed CS Save Video or any downstream video node.

Installing and the honest gotchas

Install with ComfyUI Manager (search "ComfyUI_CineStyle") or git clone https://github.com/chflame163/ComfyUI_CineStyle.git into ComfyUI/custom_nodes/, then restart. Like the rest of the pack's requirements, the heavy deps (transformers, av, and friends) install regardless, but Restore itself needs none of them - it's torch grid_sample math, no model download.

Real-world pitfalls, from the code and the workflow docs:

• Frame count and crop size must line up across all three inputs. The top beginner breakage is an intermediate node that resizes the crop or changes batch length; Restore's validation calls it out by name, so read the error.
• stable_data and source_image must come from the same Stabilize run. Re-cut the clip or re-run Stabilize and you need fresh data on this side too.
• If your local edit changed pixels outside the mask you fed Stabilize, connect the mask to Restore anyway, or those stray changes get pasted back in. No mask means full-crop paste with feathered edges - right only when you want the whole region replaced.
• It handles GPU hiccups gracefully: a frame that doesn't fit in VRAM falls back to CPU and it keeps going.

The pack is new and obscure enough that there's little community lore to lean on; the repo's CS_Spatial_Stabilize_Restore_Example.json shows the intended chain (CS Load Video → segment masks → Stabilize → your edit → Restore) and is worth loading just to see the wiring.