nbt-image-gen

CLI that renders orthographic projections and metadata for Minecraft .nbt structure files (Structure Block format) so they can be classified and described by an LLM.

Usage

uv sync
uv run nbt-image-gen <input> [--out nbt-out] [--scale 8] [--iso-scale 6]

<input> may be a single .nbt file or a directory containing .nbt files (non-recursive).

For each input file, the tool writes to <out>/<stem>/:

• top.png — bird's-eye view (north up)
• north.png, south.png, east.png, west.png — cardinal elevations (observer on that side looking at the structure)
• iso.png — 2:1 pixel-art isometric 3/4 view
• meta.json — dimensions, non-air bounding box, top-10 block histogram, and a placement heuristic indicating whether the structure looks like it has a subterranean base or sits on top of the ground

Rendering

Blocks are drawn as flat colors from src/nbt_image_gen/colors.json. Unknown block names fall back to a stable hashed color and are logged once to stderr.