ComfyUI Extension

PortraitUtils

A focused node collection designed for pipelines using real photographic images where resolutions are not standardized like they are in text-to-image generation.

By heyburns·Created 12 months ago·Updated 3 days ago· 2

heyburns/PortraitUtils

Nodes32

On cloudLocal install

CategoryPortraitUtils/Adjustment V2, PortraitUtils/Debug

Stars2

Updated3 days ago

Nodes (32)

Auto Adjust (Photoshop-style)

PortraitUtils/Adjustment V2

Comparison Gate

Make before/after images arrive at the same moment, every run

PortraitUtils/Debug

Filename: Append Suffix

Suffix filenames without breaking multi-part extensions

PortraitUtils/String

Outpaint Padding Compute

PortraitUtils/Config V2

Active Editor Target

PortraitUtils/Photo Edit

Intelligent AutoCrop

PortraitUtils/Transform

Input & Crop Config

PortraitUtils/Config V2

Crop by Margins (Image)

PortraitUtils/Transform

Crop by Margins (Mask)

PortraitUtils/Transform

Crop Prompt from Config

PortraitUtils/Config V2/Readers

Edit & Composite Config

PortraitUtils/Config V2

Editor Result Gate

PortraitUtils/Photo Edit

Editor Target Beacon

PortraitUtils/Photo Edit

Edit Prompt from Config

PortraitUtils/Config V2/Readers

Finish & Run Config

PortraitUtils/Config V2

Scale from Config

PortraitUtils/Config V2/Readers

Seed from Config

PortraitUtils/Config V2/Readers

Simple Image Saver

PortraitUtils/IO

Outpaint Config

PortraitUtils/Config V2

Outpaint Prompt from Config

PortraitUtils/Config V2/Readers

Paired Image Loader

PortraitUtils/IO

Load Image + Source Info

PortraitUtils/IO

Detect & Split Photo Panels

PortraitUtils/Photo Edit V2

Smart Photo Prepare

PortraitUtils/Photo Edit V2

Crop Box from Prepare Info

PortraitUtils/Photo Edit V2/Readers

Dimensions from Prepare Info

PortraitUtils/Photo Edit V2/Readers

Scale from Prepare Info

PortraitUtils/Photo Edit V2/Readers

Summary from Prepare Info

PortraitUtils/Photo Edit V2/Readers

Process Scanned Photo

PortraitUtils/Transform

Save Info from Source

PortraitUtils/Config V2/Readers

Stitch by Mask

PortraitUtils/Composite V2

Auto White-Balance + Color Match

PortraitUtils/Analysis

Readme

PortraitUtils 2.0

ComfyUI utilities for editing, restoring, and finishing real photographs. PortraitUtils handles subject-aware framing, editor-ready dimensions, scanned print cleanup, tone and color correction, compositing, and image I/O. It does not include generative models or replace your editor or upscaler.

Version 2.0.0 contains 32 nodes, with four compact configuration bundles and small readers that expose values only where you need them.

What's new in 2.0

One Smart Photo Prepare node: subject framing, protected-region handling, exact forced aspect ratios, and editor-specific resizing in one stage. Protected regions are respected with Smart Crop both on and off. Added canvas can use Black, White, or Edge extension padding.
Current editor targets: Qwen Image Edit 2.1, FireRed Image Edit 1.1, and Flux 2 Klein Base, plus an explicit Direct / No Editor path. Qwen 2511 and Flux Kontext targets are retired.
Compact configuration: separate crop, edit/composite, outpaint, and finishing bundles replace a central node with dozens of outputs. Three short stitch prompts can drive separate segmentation nodes.
Rebuilt processing: improved loaders, solid-border detection, scanned-print cleanup, white balance, mask compositing, and image saving. Saves support atomic file publication, workflow metadata, and optional 16-bit PNG.
Shared engines and validation: consistent image/mask handling, explicit errors, independent loader cursors, preparation diagnostics, and regression tests. Superseded node interfaces have been removed.

This is a breaking release. Read Upgrading from 1.x before replacing an existing installation.

Install / Update

Clone this repository into ComfyUI/custom_nodes/PortraitUtils, or update your existing checkout after backing up workflows that use it.
Install requirements.txt using ComfyUI's Python environment, not an unrelated system Python. For a virtual-environment installation, substitute your actual path:
```
/path/to/ComfyUI/venv/bin/python -m pip install -r /path/to/ComfyUI/custom_nodes/PortraitUtils/requirements.txt
```
Windows portable installations should use their bundled python_embeded interpreter instead. ComfyUI supplies the hardware-specific PyTorch build; this suite does not install a replacement. Use only one OpenCV wheel variant in that environment; see the dependency notes in requirements.txt.
Restart the ComfyUI server, then refresh the browser. A browser refresh alone does not reload Python nodes.

