pylitematic 0.0.0__py3-none-any.whl → 0.0.1__py3-none-any.whl

pylitematic/__init__.py

@@ -1 +1,7 @@
-__version__ = "0.0.0"
+__version__ = "0.0.1"
+
+from .block_state import BlockState
+from .geometry import BlockPosition, Size3D
+from .region import Region
+from .resource_location import ResourceLocation
+from .schematic import Schematic

pylitematic/block_property.py

@@ -0,0 +1,325 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+import json
+import nbtlib
+import re
+from typing import Any
+
+
+PROPERTY_NAME_REGEX: str = r"[a-z][a-z0-9_]*"
+PROPERTY_NAME_PATTERN: re.Pattern = re.compile(PROPERTY_NAME_REGEX)
+
+ENUM_VALUE_REGEX: str = r"[a-z]+(_[a-z]+)*" # snake case
+ENUM_VALUE_PATTERN: re.Pattern = re.compile(ENUM_VALUE_REGEX)
+
+
+class Property():
+
+    __slots__ = ("_name", "_value")
+
+    def __init__(self, name: str, value: Any | PropertyValue) -> None:
+        if not PROPERTY_NAME_PATTERN.fullmatch(name):
+            raise ValueError(f"Invalid property name {name!r}")
+        self._name = name
+
+        if not isinstance(value, PropertyValue):
+            value = PropertyValue.value_factory(value=value)
+        self._value = value
+
+    def __str__(self) -> str:
+        return f"{self._name}={self._value}"
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"name: {self._name}, value: {self._value!r})")
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, Property):
+            return NotImplemented
+        return (self.name, self.value) == (other.name, other.value)
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, Property):
+            return NotImplemented
+        return (self.name, self.value) < (other.name, other.value)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def value(self) -> Any:
+        return self._value.get()
+
+    @value.setter
+    def value(self, value: Any) -> None:
+        self._value.set(value)
+
+    def to_string(self) -> str:
+        return str(self)
+
+    @staticmethod
+    def from_string(string: str, value: str | None = None) -> Property:
+        if value is None:
+            # tread string as "name=value"
+            try:
+                string, value = string.split("=")
+            except ValueError as exc:
+                raise ValueError(f"Invalid property string {string!r}") from exc
+        return Property(name=string, value=PropertyValue.from_string(value))
+
+    def to_nbt(self) -> tuple[str, nbtlib.String]:
+        # return nbtlib.Compound(Name=nbtlib.String(self._name), Value=self._value.to_nbt()})
+        return self._name, self._value.to_nbt()
+
+    @staticmethod
+    def from_nbt(name: str, nbt: nbtlib.String) -> Property:
+        # return Property.from_string(name=nbt["Name"], value=str(nbt["Value"]))
+        return Property.from_string(string=name, value=str(nbt))
+
+
+class Properties(dict):
+
+    def __init__(self, *args, **kwargs):
+        props = {}
+        for name, value in dict(*args, **kwargs).items():
+            self.validate_name(name)
+            props[name] = PropertyValue.value_factory(value)
+        super().__init__(props)
+
+    def __getitem__(self, key):
+        return super().__getitem__(key).get()
+
+    def __setitem__(self, key, value):
+        if key not in self:
+            self.validate_name(key)
+            super().__setitem__(key, PropertyValue.value_factory(value))
+        else:
+            super().__getitem__(key).set(value)
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, Properties):
+            return NotImplemented
+        return sorted(self.items()) < sorted(other.items())
+
+    def __hash__(self) -> int:
+        return hash(tuple(sorted(self)))
+
+    def __str__(self) -> str:
+        props_str = [f"{n}={v}" for n, v in sorted(super().items())]
+        return f"[{','.join(props_str)}]"
+
+    def __repr__(self) -> str:
+        props_reps = [f"{n}: {v!r}" for n, v in sorted(super().items())]
+        return f"{type(self).__name__}({', '.join(props_reps)})"
+
+    def get(self, key, default=None):
+        value = super().get(key, None)
+        if value is None:
+            return default
+        return value.get()
+
+    def setdefault(self, key, default=None):
+        if key not in self:
+            self[key] = default
+        return self[key]
+
+    def update(self, *args, **kwargs):
+        for name, value in dict(*args, **kwargs).items():
+            self[name] = value
+
+    def pop(self, key, default=None):
+        value = super().pop(key, None)
+        if value is None:
+            return default
+        return value.get()
+
+    def popitem(self):
+        name, value = super().popitem()
+        return name, value.get()
+
+    def values(self):
+        for value in super().values():
+            yield value.get()
+
+    def items(self):
+        for key, value in super().items():
+            yield key, value.get()
+
+    @staticmethod
+    def is_valid_name(name: str) -> bool:
+        return PROPERTY_NAME_PATTERN.fullmatch(name) is not None
+
+    @staticmethod
+    def validate_name(name: str) -> None:
+        if not Properties.is_valid_name(name=name):
+            raise ValueError(f"Invalid property name {name!r}")
+
+    def to_string(self) -> str:
+        return str(self)
+
+    @staticmethod
+    def from_string(string: str) -> Properties:
+        if string in ("", "[]"):
+            return Properties()
+
+        if not (string.startswith("[") and string.endswith("]")):
+            raise ValueError(f"Invalid properties string {string!r}")
+        string = string[1:-1]
+
+        props = {}
+        for prop in string.split(","):
+            try:
+                name, val_str = prop.split("=")
+            except ValueError as exc:
+                raise ValueError(f"Invalid property string {string!r}") from exc
+            if name in props:
+                ValueError(f"Duplicate property name {name!r}")
+            props[name] = PropertyValue.from_string(string=val_str).get()
+
+        return Properties(props)
+
+    def to_nbt(self) -> nbtlib.Compound:
+        return nbtlib.Compound(
+            {name: value.to_nbt() for name, value in sorted(super().items())})
+
+    @staticmethod
+    def from_nbt(nbt: nbtlib.Compound) -> Properties:
+        props = {}
+        for name, value in nbt.items():
+            props[name] = PropertyValue.from_nbt(nbt=value).get()
+        return Properties(props)
+
+
+class PropertyValue(ABC):
+
+    __slots__ = ("_value")
+    __registry: dict[type, type[PropertyValue]] = {}
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+        py_type = cls.python_type()
+        if py_type in cls.__registry:
+            raise ValueError(
+                f"Duplicate Value subclass for type {py_type.__name__!r}:"
+                f" {cls.__registry[py_type].__name__} vs {cls.__name__}")
+        cls.__registry[py_type] = cls
+
+    def __init__(self, value: Any) -> None:
+        self.set(value)
+
+    def __str__(self) -> str:
+        return json.dumps(self._value)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._value!r})"
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, self._value))
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, self.__class__):
+            return NotImplemented
+        return self._value == other._value
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, PropertyValue):
+            return NotImplemented
+        return self._value < other._value
+
+    @classmethod
+    @abstractmethod
+    def is_valid_value(cls, value: Any) -> bool:
+        ...
+
+    @classmethod
+    def validate_value(cls, value: Any) -> None:
+        if not isinstance(value, cls.python_type()):
+            raise TypeError(
+                f"{cls.__name__} expects value of type"
+                f" {cls.python_type().__name__}, got {type(value).__name__}"
+                f" ({value!r})")
+        if not cls.is_valid_value(value):
+            raise ValueError(f"Invalid value {value!r} for {cls.__name__}")
+
+    def get(self) -> Any:
+        return self._value
+
+    def set(self, value: Any) -> None:
+        self.validate_value(value=value)
+        self._value = self.python_type()(value)
+
+    @classmethod
+    @abstractmethod
+    def python_type(cls) -> type:
+        """Return the native Python type this Value corresponds to."""
+
+    @staticmethod
+    def value_factory(value: Any) -> PropertyValue:
+        reg = PropertyValue.__registry
+        sub_cls = reg.get(type(value))
+        if sub_cls is None:
+            opt_str = ", ".join(map(lambda x: x.__name__, reg))
+            raise TypeError(
+                f"No Value subclass registered for {type(value).__name__} value"
+                f" {value!r}. Classes registered for: {opt_str}")
+        return sub_cls(value)
+
+    def to_string(self) -> str:
+        return str(self)
+
+    @staticmethod
+    def from_string(string: str) -> PropertyValue:
+        try:
+            value = json.loads(string)
+        except json.JSONDecodeError:
+            value = string
+        return PropertyValue.value_factory(value)
+
+    def to_nbt(self) -> nbtlib.String:
+        return nbtlib.String(self)
+
+    @staticmethod
+    def from_nbt(nbt: nbtlib.String) -> PropertyValue:
+        return PropertyValue.from_string(str(nbt))
+
+
+class BooleanValue(PropertyValue):
+
+    @classmethod
+    def is_valid_value(cls, value: Any) -> bool:
+        return True
+
+    @classmethod
+    def python_type(cls) -> type:
+        """Return the native Python type a BooleanValue corresponds to."""
+        return bool
+
+
+class IntegerValue(PropertyValue):
+
+    @classmethod
+    def is_valid_value(cls, value: Any) -> bool:
+        return value >= 0
+
+    @classmethod
+    def python_type(cls) -> type:
+        """Return the native Python type an IntegerValue corresponds to."""
+        return int
+
+
+class EnumValue(PropertyValue):
+
+    def __str__(self) -> str:
+        return self._value
+
+    @classmethod
+    def is_valid_value(cls, value: Any) -> bool:
+        return ENUM_VALUE_PATTERN.fullmatch(value) is not None
+
+    @classmethod
+    def python_type(cls) -> type:
+        """Return the native Python type an EnumValue corresponds to."""
+        return str

