Load Image Dict From Zip

What it's for

A folder of images plus a caption file plus a settings JSON is three things to keep in sync, and the moment you move one of them the pairing breaks. This node reads a single bundle instead: a .zip (or a folder) that holds the images, an index.json naming them, and an optional metadata JSON - and hands you the whole thing back as a live ImageDict inside the graph.

It's the read half of the pack's Dict workflow, paired with Save Image Dict To Zip. And it has one genuinely delightful property: it reads the pack's polyglot files too - the .png that is also a zip - because zipfile doesn't care that there's a PNG sitting in front of the archive.

How it works

path is a plain STRING widget, not a file picker, so you paste an absolute path in or wire it from Enumerate Files In Folder. Two shapes are accepted:

A folder - must contain index.json. The images named in it are loaded from beside it.
A zip - must contain index.json at its root.

index.json is a {key: filename} map, which is what makes the bundle labelled rather than just packed. Each image is opened, converted to RGB, scaled to 0–1 floats and wrapped as a single-image batch - the standard ComfyUI IMAGE tensor everything downstream expects. Whatever else you stuffed in the archive, the node also finds the first .json that isn't index.json, and returns its raw text plus its filename, so metadata travels with the images without you parsing anything by hand.

Inputs and outputs

One input: path. Five outputs, and all of them are useful:

ImageDict - the bundle, ready for Get from Image Dict or Image Dict to List.
json - the metadata file's raw text (empty string if the bundle has none).
json_filename - the name of that file.
zip_path - the path you fed in, passed through so you can carry it downstream.
keys - the dict's keys as a list of strings, which is the quickest way to see what's actually inside a bundle you inherited.

Installing it

Ships in ComfyUI-TinyBee under 🐝TinyBee/Dicts. No model downloads, no compiled dependencies - README says standard library, requirements.txt is pillow.

cd ComfyUI/custom_nodes
git clone https://github.com/TinyBeeman/ComfyUI-TinyBee

Or install ComfyUI-TinyBee from Manager and restart.

Where people get burned

Alpha is gone. Images are converted to RGB on load, so a PNG with transparency - including one this pack itself wrote as a mask carrier - comes back with the alpha channel dropped. If you rely on alpha downstream, this loader is the wrong door.

Memory. Every image in the bundle is decoded and held as a float32 tensor at once: roughly 12 MB per 1024×1024 image, and more for bigger ones. A bundle of a hundred images is north of a gigabyte of RAM before the sampler starts. Bundles are for tens of images, not thousands.

Silent gaps. If a filename in index.json isn't actually present in the zip, that key is skipped without complaint - you get a slightly smaller dict than the index promises. And a bundle whose zip has no index.json raises outright, which is the loud version of the same problem.

Replacing the file in place does nothing. The node is keyed on its inputs, and a path string that didn't change doesn't invalidate anything. Drop a new zip at the same path and ComfyUI may not re-read it until you dirty the node or restart.

Last one: don't leave path blank. An empty path takes an early return that hands back fewer values than the node declares, which is a poor way to end a queue.