HivisionNode

This is the node the whole pack exists for. HivisionIDPhotos is Zeyi-Lin's open-source ID-photo generator - it landed a HuggingFace demo and a r/StableDiffusion roundup in September 2024 - and HivisionNode is where its entire pipeline runs inside ComfyUI. Everything else in the pack (the background node, the layout sheet, the two params builders) is finishing work around it. If you've got a portrait and you need a photo that a passport, visa, or Chinese civil-service application will actually accept, this is the node that does the heavy lifting: cut the person out, find the face, crop to the official size, and smooth the skin.

How it works

Under the hood it runs the upstream IDCreator pipeline, vendored into the pack. Your input gets resized so its longest side is 2000px, then processed in order:

1. Human matting - the ONNX model you pick cuts the person out.
2. Beauty pass - whitening, brightness, contrast, saturation, sharpening.
3. Face detection - MTCNN by default, RetinaFace if you drop in its weights.
4. Face alignment - if the head is tilted more than ~2°, it rotates the image and re-detects.
5. Crop and resize to the exact spec size from normal_params.

That last step is the whole point. It's not a blind crop: it uses the detected face box to compute how much of the frame the head should occupy and how far it should sit from the top, then trims and rescales until the face lands where ID-photo rules want it.

The inputs that actually matter

Most of the sliders are the fun part; two inputs will trip you up.

• matting_model - this dropdown only lists models whose weights are actually in hivision/creator/weights/. Empty folder, empty dropdown, dead node. See the weights section below.
• face_alignment - on by default. Leave it unless the auto-rotation is misbehaving on a tilted photo.
• whitening_strength (0–15, default 2) is the beauty filter you'll notice first; bump it for softer skin. brightness_strength, contrast_strength, saturation_strength and sharpen_strength all default to 0 and behave like you'd expect.
• head_measure_ratio (0.1–0.5, default 0.2) and top_distance (0.02–0.5, default 0.12) control the crop composition - how big the head is in frame and how far it sits from the top edge. The defaults are right for standard specs; touch them only when a specific size needs a different composition.
• change_bg_only and crop_only are bypass modes: the first returns the raw cutout, the second skips matting and just crops.

Outputs

Two, and both keep the alpha channel from the matting step:

• standard_img - the photo at the exact spec size (413x295 for one inch, and so on).
• hd_img - the same photo upscaled so its shorter edge is at least 600px. This is the one the shipped workflow feeds into AddBackgroundNode.

Installing it

Via ComfyUI Manager: Manager → Custom Nodes Manager → search "HivisionIDPhotos" → Install, then restart. Or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/AIFSH/HivisionIDPhotos-ComfyUI

Restart ComfyUI (Manager installs requirements.txt for you; if you cloned by hand, pip install -r requirements.txt in your venv). The requirements are opencv-python, onnxruntime, requests, mtcnn-runtime, mnn, and a numpy<=1.26.4 pin.

Then the weights, into ComfyUI/custom_nodes/HivisionIDPhotos-ComfyUI/hivision/creator/weights/:

• modnet_photographic_portrait_matting.onnx (24.7MB) - the MODNet default
• hivision_modnet.onnx (24.7MB) - tuned for solid-color backgrounds
• rmbg-1.4.onnx (176MB) - BRIA, better on hair
• birefnet-v1-lite.onnx (224MB) - BiRefNet, the one to reach for when MODNet chews up the hairline

Download links and exact filenames are in the pack README. RetinaFace is optional: drop retinaface-resnet50.onnx into hivision/creator/retinaface/weights/ and face_detect_model grows a second option.

Where people get burned

• Empty matting_model dropdown is the number one "why doesn't it work" - not a bug, the list is built from whatever weights you've downloaded. Grab at least the 24MB MODNet file to get moving.
• It needs exactly one face. Multiple people or no face raises a FaceError, which the node catches, prints in Chinese, and returns nothing - you'll see a "return values mismatch" error in ComfyUI. Crop to a single face first.
• The numpy pin. numpy<=1.26.4 in a shared venv is exactly the kind of pin that fights other custom nodes in a big install. If numpy stops importing after adding the pack, that's the suspect.
• It's unmaintained. AIFSH's port-first wrappers work, but this repo's last commit is September 2024. The upstream HivisionIDPhotos project is the maintained half. If the node breaks after a ComfyUI update, don't wait for a fix - reinstall the venv deps and re-check the weights.

The whole pipeline is local and deterministic: no API calls, no keys, no GPU required. The ONNX matting models run fine on CPU, which makes this the rare ComfyUI node you can comfortably run on a laptop.