litematica-render 0.1.0__tar.gz

litematica_render-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,52 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

litematica_render-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e '.[dev]'
+      - name: Ruff
+        run: ruff check src tests
+      - name: Mypy
+        run: mypy src
+      - name: Tests
+        run: pytest -q

litematica_render-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Bytecode
+__pycache__/
+*.py[cod]
+
+# Packaging (hatchling)
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# Test / tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors
+.idea/
+.vscode/
+
+# OS junk (Windows / macOS)
+Thumbs.db
+.DS_Store
+
+# Local-only files (not tracked)
+AGENTS.md
+GLOSSARY.md
+docs/
+test/
+.scratch
+
+# Superpowers SDD workspace
+.superpowers/

litematica_render-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 late_maple
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

litematica_render-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.5
+Name: litematica-render
+Version: 0.1.0
+Summary: Parse Minecraft Litematica schematics and render them to isometric PNGs
+Project-URL: Homepage, https://github.com/late-maple/Litematica-Render
+Author: late-maple
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pillow>=9.1; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: pack
+Requires-Dist: pillow>=9.1; extra == 'pack'
+Description-Content-Type: text/markdown
+
+# Litematica-Render
+
+Offline isometric rendering of Minecraft Litematica `.litematic` schematics.
+
+## Features
+
+- Parse `.litematic` files: streaming NBT, lazy vectorized region unpacking
+- Render isometric PNGs from a resource pack's real blockstates, models, and textures
+- Pack stack: layer add-on packs (e.g. Faithful 32x) over a vanilla base, MC-style first-hit lookup
+
+## Example
+
+```python
+from litematic import load
+from litematic.render import isometric_png, unresolved_colors
+
+schem = load("schematic.litematic")
+
+png = isometric_png(
+    schem,
+    textures_path="vanilla-assets.zip",   # base pack, required
+    extra_packs=["Faithful 32x.zip"],     # add-ons, earlier = higher priority
+    max_size=2048,
+)
+with open("render.png", "wb") as f:
+    f.write(png)
+
+# block names the pack stack cannot cover; those render magenta
+missing = unresolved_colors(schem, textures_path="vanilla-assets.zip")
+```

litematica_render-0.1.0/README.md

@@ -0,0 +1,30 @@
+# Litematica-Render
+
+Offline isometric rendering of Minecraft Litematica `.litematic` schematics.
+
+## Features
+
+- Parse `.litematic` files: streaming NBT, lazy vectorized region unpacking
+- Render isometric PNGs from a resource pack's real blockstates, models, and textures
+- Pack stack: layer add-on packs (e.g. Faithful 32x) over a vanilla base, MC-style first-hit lookup
+
+## Example
+
+```python
+from litematic import load
+from litematic.render import isometric_png, unresolved_colors
+
+schem = load("schematic.litematic")
+
+png = isometric_png(
+    schem,
+    textures_path="vanilla-assets.zip",   # base pack, required
+    extra_packs=["Faithful 32x.zip"],     # add-ons, earlier = higher priority
+    max_size=2048,
+)
+with open("render.png", "wb") as f:
+    f.write(png)
+
+# block names the pack stack cannot cover; those render magenta
+missing = unresolved_colors(schem, textures_path="vanilla-assets.zip")
+```

litematica_render-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "litematica-render"
+dynamic = ["version"]
+description = "Parse Minecraft Litematica schematics and render them to isometric PNGs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "late-maple" }]
+dependencies = ["numpy"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment",
+    "Topic :: Multimedia :: Graphics",
+]
+
+[project.urls]
+Homepage = "https://github.com/late-maple/Litematica-Render"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "mypy", "Pillow>=9.1"]
+pack = ["Pillow>=9.1"]
+
+[tool.hatch.version]
+path = "src/litematic/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/litematic"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

litematica_render-0.1.0/src/litematic/__init__.py

