litematica-render 0.1.0__py3-none-any.whl

litematic/parse/parser.py

@@ -0,0 +1,317 @@
+"""Litematica palette-index bit unpacking and file-tree parsing."""
+
+from pathlib import Path
+from types import MappingProxyType
+from typing import Callable, Mapping, Optional
+
+import numpy as np
+
+from litematic.parse.errors import LitematicError, LitematicFormatError
+from litematic.parse.model import (
+    BlockEntity,
+    BlockState,
+    Entity,
+    Litematic,
+    LitematicMetadata,
+    Region,
+    Vec3i,
+)
+from litematic.parse.nbt import read_nbt
+
+
+def _bits_for(palette_size: int) -> int:
+    """Bit width per entry: enough for palette_size values, at least 2."""
+    return max(2, (palette_size - 1).bit_length())
+
+
+def _unpack_indices(
+    packed: np.ndarray,
+    bits: int,
+    size: Vec3i,
+    start_entry: int = 0,
+    stop_entry: int | None = None,
+) -> np.ndarray:
+    """Unpack litematica's continuous bit stream into an (x, y, z) index array.
+
+    Entry i starts at bit i*bits of the long array, filling each long upward
+    from its low bit; an entry straddling a boundary continues into the low
+    bits of the next long. File order is
+    YZX: index = (y*lenZ + z)*lenX + x. Palettes wider than 16 bits need
+    uint32 output. Entries are processed in fixed-size chunks so transient
+    memory stays a small multiple of the output array regardless of size.
+    Pass [start_entry, stop_entry) to unpack a Y-rows range only; the range
+    is a contiguous entry span, so no state beyond the offsets is needed.
+    """
+    count = size.x * size.y * size.z
+    if stop_entry is None:
+        stop_entry = count
+    span = stop_entry - start_entry
+    words = packed.view(np.uint64)  # logical shifts; int64 storage is untouched
+    dtype = np.uint16 if bits <= 16 else np.uint32
+    out = np.empty(span, dtype=dtype)
+    mask = np.uint64((1 << bits) - 1)
+    chunk = 1 << 18
+    for base in range(start_entry, stop_entry, chunk):
+        stop = min(base + chunk, stop_entry)
+        positions = np.arange(base, stop, dtype=np.uint64) * np.uint64(bits)
+        long_index = positions >> np.uint64(6)
+        bit_offset = positions & np.uint64(63)
+        values = words[long_index] >> bit_offset
+        spill = bit_offset.astype(np.int64) + bits - 64
+        crossing = np.nonzero(spill > 0)[0]
+        if crossing.size:
+            values[crossing] |= words[long_index[crossing] + 1] << (
+                np.uint64(64) - bit_offset[crossing]
+            )
+        values &= mask
+        out[base - start_entry : stop - start_entry] = values
+    rows = span // (size.z * size.x)
+    return out.reshape(rows, size.z, size.x).transpose(2, 0, 1)
+
+
+def _vec3(compound: Mapping, field: str, source: str) -> Vec3i:
+    try:
+        c = compound[field]
+        return Vec3i(int(c["x"]), int(c["y"]), int(c["z"]))
+    except (KeyError, TypeError, ValueError) as exc:
+        raise LitematicFormatError(f"{source}: missing or malformed {field}") from exc
+
+
+def _string(value: object, what: str, where: str) -> str:
+    if not isinstance(value, str):
+        raise LitematicFormatError(f"{where}: {what} is not a string")
+    return value
+
+
+def _parse_metadata(root: Mapping, source: str) -> LitematicMetadata:
+    try:
+        meta = root.get("Metadata") or {}
+        if not isinstance(meta, dict):
+            raise TypeError("Metadata is not a compound")
+        where = f"{source}: Metadata"
+        size = meta.get("EnclosingSize")
+        if size is None:
+            enclosing = Vec3i(0, 0, 0)
+        else:
+            enclosing = Vec3i(int(size["x"]), int(size["y"]), int(size["z"]))
+        return LitematicMetadata(
+            name=_string(meta.get("Name", ""), "Name", where),
+            author=_string(meta.get("Author", ""), "Author", where),
+            description=_string(meta.get("Description", ""), "Description", where),
+            enclosing_size=enclosing,
+            total_blocks=int(meta.get("TotalBlocks", 0)),
+            total_volume=int(meta.get("TotalVolume", 0)),
+            time_created=int(meta.get("TimeCreated", 0)),
+            time_modified=int(meta.get("TimeModified", 0)),
+            MinecraftDataVersion=int(root.get("MinecraftDataVersion", 0)),
+            LitematicVersion=int(root.get("Version",0))
+        )
+    except (KeyError, TypeError, ValueError) as exc:
+        raise LitematicFormatError(f"{source}: malformed Metadata: {exc}") from exc
+
+
+def _parse_palette(entries: object, source: str) -> list[BlockState]:
+    if not isinstance(entries, list) or not entries:
+        raise LitematicFormatError(f"{source}: BlockStatePalette is missing or empty")
+    palette = []
+    try:
+        for entry in entries:
+            props = entry.get("Properties") or {}
+            palette.append(
+                BlockState(_string(entry["Name"], "Name", source), dict(props))
+            )
+    except (AttributeError, KeyError, TypeError, ValueError) as exc:
+        raise LitematicFormatError(f"{source}: malformed palette entry: {exc}") from exc
+    return palette
+
+
+def _make_unpacker(
+    packed: np.ndarray,
+    bits: int,
+    size: Vec3i,
+    source: str,
+    palette_size: int,
+) -> Callable[[], np.ndarray]:
+    def unpack() -> np.ndarray:
+        arr = _unpack_indices(packed, bits, size)
+        if arr.size and int(arr.max()) >= palette_size:
+            raise LitematicFormatError(
+                f"{source}: block index {int(arr.max())} out of range "
+                f"for palette of {palette_size}"
+            )
+        return arr
+
+    return unpack
+
+
+def _make_slab_unpacker(
+    packed: np.ndarray,
+    bits: int,
+    size: Vec3i,
+    source: str,
+    palette_size: int,
+) -> Callable[[int, int], np.ndarray]:
+    def unpack_slab(y0: int, y1: int) -> np.ndarray:
+        span = (y1 - y0) * size.z * size.x
+        arr = _unpack_indices(
+            packed, bits, size, y0 * size.z * size.x,
+            y0 * size.z * size.x + span,
+        )
+        if arr.size and int(arr.max()) >= palette_size:
+            raise LitematicFormatError(
+                f"{source}: block index {int(arr.max())} out of range "
+                f"for palette of {palette_size} in rows [{y0}, {y1})"
+            )
+        return arr
+
+    return unpack_slab
+
+
+def _parse_pending_ticks(
+    entries: object, field: str, where: str
+) -> Optional[tuple[Mapping[str, object], ...]]:
+    """Scheduled-tick compounds ({x, y, z, Time, Priority, Block|Fluid, SubTick})."""
+    if entries is None:
+        return None
+    if not isinstance(entries, list):
+        raise LitematicFormatError(f"{where}: {field} is not a list")
+    ticks = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise LitematicFormatError(f"{where}: {field} entry is not a compound")
+        ticks.append(MappingProxyType(dict(entry)))
+    return tuple(ticks)
+
+
+def _parse_block_entities(entries: object, where: str) -> tuple[BlockEntity, ...]:
+    if not isinstance(entries, list):
+        raise LitematicFormatError(f"{where}: TileEntities is not a list")
+    out = []
+    for entry in entries:
+        try:
+            out.append(
+                BlockEntity(
+                    pos=(int(entry["x"]), int(entry["y"]), int(entry["z"])),
+                    id=_string(entry.get("id", ""), "id", where),
+                    data=MappingProxyType(dict(entry)),
+                )
+            )
+        except (AttributeError, KeyError, TypeError, ValueError) as exc:
+            raise LitematicFormatError(
+                f"{where}: malformed tile entity: {exc}"
+            ) from exc
+    return tuple(out)
+
+
+def _parse_entities(entries: object, where: str) -> tuple[Entity, ...]:
+    if not isinstance(entries, list):
+        raise LitematicFormatError(f"{where}: Entities is not a list")
+    out = []
+    for entry in entries:
+        try:
+            pos = entry["Pos"]
+            out.append(
+                Entity(
+                    id=_string(entry.get("id", ""), "id", where),
+                    pos=(float(pos[0]), float(pos[1]), float(pos[2])),
+                    data=MappingProxyType(dict(entry)),
+                )
+            )
+        except (
+            AttributeError,
+            KeyError,
+            TypeError,
+            ValueError,
+            IndexError,
+        ) as exc:
+            raise LitematicFormatError(f"{where}: malformed entity: {exc}") from exc
+    return tuple(out)
+
+
+def _parse_region(name: str, region: Mapping, source: str) -> Region:
+    where = f"{source}, region '{name}'"
+    try:
+        palette = _parse_palette(region["BlockStatePalette"], where)
+        packed = region["BlockStates"]
+    except KeyError as exc:
+        raise LitematicFormatError(f"{where}: missing field {exc}") from exc
+    pos_raw = _vec3(region, "Position", where)
+    size_raw = _vec3(region, "Size", where)
+    size = Vec3i(*(abs(s) for s in size_raw))
+    position = Vec3i(
+        *(p + (s if s < 0 else 0) for p, s in zip(pos_raw, size_raw))
+    )
+    if not isinstance(packed, np.ndarray) or packed.dtype != np.int64:
+        raise LitematicFormatError(f"{where}: BlockStates is not a long array")
+    bits = _bits_for(len(palette))
+    volume = size.x * size.y * size.z
+    expected_longs = (volume * bits + 63) // 64
+    if packed.size != expected_longs:
+        raise LitematicFormatError(
+            f"{where}: BlockStates has {packed.size} longs, "
+            f"expected {expected_longs} ({volume} blocks at {bits} bits)"
+        )
+    block_entities = _parse_block_entities(region.get("TileEntities", []), where)
+    entities = _parse_entities(region.get("Entities", []), where)
+    pending_block_ticks = _parse_pending_ticks(
+        region.get("PendingBlockTicks"), "PendingBlockTicks", where
+    )
+    pending_fluid_ticks = _parse_pending_ticks(
+        region.get("PendingFluidTicks"), "PendingFluidTicks", where
+    )
+    return Region(
+        name=name,
+        position=position,
+        size=size,
+        palette=palette,
+        block_entities=block_entities,
+        entities=entities,
+        pending_block_ticks=pending_block_ticks,
+        pending_fluid_ticks=pending_fluid_ticks,
+        packed_indices=packed,
+        _unpack=_make_unpacker(packed, bits, size, where, len(palette)),
+        _unpack_slab=_make_slab_unpacker(
+            packed, bits, size, where, len(palette)
+        ),
+    )
+
+
+def parse_schematic(root: dict, source_name: str = "") -> Litematic:
+    """Build a Litematic model from an already-parsed NBT root compound."""
+    regions = root.get("Regions")
+    if not isinstance(regions, dict) or not regions:
+        raise LitematicFormatError(f"{source_name}: no Regions")
+    parsed = {}
+    for name, raw in regions.items():
+        if not isinstance(raw, dict):
+            raise LitematicFormatError(
+                f"{source_name}, region '{name}': region is not a compound"
+            )
+        parsed[name] = _parse_region(name, raw, source_name)
+    return Litematic(metadata=_parse_metadata(root, source_name), regions=parsed)
+
+
+def loads(data: bytes) -> Litematic:
+    """Parse .litematic bytes into a Litematic model."""
+    if not isinstance(data, (bytes, bytearray, memoryview)):
+        raise LitematicError(
+            f"loads() expects bytes-like input, got {type(data).__name__}"
+        )
+    return parse_schematic(read_nbt(data), "<bytes>")
+
+
+def load(path: str | Path) -> Litematic:
+    """Read and parse a .litematic file into a Litematic model."""
+    if not isinstance(path, (str, Path)):
+        raise LitematicError(
+            f"load() expects a str or Path, got {type(path).__name__}"
+        )
+    try:
+        p = Path(path)
+    except ValueError as exc:
+        raise LitematicError(f"Cannot read {path!r}: {exc}") from exc
+    try:
+        data = p.read_bytes()
+    except OSError as exc:
+        raise LitematicError(f"Cannot read {p}: {exc}") from exc
+    return parse_schematic(read_nbt(data), str(p))

