structura-render

Minecraft structures, rendered like Minecraft.

Turn a Java Edition Structure NBT or Litematic into a PNG or a portable 3D model. structura-render reads the blockstates, models and textures from your own Minecraft client, so stairs stay stairs, doors keep their state, glass keeps its alpha and every export agrees with the preview.

Quick start

Install only the output you need:

pip install "structura-render[hero,usdz]"

Render a showcase image and export the same geometry:

structura-render png house.litematic house.png --transparent --orthographic
structura-render usdz house.litematic house.usdz

For Minecraft 1.21.1, the standard launcher installation is detected automatically on macOS, Linux and Windows. To use another client or resource pack, point the renderer at its .jar or extracted assets/minecraft folder:

export STRUCTURA_MINECRAFT_ASSETS="$HOME/.minecraft/versions/1.21.1/1.21.1.jar"

The jar is extracted once into the user cache. Mojang assets are never bundled, copied into the package or redistributed.

Outputs

Extras can be combined:

pip install "structura-render[hero,usdz,gltf,obj,stl]"

Every command accepts .nbt and .litematic natively. Legacy .schematic and Sponge .schem inputs are available through the legacy extra:

pip install "structura-render[hero,legacy]"
structura-render-hero castle.schematic castle.png

Preview conversion preserves the selection's bounds, authored air, block materials, connections and all entities. It does not apply datapack placement cleanup. Litematic v5–v7 supports multiple disjoint regions, signed sizes and entity positions without requiring the legacy extra. Use --region Main to render one named region. Overlaps require an explicit region choice. Other Amulet input formats are not verified by the conversion tests.

Texture-backed exporters fail clearly when client assets are unavailable, instead of silently producing a misleading result. For diagnostics only, the 3D exporters can retain the old coloured-cube fallback with --allow-flat-fallback. Hero renders expose the same choice as --no-textures.

The commands support --help without optional backends or Minecraft assets. PNG and USDZ do not require trimesh. OBJ, STL, glTF/GLB and USDZ do not install or import PyVista/VTK; only the [hero] extra needs a plotting backend. If an application previously installed [usdz] and also rendered PNGs, it should now request [hero,usdz] explicitly.

The unified command and python -m structura_render accept projections, png, glb, gltf, obj, stl and usdz. Existing commands remain supported:

python -m structura_render glb house.litematic house.glb
structura-render projections house.litematic views.png --views top north
uvx --from 'structura-render[gltf]' structura-render glb house.litematic house.glb

Python images

from structura_core import load_structure
from structura_render import render_hero, render_projection, render_projections

structure = load_structure("house.litematic", region="Main")
image = render_projection(structure, view="top", scale=8, transparent=True)
image.save("top.png")
render_projections(structure, "views.png", views=("top", "north"))
render_hero(structure, "house.png", transparent=True, orthographic=True)

All three return a Pillow image. The sheet and hero functions optionally write an output atomically; the existing destination survives an encoding failure. Projection images need neither Minecraft textures nor a graphics backend. They show the nearest non-air block cell rather than textured model geometry. An explicit structure_void is invisible. Plain projections allocate memory according to image area, without constructing a dense 3D volume.

Default guards are 16,000,000 output pixels (max_pixels / --max-pixels), 16,000,000 cells in a 3D bounding box (max_voxels / --max-voxels) and 2,000,000 decoded Litematic cells (--max-blocks). Larger trusted inputs can raise these limits; choosing --region avoids allocating the empty space between distant regions. These guards are not a bound on total process memory.

Shared geometry

geometry.TexturedMesh contains NumPy points, quads, UV coordinates, per-face alpha modes and an RGBA atlas. mesh.build_textured_geometry produces these buffers once; file exporters consume them directly. TexturedMesh.to_pyvista adapts them for image rendering. The existing build_textured_meshes function retains its PyVista return values for callers using that interface.

Format-specific materials and file writing stay in their exporters. There is no second scene graph, editing model, interactive viewer or plugin framework. New image and file formats can reuse the same geometry without importing a graphics engine.

Moving exports

GLB and USDZ are single-file exports. For .gltf or .obj, keep the model together with its generated resources when moving or sharing it:

• glTF uses a <filename>.assets/ directory;
• OBJ uses an adjacent .mtl file and a <filename>.assets/ directory;
• resource filenames are derived from their contents, so exporting another model into the same directory does not overwrite the first model's assets.

The main glTF/OBJ file is published after its resources are written. Old resources are retained when a model is replaced, since another exported model may still reference them. Paths inside the export use relative, ASCII-safe resource names, including when the model's filename contains spaces or Unicode.

What makes the output faithful

• Client-driven models. Blockstate variants, multipart conditions, parent models, element rotations, UV rotation and UV locking come from the game.
• One geometry pipeline. PNG, USDZ, glTF, OBJ and STL share the same mesh builder, so format-specific implementations do not drift apart.
• State-aware special blocks. Chests, signs, banners, beds, heads, shulker boxes, bells, decorated pots, fluids and portals use compact textured models.
• Structure entities. Paintings, populated item frames, armor stands, dropped items and the vanilla entity catalog through 26.2 remain visible.
• Correct transparency. Per-pixel alpha is preserved for glass, foliage, bars, panes, water and other cutout or translucent surfaces. glTF and USDZ group geometry into opaque, cutout and blended materials. glTF explicitly requests nearest texture filtering; OBJ includes a grayscale opacity map.
• No stale cube list. Occlusion data is derived from client model geometry.

The generic resolver follows the client data rather than a short table of guessed blocks. New JSON-modelled blocks therefore work without adding another hardcoded shape to the renderer.

Choosing Minecraft assets

STRUCTURA_MINECRAFT_ASSETS accepts either:

• a Minecraft client .jar;
• an extracted assets/minecraft directory.

When the variable is unset, the renderer first looks for assets/minecraft in the working tree and then for a launcher-installed 1.21.1 client. Cached jar content is keyed by the jar path, size and modification time, so different versions do not collide.

Minecraft 1.13 and newer use the supported asset layout. The renderer is verified end to end with 1.21.1 and 26.2. This repository's own datapack targets Java 1.21.1, so use that client when exact project parity matters.

Honest limits

Entity rendering is static. The renderer does not evaluate animation, AI, item predicates, enchantment glint, armor trims or arbitrary display transforms. Entity previews preserve identity and silhouette; they are not a replacement for Minecraft's animated renderer. Block geometry still follows the client model pipeline described above.

The base install contains structura-core, NumPy and Pillow. PyVista, OpenUSD and trimesh are installed only by the output extras that need them.

STL contains geometry only. Its exporter welds vertices and removes duplicate triangles; an isolated solid cube produces a closed, outward-facing surface. Plants, intersecting shapes and open planes may still require repair or thickening before 3D printing. STL does not retain textures or transparency.

For implementation coverage and explicit dynamic-render limitations, see docs/block-render-audit-26.2.md.