Python 3.10+ and a working ComfyUI installation are required. Some compressed 16-bit TIFFs additionally require the optional imagecodecs package; the loader reports when it is needed. Editor models, segmentation nodes, upscalers, group muters, and image choosers are separate installations, not suite dependencies.

Typical wiring

Load Image → Intelligent AutoCrop → Smart Photo Prepare
                                     ↓
                              Selected editor
                                     ↓
                             Editor Result Gate → Upscaler → Finish / Save

Generate subject/protected-region masks from the image after border cleanup, and connect them to Photo Prepare on the same pixel grid. Put a Target Beacon inside each mutually exclusive editor group; one Active Editor Target outside those groups drives both Photo Prepare and Editor Result Gate. Only the selected editor's decoded result passes through the gate. Direct / No Editor is an explicit opt-in, not a fallback when an editor result is missing.

Use Photo Prepare's prepared_image for editor input. native_crop is the original-resolution source crop before padding or resizing, not the editor-ready image. The other outputs are prepared_mask and prepare_info; local readers extract dimensions, crop coordinates, scale, or diagnostics.

| Editor target | Automatic sizing | Gate input | | --- | --- | --- | | Qwen Image Edit 2.1 | Dynamic, 32-aligned sizes at 1 MP, 1.5 MP, or 2K (~4 MP) | qwen21_image | | FireRed Image Edit 1.1 | Approximately 1 MP presets used by its official workflow | firered_image | | Flux 2 Klein Base | Dynamic, 16-aligned sizes at 1 MP or 1.5 MP | klein_image |

Auto (preserve detail) prefers a tier that avoids downscaling when available. Force 1 MP is available for testing; FireRed's Force 1.5 MP is an experimental larger output, not a documented native tier. Force 2K is Qwen 2.1 only. Forced aspect ratios are mathematically exact with the selected editor's alignment. The direct path retains source scale rather than selecting an editor tier.

Avoid a second crop/resize node after Photo Prepare: in particular, remove the FireRed example's FluxKontextImageScale when using prepared_image. See the editor-specific wiring and sizing guide and configuration guide for details.

Node guide

Each current node has its own screenshot slot below. Existing screenshot assets are retained in docs/screenshots/; placeholders mark interfaces needing a current 2.0 capture. To fill a slot, save the named PNG there and replace the placeholder line with the commented image markup below it. Existing displayed screenshots use the same centered, 500-pixel-wide layout.

Loading, saving & comparison

Load Image + Source Info

Single-image or auto-advancing folder loading with independent cursors, EXIF orientation, explicit color/alpha handling, and one source-info bundle. Guide

<div align="center"><em>Screenshot placeholder: <code>photo_loader_node.png</code></em></div>

Paired Image Loader

Load matching source/output files for before-and-after comparison, with natural ordering and independent, transactional pair cursors. Guide

<div align="center"><em>Screenshot placeholder: <code>portraitutils_paired_image_loader.png</code></em></div>

Simple Image Saver

Atomic PNG/JPG saves with filename suffixes, collision handling, optional workflow metadata, 8/16-bit PNG, and a black/white JPEG alpha matte. Guide

<div align="center"><em>Screenshot placeholder: <code>simple_image_saver.png</code></em></div>

Filename: Append Suffix

Construct a filename with a configurable suffix before passing it to a saver. Guide

<div align="center"><img src="docs/screenshots/filename_append_suffix.png" alt="Filename: Append Suffix node" width="500" /></div>

Comparison Gate

Select a populated final/source image pair for a comparison viewer. This is a pair selector, not an interactive pause or an editor-routing gate. Guide

<div align="center"><img src="docs/screenshots/comparison_gate.png" alt="Comparison Gate node" width="500" /></div>

Cropping & photo preparation

Intelligent AutoCrop

Remove solid borders and supported text-bearing footers, including Alamy-style borders, before subject framing. Conservative detection and an explicit border policy help avoid treating photographic content as a border. Guide

<div align="center"><em>Screenshot placeholder: <code>intelligent_autocrop_node.png</code></em></div>

Smart Photo Prepare

Crop, pad, and resize once for the selected editor or direct-upscaler path. Combines optional subject framing with protected regions, configured safety margins, exact forced aspects, and editor-size selection. Four outputs keep the node compact without losing the original source crop or diagnostics. Guide