litematic/render/__init__.py

@@ -0,0 +1,134 @@
+"""Offline isometric rendering of parsed .litematic schematics."""
+
+from collections.abc import Sequence
+from pathlib import Path
+
+import numpy as np
+
+from litematic.parse.model import Litematic
+from litematic.render.errors import RenderError
+from litematic.render.pack import load_pack
+from litematic.render.png import encode_png
+from litematic.render.scene.isometric import _AIR_NAMES, _compose
+from litematic.render.scene.painter import _choose_scale, _downsample, _paint
+
+__all__ = [
+    "RenderError",
+    "isometric",
+    "isometric_png",
+    "to_png",
+    "unresolved_colors",
+]
+
+_MAX_SIZE_BOUNDS = (16, 8192)
+_SS_BOUNDS = (1, 4)
+
+
+def isometric(
+    schem: Litematic,
+    *,
+    textures_path: str | Path | None = None,
+    extra_packs: Sequence[str | Path] = (),
+    yaw: int = 0,
+    max_size: int = 2048,
+    supersample: int = 2,
+    background: tuple[int, int, int, int] | None = None,
+) -> np.ndarray:
+    """Render a schematic to an RGBA isometric image within max_size."""
+    if yaw not in (0, 1, 2, 3):
+        raise RenderError(f"render: yaw must be 0-3, got {yaw}")
+    if not _MAX_SIZE_BOUNDS[0] <= max_size <= _MAX_SIZE_BOUNDS[1]:
+        raise RenderError(
+            f"render: max_size must be "
+            f"{_MAX_SIZE_BOUNDS[0]}-{_MAX_SIZE_BOUNDS[1]}, got {max_size}"
+        )
+    if not _SS_BOUNDS[0] <= supersample <= _SS_BOUNDS[1]:
+        raise RenderError(
+            f"render: supersample must be {_SS_BOUNDS[0]}-{_SS_BOUNDS[1]}, "
+            f"got {supersample}"
+        )
+    bg = _background(background)
+    textures = load_pack(_require_pack(textures_path), extra_packs)
+    scene = _compose(schem, yaw, textures)
+    if len(scene.x) == 0:
+        raise RenderError("render: no blocks to render")
+    t, _ = _choose_scale(scene.span_w, scene.span_h, max_size, supersample)
+    img = _paint(scene, t, bg)
+    height, width = img.shape[:2]
+    if max(height, width) > max_size:
+        factor = max_size / max(height, width)
+        img = _downsample(
+            img, max(1, round(width * factor)), max(1, round(height * factor))
+        )
+    return img
+
+
+def isometric_png(
+    schem: Litematic,
+    *,
+    textures_path: str | Path | None = None,
+    extra_packs: Sequence[str | Path] = (),
+    yaw: int = 0,
+    max_size: int = 2048,
+    supersample: int = 2,
+    background: tuple[int, int, int, int] | None = None,
+) -> bytes:
+    """Render a schematic and encode the image as PNG bytes."""
+    return encode_png(
+        isometric(
+            schem,
+            textures_path=textures_path,
+            extra_packs=extra_packs,
+            yaw=yaw,
+            max_size=max_size,
+            supersample=supersample,
+            background=background,
+        )
+    )
+
+
+def to_png(image: np.ndarray) -> bytes:
+    """Encode an RGBA uint8 image array as PNG bytes."""
+    return encode_png(image)
+
+
+def unresolved_colors(
+    schem: Litematic,
+    *,
+    textures_path: str | Path,
+    extra_packs: Sequence[str | Path] = (),
+) -> set[str]:
+    """Return block names the pack stack cannot cover; these render magenta."""
+    textures = load_pack(_require_pack(textures_path), extra_packs)
+    return {
+        state.name
+        for region in schem.regions.values()
+        for state in region.palette
+        if state.name not in _AIR_NAMES
+        and textures.resolve(state).miss is not None
+    }
+
+
+def _background(
+    value: tuple[int, int, int, int] | None,
+) -> tuple[int, int, int, int]:
+    if value is None:
+        return (0, 0, 0, 0)
+    if (
+        isinstance(value, tuple)
+        and len(value) == 4
+        and all(
+            isinstance(v, int) and not isinstance(v, bool) and 0 <= v <= 255
+            for v in value
+        )
+    ):
+        return value
+    raise RenderError("render: background must be None or 4 ints in [0, 255]")
+
+
+def _require_pack(textures_path: str | Path | None) -> str | Path:
+    if textures_path is None:
+        raise RenderError(
+            "render: a resource pack zip is required (pass textures_path)"
+        )
+    return textures_path