@@ -0,0 +1,34 @@
+"""litematic - read-only parser for Minecraft Litematica .litematic schematics.
+
+Instances are not thread-safe: parse and query a Litematic from a single
+thread or asyncio task at a time.
+"""
+
+from litematic.parse.errors import LitematicError, LitematicFormatError, NbtError
+from litematic.parse.model import (
+    BlockEntity,
+    BlockState,
+    Entity,
+    Litematic,
+    LitematicMetadata,
+    Region,
+    Vec3i,
+)
+from litematic.parse.parser import load, loads
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BlockEntity",
+    "BlockState",
+    "Entity",
+    "Litematic",
+    "LitematicError",
+    "LitematicFormatError",
+    "LitematicMetadata",
+    "NbtError",
+    "Region",
+    "Vec3i",
+    "load",
+    "loads",
+]

litematica_render-0.1.0/src/litematic/parse/__init__.py

@@ -0,0 +1 @@
+"""Parsing core: NBT reading, data model, and .litematic decoding."""

litematica_render-0.1.0/src/litematic/parse/errors.py

@@ -0,0 +1,13 @@
+"""Public exception tree for litematic."""
+
+
+class LitematicError(Exception):
+    """Base class for all exceptions raised by this library."""
+
+
+class NbtError(LitematicError):
+    """Input is not valid Java NBT: bad tag type, truncated stream, bad compression."""
+
+
+class LitematicFormatError(LitematicError):
+    """Input is valid NBT but violates the .litematic structure constraints."""

litematica_render-0.1.0/src/litematic/parse/model.py