pylitematic/block_state.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from nbtlib import Compound
+from typing import Any, Iterator
+
+from .resource_location import ResourceLocation
+from .block_property import Properties
+
+
+class BlockState:
+
+    __slots__ = ("_id", "_props")
+
+    def __init__(self, _id: str, **props: Any) -> None:
+        self._id: ResourceLocation = ResourceLocation.from_string(_id)
+        self._props: Properties = Properties(**props)
+
+    def __getitem__(self, name: str) -> Any:
+        try:
+            return self._props[name]
+        except KeyError as exc:
+            raise KeyError(
+                f"{type(self).__name__} '{self}' does not"
+                f" have {name!r} property") from exc
+
+    # def __getattr__(self, name: str) -> Any:
+    #     return self[name]
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._props
+
+    def __len__(self) -> int:
+        return len(self._props)
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, str):
+            other = BlockState.from_string(other)
+        elif not isinstance(other, BlockState):
+            return NotImplemented
+        return (self.id, self._props) == (other.id, other._props)
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, BlockState):
+            return NotImplemented
+        return (self.id, self._props) < (other.id, other._props)
+
+    def __hash__(self) -> int:
+        return hash((self._id, self._props))
+
+    def __str__(self) -> str:
+        props_str = "" if not self._props else str(self._props)
+        return f"{self.id}{props_str}"
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"id: {self._id!r}, props: {self._props!r})")
+
+    @property
+    def id(self) -> str:
+        return str(self._id)
+
+    def props(self) -> Iterator[tuple[str, Any]]:
+        return self._props.items()
+
+    def to_string(self) -> str:
+        return str(self)
+
+    @staticmethod
+    def from_string(string: str) -> BlockState:
+        idx = string.find("[") # basic parsing to separate block:id[name=value]
+        if idx == -1:
+            id, props = string, ""
+        else:
+            id, props = string[:idx], string[idx:]
+
+        state = BlockState(id)
+        state._props = Properties.from_string(props)
+        return state
+
+    def to_nbt(self) -> Compound:
+        nbt = Compound()
+        nbt["Name"] = self._id.to_nbt()
+        if self._props:
+            nbt["Properties"] = self._props.to_nbt()
+        return nbt
+
+    @staticmethod
+    def from_nbt(nbt: Compound) -> BlockState:
+        state = BlockState(str(nbt["Name"]))
+        state._props = Properties.from_nbt(nbt.get("Properties", Compound()))
+        return state
+
+    def with_id(self, id: str) -> BlockState:
+        state = BlockState(id)
+        state._props = deepcopy(self._props)
+        return state
+
+    def with_props(self, **props: Any) -> BlockState:
+        state = BlockState(self.id)
+        new_props = deepcopy(self._props)
+        for name, value in props.items():
+            if value is None:
+                del new_props[name]
+            else:
+                new_props[name] = value
+        state._props = new_props
+        return state
+
+    def without_props(self) -> BlockState:
+        return BlockState(self.id)

