structura-render

Minecraft structures, rendered like Minecraft.

Create textured previews, vector plans and portable 3D models from Minecraft structures. Textured previews and mesh exports share one geometry pipeline. Install only the output backends you need.

_{Builds: ProMcEngineering, Ohnoitswoody, Arolas, EdCr0w, GameBreaker, Zeira4424, DaveGR.}

Quick start

No Minecraft resources or graphics backend are needed for projections and SVG:

pip install structura-render
structura-render examples demo
structura-render projections demo/demo.nbt demo/views.png
structura-render svg demo/demo.nbt demo/floor.svg --view top --depth 1 4

For textured previews and 3D export:

pip install "structura-render[hero,usdz]"
structura-render png demo/demo.nbt demo/house.png --orthographic
structura-render usdz demo/demo.nbt demo/house.usdz

A launcher-installed Minecraft 1.21.1 client is detected automatically. For another client or resource pack, set STRUCTURA_MINECRAFT_ASSETS to its .jar or extracted assets/minecraft directory. Game assets are not bundled.

Outputs

The glTF/USD output extension selects the encoding. WebP uses Pillow's default encoding in the CLI; lossless saving is shown below. SVG and VOX need no game assets. Only [hero] needs PyVista/VTK. Extras can be combined, for example pip install "structura-render[hero,gltf,usdz]".

Inputs

These are structure-to-image/model conversions; 3D models and images are not accepted as input. Native Java loading retains the source game version.

Python

from structura_render import export_structure, render_hero, render_projection, render_svg

image = render_projection("house.nbt", view="top", depth=(1, 4))
image.save("floor.webp", lossless=True, method=6)
render_svg("house.nbt", "floor.svg", view="top", depth=(1, 4))
render_hero("house.nbt", "house.png", orthographic=True)
export_structure("house.nbt", "house.glb")

The same functions accept an in-memory structura_core.Structure. PNG, SVG and 3D entry points can write outputs atomically; render_projection returns a Pillow image. WebP requires a Pillow build with WebP support.

Reported render approximations produce RenderWarning; use --strict or strict=True on hero/3D exports to reject them before writing. VOX uses coloured cubes; STL has no textures and may need repair for printing. Entities are static approximations. Keep generated resource directories with glTF, OBJ and plain USD.

Documentation

• Release verification: core compatibility, installed packages and integration checks.
• Architecture: geometry pipeline, model catalogs and module boundaries.
• Rendering guide: Python API, layers, overlays, resource caches and output limits.
• Format recipes: SVG, USD, VOX, WebP and Bedrock input.
• Diagnostics and showcase: structura-render doctor, doctor --render-test, examples --showcase.
• Rendering coverage: supported blocks/entities and fidelity limits.

Every command supports --help. python -m structura_render is equivalent to structura-render; existing dedicated render/export commands remain supported.