litematic/render/errors.py

@@ -0,0 +1,9 @@
+"""Errors raised by the render subpackage."""
+
+from litematic.parse.errors import LitematicError
+
+__all__ = ["RenderError"]
+
+
+class RenderError(LitematicError):
+    """Raised when a render request cannot be fulfilled."""

litematic/render/pack/__init__.py

@@ -0,0 +1,7 @@
+"""Resource-pack pipeline: blockstates → models → quads → cached npz."""
+
+from litematic.render.pack.extract import ExtractSummary
+from litematic.render.pack.loader import load_pack
+from litematic.render.pack.resolve import Resolution, Resolver
+
+__all__ = ["ExtractSummary", "Resolution", "Resolver", "load_pack"]

litematic/render/pack/blockstate.py

@@ -0,0 +1,111 @@
+"""Blockstate JSON parsing: variants and multipart part records."""
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+
+def _normalize_state_key(key: str) -> str:
+    if not key:
+        return ""
+    pairs = [pair.strip() for pair in key.split(",") if pair.strip()]
+    pairs.sort(key=lambda pair: pair.split("=", 1)[0])
+    return ",".join(pairs)
+
+
+
+def _block_id(state_name: str) -> str:
+    parts = state_name.split("/")
+    ns = parts[1]
+    stem = parts[-1][: -len(".json")]
+    return f"{ns}:{stem}"
+
+
+
+def _state_pairs(state_key: str) -> dict[str, str]:
+    """Parse a state key into its property pairs; the empty key is {}."""
+    pairs: dict[str, str] = {}
+    for part in state_key.split(","):
+        prop, sep, value = part.partition("=")
+        if sep:
+            pairs[prop] = value
+    return pairs
+
+
+
+def _when_matches(
+    condition: Mapping[str, Any], values: Mapping[str, str]
+) -> bool:
+    """Vanilla multipart condition: OR/AND nesting, | alternatives."""
+    if not isinstance(condition, Mapping):
+        return False
+    for key, expected in condition.items():
+        if key == "OR" or key == "AND":
+            if not isinstance(expected, list):
+                return False
+            sub = [_when_matches(item, values) for item in expected]
+            if key == "OR" and not any(sub):
+                return False
+            if key == "AND" and not all(sub):
+                return False
+        else:
+            actual = values.get(str(key))
+            if actual is None or actual not in str(expected).split("|"):
+                return False
+    return True
+
+
+
+def _parse_blockstate(
+    state: dict[str, Any],
+) -> tuple[
+    list[tuple[str, list[dict[str, Any]]]],
+    list[dict[str, Any]] | None,
+    list[str],
+]:
+    """Split a blockstate into variant entries and multipart part records.
+
+    Variant keys are alternatives and map to one apply, keyed for the
+    state-keyed section. Conditional multiparts keep their raw condition
+    trees: render-time evaluation against the live properties (the
+    Blockscope select_variants shape) needs no key enumeration and no
+    property-domain inference. The model refs cover every referenced
+    model regardless, feeding the spec 5.3 texture fallback.
+    """
+    out: list[tuple[str, list[dict[str, Any]]]] = []
+    variants = state.get("variants")
+    if isinstance(variants, dict):
+        for key, value in variants.items():
+            variant = value[0] if isinstance(value, list) and value else value
+            if isinstance(variant, dict) and isinstance(variant.get("model"), str):
+                out.append((_normalize_state_key(key), [variant]))
+    parts: list[dict[str, Any]] | None = None
+    raw = state.get("multipart")
+    if isinstance(raw, list) and raw:
+        parts = []
+        for part in raw:
+            if not isinstance(part, dict):
+                continue
+            when = part.get("when")
+            record_when = None
+            if isinstance(when, Mapping):
+                record_when = json.loads(json.dumps(when))
+            apply = part.get("apply")
+            entries = apply if isinstance(apply, list) else [apply]
+            for entry in entries:
+                # Multipart apply arrays are several models rendered
+                # together under one condition: flatten to one record per
+                # model, all sharing the part's condition.
+                if isinstance(entry, dict) and isinstance(entry.get("model"), str):
+                    record = {
+                        "model": entry["model"],
+                        "when": record_when,
+                        "x": int(entry.get("x", 0)),
+                        "y": int(entry.get("y", 0)),
+                        "uvlock": bool(entry.get("uvlock", False)),
+                    }
+                    parts.append(record)
+    refs = [v["model"] for _, applies in out for v in applies]
+    if parts is not None:
+        refs.extend(p["model"] for p in parts)
+    return out, parts, refs