pylitematic/geometry.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import nbtlib
+import numpy as np
+
+
+@dataclass(frozen=True)
+class Vec3i:
+    _a: int
+    _b: int
+    _c: int
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_a", self._to_int(self._a))
+        object.__setattr__(self, "_b", self._to_int(self._b))
+        object.__setattr__(self, "_c", self._to_int(self._c))
+
+    def __str__(self) -> str:
+        return str(list(self))
+
+    def __add__(self, other) -> Vec3i:
+        arr = np.array(self)
+        other_arr = self._to_array(other)
+        try:
+            result = arr + other_arr
+        except Exception:
+            return NotImplemented
+        return type(self)(*result.astype(int))
+
+    def __radd__(self, other) -> Vec3i:
+        return self.__add__(other)
+
+    def __sub__(self, other) -> Vec3i:
+        arr = np.array(self)
+        other_arr = self._to_array(other)
+        try:
+            result = arr - other_arr
+        except Exception:
+            return NotImplemented
+        return type(self)(*result.astype(int))
+
+    def __rsub__(self, other) -> Vec3i:
+        arr = np.array(self)
+        try:
+            result = other - arr
+        except Exception:
+            return NotImplemented
+        return type(self)(*result.astype(int))
+
+    def __mul__(self, scalar: int) -> Vec3i:
+        return type(self)(
+            self._a * scalar, self._b * scalar, self._c * scalar)
+
+    def __floordiv__(self, scalar: int) -> Vec3i:
+        return type(self)(
+            self._a // scalar, self._b // scalar, self._c // scalar)
+
+    def __neg__(self) -> Vec3i:
+        return type(self)(-self._a, -self._b, -self._c)
+
+    def __getitem__(self, index: int) -> int:
+        return self.to_tuple()[index]
+
+    def __iter__(self):
+        return iter(self.to_tuple())
+
+    def __abs__(self) -> Vec3i:
+        return type(self)(*np.abs(self))
+
+    def __lt__(self, other):
+        return np.array(self) < self._to_array(other)
+
+    def __le__(self, other):
+        return np.array(self) <= self._to_array(other)
+
+    def __gt__(self, other):
+        return np.array(self) > self._to_array(other)
+
+    def __ge__(self, other):
+        return np.array(self) >= self._to_array(other)
+
+    def __eq__(self, other):
+        return np.array(self) == self._to_array(other)
+
+    def __ne__(self, other):
+        return np.array(self) != self._to_array(other)
+
+    def __array__(self, dtype: type | None = None, copy: bool = True):
+        arr = np.array([self._a, self._b, self._c], dtype=dtype)
+        if copy:
+            return arr.copy()
+        else:
+            return arr
+
+    def _to_array(self, other):
+        if isinstance(other, Vec3i):
+            return np.array(other)
+        else:
+            return other
+
+    @staticmethod
+    def _to_int(value) -> int:
+        if isinstance(value, (int, np.integer)):
+            return int(value)
+        elif isinstance(value, float):
+            if value.is_integer():
+                return int(value)
+        raise TypeError(
+            f"{type(value).__name__} value {value!r} is not"
+            " int, numpy integer, or whole float")
+
+    def to_tuple(self) -> tuple[int, int, int]:
+        return (self._a, self._b, self._c)
+
+    @classmethod
+    def from_tuple(cls, t: tuple[int, int, int]) -> Vec3i:
+        return cls(*t)
+
+    def to_nbt(self) -> nbtlib.Compound:
+        return nbtlib.Compound({
+            "x": nbtlib.Int(self._a),
+            "y": nbtlib.Int(self._b),
+            "z": nbtlib.Int(self._c),
+        })
+
+    @classmethod
+    def from_nbt(cls, nbt: nbtlib.Compound) -> Vec3i:
+        return cls(int(nbt["x"]), int(nbt["y"]), int(nbt["z"]))
+
+
+@dataclass(frozen=True)
+class BlockPosition(Vec3i):
+
+    @property
+    def x(self) -> int:
+        return self._a
+
+    @property
+    def y(self) -> int:
+        return self._b
+
+    @property
+    def z(self) -> int:
+        return self._c
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(x={self.x}, y={self.y}, z={self.z})"
+
+
+@dataclass(frozen=True)
+class Size3D(Vec3i):
+
+    @property
+    def width(self) -> int:
+        return self._a
+
+    @property
+    def height(self) -> int:
+        return self._b
+
+    @property
+    def length(self) -> int:
+        return self._c
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"width={self.width}, height={self.height}, length={self.length})")

