Load Image (BlueBox)

The mask is the reason this node exists

ComfyUI's stock Load Image gives you an IMAGE and a MASK, so on paper this looks redundant. The difference is where the mask comes from. The core node only fills the mask from an alpha channel, which means a JPEG - the format most people's source images are in - gives you an empty mask and a shrug.

Load Image (BlueBox) looks in four places, in order, and it'll also pair your image with a mask file that's already sitting next to it. Then it hooks into the pack's WebGL editor, which is the part you'll actually use: right-click the node, open the BlueBox editor, paint or crop or outpaint, hit apply, and the mask comes back into the graph as a widget value rather than as a separate file you have to juggle. That workflow - load, mark up, inpaint - is the manual half of the masked-inpainting routine everyone still keeps around for when an edit model won't leave the rest of the frame alone.

The mask priority chain

Straight from the source, in this order:

1. mask_file - if you typed a filename, load it as greyscale.
2. A sidecar file - <yourimage>_mask.png, <yourimage>_mask.jpg, or if your image starts with bb_, the same name with bb_mask_ instead. So photo.png picks up photo_mask.png automatically.
3. The alpha channel - for RGBA/LA images (and palette images with transparency). It's inverted, so fully transparent pixels become masked. That's the behaviour you want for inpainting a cut-out subject, and it's what lets a background-removal matte drop straight into an inpaint graph as a mask.
4. All zeros - the fallback, meaning "nothing masked, nothing to inpaint".

Every mask goes through a size check. If the mask's dimensions don't match the image's, the node prints a line to the console and throws the mask away - you silently get zeros. White (1.0) is the masked region, same convention as every other ComfyUI inpaint path.

Inputs and outputs

• image (required) - a dropdown of image files in ComfyUI/input, with an upload button, so you can drop a file in straight from the widget.
• mask_file (optional, STRING, default empty) - a filename, not a file picker. You type it. Note what that implies: a typo is not an error, it's a silent fall-through to the sidecar/alpha/zero logic.

Outputs are image and mask. Image goes wherever the pipeline starts; mask goes into VAEEncodeForInpaint, SetLatentNoiseMask, or an Inpaint Crop pair. Also note it re-orients photos by EXIF before doing anything, so a phone shot doesn't come in sideways and quietly mismatch its mask.

The node's own preview is a green-tinted composite - your image blended 50/50 with the pack's mask colour. It's a diagnostic, not a render. Don't judge exposure or colour from it; put an AllPreview or Preview Image downstream if you want to see the pixels.

Installing

cd ComfyUI/custom_nodes
git clone https://github.com/zhoutingxi/ComfyUI-BlueBox.git ComfyUI-BlueBox

or search ComfyUI-BlueBox in ComfyUI Manager. Restart. The repo's requirements.txt is empty and the README's "no third-party Python packages" line checks out against the source. Nothing to download model-wise; this is pure I/O. The editor needs WebGL and IndexedDB, so Chrome or Edge - the README specifically warns that Safari clears IndexedDB after seven days of inactivity, which is where in-progress editor snapshots live.

Common issues

"My mask is empty and nothing errored." Either the mask_file string doesn't resolve to a real file in input/, or the mask's size doesn't match the image. Both cases print to the console and both fall back to zeros. This is the single most common way to waste twenty minutes with this node.

"My images don't show in the dropdown." The list is a flat scan of the top level of ComfyUI/input, filtered to png/jpg/jpeg/webp/bmp. Images in subfolders won't appear. Uploading through the widget puts you where the list will see it.

"The editor opens blank." Nothing to edit yet - no image selected in the widget. The README's FAQ says the same thing and it's the usual cause.

"I edited the mask but the graph still uses the old one." The node's change detection keys on the image's file mtime plus the mask_file string, so re-uploading a file under the same name does refresh. If you're still seeing stale results, check you clicked apply in the editor - apply is what writes the values back to the widgets.