<div align="center"><em>Screenshot placeholder: <code>smart_photo_prepare_node.png</code></em></div>

Process Scanned Photo

Straighten a dominant scanned print and remove the white scanner bed. Choose Scanner Bed Only to keep the print's own border, or Inner Photo Frame to also remove a frame such as a Polaroid border. Guide

<div align="center"><em>Screenshot placeholder: <code>process_scanned_photo_node.png</code></em></div>

Crop by Margins (Image)

Trim explicit pixel margins without resizing. Optional dimension snapping trims additional pixels from the right/bottom; this manual tool has no subject or protected-region logic. Guide

<div align="center"><em>Screenshot placeholder: <code>crop_image_by_margins.png</code></em></div>

Crop by Margins (Mask)

Apply the same pixel-margin calculation to a mask. Use matching values on the image and mask nodes to keep their grids aligned. Guide

<div align="center"><em>Screenshot placeholder: <code>crop_mask_by_margins.png</code></em></div>

Editor selection & routing

Editor Target Beacon

Declare an editor target inside a group controlled by your group muter. New beacons default to Qwen Image Edit 2.1; set each group's target explicitly. Guide

<div align="center"><em>Screenshot placeholder: <code>editor_target_beacon_node.png</code></em></div>

Active Editor Target

Resolve the connected active beacons into one target shared by Photo Prepare and the result gate. Keep it outside the mutually exclusive editor groups. Guide

<div align="center"><em>Screenshot placeholder: <code>active_editor_target_node.png</code></em></div>

Editor Result Gate

Lazily route the selected editor's decoded IMAGE onward to the upscaler. A missing selected result is an error; it never silently substitutes another editor or the unedited source. Guide

<div align="center"><em>Screenshot placeholder: <code>editor_result_gate_node.png</code></em></div>

Tone, color & compositing

Auto Adjust (Photoshop-style)

Automatic shared-channel contrast, per-channel tone, and neutral-aware color correction, with strength and clipping controls. Follows Photoshop-style behavior; it is not a bit-for-bit implementation of Adobe's algorithms. Guide

<div align="center"><em>Screenshot placeholder: <code>auto_adjust_node.png</code></em></div>

Auto White-Balance + Color Match

Linear-light white balance and D65 Lab reference matching, with alpha-aware statistics and optional analysis-only resizing. Guide

<div align="center"><em>Screenshot placeholder: <code>auto_wb_color_match.png</code></em></div>

Stitch by Mask

Blend image versions with a mask, configured blend/stitch opacity, feathering, and alpha-aware compositing. Guide

<div align="center"><em>Screenshot placeholder: <code>stitch_by_mask.png</code></em></div>

Outpaint Padding Compute

Convert Outpaint Config and image dimensions into left/top/right/bottom pixel padding for an external padding or outpainting node. This node computes margins; it does not generate new image content. Guide

<div align="center"><em>Screenshot placeholder: <code>outpaint_padding_compute_node.png</code></em></div>

Configuration

Each configuration node emits one typed bundle, not a separate socket for every setting. Connect it directly to matching PortraitUtils consumers, or use the readers below for third-party primitive inputs. Images and masks remain separate. Set/Get nodes are optional wiring helpers, not required dependencies.

Input & Crop Config

Configure border cleanup first, then subject framing, resolution policy, forced aspect ratio, subject-mask prompt, and Black/White/Edge extension padding. Guide

<div align="center"><em>Screenshot placeholder: <code>input_crop_config_node.png</code></em></div>

Edit & Composite Config

Share the edit prompt, blend/stitch opacity, and three short stitch-mask prompts without adding outputs to the configuration center. Guide

<div align="center"><em>Screenshot placeholder: <code>edit_composite_config_node.png</code></em></div>

Outpaint Config

Share expansion mode, gravity, percentage/pixel margins, and the outpainting prompt. Guide

<div align="center"><em>Screenshot placeholder: <code>outpaint_config_node.png</code></em></div>

Finish & Run Config

Share initial/final upscale factors, automatic adjustment switches, horizontal flip, and the run seed. Guide

<div align="center"><em>Screenshot placeholder: <code>finish_run_config_node.png</code></em></div>

Local readers

Use these small nodes next to consumers that need a STRING, INT, or FLOAT instead of a typed bundle. They expose existing values; they do not rerun preparation.

Crop Prompt from Config

Read the subject-mask prompt for a segmentation node. Guide

<div align="center"><em>Screenshot placeholder: <code>crop_prompt_reader_node.png</code></em></div>

Edit Prompt from Config