pylitematic/region.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from bitpacking import bitpack, bitunpack
+import nbtlib
+import numpy as np
+import twos
+
+from .block_state import BlockState
+from .geometry import BlockPosition, Size3D
+
+
+AIR = BlockState("air")
+
+
+class Region:
+    def __init__(
+        self,
+        size: tuple[int, int, int] | Size3D,
+        origin: tuple[int, int, int] | BlockPosition = (0, 0, 0),
+    ):
+        self._origin: BlockPosition = BlockPosition(*origin)
+        self._size: Size3D = Size3D(*size)
+
+        self._palette: list[BlockState] = [AIR]
+        self._palette_map: dict[BlockState, int] = {AIR: 0} # FIXME
+        self._blocks = np.zeros(abs(self._size))
+        self._entities: list[nbtlib.Compound] = []
+        self._tile_entities: list[nbtlib.Compound] = []
+        self._block_ticks: list[nbtlib.Compound] = []
+        self._fluid_ticks: list[nbtlib.Compound] = []
+
+    def __getitem__(self, key):
+        if isinstance(key, BlockPosition):
+            index = self._blocks[key.x, key.y, key.z]
+            return self._palette[index]
+
+        indices = self._blocks[key]
+        if np.isscalar(indices):
+            return self._palette[indices]
+
+        return np.array(self._palette, dtype=object)[indices]
+
+    def __setitem__(self, key, value) -> None:
+        if isinstance(key, BlockPosition):
+            key = key.to_tuple()
+
+        if isinstance(value, list):
+            value = np.array(value, dtype=object)
+
+        if isinstance(value, BlockState):
+            # assign single BlockState to slice
+            if value not in self._palette_map:
+                self._palette_map[value] = len(self._palette)
+                self._palette.append(value)
+            index = self._palette_map[value]
+            self._blocks[key] = index
+
+        elif isinstance(value, np.ndarray):
+            if value.shape != self._blocks[key].shape:
+                raise ValueError(
+                    "Shape mismatch between assigned array and target slice")
+
+            # look up (or add) indices for all BlockStates
+            unique_states, xdi = np.unique(value, return_inverse=True)
+            idx = []
+            for state in unique_states:
+                if state not in self._palette_map:
+                    self._palette_map[state] = len(self._palette)
+                    self._palette.append(state)
+                idx.append(self._palette_map[state])
+            index_array = np.array(idx, dtype=int)[xdi].reshape(value.shape)
+            self._blocks[key] = index_array
+        else:
+            raise TypeError(
+                "Value must be a BlockState or a list of BlockStates")
+
+    def compact_palette(self) -> None:
+        idx = np.unique(self._blocks)
+        # always include minecraft:air in a palette
+        if 0 not in idx:
+            idx = np.insert(idx, 0, 0)
+        index_map = {old: new for new, old in enumerate(idx)}
+
+        # compacted palette and mapping
+        palette = np.array(self._palette, dtype=object)[idx].tolist()
+        palette_map = {res: idx for idx, res in enumerate(palette)}
+
+        lookup = np.full(max(index_map) + 1, -1, dtype=int)
+        for old, new in index_map.items():
+            lookup[old] = new
+        self._blocks = lookup[self._blocks]
+
+        self._palette = palette
+        self._palette_map = palette_map
+
+    def _bits_per_state(self) -> int:
+        return max(2, (len(self._palette) - 1).bit_length())
+
+    def _decode_block_states(
+        self,
+        data: nbtlib.LongArray,
+    ) -> np.ndarray[int]:
+        states = bitunpack(
+            chunks=[twos.to_unsigned(x, 64) for x in data],
+            field_width=self._bits_per_state(),
+            chunk_width=64,
+        )
+        states = list(states)[:self.volume]
+        shape = (abs(self.height), abs(self.length), abs(self.width))
+        states = np.asarray(states, dtype=int).reshape(shape) # y,z,x
+        return states.transpose(2, 0, 1) # x,y,z
+
+    def _encode_block_states(self) -> nbtlib.LongArray:
+        states = self._blocks.transpose(1, 2, 0).ravel() # x,y,z to y,z,x
+        chunks = bitpack(
+            states.tolist(),
+            field_width=self._bits_per_state(),
+            chunk_width=64,
+        )
+        return nbtlib.LongArray([twos.to_signed(x, 64) for x in chunks])
+
+    @property
+    def size(self) -> Size3D:
+        return self._size
+
+    @property
+    def origin(self) -> BlockPosition:
+        return self._origin
+
+    @property
+    def end(self) -> BlockPosition:
+        return self._origin + np.where(
+            self._size > 0, self._size - 1, self._size + 1)
+
+    @property
+    def width(self) -> int:
+        return self._size.width
+
+    @property
+    def height(self) -> int:
+        return self._size.height
+
+    @property
+    def length(self) -> int:
+        return self._size.length
+
+    @property
+    def volume(self) -> int:
+        return np.prod(self.shape).item()
+
+    @property
+    def blocks(self) -> int: # TODO: rename
+        return np.count_nonzero(self._blocks)
+
+    @property
+    def shape(self) -> tuple[int, int, int]:
+        return self._blocks.shape
+
+    @property
+    def lower(self) -> BlockPosition:
+        return BlockPosition(*np.min((self.origin, self.end), axis=0))
+
+    @property
+    def upper(self) -> BlockPosition:
+        return BlockPosition(*np.max((self.origin, self.end), axis=0))
+
+    @property
+    def bounds(self) -> tuple[BlockPosition, BlockPosition]:
+        return self.lower, self.upper
+
+    # def count(self, block: BlockState, ignore_props: bool = False) -> int:
+    #     ...
+
+    def global_position(self, pos: BlockPosition) -> BlockPosition:
+        return self._origin + pos
+
+    def local_position(self, pos: BlockPosition) -> BlockPosition:
+        return pos - self._origin
+
+    def to_nbt(self) -> nbtlib.Compound:
+        nbt = nbtlib.Compound()
+
+        nbt["Position"] = self._origin.to_nbt()
+        nbt["Size"] = self._size.to_nbt()
+
+        pal = [block.to_nbt() for block in self._palette]
+        nbt["BlockStatePalette"] = nbtlib.List[nbtlib.Compound](pal)
+        nbt["BlockStates"] = self._encode_block_states()
+
+        nbt["Entities"] = self._entities
+        nbt["TileEntities"] = self._tile_entities
+        nbt["PendingBlockTicks"] = self._block_ticks
+        nbt["PendingFluidTicks"] = self._fluid_ticks
+
+        return nbt
+
+    @staticmethod
+    def from_nbt(nbt: nbtlib.Compound) -> Region:
+        pos = BlockPosition.from_nbt(nbt["Position"])
+        size = Size3D.from_nbt(nbt["Size"])
+
+        region = Region(origin=pos, size=size)
+
+        region._palette = [
+            BlockState.from_nbt(block) for block in nbt["BlockStatePalette"]]
+        region._palette_map = {bl: i for i, bl in enumerate(region._palette)}
+        region._blocks = region._decode_block_states(nbt["BlockStates"])
+
+        region._entities = nbt["Entities"]
+        region._tile_entities = nbt["TileEntities"]
+        region._block_ticks = nbt["PendingBlockTicks"]
+        region._fluid_ticks = nbt["PendingFluidTicks"]
+
+        return region

