heyburns-PortraitUtils/docs/PhotoLoaderPreview.md

Load Image + Source Info

Node ID: PortraitPhotoLoaderPreview. Category: PortraitUtils/IO.

This production loader replaces LoadImageCombinedV2, which is no longer registered. It has independent transactional batch cursors and content-based change detection. It loads photos; it does not crop, straighten, resize, adjust levels, or remove borders. The v5.3 workflow already uses it.

Wiring

Restart ComfyUI and add Load Image + Source Info. Its two outputs are:

• image goes where the old loader's image went, including Intelligent AutoCrop.
• source_info goes to the existing source-info Set node or Save Info from Source reader. It is the same PORTRAIT_SOURCE_INFO_V2 type, not a new bus.

Mask generation and editor/upscaler routing do not change.

Controls

The first seven controls correspond to the current loader:

• mode: Single loads the uploaded/selected image. Batch loads one photo from a folder per queued execution, not a multi-image tensor batch.
• input_dir: Required in Batch mode. An absolute path, a ~ path, or a path relative to ComfyUI/input. Ignored in Single mode.
• output_dir: Passed unchanged apart from surrounding whitespace to source info. Blank leaves output-directory selection to the saver. Loading does not create folders or write any images.
• pattern: Batch glob; blank means *. **/*.png includes subfolders. Only PNG, JPEG, WebP, TIFF, and BMP files are eligible. Sorting is deterministic and natural: photo2 comes before photo10.
• strip_trailing_numbers: Removes a final copy marker such as photo (2). It does not strip normal digits such as scan2024.
• repeat_last: Holds the last successfully loaded batch photo. With no previous photo, loads the first one. Missing/deleted previous files restart at the first available file. A held unchanged photo remains cacheable downstream.
• image: Selection/upload for Single mode. It is ignored in Batch mode, even if that selection is missing or ComfyUI/input has no uploaded images.

Two additional controls make decoding explicit:

• color_management: Convert to sRGB (default) honors embedded 8-bit ICC profiles. Untagged RGB photos are assumed sRGB. Keep encoded values skips ICC conversion, useful for comparison with the old loader. Non-RGB sources still need conversion to RGB; untagged CMYK conversion is approximate.
• alpha_background: White (default) or Black for transparency. Transparency is composited, not discarded. No alpha mask is emitted.

Reliability and image fidelity

Each node instance keeps its own cursor for each folder/pattern, with up to 32 recent listings retained. Two loaders pointed at the same folder do not advance each other's positions. A failed decode never commits a new cursor position. Repair or replace the offending file to retry; it is not silently skipped. Adding files does not reset a cursor whose last file still exists.

State lasts only while ComfyUI retains the node object. Restarting the server, clearing its object cache, or recreating the node starts from the first file. ComfyUI's no-cache mode does not retain node objects, so folder advancement requires a normal caching mode. Identical preview nodes remain separate in the output cache because their hidden node IDs are included in ComfyUI's cache keys.

The image output is CPU float32 RGB, [1, height, width, 3]. EXIF orientation is applied before recording source dimensions. No spatial resampling occurs. Single and held-batch images use streamed content hashes, so even replacements with the same filename, size, and timestamp invalidate cached results.

Standard 16-bit grayscale/RGB/RGBA PNG/TIFF decoding preserves 16-bit samples. TIFF uses tifffile (already installed in this development environment and now listed in requirements) to avoid decoder-specific orientation problems. Common compressed files without orientation/premultiplied-alpha transforms can use the existing OpenCV decoder as a lossless fallback. Other compressed TIFF variants may additionally need imagecodecs; a missing codec is reported with install or export guidance rather than silently losing precision. Embedded ICC conversion for these files is deliberately refused because the available Pillow ICC converter operates at 8-bit precision. Export a 16-bit sRGB copy without an embedded profile, or deliberately select Keep encoded values if the encoded colors are appropriate. 32-bit/HDR files fail with export guidance instead of being silently clipped or normalized. Animated/multipage inputs load only their first frame/page; this is a still-photo loader.

The preview does not remove Alamy or other image-hosting borders. Those remain the responsibility of the following Intelligent AutoCrop stage.