torch-geopooling 1.2.0__cp312-cp312-manylinux_2_28_aarch64.whl

torch_geopooling/return_types.py

@@ -0,0 +1,29 @@
+# Copyright (C) 2024, Yakau Bubnou
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+from typing import NamedTuple
+
+from torch import Tensor
+
+
+class quad_pool2d(NamedTuple):
+    tiles: Tensor
+    weight: Tensor
+    values: Tensor
+
+
+class adaptive_quad_pool2d(NamedTuple):
+    weight: Tensor
+    values: Tensor

torch_geopooling/tiling.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from collections import deque
+from itertools import product
+from typing import Iterator, NamedTuple, Tuple
+
+from shapely.geometry import Polygon
+
+__all__ = ["Exterior", "ExteriorTuple", "Tile", "regular_tiling"]
+
+
+class Tile(NamedTuple):
+    z: int
+    x: int
+    y: int
+
+    @classmethod
+    def root(cls) -> Tile:
+        return cls(0, 0, 0)
+
+    def child(self, x: int, y: int) -> Tile:
+        return Tile(self.z + 1, self.x * 2 + x, self.y * 2 + y)
+
+    def children(self) -> Iterator[Tile]:
+        for x, y in product(range(2), range(2)):
+            yield self.child(x, y)
+
+
+ExteriorTuple = Tuple[float, float, float, float]
+
+
+class Exterior(NamedTuple):
+    xmin: float
+    ymin: float
+    width: float
+    height: float
+
+    @classmethod
+    def from_tuple(cls, exterior_tuple: ExteriorTuple) -> Exterior:
+        return cls(*exterior_tuple)
+
+    @property
+    def xmax(self) -> float:
+        return self.xmin + self.width
+
+    @property
+    def ymax(self) -> float:
+        return self.ymin + self.height
+
+    def slice(self, tile: Tile) -> Exterior:
+        w = self.width / (1 << tile.z)
+        h = self.height / (1 << tile.z)
+        return Exterior(self.xmin + tile.x * w, self.ymin + tile.y * h, w, h)
+
+    def as_polygon(self) -> Polygon:
+        return Polygon(
+            [
+                (self.xmin, self.ymin),
+                (self.xmax, self.ymin),
+                (self.xmax, self.ymax),
+                (self.xmin, self.ymax),
+            ]
+        )
+
+
+def regular_tiling(
+    polygon: Polygon, exterior: Exterior, z: int, internal: bool = False
+) -> Iterator[Tile]:
+    """Returns a regular quad-tiling (tiles of the same size).
+
+    Method returns all tiles of level (z) that have a common intersection with a specified
+    polygon.
+
+    Args:
+        polygon: A polygon to cover with tiles.
+        exterior: Exterior (bounding box) of the quadtree. For example, for geospatial
+            coordinates, this will be `(-180.0, -90.0, 360.0, 180.0)`.
+        z: Zoom level of the tiles.
+        internal: When `True`, returns internal tiles (nodes) of the quadtree up to a root
+            tile (0,0,0).
+
+    Returns:
+        Iterator of tiles.
+    """
+    queue = deque([Tile.root()])
+
+    while len(queue) > 0:
+        tile = queue.pop()
+
+        tile_poly = exterior.slice(tile).as_polygon()
+        if not tile_poly.intersects(polygon):
+            continue
+
+        if internal or tile.z >= z:
+            yield tile
+        if tile.z < z:
+            queue.extend(tile.children())

torch_geopooling/transforms.py

@@ -0,0 +1,103 @@
+# Copyright (C) 2024, Yakau Bubnou
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from typing import Iterator, Tuple
+
+from torch import Tensor
+
+from torch_geopooling.tiling import Tile
+
+__all__ = ["TileWKT"]
+
+
+class _TileSet(set):
+    def __init__(self, tiles: Tensor) -> None:
+        super().__init__(Tile(*tile.detach().tolist()) for tile in tiles)
+
+    def is_terminal(self, tile: Tile) -> bool:
+        return (
+            (tile.child(0, 0) not in self)
+            and (tile.child(0, 1) not in self)
+            and (tile.child(1, 0) not in self)
+            and (tile.child(1, 1) not in self)
+        )
+
+
+class TileWKT:
+    """Convert a Tile to a WKT polygon given the exterior of the whole geometry.
+
+    Module returns a tile geometry in WKT format, which comprises a polygon.
+
+    Args:
+        exterior: Exterior coordinates in (X, Y, W, H) format. The exterior is used to calculate
+            boundaries of a tile to produce a final WKT.
+        precision: A precision of the resulting geometry, digits after the decimal point.
+        internal: When `True`, output includes internal nodes of the quadtree tiles.
+            Otherwise (default) returns only geometry of terminal nodes.
+    """
+
+    def __init__(
+        self,
+        exterior: Tuple[float, float, float, float],
+        precision: int = 7,
+        internal: bool = False,
+    ) -> None:
+        self.exterior = tuple(map(float, exterior))
+        self.precision = precision
+        self.internal = internal
+
+        self._xmin, self._ymin, self._width, self._height = exterior
+        if self._width <= 0:
+            raise ValueError(f"exterior width should be >0, got {self._width}")
+        if self._height <= 0:
+            raise ValueError(f"exterior height should be >0, got {self._height}")
+
+    def __call__(self, tiles: Tensor) -> Iterator[str]:
+        if len(tiles.size()) != 2:
+            raise ValueError(f"tiles tensor must be a 2D tensor, got {tiles.size()} shape")
+
+        if tiles.size(1) != 3:
+            raise ValueError(
+                f"tiles should be triplets of (z, x, y), got tensor of shape {tiles.size()}"
+            )
+
+        tileset = _TileSet(tiles)
+
+        for tile in tiles:
+            z, x, y = tile.detach().tolist()
+            width = self._width / (1 << z)
+            height = self._height / (1 << z)
+
+            if (not self.internal) and (not tileset.is_terminal(Tile(z, x, y))):
+                continue
+
+            xmin = self._xmin + width * x
+            xmax = round(xmin + width, self.precision)
+            xmin = round(xmin, self.precision)
+
+            ymin = self._ymin + height * y
+            ymax = round(ymin + height, self.precision)
+            ymin = round(ymin, self.precision)
+
+            yield (
+                "POLYGON (("
+                f"{xmin} {ymin}, {xmax} {ymin}, {xmax} {ymax}, {xmin} {ymax}, {xmin} {ymin}"
+                "))"
+            )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(exterior={self.exterior})"

torch_geopooling/transforms_test.py

@@ -0,0 +1,37 @@
+# Copyright (C) 2024, Yakau Bubnou
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import torch
+
+from torch_geopooling.transforms import TileWKT
+
+
+def test_tile_wkt() -> None:
+    tile_wkt4 = TileWKT(exterior=(0.0, 0.0, 10.0, 10.0), internal=False)
+    tile_wkt5 = TileWKT(exterior=(0.0, 0.0, 10.0, 10.0), internal=True)
+
+    tiles = torch.tensor(
+        [
+            [0, 0, 0],
+            [1, 0, 0],
+            [1, 0, 1],
+            [1, 1, 0],
+            [1, 1, 1],
+        ],
+        dtype=torch.int32,
+    )
+
+    assert len(list(tile_wkt4(tiles))) == 4
+    assert len(list(tile_wkt5(tiles))) == 5