pylitematic/resource_location.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import nbtlib
+import re
+from typing import Any
+
+
+NAMESPACE_REGEX: str = r"[a-z0-9_.-]+"
+NAMESPACE_PATTERN: re.Pattern = re.compile(NAMESPACE_REGEX)
+DEFAULT_NAMESPACE: str = "minecraft"
+
+PATH_REGEX: str = r"[a-z0-9_.-][a-z0-9_./-]*"
+PATH_PATTERN: re.Pattern = re.compile(PATH_REGEX)
+
+LOCATION_PATTERN: re.Pattern = re.compile(
+    rf"(?:(?P<namespace>{NAMESPACE_REGEX})?\:)?(?P<path>{PATH_REGEX})")
+
+@dataclass(frozen=True, order=True)
+class ResourceLocation:
+
+    path: str
+    namespace: str = ""
+
+    def __post_init__(self) -> None:
+        if not PATH_PATTERN.fullmatch(self.path):
+            raise ValueError(f"Invalid resource location path {self.path!r}")
+
+        if not self.namespace:
+            object.__setattr__(self, "namespace", DEFAULT_NAMESPACE)
+        elif not NAMESPACE_PATTERN.fullmatch(self.namespace):
+            raise ValueError(
+                f"Invalid resource location namespace {self.namespace!r}")
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, ResourceLocation):
+            return (self.namespace, self.path) == (other.namespace, other.path)
+        elif isinstance(other, str):
+            try:
+                other = ResourceLocation.from_string(other)
+                return self == other
+            except ValueError:
+                return False
+        else:
+            return NotImplemented
+
+    def __str__(self) -> str:
+        return f"{self.namespace}:{self.path}"
+
+    def to_string(self) -> str:
+        return str(self)
+
+    @staticmethod
+    def from_string(string: str) -> ResourceLocation:
+        match = LOCATION_PATTERN.fullmatch(string)
+        if not match:
+            raise ValueError(f"Invalid resource location string {string!r}")
+
+        namespace = match.group("namespace")
+        path = match.group("path")
+
+        return ResourceLocation(path=path, namespace=namespace)
+
+    def to_nbt(self) -> nbtlib.String:
+        return nbtlib.String(self)
+
+    @staticmethod
+    def from_nbt(nbt: nbtlib.String) -> ResourceLocation:
+        return ResourceLocation.from_string(str(nbt))

