polycubetools 1.1.0__py3-none-any.whl

polycubetools/utils.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import importlib.resources
+import json
+import logging
+from typing import Any, TYPE_CHECKING
+
+from .models import TWENTY_SIX_NEIGHBORHOOD_DIRECTIONS, Polycube, RotatedPolycube, Coordinate
+
+if TYPE_CHECKING:
+    from os import PathLike
+
+_logger = logging.getLogger(__name__)
+
+NO_VOLUME = -1
+MULTIPLE_VOLUME_COMPONENTS = -2
+ERROR_IN_ALGORITHM = -3
+
+__all__ = (
+    "compute_volume",
+    "get_extreme_points",
+    "is_valid_fence",
+    "load_polycubes",
+    "load_pentacubes",
+    "load_hexacubes",
+    "load_heptacubes",
+    "load_octacubes",
+    "PolycubeDecoder",
+    "PolycubeEncoder",
+)
+
+
+def is_valid_fence(coords: set[Coordinate]) -> bool:
+    """Checks if the given set of coordinates form a valid fence in 3D space."""
+    # TODO build a check whether all used polycubes are only used once and are valid to their ID
+    #  (is one of the known rotated polycubes)
+    return compute_volume(coords) > 0
+
+
+def _is_border_coordinate(coord: Coordinate, max_extrem_point: Coordinate, min_extrem_point: Coordinate) -> bool:
+    """Checks if the given coordinate is on the border of the bounding box defined by the max values."""
+    return (
+        coord.x == max_extrem_point.x
+        or coord.x == min_extrem_point.x
+        or coord.y == max_extrem_point.y
+        or coord.y == min_extrem_point.y
+        or coord.z == max_extrem_point.z
+        or coord.z == min_extrem_point.z
+    )
+
+
+def _find_connected_component(visible_coords: set[Coordinate]) -> set[Coordinate]:
+    """Finds all coordinates connected to the first coordinate in the set using 26-neighborhood."""
+    start = visible_coords.pop()
+    stack = [start]
+    component: set[Coordinate] = {start}
+
+    while stack:
+        current = stack.pop()
+
+        for delta in TWENTY_SIX_NEIGHBORHOOD_DIRECTIONS:
+            neighbor = current + delta
+            if neighbor not in visible_coords:
+                continue
+
+            stack.append(neighbor)
+            component.add(neighbor)
+            visible_coords.remove(neighbor)
+
+    return component
+
+
+def get_extreme_points(coords: set[Coordinate]) -> tuple[Coordinate, Coordinate]:
+    initial_coord = coords.pop()
+    x_max, y_max, z_max = initial_coord.x, initial_coord.y, initial_coord.z
+    x_min, y_min, z_min = initial_coord.x, initial_coord.y, initial_coord.z
+    for coord in coords:
+        x_max = max(x_max, coord.x)
+        y_max = max(y_max, coord.y)
+        z_max = max(z_max, coord.z)
+        x_min = min(x_min, coord.x)
+        y_min = min(y_min, coord.y)
+        z_min = min(z_min, coord.z)
+    coords.add(initial_coord)
+
+    return Coordinate(x_max, y_max, z_max), Coordinate(x_min, y_min, z_min)
+
+
+def compute_volume(coords: set[Coordinate]) -> int:
+    """Compute the volume from the hull formed by the coordinates"""
+    max_extreme_point, min_extreme_point = get_extreme_points(coords)
+    max_extreme_point = Coordinate(max_extreme_point.x + 1, max_extreme_point.y + 1, max_extreme_point.z + 1)
+    min_extreme_point = Coordinate(min_extreme_point.x - 1, min_extreme_point.y - 1, min_extreme_point.z - 1)
+
+    visible_coords = {
+        c
+        for x in range(min_extreme_point.x, max_extreme_point.x + 1)
+        for y in range(min_extreme_point.y, max_extreme_point.y + 1)
+        for z in range(min_extreme_point.z, max_extreme_point.z + 1)
+        if (c := Coordinate(x, y, z)) not in coords
+    }
+
+    # the here popped coordinate is always outside the hull; this is because we added this outside new layer!
+    _find_connected_component(visible_coords)
+
+    # we return false because there is no second component, meaning the shape has no volume
+    if not visible_coords:
+        _logger.warning("No volume found! Only one component detected.")
+        return NO_VOLUME
+
+    volume_cubes = _find_connected_component(visible_coords)
+    if visible_coords:
+        _logger.warning(
+            f"Found {len(volume_cubes)} as volume, but still {len(visible_coords)} unvisited cubes left. Exists another enclosed area!"
+        )
+        return MULTIPLE_VOLUME_COMPONENTS
+
+    if any(_is_border_coordinate(c, max_extreme_point, min_extreme_point) for c in volume_cubes):
+        _logger.warning("Volume has been found on the border! Bug in the validation.")
+        return ERROR_IN_ALGORITHM
+
+    return len(volume_cubes)
+
+
+class PolycubeEncoder(json.JSONEncoder):
+    """JSON Encoder for Polycube objects."""
+
+    def default(self, o: Any) -> Any:
+        if isinstance(o, Polycube):
+            return {"id": o.id, "rotations": [self.default(rot) for rot in o.rotations]}
+
+        if isinstance(o, RotatedPolycube):
+            return {"id": o.id, "coords": [self.default(coord) for coord in o.coords]}
+
+        if isinstance(o, Coordinate):
+            return {"x": o.x, "y": o.y, "z": o.z}
+
+        return super().default(o)
+
+
+class PolycubeDecoder(json.JSONDecoder):
+    """JSON Decoder for Polycube objects."""
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        super().__init__(object_hook=self._polycube_object_hook, *args, **kwargs)
+
+    @staticmethod
+    def _polycube_object_hook(obj: Any) -> Any:
+        # Coordinate dict -> Coordinate instance
+        if set(obj.keys()) == {"x", "y", "z"}:
+            return Coordinate(obj["x"], obj["y"], obj["z"])
+
+        # RotatedPolycube dict -> RotatedPolycube instance
+        if "id" in obj and "coords" in obj:
+            # coords expected to be list of Coordinate instances (from inner object_hook)
+            return RotatedPolycube(id=obj["id"], coords=frozenset(obj["coords"]))
+
+        # Polycube dict -> Polycube instance
+        if "id" in obj and "rotations" in obj:
+            # rotations expected to be list of RotatedPolycube instances
+            return Polycube(id=obj["id"], rotations=tuple(obj["rotations"]))
+
+        return obj
+
+
+def load_polycubes(filename: str | PathLike[str]) -> tuple[Polycube, ...]:
+    """Load polycubes from a JSON file."""
+    with open(filename, encoding="UTF-8") as f:
+        js = json.load(f, cls=PolycubeDecoder)
+
+    return tuple(js)
+
+
+def _load_resource(filename: str) -> tuple[Polycube, ...]:
+    """Load a resource file from the package's data directory."""
+    resource_path = importlib.resources.files(__package__) / "data" / filename
+    with importlib.resources.as_file(resource_path) as path:
+        return load_polycubes(path)
+
+
+def load_pentacubes() -> tuple[Polycube, ...]:
+    """Load pentacubes from the default JSON file."""
+    return _load_resource("pentacubes.json")
+
+
+def load_hexacubes() -> tuple[Polycube, ...]:
+    """Load hexacubes from the default JSON file."""
+    return _load_resource("hexacubes.json")
+
+
+def load_heptacubes() -> tuple[Polycube, ...]:
+    """Load heptacubes from the default JSON file."""
+    return _load_resource("heptacubes.json")
+
+
+def load_octacubes() -> tuple[Polycube, ...]:
+    """Load octacubes from the default JSON file."""
+    return _load_resource("octacubes.json")

