litematica-render 0.1.0__py3-none-any.whl

litematic/render/pack/texture.py

@@ -0,0 +1,347 @@
+"""Texture resolution: refs, models, PNG decode, tints."""
+
+import io
+import json
+from typing import Any
+
+import numpy as np
+
+from litematic.render.errors import RenderError
+from litematic.render.pack.resolve import _tint_for
+from litematic.render.pack.stack import PackStack
+from litematic.render.quads import _redstone_tint
+
+_VEC = {
+    "up": (0, 1, 0),
+    "down": (0, -1, 0),
+    "north": (0, 0, -1),
+    "south": (0, 0, 1),
+    "west": (-1, 0, 0),
+    "east": (1, 0, 0),
+}
+_NAME = {v: k for k, v in _VEC.items()}
+
+
+
+class _Budget:
+    """Reject oversize or over-budget pack textures as missing."""
+
+    MAX_SIDE = 2048
+    MAX_BYTES = 256 * 1024 * 1024
+
+    def __init__(self) -> None:
+        self.bytes = 0
+
+    def take(self, shape: tuple[int, ...]) -> bool:
+        """Account one decoded texture's bytes; False when over a cap."""
+        height, width = int(shape[0]), int(shape[1])
+        if max(height, width) > self.MAX_SIDE:
+            return False
+        size = height * width * 4
+        if self.bytes + size > self.MAX_BYTES:
+            return False
+        self.bytes += size
+        return True
+
+
+
+def _resolve_ref(ref: Any, textures: dict[str, str]) -> str | None:
+    """Resolve a face texture reference, following # chains up to depth 32."""
+    if not isinstance(ref, str) or not ref:
+        return None
+    current = ref
+    for _ in range(32):
+        if not current.startswith("#"):
+            return current
+        nxt = textures.get(current[1:])
+        if not isinstance(nxt, str):
+            return None
+        current = nxt
+    return None
+
+
+
+def _texture_key(ref: str, ns: str) -> str:
+    ref_ns, _, path = ref.partition(":")
+    if not path:
+        ref_ns, path = ns, ref_ns
+    if ref_ns == "minecraft":
+        return path
+    return f"{ref_ns}:{path}"
+
+
+
+def _asset_path(ns: str, ref: str, kind: str, suffix: str) -> str | None:
+    if ".." in ref:
+        return None
+    ref_ns, _, path = ref.partition(":")
+    if not path:
+        return f"assets/{ns}/{kind}/{ref_ns}{suffix}"
+    path = path.removeprefix(f"{kind}/")
+    return f"assets/{ref_ns}/{kind}/{path}{suffix}"
+
+
+
+def _cached_model(
+    stack: PackStack,
+    ns: str,
+    ref: str,
+    cache: dict[str, dict[str, Any] | None],
+) -> dict[str, Any] | None:
+    key = f"{ns}|{ref}"
+    if key not in cache:
+        model = _resolve_model(stack, ns, ref)
+        if model is None:
+            cache[key] = None
+        elif model["elements"] is None:
+            stub_ref = _stub_texture(stack, ns, model["textures"])
+            cache[key] = (
+                None
+                if stub_ref is None
+                else {
+                    "textures": model["textures"],
+                    "elements": None,
+                    "stub_ref": stub_ref,
+                    "builtin_cut": bool(model.get("builtin_cut")),
+                }
+            )
+        else:
+            cache[key] = model
+    return cache[key]
+
+
+
+def _stub_texture(
+    stack: PackStack, ns: str, textures: dict[str, Any]
+) -> str | None:
+    """Find the first concrete texture ref an element-less model can load."""
+    for value in textures.values():
+        if not isinstance(value, str) or value.startswith("#"):
+            continue
+        path = _asset_path(ns, value, "textures", ".png")
+        if path is not None and stack.exists(path):
+            return value
+    return None
+
+
+
+def _resolve_model(
+    stack: PackStack, ns: str, model_ref: str
+) -> dict[str, Any] | None:
+    """Walk the parent chain and merge textures; nearest elements win."""
+    merged_textures: dict[str, str] = {}
+    elements: list[dict[str, Any]] | None = None
+    seen: set[str] = set()
+    ref: str | None = model_ref
+    while ref is not None and not ref.split(":")[-1].startswith("builtin"):
+        if ref in seen:
+            return None
+        seen.add(ref)
+        file = _asset_path(ns, ref, "models", ".json")
+        if file is None or not stack.exists(file):
+            return None
+        raw = stack.read(file)
+        if raw is None:  # unreachable: the path exists per the check above
+            return None
+        model = json.loads(raw)
+        if not isinstance(model, dict):
+            return None
+        textures = model.get("textures")
+        if isinstance(textures, dict):
+            for key, value in textures.items():
+                merged_textures.setdefault(key, value)
+        if elements is None and isinstance(model.get("elements"), list):
+            elements = model["elements"]
+        parent = model.get("parent")
+        ref = parent if isinstance(parent, str) else None
+    if elements is None:
+        if ref is not None:
+            # Chain terminated at a builtin/* parent: no pack geometry, but
+            # the merged textures still feed the spec 5.3 texture fallback.
+            return {
+                "textures": merged_textures,
+                "elements": None,
+                "builtin_cut": True,
+            }
+        return {"textures": merged_textures, "elements": None}
+    return {"textures": merged_textures, "elements": elements}
+
+
+
+def _rotate(face: str, x: int, y: int) -> str:
+    vec = _VEC[face]
+    for _ in range((x // 90) % 4):  # y' = z, z' = -y
+        vec = (vec[0], vec[2], -vec[1])
+    for _ in range((y // 90) % 4):  # x' = -z, z' = x
+        vec = (-vec[2], vec[1], vec[0])
+    return _NAME[vec]
+
+
+
+def _load_texture(
+    stack: PackStack,
+    ns: str,
+    tex_ref: str,
+    tex_key: str,
+    cache: dict[str, np.ndarray | None],
+    budget: _Budget,
+) -> np.ndarray | None:
+    if tex_key in cache:
+        return cache[tex_key]
+    file = _asset_path(ns, tex_ref, "textures", ".png")
+    result: np.ndarray | None = None
+    if file is not None:
+        found = stack.read_ranked(file)
+        if found is not None:
+            data, pack_index = found
+            try:
+                image = _decode_png(data, _is_animated(stack, file, pack_index))
+                raw = np.asarray(image, dtype=np.uint8)
+                if budget.take(raw.shape):
+                    result = raw
+            except RenderError:
+                raise
+            except Exception:
+                result = None
+    cache[tex_key] = result
+    return result
+
+
+
+def _is_animated(stack: PackStack, file: str, pack_index: int) -> bool:
+    """True when the texture's .mcmeta above its own pack declares an animation."""
+    data = stack.mcmeta(file, pack_index)
+    if data is None:
+        return False
+    try:
+        parsed = json.loads(data)
+    except Exception:
+        return False
+    return isinstance(parsed, dict) and "animation" in parsed
+
+
+
+def _decode_png(data: bytes, animated: bool) -> Any:
+    from PIL import Image
+
+    image = Image.open(io.BytesIO(data)).convert("RGBA")
+    if animated:  # vertical strip: first frame only
+        width, height = image.size
+        side = min(width, height)
+        image = image.crop((0, 0, side, side))
+    return image
+
+
+
+def _apply_tint(array: np.ndarray, tint: tuple[int, int, int]) -> np.ndarray:
+    factor = np.array(tint + (255,), dtype=np.uint16)
+    return ((array.astype(np.uint16) * factor) // 255).astype(np.uint8)
+
+
+
+def _register_array(
+    raw: np.ndarray,
+    tex_key: str,
+    tint: tuple[int, int, int] | None,
+    tex_arrays: dict[str, np.ndarray],
+) -> str:
+    """Store a raw texture under tex_key, adding a tinted variant if asked."""
+    if tint is None:
+        tex_arrays.setdefault(tex_key, raw)
+        return tex_key
+    array_key = f"{tex_key}@{tint[0]},{tint[1]},{tint[2]}"
+    if array_key not in tex_arrays:
+        tex_arrays[array_key] = _apply_tint(raw, tint)
+    return array_key
+
+
+
+def _first_model_texture(
+    stack: PackStack,
+    ns: str,
+    model_refs: list[str],
+    model_cache: dict[str, dict[str, Any] | None],
+    texture_cache: dict[str, np.ndarray | None],
+    budget: _Budget,
+) -> np.ndarray | None:
+    """First loadable concrete texture among the referenced models."""
+    for ref in model_refs:
+        model = _cached_model(stack, ns, ref, model_cache)
+        if model is None:
+            continue
+        for value in model["textures"].values():
+            tex_ref = _resolve_ref(value, model["textures"])
+            if tex_ref is None:
+                continue
+            raw = _load_texture(
+                stack,
+                ns,
+                tex_ref,
+                _texture_key(tex_ref, ns),
+                texture_cache,
+                budget,
+            )
+            if raw is not None:
+                return raw
+    return None
+
+
+
+def _register_builtin_texture(
+    stack: PackStack,
+    ns: str,
+    block_id: str,
+    model_refs: list[str],
+    model_cache: dict[str, dict[str, Any] | None],
+    texture_cache: dict[str, np.ndarray | None],
+    tex_arrays: dict[str, np.ndarray],
+    budget: _Budget,
+) -> None:
+    """Register the builtin layer texture under the block's canonical key.
+
+    Spec 5.3 chain: the block's own model textures first, then
+    textures/block/<stem>.png; unresolved blocks stay for magenta.
+    """
+    raw = _first_model_texture(
+        stack, ns, model_refs, model_cache, texture_cache, budget
+    )
+    stem = block_id.partition(":")[2]
+    tex_key = _texture_key(f"block/{stem}", ns)
+    if raw is None:
+        raw = _load_texture(
+            stack, ns, f"block/{stem}", tex_key, texture_cache, budget
+        )
+    if raw is None:
+        return
+    tex_arrays.setdefault(tex_key, raw)
+    tint = _tint_for(block_id, "")
+    if tint is not None:
+        array_key = f"{tex_key}@{tint[0]},{tint[1]},{tint[2]}"
+        if array_key not in tex_arrays:
+            tex_arrays[array_key] = _apply_tint(raw, tint)
+
+
+
+_WIRE_DUST_TEXTURES = ("block/redstone_dust_dot", "block/redstone_dust_line0")
+
+
+
+def _register_wire_dust(
+    stack: PackStack,
+    ns: str,
+    texture_cache: dict[str, np.ndarray | None],
+    tex_arrays: dict[str, np.ndarray],
+    budget: _Budget,
+) -> None:
+    """Register power-tinted dust textures for the builtin wire family."""
+    for ref in _WIRE_DUST_TEXTURES:
+        tex_key = _texture_key(ref, ns)
+        raw = _load_texture(stack, ns, ref, tex_key, texture_cache, budget)
+        if raw is None:
+            continue
+        for power in range(16):
+            tint = _redstone_tint(power)
+            tex_arrays.setdefault(
+                f"{tex_key}@{tint[0]},{tint[1]},{tint[2]}",
+                _apply_tint(raw, tint),
+            )

litematic/render/png.py

@@ -0,0 +1,54 @@
+"""Minimal deterministic PNG encoder for RGBA uint8 images."""
+
+import struct
+import zlib
+
+import numpy as np
+
+from litematic.render.errors import RenderError
+
+__all__ = ["encode_png"]
+
+_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def encode_png(image: np.ndarray) -> bytes:
+    """Encode (H, W, 4) uint8 RGBA as PNG; zero transparent RGB; raises RenderError."""
+    if (
+        not isinstance(image, np.ndarray)
+        or image.dtype != np.uint8
+        or image.ndim != 3
+        or image.shape[2] != 4
+        or min(image.shape[:2]) < 1
+    ):
+        raise RenderError(
+            "encode: expected (H, W, 4) uint8 array, got "
+            f"dtype={getattr(image, 'dtype', type(image).__name__)} "
+            f"shape={getattr(image, 'shape', None)}"
+        )
+
+    pixels = image.copy()
+    transparent = pixels[..., 3] == 0
+    pixels[..., :3][transparent] = 0
+
+    height, width = pixels.shape[:2]
+    scanlines = np.zeros((height, width * 4 + 1), dtype=np.uint8)
+    scanlines[:, 1:] = pixels.reshape(height, width * 4)
+    raw = scanlines.tobytes()
+
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0)
+    return (
+        _SIGNATURE
+        + _chunk(b"IHDR", ihdr)
+        + _chunk(b"IDAT", zlib.compress(raw))
+        + _chunk(b"IEND", b"")
+    )
+
+
+def _chunk(tag: bytes, data: bytes) -> bytes:
+    return (
+        struct.pack(">I", len(data))
+        + tag
+        + data
+        + struct.pack(">I", zlib.crc32(tag + data))
+    )

litematic/render/quads.py

@@ -0,0 +1,106 @@
+"""Quad data core: dtype, face tiers, unit cubes, ordering, geometry checks."""
+
+import numpy as np
+
+__all__ = [
+    "AO_LEVELS",
+    "CULL_NONE",
+    "FACE_LIGHT",
+    "QUAD_DTYPE",
+    "TIER_DOWN",
+    "TIER_EAST",
+    "TIER_NORTH",
+    "TIER_SOUTH",
+    "TIER_UP",
+    "TIER_WEST",
+    "is_parallelogram",
+    "sort_quads",
+    "unit_cube_quads",
+]
+
+QUAD_DTYPE = np.dtype(
+    [
+        ("vtx", "f4", (4, 3)),
+        ("uv", "f4", (4, 2)),
+        ("texkey", "U64"),
+        ("shade", "u1"),
+        ("dbl", "?"),
+        ("cull", "u1"),
+    ]
+)
+
+# No cullface direction: the quad never disappears through neighbor culling.
+CULL_NONE = 255
+
+TIER_DOWN = 0
+TIER_UP = 1
+TIER_NORTH = 2
+TIER_SOUTH = 3
+TIER_WEST = 4
+TIER_EAST = 5
+
+FACE_LIGHT = (0.5, 1.0, 0.8, 0.8, 0.6, 0.6)
+AO_LEVELS = (0.4, 0.6, 0.8, 1.0)
+
+# Per-tier corners in the pinned winding; auto-UVs follow vanilla defaultFaceUV.
+_CUBE_VTX = np.array(
+    [
+        [(0, 0, 16), (16, 0, 16), (16, 0, 0), (0, 0, 0)],  # down
+        [(0, 16, 0), (16, 16, 0), (16, 16, 16), (0, 16, 16)],  # up
+        [(16, 16, 0), (0, 16, 0), (0, 0, 0), (16, 0, 0)],  # north
+        [(0, 16, 16), (16, 16, 16), (16, 0, 16), (0, 0, 16)],  # south
+        [(0, 16, 16), (0, 16, 0), (0, 0, 0), (0, 0, 16)],  # west
+        [(16, 16, 0), (16, 16, 16), (16, 0, 16), (16, 0, 0)],  # east
+    ],
+    dtype="f4",
+)
+_CUBE_UV = np.tile(
+    np.array([(0, 0), (16, 0), (16, 16), (0, 16)], dtype="f4"), (6, 1, 1)
+)
+# West/east corners run the opposite winding, hence the flipped uv ring.
+_CUBE_UV[TIER_WEST] = [(16, 0), (0, 0), (0, 16), (16, 16)]
+_CUBE_UV[TIER_EAST] = [(16, 0), (0, 0), (0, 16), (16, 16)]
+
+
+def unit_cube_quads(texkey: str, shade_faces: bool = True) -> np.ndarray:
+    """Build the six textured faces of a full 0..16 unit cube."""
+    quads = np.empty(6, dtype=QUAD_DTYPE)
+    quads["vtx"] = _CUBE_VTX
+    quads["uv"] = _CUBE_UV
+    quads["texkey"] = texkey
+    if shade_faces:
+        quads["shade"] = np.arange(6, dtype=np.uint8)
+    else:
+        quads["shade"] = np.full(6, TIER_UP, dtype=np.uint8)
+    quads["dbl"] = False
+    quads["cull"] = CULL_NONE
+    return quads
+
+
+def sort_quads(quads: np.ndarray) -> np.ndarray:
+    """Return a canonical copy ordered by the raw byte sequence of vtx."""
+    vtx = np.ascontiguousarray(quads["vtx"]).reshape(quads.shape[0], 12)
+    keys = vtx.view(np.dtype((np.void, vtx.dtype.itemsize * 12))).reshape(-1)
+    order = np.argsort(keys, kind="stable")
+    return quads[order]
+
+
+def is_parallelogram(quads: np.ndarray, eps: float = 1e-3) -> np.ndarray:
+    """Flag quads whose diagonal midpoints coincide within eps on each axis."""
+    vtx = quads["vtx"]
+    diag = (vtx[:, 0] + vtx[:, 2]) - (vtx[:, 1] + vtx[:, 3])
+    return np.all(np.abs(diag) <= eps, axis=-1)
+
+_REDSTONE_LOW = (76, 0, 0)
+_REDSTONE_HIGH = (255, 26, 26)
+
+
+def _redstone_tint(power: int) -> tuple[int, int, int]:
+    """Vanilla dust color for a redstone power level, 0-15."""
+    factor = max(0, min(15, power)) / 15.0
+    low, high = _REDSTONE_LOW, _REDSTONE_HIGH
+    return (
+        round(low[0] + (high[0] - low[0]) * factor),
+        round(low[1] + (high[1] - low[1]) * factor),
+        round(low[2] + (high[2] - low[2]) * factor),
+    )

litematic/render/scene/__init__.py

@@ -0,0 +1,6 @@
+"""Scene pipeline: world composition and the isometric painter."""
+
+from litematic.render.scene.isometric import _compose
+from litematic.render.scene.painter import _choose_scale, _downsample, _paint
+
+__all__ = ["_choose_scale", "_compose", "_downsample", "_paint"]