pylitematic/schematic.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from datetime import datetime
+import nbtlib
+import numpy as np
+import pathlib
+import time
+import twos
+from typing import Iterator
+
+from .geometry import BlockPosition, Size3D
+from .region import Region
+
+
+DEFAULT_VERSION_MAJOR: int = 7
+DEFAULT_VERSION_MINOR: int = 1
+DEFAULT_MC_VERSION: int = 4325
+
+PREVIEW_CHANNELS: int = 4
+PREVIEW_BIT_DEPTH: int = 8
+
+
+def decode_image_data(data: nbtlib.IntArray) -> np.ndarray[int]:
+    bit_mask = (1 << PREVIEW_BIT_DEPTH) - 1
+
+    data = np.vectorize(twos.to_unsigned)(
+        data.unpack(), PREVIEW_CHANNELS * PREVIEW_BIT_DEPTH)
+    size = int(np.sqrt(len(data))) # TODO: Handle non-squares
+    shape = (size, size, PREVIEW_CHANNELS)
+    pixels = np.zeros(data.shape + (PREVIEW_CHANNELS,), dtype=int)
+    for i in range(PREVIEW_CHANNELS):
+        pixels[..., i] = (data >> (i * PREVIEW_BIT_DEPTH) & bit_mask)
+    pixels = np.asarray(pixels, dtype=np.uint32).reshape(shape)
+    return pixels[:, :, [2, 1, 0, 3]] # BGRA -> RGBA
+
+
+def encode_image_data(img: np.ndarray[int]) -> nbtlib.IntArray:
+    bit_mask = (1 << PREVIEW_BIT_DEPTH) - 1
+
+    # TODO: Handle images w/o alpha channel
+    img = img[:, :, [2, 1, 0, 3]] # RGBA -> BGRA
+    img = img.reshape(-1, PREVIEW_CHANNELS)
+    data = np.zeros(len(img), dtype=int)
+    for i in range(PREVIEW_CHANNELS):
+        data |= ((img[..., i] & bit_mask )<< (i * PREVIEW_BIT_DEPTH))
+    data = np.vectorize(twos.to_signed)(
+        data, PREVIEW_CHANNELS * PREVIEW_BIT_DEPTH)
+    return nbtlib.IntArray(data)
+
+
+class Schematic:
+    def __init__(
+        self,
+        name: str,
+        author: str = "",
+        description: str = "",
+        regions: dict[str, Region] = {},
+        preview: np.ndarray[int] | None = None,
+        version_major: int = DEFAULT_VERSION_MAJOR,
+        version_minor: int | None = DEFAULT_VERSION_MINOR,
+        mc_version: int = DEFAULT_MC_VERSION,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.author = author
+        self._preview = preview
+
+        self._regions: dict[str, Region] = regions
+
+        self._created_at = round(time.time() * 1000)
+        self._modified_at = self._created_at
+
+        self.version_major = version_major
+        self.version_minor = version_minor
+        self.mc_version = mc_version
+
+        self.modified: bool = True
+
+    def __getitem__(self, key):
+        return self._regions[key]
+
+    def __setitem__(self, key, value):
+        if not isinstance(value, Region):
+            raise TypeError(
+                f"Can only add Region objects, got {type(value).__name__}")
+        self._regions[key] = value
+
+    @property
+    def width(self) -> int:
+        return self.size.width
+
+    @property
+    def height(self) -> int:
+        return self.size.height
+
+    @property
+    def length(self) -> int:
+        return self.size.length
+
+    @property
+    def size(self) -> Size3D:
+        lower, upper = self.bounds
+        return Size3D(*abs(upper - lower)) + 1
+
+    @property
+    def bounds(self) -> tuple[BlockPosition, BlockPosition]:
+        lowers = []
+        uppers = []
+        for reg in self._regions.values():
+            lower, upper = reg.bounds
+            lowers.append(lower)
+            uppers.append(upper)
+        return (
+            BlockPosition(*np.min(lowers, axis=0)),
+            BlockPosition(*np.max(uppers, axis=0)),
+        )
+
+    @property
+    def volume(self) -> int:
+        return sum(reg.volume for reg in self._regions.values())
+
+    @property
+    def blocks(self) -> int:
+        return sum(reg.blocks for reg in self._regions.values())
+
+    @property
+    def region_count(self) -> int:
+        return len(self._regions)
+
+    @property
+    def version(self) -> str:
+        if self.version_minor is None:
+            return str(self.version_major)
+        return f"{self.version_major}.{self.version_minor}"
+
+    @property
+    def preview(self) -> np.ndarray[int] | None:
+        return self._preview
+
+    def regions(self) -> Iterator[tuple[str, Region]]:
+        return self._regions.items()
+
+    def add_region(self, name: str, region: Region) -> None:
+        self._regions[name] = region
+        self._update()
+
+    def remove_region(self, name: str) -> Region:
+        return self._regions.pop(name)
+
+    @property
+    def created_at(self) -> datetime:
+        return datetime.fromtimestamp(int(self._created_at / 1000))
+
+    @property
+    def modified_at(self) -> datetime:
+        return datetime.fromtimestamp(int(self._modified_at / 1000))
+
+    def save(self, path: pathlib.Path | str) -> None:
+        file = nbtlib.File(self.to_nbt())
+        file.save(path, gzipped=True, byteorder="big")
+
+    @staticmethod
+    def load(path: pathlib.Path | str) -> Schematic:
+        if isinstance(path, str):
+            path = pathlib.Path(path)
+        nbt = nbtlib.File.load(path.expanduser(), True)
+        return Schematic.from_nbt(nbt)
+
+    def to_nbt(self) -> nbtlib.Compound:
+        # self._update()
+        nbt = nbtlib.Compound()
+
+        # meta data
+        meta = nbtlib.Compound()
+        meta["Name"] = nbtlib.String(self.name)
+        meta["Author"] = nbtlib.String(self.author)
+        meta["Description"] = nbtlib.String(self.description)
+
+        meta["TimeCreated"] = nbtlib.Long(self._created_at)
+        meta["TimeModified"] = nbtlib.Long(self._modified_at)
+
+        meta["RegionCount"] = nbtlib.Int(self.region_count)
+        if self._preview is not None:
+            meta["PreviewImageData"] = encode_image_data(self._preview)
+
+        meta["EnclosingSize"] = self.size.to_nbt()
+        meta["TotalVolume"] = nbtlib.Long(self.volume)
+        meta["TotalBlocks"] = nbtlib.Long(self.blocks)
+        nbt["Metadata"] = meta
+
+        # regions
+        regions = nbtlib.Compound()
+        for name, region in self.regions():
+            region.compact_palette()
+            regions[name] = region.to_nbt()
+        nbt["Regions"] = regions
+
+        # versions
+        nbt["Version"] = nbtlib.Int(self.version_major)
+        if self.version_minor is not None:
+            nbt["SubVersion"] = nbtlib.Int(self.version_minor)
+        nbt["MinecraftDataVersion"] = nbtlib.Int(self.mc_version)
+
+        return nbt
+
+    @staticmethod
+    def from_nbt(nbt: nbtlib.Compound) -> Schematic:
+        # meta data
+        try:
+            meta = nbt["Metadata"]
+        except KeyError as exc:
+            raise KeyError(
+                "Can't load from NBT without 'Metadata' entry") from exc
+
+        name = meta["Name"].unpack()
+        author = meta["Author"].unpack()
+        description = meta["Description"].unpack()
+
+        preview = meta.get("PreviewImageData")
+        if preview is not None:
+            preview = decode_image_data(preview)
+
+        created_at = meta["TimeCreated"].unpack()
+        modified_at = meta["TimeModified"].unpack()
+
+        # regions
+        try:
+            regions = nbt["Regions"]
+        except KeyError as exc:
+            raise KeyError(
+                "Can't load from NBT without 'Regions' entry") from exc
+        regions = {name: Region.from_nbt(nbt) for name, nbt in regions.items()}
+
+        # version(s)
+        try:
+            major = nbt["Version"].unpack()
+        except KeyError as exc:
+            raise KeyError(
+                "Can't load from NBT without 'Version' entry") from exc
+
+        try:
+            minor = nbt["SubVersion"].unpack()
+        except KeyError:
+            minor = None
+
+        mc_version = nbt.get("MinecraftDataVersion")
+
+        schem = Schematic(
+            name=name,
+            author=author,
+            description=description,
+            regions=regions,
+            preview=preview,
+            version_major=major,
+            version_minor=minor,
+            mc_version=mc_version,
+        )
+
+        schem._created_at = created_at
+        schem._modified_at = modified_at
+
+        return schem

pylitematic/test.py

@@ -0,0 +1,23 @@
+import pathlib
+from pylitematic import BlockPosition, BlockState, Schematic
+
+
+path = pathlib.Path("/mnt/d/minecraft/schematics/Litematica/test/subs.litematic")
+path = pathlib.Path("/mnt/d/minecraft/schematics/Litematica/test/creeper_test.litematic")
+path = pathlib.Path("/mnt/d/minecraft/schematics/Litematica/test/regions.litematic")
+stone = BlockState.from_string("minecraft:stone")
+dirt = BlockState.from_string("minecraft:dirt")
+s = Schematic.load(path)
+print(f"{s.volume=} {s.size=} {s.bounds=}")
+for name, reg in s.regions():
+    print(name)
+    print(f"\t{reg.shape=} {reg.volume=} {reg.blocks=}")
+    print(f"\t{reg.origin=!s} {reg.end=!s}")
+    print(f"\t{reg.lower=} {reg.upper=!s} {reg.size=}")
+    # print(f"\t{reg[..., 1, 0]}")
+    # print(f"\t{reg[:][1][0]}")
+    # print(f"\t{reg[BlockPosition(0, 1, 0)]}")
+    reg[1,1,1] = BlockState.from_string("minecraft:stone")
+    reg[0,:,0] = [dirt, stone, dirt]
+    print(f"\t{reg[:]}")
+s.save("/mnt/d/minecraft/schematics/Litematica/test/pylitematic.litematic")

{pylitematic-0.0.0.dist-info → pylitematic-0.0.1.dist-info}/METADATA

@@ -1,18 +1,18 @@
 Metadata-Version: 2.4
 Name: pylitematic
-Version: 0.0.0
+Version: 0.0.1
 Summary: Load, modify, and save Litematica schematics
 Author-email: Boscawinks <bosca.winks@gmx.de>
 License: GPL-3.0-only
-Project-URL: Homepage, https://github.com/nieswand/pylitematic
-Project-URL: Repository, https://github.com/nieswand/pylitematic
-Project-URL: Issues, https://github.com/nieswand/pylitematic/issues
+Project-URL: Homepage, https://github.com/boscawinks/pylitematic
+Project-URL: Repository, https://github.com/boscawinks/pylitematic
+Project-URL: Issues, https://github.com/boscawinks/pylitematic/issues
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.7
+Requires-Python: >=3.10.12
 Description-Content-Type: text/markdown
 Requires-Dist: bitpacking>=0.1.0
-Requires-Dist: nbtlib>=1.6
-Requires-Dist: numpy>=1.21
+Requires-Dist: nbtlib>=2.0.4
+Requires-Dist: numpy>=2.2.6
 
 # pylitematic
 
@@ -25,5 +25,5 @@ Load, modify, and save [Litematica](https://litematica.org/) schematics
 
 `pylitematic` is available on pypi:
 ```bash
-pip install --upgrade pylitematic
+python3 -m pip install --upgrade pylitematic
 ```

pylitematic-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+pylitematic/__init__.py,sha256=xVVYkyJ7nV4I2eZ-XAcDz7yP2wXQHA-DWcMYRy_UUyg,211
+pylitematic/block_property.py,sha256=eV9YbMcuttX-WPdbqN6dMmhb4jK_8_zRv33wNaVd8_o,9887
+pylitematic/block_state.py,sha256=hC8ptOTR6XKokn-m2Nlxpi44AvL-vwlgive3KQ4VtUg,3328
+pylitematic/geometry.py,sha256=J_Hu4umWUKxN6MFrem0f1hxmAEJPJugxJ2v2oXIygVk,4432
+pylitematic/region.py,sha256=86Nr3vPvzEYXLnrPaRHx62DsxJFWNCD9leUHJ6ThPNs,7009
+pylitematic/resource_location.py,sha256=kVv9-4WVu_Ak24Um05bucKG-mcXymnylwHMha-ORLoo,2143
+pylitematic/schematic.py,sha256=HuPxQBmnE_AswncG0LN-lxQYJHADKxEl6JPLYK2MRUY,7867
+pylitematic/test.py,sha256=vJU2d3ncw1EFEWALbUPXzsofk16-zWBDOZuJm6qNS7I,1019
+pylitematic-0.0.1.dist-info/METADATA,sha256=KI4k64vSJ2LaVsK8_P0p0ARDc3b_UAsYM4TKgVP3oVA,948
+pylitematic-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pylitematic-0.0.1.dist-info/top_level.txt,sha256=sYUxm6O7Dh5TzuP-kPFe2FHJWUuwHFO69vN2VBiEG4A,12
+pylitematic-0.0.1.dist-info/RECORD,,

pylitematic-0.0.0.dist-info/RECORD

@@ -1,5 +0,0 @@
-pylitematic/__init__.py,sha256=ShXQBVjyiSOHxoQJS2BvNG395W4KZfqMxZWBAR0MZrE,22
-pylitematic-0.0.0.dist-info/METADATA,sha256=lWoUEdP2KWSKCQMTdYU-bdctHPwuFTAnO43GHQlh_mA,924
-pylitematic-0.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pylitematic-0.0.0.dist-info/top_level.txt,sha256=sYUxm6O7Dh5TzuP-kPFe2FHJWUuwHFO69vN2VBiEG4A,12
-pylitematic-0.0.0.dist-info/RECORD,,