Select the edit prompt or one of the three stitch prompts. Use separate readers for separate segmentation inputs. Guide

<div align="center"><em>Screenshot placeholder: <code>edit_prompt_reader_node.png</code></em></div>

Outpaint Prompt from Config

Read the shared outpainting prompt as a STRING. Guide

<div align="center"><em>Screenshot placeholder: <code>outpaint_prompt_reader_node.png</code></em></div>

Seed from Config

Read the resolved run seed for a sampler or third-party node. Guide

<div align="center"><em>Screenshot placeholder: <code>seed_reader_node.png</code></em></div>

Scale from Config

Select the initial or final upscale factor as a FLOAT. Guide

<div align="center"><em>Screenshot placeholder: <code>scale_reader_node.png</code></em></div>

Save Info from Source

Extract the filename and output directory from the loader's source-info bundle. Guide

<div align="center"><em>Screenshot placeholder: <code>save_info_reader_node.png</code></em></div>

Dimensions from Prepare Info

Read the prepared output width and height as INT values. Guide

<div align="center"><em>Screenshot placeholder: <code>prepare_dimensions_reader_node.png</code></em></div>

Crop Box from Prepare Info

Read the source-coordinate crop rectangle: x, y, width, and height. Guide

<div align="center"><em>Screenshot placeholder: <code>prepare_crop_box_reader_node.png</code></em></div>

Scale from Prepare Info

Read the resize factor, per-axis scale, or percentage of source pixels cropped. Guide

<div align="center"><em>Screenshot placeholder: <code>prepare_scale_reader_node.png</code></em></div>

Summary from Prepare Info

Read the resolution, selection reason, diagnostic text, or structured JSON. Guide

<div align="center"><em>Screenshot placeholder: <code>prepare_summary_reader_node.png</code></em></div>

Standalone panel utility

Detect & Split Photo Panels

Extract rectangular photos from a composite without resizing the source pixels. Supports gutters, opt-in seam detection, and manual splits. Its differently sized IMAGE list can feed a separate chooser such as Image Chooser Classic. The splitter itself does not pause for selection or require a chooser package. Guide

<div align="center"><em>Screenshot placeholder: <code>photo_panel_splitter_node.png</code></em></div>

Upgrading from 1.x

Back up your workflows first. Version 2.0 removes legacy IDs rather than keeping duplicate implementations or compatibility aliases. An older workflow may show missing nodes until you replace them and reconnect the matching sockets.

Replace Flux Resolution Prepare and the old Smart Crop/Prepare combinations with Smart Photo Prepare and Input & Crop Config.
Replace Universal Project Config and generic config extraction with the four stage-specific bundles and matching readers.
Replace superseded loader, crop, saver, white-balance, stitch, and scanned-photo nodes using the retired-node map and replacement notes. Copy settings deliberately; swapping a JSON node ID does not migrate widget values or socket order.
Recreate Editor Result Gate if it still shows retired sockets. Connect current editor outputs to qwen21_image, firered_image, and klein_image, and update the corresponding beacons. The former qwen_image socket has no legacy alias.
Some production Python IDs and guide filenames still contain Preview for identification; these are the current nodes, not parallel preview versions. The ComfyUI display names above are the names to search for.

No workflow JSON or model weights are bundled or automatically rewritten. Historical local workflows named PortraitUtilsv5.2.json use retired nodes; PortraitUtilsv5.3.json also needs current editor labels and gate wiring. Neither should be treated as an up-to-date 2.0 template without checking its connections.

Development & release checks

Processing engines live in core/, separate from ComfyUI node interfaces. Immutable configs/plans, image/mask validation, float resizing, transactional loader state, and diagnostics are shared. See the architecture and contracts.

Run the regression suite using ComfyUI's Python environment:

/path/to/ComfyUI/venv/bin/python -m unittest discover -s tests -v
git diff --check

Tests cover decoding and loader sequencing, borders and scans, tone/color math, compositing, metadata and concurrent saves, protected framing and padding, panel splitting, typed readers, editor routing, and the complete node registry. These are utility/contract tests, not a substitute for end-to-end GPU tests of your chosen editor and upscaler.

Before publishing, include all new runtime modules, core/, documentation, and tests in the release commit. Keep dependencies in pyproject.toml and requirements.txt synchronized. Replace screenshot placeholders as captures become available; editor recovery files and patch backups are ignored.

The existing publish action publishes to Comfy Registry when a push to main or master changes pyproject.toml, or when manually dispatched. A local version bump alone does not publish a release.

License

GPLv3 — see LICENSE.