polycubetools-1.1.0.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: polycubetools
+Version: 1.1.0
+Summary: Basic framework for working with polycubes in a 3-dimensional grid.
+Author: Team Polycube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: coverage[toml]; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# polycube-framework
+
+### Workflows
+
+These are **only** available on github, not locally
+
+1. lint workflow (runs automatically on PR, required for merging in main:
+    - runs pyright with the config in pyproject.toml (pyright strict)
+    - runs `black --check --line-length 120 "./src/polycubetools"`
+2. format workflow (can be run manually)
+    - runs `black --line-length 120 "./src/polycubetools"`
+    - commits and push to the chosen branch
+
+### Recommendations
+
+1. PyCharm IDE
+    - EAP (EARLY ACCESS PRODUCT) version: has pyright and black tools integrated
+    - alternatively: `pip install pyright black`
+
+### Getting started
+
+1. Have a look at pyproject.toml
+2. Configure a virtual environment (use python `>=3.12`)
+3. For quick testing, feel free to create a script in `scripts/`

polycubetools-1.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+polycubetools/__init__.py,sha256=nvdLE5imasBZJQvtr79OrJ7eCPAVSirOWbGIkin96qM,372
+polycubetools/grid.py,sha256=UbUXxQ5opEAPKlPmbv7KIorUnRw41cuK7mkVoLDhqLE,7540
+polycubetools/hull.py,sha256=tM6pipw05fAWJ3N0KXgzCpXnZbQsRljPUXAinNXOd2w,4257
+polycubetools/models.py,sha256=5qi9WWOxYg8666x1LOkfyQoDSLf4Qzs3Z94-8N_zRLU,5128
+polycubetools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+polycubetools/solver.py,sha256=X_6dXQ9WBm4CRHXILvs2whXbxYjW-ZeChBczosKJ7vM,5918
+polycubetools/utils.py,sha256=80gA7bVXO5hxLuHNbsfC_s9Wz7shBubMWyKVm52Taw8,6928
+polycubetools/data/heptacubes.json,sha256=vQ9QA3J5vOtjqw9wFYYDLLhmw7oMmOYzNdmTRiMga20,15393824
+polycubetools/data/hexacubes.json,sha256=klfA_tcan_J0CFsOaQdmZgerbVIWDEN1yjW2tq31kd8,1986336
+polycubetools/data/pentacubes.json,sha256=U3lpdByY9jPlDQRcuOUxS3xQBGpPwh9MNpEeSYTq7KE,259662
+polycubetools-1.1.0.dist-info/licenses/LICENSE,sha256=dhlyH2n5C_8e4NuZqQk-CKpYSg8BaCHKep2mPLBZHiQ,1064
+polycubetools-1.1.0.dist-info/METADATA,sha256=Pwsw00NgRNvTq-YNjAA0KC-HhkmWMG3vQ7NBhb14qtQ,1476
+polycubetools-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+polycubetools-1.1.0.dist-info/top_level.txt,sha256=3pdiwnGYfuq3VSO8Y5L2wJYyU2U87PrfH5BBcBZjeKI,14
+polycubetools-1.1.0.dist-info/RECORD,,

polycubetools-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

polycubetools-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sprylos
+
+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.

polycubetools-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+polycubetools