166 lines
6.8 KiB
Markdown
166 lines
6.8 KiB
Markdown
# ComfyUI Stable Manifold Compander
|
|
|
|
Stable Manifold Compander is a ComfyUI custom node pack for correcting the high-resolution drift that can show up in FLUX.2-style workflows, especially with detail crops, masked edits, and larger full-frame renders.
|
|
|
|
Instead of only resizing the image, the pack tries to pull the high-resolution result back toward a lower-resolution reference state that is usually compositionally more stable. In practice this helps counter issues such as:
|
|
|
|
- outward zoom or expansion drift
|
|
- low-frequency washout or relighting
|
|
- reduced color richness or chroma flattening
|
|
- crop-to-image mismatch after compositing a detailed region back into the source image
|
|
|
|
The pack includes a primary anchor-guided workflow for general use, an affine diagnostic/fallback workflow, and an optional Impact Pack hook for in-detailer correction.
|
|
|
|
## What it does
|
|
|
|
The core idea is simple:
|
|
|
|
1. derive or provide a lower-resolution anchor that represents the more stable version of the image or crop
|
|
2. compare the high-resolution result against that anchor
|
|
3. apply a controlled correction that pulls geometry and low-frequency structure inward without throwing away high-frequency detail
|
|
|
|
This makes the pack useful for both whole-image correction and crop-based detailing workflows.
|
|
|
|
## Included nodes
|
|
|
|
### Main workflow
|
|
- **SMC Config**
|
|
- **SMC Make Anchor**
|
|
- **SMC Anchor Resolution**
|
|
- **SMC Anchor-Guided Compand**
|
|
- **SMC Extract Masked Crop**
|
|
- **SMC Composite Crop**
|
|
- **SMC Frequency Split**
|
|
- **SMC Compand Blend**
|
|
- **SMC Describe Config**
|
|
|
|
### Affine / diagnostic workflow
|
|
- **SMC Affine Profile**
|
|
- **SMC Affine Anchor Resize**
|
|
- **SMC Affine Estimate Drift**
|
|
- **SMC Affine Compand**
|
|
- **SMC Affine Low / High Split**
|
|
- **SMC Affine Recombine**
|
|
|
|
### Optional Impact Pack integration
|
|
- **SMC Self-Anchor Detailer Hook Provider**
|
|
|
|
## Recommended workflows
|
|
|
|
### 1. Masked crop detailing
|
|
This is the most useful workflow when a face, subject, or region drifts after high-resolution detailing.
|
|
|
|
1. Create a mask for the region you want to process.
|
|
2. Use **SMC Extract Masked Crop** to pull out the image region and crop mask.
|
|
3. Run your normal upscale, detail, or edit pass on that crop.
|
|
4. Use **SMC Anchor-Guided Compand** on the edited crop.
|
|
- Supply an explicit anchor if you already have a low-resolution reference.
|
|
- Otherwise let the node derive one from the configured anchor megapixel target.
|
|
5. Paste the corrected crop back with **SMC Composite Crop**.
|
|
|
|
This workflow is usually the best fit for reducing crop expansion, relighting drift, and paste mismatch.
|
|
|
|
### 2. Whole-image correction
|
|
Use this when the full image drifts as resolution rises.
|
|
|
|
1. Build a mask for the affected subject or area, or use a broad mask for the whole image.
|
|
2. Create settings with **SMC Config**.
|
|
3. Run **SMC Anchor-Guided Compand** on the high-resolution image.
|
|
4. Use **SMC Compand Blend** if you want a softer or partial blend back to the original.
|
|
|
|
### 3. Diagnostic or fallback correction
|
|
Use the affine nodes when you want a more explicit and interpretable correction path.
|
|
|
|
The affine workflow is useful for:
|
|
- estimating scale and translation drift directly
|
|
- testing correction strength in a more controlled way
|
|
- older experiments where you want a clearer diagnostic readout
|
|
- the optional Impact Pack self-anchor hook
|
|
|
|
## Node overview
|
|
|
|
### SMC Config
|
|
Builds the main correction configuration used by the anchor-guided path.
|
|
|
|
Important controls:
|
|
- **anchor_mp**: target size of the internal low-resolution anchor
|
|
- **warp_strength**: overall strength of the inward correction
|
|
- **radial_strength**: how strongly the correction behaves like inward compaction
|
|
- **lowfreq_anchor_mix**: how much low-frequency structure is pulled toward the anchor
|
|
- **chroma_restore** / **contrast_restore**: restore color and tonal presence after correction
|
|
- **detail_preservation**: keeps high-frequency detail from collapsing
|
|
- **max_inward_shift_px**: safety cap on geometric correction magnitude
|
|
|
|
### SMC Make Anchor
|
|
Creates a low-resolution anchor and also returns a resized version at the original resolution for inspection.
|
|
|
|
### SMC Anchor Resolution
|
|
Calculates the anchor resolution for a given megapixel target while preserving aspect ratio.
|
|
|
|
### SMC Anchor-Guided Compand
|
|
Main correction node. It takes a high-resolution image, a mask, and a config, then outputs:
|
|
- corrected image
|
|
- anchor image used internally
|
|
- warped intermediate
|
|
- flow visualization
|
|
- debug mask
|
|
- numeric metrics summary
|
|
|
|
### SMC Extract Masked Crop / SMC Composite Crop
|
|
Utility nodes for crop-based workflows. These make it easier to extract a masked region, process it externally, and composite it back cleanly.
|
|
|
|
### SMC Frequency Split / SMC Compand Blend
|
|
Inspection and finishing utilities. Use them to preview low/high components or blend the processed result back more gently.
|
|
|
|
### Affine nodes
|
|
These expose a more explicit correction path based on drift estimation and affine-style compaction. They are especially useful when you want to inspect the estimated scale and translation values directly.
|
|
|
|
### SMC Self-Anchor Detailer Hook Provider
|
|
Optional Impact Pack hook.
|
|
|
|
It stores the post-upscale crop as a self-anchor, then runs the affine compand path after decode. This is a practical fallback for FaceDetailer-style workflows when you want some correction inside the hook surface itself.
|
|
|
|
## Installation
|
|
|
|
Clone or copy this repository into:
|
|
|
|
`ComfyUI/custom_nodes/ComfyUI-Stable-Manifold-Compander`
|
|
|
|
Then restart ComfyUI.
|
|
|
|
## Requirements
|
|
|
|
No extra Python dependencies are required beyond a normal ComfyUI PyTorch installation.
|
|
|
|
For **SMC Self-Anchor Detailer Hook Provider**, you also need **ComfyUI-Impact-Pack** installed.
|
|
|
|
## Notes and limitations
|
|
|
|
- **SMC Extract Masked Crop** and **SMC Composite Crop** currently support batch size 1 only.
|
|
- The main anchor-guided method is training-free and heuristic. It is not a learned deformation model, optical flow solver, or landmark-based warp.
|
|
- The Impact hook is a practical fallback, not a replacement for a true two-pass low-resolution anchor branch.
|
|
- Results depend heavily on mask quality and on choosing an anchor megapixel range that matches the model's stable regime.
|
|
|
|
## When to use which path
|
|
|
|
Use the **anchor-guided path** when:
|
|
- you want the main intended workflow
|
|
- you are correcting FLUX.2 klein high-resolution drift directly
|
|
- you are working with masked crops or broad masked regions
|
|
|
|
Use the **affine path** when:
|
|
- you want direct drift estimates
|
|
- you need a more diagnostic or interpretable correction route
|
|
- you want the optional Impact Pack self-anchor hook
|
|
|
|
## Files
|
|
|
|
- `core.py` — anchor-guided compand implementation
|
|
- `affine_core.py` — affine/profile correction implementation
|
|
- `impact_hook.py` — Impact Pack self-anchor hook
|
|
- `nodes.py` — ComfyUI node registration and UI surface
|
|
- `__init__.py`
|
|
- `pyproject.toml`
|
|
- `requirements.txt`
|
|
- `.gitignore`
|