@@ -0,0 +1,225 @@
+"""Read-only data model: metadata, block states, and lazily materialized regions."""
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Callable, Mapping, NamedTuple, Optional, Sequence
+
+import numpy as np
+
+
+class Vec3i(NamedTuple):
+    """A 3D integer vector (x, y, z)."""
+
+    x: int
+    y: int
+    z: int
+
+
+@dataclass(frozen=True)
+class BlockState:
+    """A palette entry: block id plus blockstate properties."""
+
+    name: str
+    properties: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "properties", MappingProxyType(dict(self.properties))
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.name, frozenset(self.properties.items())))
+
+
+@dataclass(frozen=True)
+class LitematicMetadata:
+    """Schematic-level metadata from the Metadata compound."""
+
+    name: str
+    author: str
+    description: str
+    enclosing_size: Vec3i
+    total_blocks: int
+    total_volume: int
+    time_created: int
+    time_modified: int
+    MinecraftDataVersion: int
+    LitematicVersion: int
+
+
+@dataclass(frozen=True)
+class BlockEntity:
+    """A tile entity: position, id, and its raw NBT payload as a plain mapping.
+
+    The mapping is read-only at the top level only; nested compounds
+    (a chest's items, for example) stay mutable dicts.
+    """
+
+    pos: tuple[int, int, int]
+    id: str
+    data: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class Entity:
+    """An entity: id, position, and its raw NBT payload as a plain mapping.
+
+    The mapping is read-only at the top level only; nested compounds
+    stay mutable dicts.
+    """
+
+    id: str
+    pos: tuple[float, float, float]
+    data: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class Litematic:
+    """A parsed schematic: metadata plus named regions.
+
+    `regions` is exposed as a read-only mapping.
+    """
+
+    metadata: LitematicMetadata
+    regions: Mapping[str, "Region"]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "regions", MappingProxyType(self.regions))
+
+
+class Region:
+    """One schematic region.
+
+    Block data is kept in packed form; `block_indices` materializes it on
+    first access and caches the result until `release()`.
+    `pending_block_ticks`/`pending_fluid_ticks` are sequences of scheduled-tick
+    compounds ({x, y, z, Time, Priority, Block or Fluid, SubTick}), retained
+    verbatim (semantics defined by the writing Litematica version).
+    Not thread-safe.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        position: Vec3i,
+        size: Vec3i,
+        palette: Sequence[BlockState],
+        block_entities: tuple[BlockEntity, ...],
+        entities: tuple[Entity, ...],
+        pending_block_ticks: Optional[tuple[Mapping[str, object], ...]],
+        pending_fluid_ticks: Optional[tuple[Mapping[str, object], ...]],
+        packed_indices: np.ndarray,
+        _unpack: Callable[[], np.ndarray],
+        _unpack_slab: Optional[Callable[[int, int], np.ndarray]] = None,
+    ) -> None:
+        self._name = name
+        self._position = position
+        self._size = size
+        self._palette = tuple(palette)
+        self._block_entities = block_entities
+        self._entities = entities
+        self._pending_block_ticks = pending_block_ticks
+        self._pending_fluid_ticks = pending_fluid_ticks
+        # Read-only view: the caller keeps ownership of the array it passed.
+        packed = packed_indices.view()
+        packed.flags.writeable = False
+        self._packed_indices = packed
+        self._unpack = _unpack
+        self._unpack_slab = _unpack_slab
+        self._indices: Optional[np.ndarray] = None
+
+    @property
+    def name(self) -> str:
+        """Region name as written in the file."""
+        return self._name
+
+    @property
+    def position(self) -> Vec3i:
+        """Min corner in schematic coordinates (negative sizes normalized)."""
+        return self._position
+
+    @property
+    def size(self) -> Vec3i:
+        """Region extents along x, y, z; always positive."""
+        return self._size
+
+    @property
+    def palette(self) -> tuple[BlockState, ...]:
+        """Block states addressable by the values in `block_indices`."""
+        return self._palette
+
+    @property
+    def block_entities(self) -> tuple[BlockEntity, ...]:
+        """Tile entities (chests, signs, spawners, ...) in this region."""
+        return self._block_entities
+
+    @property
+    def entities(self) -> tuple[Entity, ...]:
+        """Entities (mobs, items, item frames, ...) in this region."""
+        return self._entities
+
+    @property
+    def pending_block_ticks(self) -> Optional[tuple[Mapping[str, object], ...]]:
+        """Scheduled block ticks, one compound per tick; None if absent."""
+        return self._pending_block_ticks
+
+    @property
+    def pending_fluid_ticks(self) -> Optional[tuple[Mapping[str, object], ...]]:
+        """Scheduled fluid ticks, one compound per tick; None if absent."""
+        return self._pending_fluid_ticks
+
+    @property
+    def packed_indices(self) -> np.ndarray:
+        """The raw packed BlockStates long array, read-only."""
+        return self._packed_indices
+
+    @property
+    def is_unpacked(self) -> bool:
+        """Whether `block_indices` is currently materialized."""
+        return self._indices is not None
+
+    @property
+    def block_indices(self) -> np.ndarray:
+        """Palette indices as a read-only (x, y, z) array; materializes lazily."""
+        if self._indices is None:
+            indices = self._unpack()
+            indices.flags.writeable = False
+            self._indices = indices
+        return self._indices
+
+    def slab_indices(self, y0: int, y1: int) -> np.ndarray:
+        """Palette indices for rows [y0, y1), shape (x, y1-y0, z); not cached.
+
+        Unpacks only the slab's contiguous entry span of the packed stream
+        when the parser injected a slab unpacker, so callers can stream a
+        region without ever materializing `block_indices`.
+        """
+        if not (0 <= y0 < y1 <= self._size.y):
+            raise IndexError(
+                f"Slab rows out of range: [{y0}, {y1}) for size {self._size}"
+            )
+        if self._unpack_slab is not None:
+            arr = self._unpack_slab(y0, y1)
+        else:
+            arr = np.ascontiguousarray(self.block_indices[:, y0:y1, :])
+        arr.flags.writeable = False
+        return arr
+
+    def get_block(self, x: int, y: int, z: int) -> BlockState:
+        """Return the block state at local coordinates (x, y, z).
+
+        Out-of-range coordinates are a caller bug and raise IndexError;
+        file corruption raises LitematicFormatError on first unpack.
+        """
+        size_x, size_y, size_z = self._size
+        if not (0 <= x < size_x and 0 <= y < size_y and 0 <= z < size_z):
+            raise IndexError(
+                f"Block coordinates out of range: ({x}, {y}, {z})"
+                f" for size {self._size}"
+            )
+        index = int(self.block_indices[x, y, z])
+        return self._palette[index]
+
+    def release(self) -> None:
+        """Drop the materialized `block_indices` cache to reclaim memory."""
+        self._indices = None