tilegrab 1.2.0b1__py3-none-any.whl → 1.2.0b2__py3-none-any.whl

tilegrab/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.2.0b1"
+__version__ = "1.2.0b2"
 # from tilegrab import downloader
 # from tilegrab import sources
 # from tilegrab import mosaic

tilegrab/cli.py

@@ -2,8 +2,9 @@
 import logging
 import argparse
 from pathlib import Path
+from typing import List
 from tilegrab.downloader import Downloader
-from tilegrab.images import TileImageCollection
+from tilegrab.images import TileImageCollection, ExportType
 from tilegrab.logs import setup_logging
 from tilegrab.tiles import TilesByShape, TilesByBBox
 from tilegrab.dataset import GeoDataset
@@ -14,7 +15,8 @@ logger = logging.getLogger(__name__)
 
 def parse_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(
-        prog="tilegrab", description="Download and mosaic map tiles"
+        prog="tilegrab", 
+        description="Download and mosaic map tiles"
     )
 
     # Create a named group for the vector polygon source
@@ -56,13 +58,14 @@ def parse_args() -> argparse.Namespace:
     mosaic_out_group = p.add_argument_group(
         title="Mosaic export formats", description="Formats for the output mosaic image"
     )
-    mosaic_group = mosaic_out_group.add_mutually_exclusive_group(required=True)
+    mosaic_group = mosaic_out_group.add_mutually_exclusive_group(required=False)
     mosaic_group.add_argument("--jpg", action="store_true", help="JPG image; no geo-reference")
     mosaic_group.add_argument("--png", action="store_true", help="PNG image; no geo-reference")
     mosaic_group.add_argument("--tiff", action="store_true", help="GeoTiff image; with geo-reference")
+    mosaic_group.set_defaults(tiff=True)
 
     # other options
-    p.add_argument("--zoom", type=int, required=True, help="Zoom level (integer)")
+    p.add_argument("--zoom", type=int, required=True, help="Zoom level (integer between 1 and 22)")
     p.add_argument(
         "--tiles-out",
         type=Path,
@@ -80,16 +83,31 @@ def parse_args() -> argparse.Namespace:
         help="Only mosaic tiles; do not download",
     )
     p.add_argument(
-        "--no-progress", action="store_false", help="Hide download progress bar"
+        "--group-tiles", type=str, default=None, help="Mosaic tiles but according to given WxH into ./grouped_tiles"
     )
-    p.add_argument("--quiet", action="store_true", help="Hide all prints")
-    p.add_argument("--debug", action="store_true", help="Enable debug logging")
     p.add_argument(
-        "--test",
-        action="store_true",
-        help="Only for testing purposes, not for normal use",
+        "--group-overlap", action="store_true", help="Overlap with the next consecutive tile when grouping"
     )
-
+    p.add_argument(
+        "--tile-limit", type=int, default=250, help="Override maximum tile limit that can download (use with caution)"
+    )
+    p.add_argument(
+        "--workers", type=int, default=None, help="Max number of threads to use when parallel downloading"
+    )
+    p.add_argument(
+        "--parallel",
+        action=argparse.BooleanOptionalAction,
+        default=False, 
+        help="Download tiles sequentially, no parallel downloading"
+    )
+    p.add_argument(
+        "--progress", 
+        action=argparse.BooleanOptionalAction,
+        default=False, 
+        help="Hide tile download progress bar"
+    )
+    p.add_argument("--quiet", action="store_true", help="Hide all prints")
+    p.add_argument("--debug", action="store_true", help="Enable debug logging")
     return p.parse_args()
 
 
@@ -125,9 +143,9 @@ def main():
         )
 
         if args.shape:
-            tiles = TilesByShape(dataset, zoom=args.zoom)
+            tiles = TilesByShape(geo_dataset=dataset, zoom=args.zoom, SAFE_LIMIT=args.tile_limit)
         elif args.bbox:
-            tiles = TilesByBBox(dataset, zoom=args.zoom)
+            tiles = TilesByBBox(geo_dataset=dataset, zoom=args.zoom, SAFE_LIMIT=args.tile_limit)
         else:
             logger.error("No extent selector selected")
             raise SystemExit("No extent selector selected")
@@ -154,18 +172,44 @@ def main():
             logger.error("No tile source selected")
             raise SystemExit("No tile source selected")
 
-        downloader = Downloader(tiles, source, args.tiles_out)
+        downloader = Downloader(
+            tile_collection=tiles, 
+            tile_source=source, 
+            temp_tile_dir=args.tiles_out)
+        
         result: TileImageCollection
-
         if args.mosaic_only:
-            result = TileImageCollection(args.tiles_out)
-            result.load(tiles)
+            result = TileImageCollection(path=args.tiles_out)
+            result.load(tile_collection=tiles)
         else:
-            result = downloader.run(show_progress=args.no_progress)
+            result = downloader.run(
+                workers=args.workers, 
+                show_progress=args.no_progress, 
+                parallel_download=args.no_parallel)
             logger.info(f"Download result: {result}")
 
+        ex_types: List[int] = []
+        
         if not args.download_only:
-            result.mosaic(tiff=args.tiff, png=args.png)
+            if args.tiff: 
+                ex_types.append(ExportType.TIFF)
+            if args.png: 
+                ex_types.append(ExportType.PNG)
+            if args.jpg: 
+                ex_types.append(ExportType.JPG)
+
+            if args.group_tiles:
+                w,h = args.group_tiles.lower().split("x")
+                result.group(
+                    width=int(w), 
+                    height=int(h),
+                    export_types=ex_types,
+                    overlap=args.group_overlap)
+            else:
+                result.mosaic(export_types=ex_types)
+            
+            
+
         logger.info("Done")
 
     except Exception as e:

tilegrab/dataset.py

@@ -1,15 +1,17 @@
+from dataclasses import dataclass
 import logging
 from pathlib import Path
 from box import Box
 from typing import Union
-
+from functools import cache
 
 logger = logging.getLogger(__name__)
 
 TILE_EPSG = 4326 #Web Mercator - 3857 | 4326 - WGS84
-class GeoDataset:
 
+class GeoDataset:
     @property
+    @cache
     def bbox(self):
         minx, miny, maxx, maxy = self.source.total_bounds
         bbox_dict = Box({"minx": minx, "miny": miny, "maxx": maxx, "maxy": maxy})
@@ -22,14 +24,14 @@ class GeoDataset:
     
     @property
     def x_extent(self):
-        minx, maxx = self.source.total_bounds
+        minx, _, maxx, _ = self.source.total_bounds
         extent = (maxx - minx) + 1
         logger.debug(f"X extent calculated: {extent}")
         return extent
 
     @property
     def y_extent(self):
-        miny, maxy = self.source.total_bounds
+        _, miny, _, maxy = self.source.total_bounds
         extent = (maxy - miny) + 1
         logger.debug(f"Y extent calculated: {extent}")
         return extent

tilegrab/downloader.py

@@ -1,24 +1,20 @@
 import logging
 import os
-from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass
 from typing import List, Optional, Union
 import requests
-from requests.adapters import HTTPAdapter, Retry
-from tqdm import tqdm
-import tempfile
 from pathlib import Path
 
 from tilegrab.sources import TileSource
 from tilegrab.tiles import TileCollection, Tile
 from tilegrab.images import TileImageCollection, TileImage
-from PIL import Image
+
 
 logger = logging.getLogger(__name__)
 
 @dataclass
 class Downloader:
-    tiles: TileCollection
+    tile_collection: TileCollection
     tile_source: TileSource
     temp_tile_dir: Optional[Union[str, Path]] = None
     session: Optional[requests.Session] = None
@@ -29,6 +25,7 @@ class Downloader:
 
     def __post_init__(self):
         if not self.temp_tile_dir:
+            import tempfile
             tmpdir = tempfile.mkdtemp()
             self.temp_tile_dir = Path(tmpdir)
             logger.debug(f"Created temporary directory: {tmpdir}")
@@ -41,6 +38,8 @@ class Downloader:
         logger.info(f"Downloader initialized: source={self.tile_source.name}, timeout={self.REQUEST_TIMEOUT}s, max_retries={self.MAX_RETRIES}")
 
     def _init_session(self) -> requests.Session:
+        from requests.adapters import HTTPAdapter, Retry
+
         logger.debug("Initializing HTTP session with retry strategy")
         session = requests.Session()
         retries = Retry(
@@ -90,36 +89,41 @@ class Downloader:
 
     def run(
         self,
-        workers: int = 8,   
+        workers: Union[int, None] = None,   
         show_progress: bool = True,
+        parallel_download: bool = True
     ) -> TileImageCollection:
-        logger.info(f"Starting download run: {len(self.tiles)} tiles, workers={workers}, show_progress={show_progress}")
+        logger.info(f"Starting download run: {len(self.tile_collection)} tiles, workers={workers}, show_progress={show_progress}")
         
         results = []
 
         if show_progress:
-            pbar = tqdm(total=len(self.tiles), desc=f"Downloading", unit="tile")
+            from tqdm import tqdm
+            pbar = tqdm(total=len(self.tile_collection), desc=f"      Downloading", unit="tile")
         else:
             pbar = None
         
-        for tile in self.tiles.to_list:
-            res = self.download_tile(tile)
-            results.append(res)
-            if pbar:
-                pbar.update(1)
-        
-        # with ThreadPoolExecutor(max_workers=workers) as exe:
-        #     future_to_tile = {
-        #         exe.submit(self.download_tile, tile): tile for tile in self.tiles.to_list
-        #     }
-        #     for fut in as_completed(future_to_tile):
-        #         try:
-        #             results.append(fut.result())
-        #         except Exception:
-        #             results.append(False)
-
-        #         if pbar:
-        #             pbar.update(1)
+
+        if parallel_download:
+            from concurrent.futures import ThreadPoolExecutor, as_completed
+            with ThreadPoolExecutor(max_workers=workers) as exe:
+                future_to_tile = {
+                    exe.submit(self.download_tile, tile): tile for tile in self.tile_collection.to_list
+                }
+                for fut in as_completed(future_to_tile):
+                    try:
+                        results.append(fut.result())
+                    except Exception:
+                        results.append(False)
+                        
+                    if pbar:
+                        pbar.update(1)
+        else:
+            for tile in self.tile_collection.to_list:
+                res = self.download_tile(tile)
+                results.append(res)
+                if pbar:
+                    pbar.update(1)
 
         if pbar:
             pbar.close()
@@ -129,7 +133,7 @@ class Downloader:
 
     def _evaluate_result(self, result: List):
         success = sum(1 for v in result if v)
-        total = len(self.tiles)
+        total = len(self.tile_collection)
         logger.info(f"Download completed: {success}/{total} successful ({100*success/total:.1f}%)")
         if success < total:
             logger.warning(f"Failed to download {total - success} tiles")

tilegrab/images.py

@@ -1,35 +1,44 @@
+from collections import defaultdict
+from functools import cache
 import logging
 from dataclasses import dataclass
-from io import BytesIO
 from pathlib import Path, PosixPath, WindowsPath
-import re
 from typing import Any, List, Union
-from PIL import Image as PLIImage
+from PIL import Image as PILImage
 from box import Box
 from tilegrab.tiles import Tile, TileCollection
 import os
+import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
 
 logger = logging.getLogger(__name__)
 
+
 class ExportType:
     PNG: int = 1
     JPG: int = 2
     TIFF: int = 3
 
+
 @dataclass
 class TileImage:
     width: int = 256
     height: int = 256
 
     def __init__(self, tile: Tile, image: Union[bytes, bytearray]) -> None:
+        from io import BytesIO
+
         self._tile = tile
         try:
-            self._img = PLIImage.open(BytesIO(image))
+            self._img = PILImage.open(BytesIO(image))
             logger.debug(f"TileImage created for z={tile.z},x={tile.x},y={tile.y}")
         except Exception as e:
-            logger.error(f"Failed to open image for tile z={tile.z},x={tile.x},y={tile.y}", exc_info=True)
+            logger.error(
+                f"Failed to open image for tile z={tile.z},x={tile.x},y={tile.y}",
+                exc_info=True,
+            )
             raise
-        
+
         self._path: Union[Path, None] = None
         self._ext: str = self._get_image_type(image)
 
@@ -40,23 +49,23 @@ class TileImage:
         b = bytes(data)
 
         # PNG: 8 bytes
-        if b.startswith(b'\x89PNG\r\n\x1a\n'):
+        if b.startswith(b"\x89PNG\r\n\x1a\n"):
             logger.debug(f"Image detected as PNG")
-            return 'png'
+            return "png"
 
         # JPEG / JPG: files start with FF D8 and end with FF D9
-        if len(b) >= 2 and b[0:2] == b'\xff\xd8':
+        if len(b) >= 2 and b[0:2] == b"\xff\xd8":
             logger.debug(f"Image detected as JPG")
-            return 'jpg'
+            return "jpg"
 
         # BMP: starts with 'BM' (0x42 0x4D)
-        if len(b) >= 2 and b[0:2] == b'BM':
+        if len(b) >= 2 and b[0:2] == b"BM":
             logger.debug(f"Image detected as BMP")
-            return 'bmp'
+            return "bmp"
 
         logger.warning(f"Unknown image format, defaulting to PNG")
         return "png"
-    
+
     def save(self):
         try:
             self._img.save(self.path)
@@ -68,16 +77,16 @@ class TileImage:
     @property
     def name(self) -> str:
         return f"{self._tile.z}_{self._tile.x}_{self._tile.y}.{self._ext}"
-    
+
     @property
     def tile(self) -> Tile:
         return self._tile
-    
+
     @property
-    def image(self) -> PLIImage.Image:
+    def image(self) -> PILImage.Image:
         self._img.load()
         return self._img
-    
+
     @property
     def path(self) -> Path:
         if self._path is None:
@@ -132,30 +141,69 @@ class TileImage:
     def url(self) -> Union[str, None]:
         return self._tile.url
 
+
 WEB_MERCATOR_EXTENT = 20037508.342789244
 EPSG = 3857
+
+
 class TileImageCollection:
     images: List[TileImage] = []
     width: int = 0
     height: int = 0
 
+    def __init__(self, path: Union[Path, str]) -> None:
+        self.path = Path(path)
+        logger.info(f"TileImageCollection initialized at {self.path}")
+
+    def __len__(self):
+        return sum(1 for _ in self)
+
+    def __iter__(self):
+        for i in self.images:
+            yield i
+
+    def __repr__(self) -> str:
+        return f"ImageCollection; len={len(self)}"
+
+    def _update_collection_dim(self):
+        if not self.images:
+            logger.warning("Attempting to update collection dimensions with no images")
+            return
+
+        x = [img.tile.x for img in self.images]
+        y = [img.tile.y for img in self.images]
+        minx, maxx = min(x), max(x)
+        miny, maxy = min(y), max(y)
+        self.minx, self.maxx = minx, maxx
+        self.miny, self.maxy = miny, maxy
+        logger.debug(f"Tile range x=({self.minx}, {self.maxx}); y=({self.miny}, {self.maxy})")
+
+        self.width = int((maxx - minx + 1) * self.images[0].width)
+        self.height = int((maxy - miny + 1) * self.images[0].height)
+       
+        
+        logger.info(f"Collection dimensions calculated: {self.width}x{self.height}")
+
     def mosaic_bounds(self, x_min, y_min, x_max, y_max, z):
-        n = 2 ** z
+        n = 2**z
         tile_size_m = 2 * WEB_MERCATOR_EXTENT / n
 
-        xmin = (WEB_MERCATOR_EXTENT*-1) + x_min * tile_size_m
-        xmax = (WEB_MERCATOR_EXTENT*-1) + (x_max + 1) * tile_size_m
+        xmin = (WEB_MERCATOR_EXTENT * -1) + x_min * tile_size_m
+        xmax = (WEB_MERCATOR_EXTENT * -1) + (x_max + 1) * tile_size_m
 
         ymax = WEB_MERCATOR_EXTENT - y_min * tile_size_m
         ymin = WEB_MERCATOR_EXTENT - (y_max + 1) * tile_size_m
 
         return xmin, ymin, xmax, ymax
 
-    def load(self, tile_collection:TileCollection):
+    def load(self, tile_collection: TileCollection):
+        import re
+
         logger.info("Start loading saved ImageTiles")
-        pat = re.compile(r'^([0-9]+)_([0-9]+)_([0-9]+)\.[A-Za-z0-9]+$')
+        pat = re.compile(r"^([0-9]+)_([0-9]+)_([0-9]+)\.[A-Za-z0-9]+$")
         image_col = [p for p in self.path.glob(f"*.*") if p.is_file()]
         self.zoom = tile_collection.to_list[0].z
+        logger.info(f"Found {len(image_col)} images at {self.path}")
 
         for tile in tile_collection.to_list:
             found_matching_image = False
@@ -168,15 +216,20 @@ class TileImageCollection:
 
                     if tile.x == x and tile.y == y and tile.z == z:
                         logger.debug(f"Processing ImageTile x={x} y={y} z={z}")
-                        with open(image_path, 'rb') as f:
+                        with open(image_path, "rb") as f:
                             tile_image = TileImage(tile, f.read())
                             tile_image.path = image_path
                             self.images.append(tile_image)
                             found_matching_image = True
                             continue
 
-            if not found_matching_image: logger.warning(f"Missing ImageTile x={tile.x} y={tile.y} z={tile.z}")
+            if not found_matching_image:
+                logger.warning(f"Missing ImageTile x={tile.x} y={tile.y} z={tile.z}")
         
+        logger.info(f"{len(self.images)} images loaded, {len(image_col) - len(self.images)} skipped")
+
+        self._update_collection_dim()
+
     def append(self, img: TileImage):
         img.path = os.path.join(self.path, img.name)
         self.images.append(img)
@@ -185,57 +238,34 @@ class TileImageCollection:
 
         self.zoom = img.tile.z
 
-    def __init__(self, path: Union[Path, str]) -> None:
-        self.path = Path(path)
-        logger.info(f"TileImageCollection initialized at {self.path}")
-
-    def __len__(self):
-        return sum(1 for _ in self)
-
-    def __iter__(self):
-        for i in self.images:
-            yield i
-
-    def __repr__(self) -> str:
-        return f"ImageCollection; len={len(self)}"
-
-    def _update_collection_dim(self):
-        if not self.images:
-            logger.warning("Attempting to update collection dimensions with no images")
-            return
-        
-        x = [img.tile.x for img in self.images]
-        y = [img.tile.y for img in self.images]
-        minx, maxx = min(x), max(x)
-        miny, maxy = min(y), max(y)
-
-        self.width = int((maxx - minx + 1) * self.images[0].width)
-        self.height = int((maxy - miny + 1) * self.images[0].height)
-        self.minx, self.maxx = minx, maxx
-        self.miny, self.maxy = miny, maxy
-
-        logger.info(f"Collection dimensions calculated: {self.width}x{self.height}")
-
-    def mosaic(self, tiff:bool=True, png:bool=False):
-        logger.info("Starting mosaic creation")
+    @cache
+    def _create_mosaic(self) -> PILImage.Image:
+        logger.info("Start mosaicing TileImageCollection")
         self._update_collection_dim()
-    
-        logger.info(f"Mosaicking {len(self.images)} images into {self.width}x{self.height}")
-        merged_image = PLIImage.new("RGB", (self.width, self.height))
+
+        logger.info(
+            f"Mosaicking {len(self.images)} images into {self.width}x{self.height}"
+        )
+        merged_image = PILImage.new("RGB", (self.width, self.height))
 
         for image in self.images:
             px = int((image.position.x) * image.width)
             py = int((image.position.y) * image.height)
             logger.debug(f"Pasting image at position ({px}, {py}): {image.name}")
             merged_image.paste(image.image, (px, py))
+        
+        return merged_image
 
+    def mosaic(self, export_types: List[int]):
+        
+        merged_image = self._create_mosaic()
         # TODO: fix this monkey patch
-        if tiff:
+        if ExportType.TIFF in export_types:
             output_path = "mosaic.tiff"
             import numpy as np
             from rasterio.transform import from_bounds
             import rasterio
-            
+
             data = np.array(merged_image)
             data = data.transpose(2, 0, 1)
 
@@ -244,10 +274,7 @@ class TileImageCollection:
                 self.minx, self.miny, self.maxx, self.maxy, self.images[0].tile.z
             )
 
-            transform = from_bounds(
-                xmin, ymin, xmax, ymax,
-                width_px, height_px
-            )
+            transform = from_bounds(xmin, ymin, xmax, ymax, width_px, height_px)
 
             with rasterio.open(
                 output_path,
@@ -263,11 +290,51 @@ class TileImageCollection:
                 dst.write(data)
 
             logger.info(f"Mosaic saved to {output_path}")
-        if png:
+        if ExportType.PNG in export_types:
             output_path = "mosaic.png"
             merged_image.save(output_path)
             logger.info(f"Mosaic saved to {output_path}")
+        if ExportType.JPG in export_types:
+            output_path = "mosaic.jpg"
+            merged_image.save(output_path)
+            logger.info(f"Mosaic saved to {output_path}")
+
+    def group(self, width: int, height: int, export_types:List[int], overlap: bool):
+        if width <= 0 or height <= 0:
+            raise ValueError("width and height must be positive integers")
+        
+        out_dir = "grouped_tiles"
+        os.makedirs(out_dir, exist_ok=True)
+        logger.info(f"Start grouping {len(self.images)} TileImages into {width}x{height} groups")
+
+        merged_image= self._create_mosaic()
+        merged_image_arr = np.asanyarray(merged_image)
+
+        image_px_width = 256
+        image_px_height = 256
+        kh, kw = image_px_height*height, image_px_width*width
+        view = sliding_window_view(merged_image_arr, (kh, kw, merged_image_arr.shape[2]))
+        
+        view = view[..., 0, :, :, :]
+        OH, OW = view.shape[:2]
+        logger.info(f"Saving groups into ./{out_dir}")
+        for i in range(0, OH, height*image_px_height):
+            for j in range(0, OW, width*image_px_width):
+                patch = view[i, j]
+                if not (patch == 0).all():
+                    img = PILImage.fromarray(patch)
+                    if ExportType.PNG in export_types:
+                        logger.debug(f"Saving group {i}{j} as {i}{j}.png")
+                        img.save(os.path.join(out_dir, f"{i}{j}.png"))
+                    if ExportType.JPG in export_types:
+                        logger.debug(f"Saving group {i}{j} as {i}{j}.jpg")
+                        img.save(os.path.join(out_dir, f"{i}{j}.jpg"))
+                    if ExportType.TIFF in export_types:
+                        logger.error(f"TIFF exports for tile groups not implemented yet")
+                        raise NotImplementedError
+                else:
+                    logger.debug(f"Skip no-data group {i}{j}")
 
     def export_collection(self, type: ExportType):
         logger.info(f"Exporting collection as type {type}")
-        pass
+        raise NotImplementedError

tilegrab/sources.py

@@ -4,8 +4,10 @@ from typing import Dict, Optional
 logger = logging.getLogger(__name__)
 
 class TileSource:
-    URL_TEMPLATE = ""
-    name = None
+    url_template: str
+    name: str
+    description: str
+    output_dir: str
 
     def __init__(
         self, 
@@ -17,7 +19,7 @@ class TileSource:
         logger.debug(f"Initializing TileSource: {self.name}, has_api_key={api_key is not None}")
 
     def get_url(self, z: int, x: int, y: int) -> str:
-        url = self.URL_TEMPLATE.format(x=x, y=y, z=z)
+        url = self.url_template.format(x=x, y=y, z=z)
         logger.debug(f"Generated URL for {self.name}: z={z}, x={x}, y={y}")
         return url
 
@@ -33,30 +35,34 @@ class TileSource:
 
 
 class GoogleSat(TileSource):
+    output_dir = "ggl_sat"
     name = "GoogleSat"
     description = "Google satellite imageries"
-    URL_TEMPLATE = "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}"
+    url_template = "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}"
     
 
 class OSM(TileSource):
+    output_dir = "osm"
     name = "OSM"
     description = "OpenStreetMap imageries"
-    URL_TEMPLATE = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
+    url_template = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
 
 class ESRIWorldImagery(TileSource):
+    output_dir = "esri_world"
     name = "ESRIWorldImagery"
     description = "ESRI satellite imageries"
-    URL_TEMPLATE = "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"
+    url_template = "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"
 
 class Nearmap(TileSource):
+    output_dir = "nearmap_sat"
     name = "NearmapSat"
     description = "Nearmap satellite imageries"
-    URL_TEMPLATE = "https://api.nearmap.com/tiles/v3/Vert/{z}/{x}/{y}.png?apikey={token}"
+    url_template = "https://api.nearmap.com/tiles/v3/Vert/{z}/{x}/{y}.png?apikey={token}"
 
     def get_url(self, z: int, x: int, y: int) -> str:
         if not self.api_key:
             logger.error("Nearmap API key is required but not provided")
             raise AssertionError("API key required for Nearmap")
-        url = self.URL_TEMPLATE.format(x=x, y=y, z=z, token=self.api_key)
+        url = self.url_template.format(x=x, y=y, z=z, token=self.api_key)
         logger.debug(f"Generated Nearmap URL: z={z}, x={x}, y={y}")
         return url

tilegrab/tiles.py

@@ -1,13 +1,11 @@
 import logging
 import math
-from typing import Any, Dict, Generator, Iterator, List, Tuple
+from typing import Iterator, List, Tuple, Union
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import Union
 from .dataset import GeoDataset
 from box import Box
-from shapely.geometry import box
-from shapely import intersects
+from functools import cache
 
 logger = logging.getLogger(__name__)
 
@@ -23,7 +21,7 @@ class Tile:
 
     def __post_init__(self):
         self._position = None
-        logger.debug(f"Tile created: z={self.z}, x={self.x}, y={self.y}")
+        logger.debug(f"Tile created: x={self.x}, y={self.y}, z={self.z}")
 
     # @classmethod
     # def from_tuple(cls, t: tuple[int, int, int]) -> "Tile":
@@ -73,17 +71,21 @@ class TileCollection(ABC):
         for t in self._cache:
             yield t
 
-    def __init__(self, feature: GeoDataset, zoom: int, SAFE_LIMIT: int = 250):
+    def __init__(self, 
+        geo_dataset: GeoDataset, 
+        zoom: int, 
+        SAFE_LIMIT: int = 250
+    ):
         self.zoom = zoom
         self.SAFE_LIMIT = SAFE_LIMIT
-        self.feature = feature
+        self.geo_dataset = geo_dataset
 
         logger.info(
             f"Initializing TileCollection: zoom={zoom}, safe_limit={SAFE_LIMIT}"
         )
 
-        assert feature.bbox.minx < feature.bbox.maxx
-        assert feature.bbox.miny < feature.bbox.maxy
+        assert geo_dataset.bbox.minx < geo_dataset.bbox.maxx
+        assert geo_dataset.bbox.miny < geo_dataset.bbox.maxy
 
         self._build_tile_cache()
 
@@ -96,7 +98,7 @@ class TileCollection(ABC):
         logger.info(f"TileCollection initialized with {len(self)} tiles")
 
     def __repr__(self) -> str:
-        return f"TileCollection; len={len(self)}; x-extent=({self.feature.bbox.minx}-{self.feature.bbox.maxx}); y-extent=({self.feature.bbox.miny}-{self.feature.bbox.maxy})"
+        return f"TileCollection; len={len(self)}; x-extent=({self.geo_dataset.bbox.minx}-{self.geo_dataset.bbox.maxx}); y-extent=({self.geo_dataset.bbox.miny}-{self.geo_dataset.bbox.maxy})"
 
     def tile_bounds(self, tile: Union[Tile, Box]) -> Tuple[float, float, float, float]:
         x, y, z = tile.x, tile.y, tile.z
@@ -114,6 +116,7 @@ class TileCollection(ABC):
         return lon_min, lat_min, lon_max, lat_max
 
     @property
+    @cache
     def to_list(self) -> List[Tile]:
         cache = list(self._cache)
         if cache is None or len(cache) < 1:
@@ -162,7 +165,7 @@ class TileCollection(ABC):
 
     def _tiles_in_bounds(self, clip_to_shape=False) -> Iterator[Tile]:
         
-        bbox = self.feature.bbox
+        bbox = self.geo_dataset.bbox
 
         def tile(lng, lat, zoom):
             logger.debug(f"Creating new Tile; lat={lat}; lng={lng}")
@@ -221,8 +224,9 @@ class TileCollection(ABC):
         for i in range(ul_tile.x, lr_tile.x + 1):
             for j in range(ul_tile.y, lr_tile.y + 1):
                 if clip_to_shape:
+                    from shapely.geometry import box
                     tb = box(*self.tile_bbox(i,j,self.zoom))
-                    if not tb.intersects(self.feature.shape.geometry).any():
+                    if not tb.intersects(self.geo_dataset.shape.geometry).any():
                         logger.debug(f"Tile excluded: z={self.zoom}, x={i}, y={j}")
                         continue
                 self._tile_count += 1
@@ -235,7 +239,7 @@ class TilesByBBox(TileCollection):
 
     def _build_tile_cache(self) -> List[Tile]:
         logger.info(f"Building tiles by bounding box at zoom level {self.zoom}")
-        bbox = self.feature.bbox
+        bbox = self.geo_dataset.bbox
         logger.debug(
             f"BBox coordinates: minx={bbox.minx}, miny={bbox.miny}, maxx={bbox.maxx}, maxy={bbox.maxy}"
         )
@@ -251,7 +255,7 @@ class TilesByShape(TileCollection):
 
         logger.info(f"Building tiles by shape intersection at zoom level {self.zoom}")
         
-        bbox = self.feature.bbox
+        bbox = self.geo_dataset.bbox
         logger.debug(
             f"Checking tiles within bbox: minx={bbox.minx}, miny={bbox.miny}, maxx={bbox.maxx}, maxy={bbox.maxy}"
         )

{tilegrab-1.2.0b1.dist-info → tilegrab-1.2.0b2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilegrab
-Version: 1.2.0b1
+Version: 1.2.0b2
 Summary: Fast geospatial map tile downloader and mosaicker
 Author: Thiwanka Munasinghe
 License-Expression: MIT
@@ -32,13 +32,13 @@ Dynamic: license-file
 
 <div align="center">
     <h1 align="center">TileGrab 🧩</h1>
-    <!-- until publish on PyPi -->
-    <img alt="TileGrab" src="https://img.shields.io/badge/testpypi-1.0.0-blue">
-    <!-- <img alt="TileGrab" src="https://img.shields.io/pypi/v/tilegrab.svg"> -->
-    <img alt="TileGrab - Python Versions" src="https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11|%203.12|%203.13-blue">
-    <!-- <img alt="TileGrab - Python Versions" src="https://img.shields.io/pypi/pyversions/tilegrab.svg"> -->
-    <!--  -->
-    <img alt="Test Status" src="https://img.shields.io/github/actions/workflow/status/thiwaK/tilegrab/test.yml?branch=main&event=push&style=flat&label=test">
+    <img alt="TileGrab" src="https://img.shields.io/pypi/v/tilegrab.svg">
+    <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/tilegrab.svg">
+    <img alt="PyPI - Wheel" src="https://img.shields.io/pypi/wheel/tilegrab">
+    <img alt="Test Status" src="https://img.shields.io/github/actions/workflow/status/thiwaK/tilegrab/test.yml?branch=main&event=push&style=flat&label=CI">
+    <img alt="PyPI - Implementation" src="https://img.shields.io/pypi/implementation/tilegrab">
+    <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/thiwaK/tilegrab">
+    <img alt="GitHub License" src="https://img.shields.io/github/license/thiwaK/tilegrab">
     <br/>
     <br/>
 </div>
@@ -47,7 +47,7 @@ Dynamic: license-file
 **Fast, scriptable map tile downloader and mosaicker for geospatial workflows.**
 
 
-`tilegrab` downloads raster map tiles from common providers (OSM, Google Satellite, ESRI World Imagery) using a **vector extent** (polygon or bounding box), then optionally mosaics them into a single raster. Built for automation, reproducibility, and real GIS work — not GUI clicking.
+`tilegrab` downloads raster map tiles from common providers (OSM, Google Satellite, ESRI World Imagery) using a **vector extent** (polygon shape or bounding box), then optionally mosaics them into a single or multiple rasters.
 
 ---
 
@@ -62,20 +62,19 @@ Dynamic: license-file
 
 ## Why tilegrab?
 
-Most tile downloaders fall into one of two traps:
+Most tile downloaders have two major drawbacks:
 - GUI tools that don’t scale or automate
 - Scripts that only support bounding boxes and break on real geometries
 
 `tilegrab` is different:
 
-- Uses **actual vector geometries**, not just extents  
+- Uses **actual vector geometries**, not only just extents 
+- Scalable API
 - Clean CLI, easy to script and integrate  
 - Works with **Shapefiles, GeoPackages, GeoJSON**  
-- Supports **download-only**, **mosaic-only**, or full pipelines  
+- Supports **download-only**, **mosaic-only** or full pipelines  
 - Designed for **GIS, remote sensing, and map production workflows**
 
-No magic. No black boxes.
-
 ---
 
 ## Features
@@ -86,8 +85,9 @@ No magic. No black boxes.
 - Multiple tile providers  
   - OpenStreetMap  
   - Google Satellite  
-  - ESRI World Imagery  
-- Automatic tile mosaicking  
+  - ESRI World Imagery
+  - or Custom providers
+- Tile mosaicking 
 - Progress reporting (optional)  
 - API-key support where required  
 - Sensible defaults, strict CLI validation  
@@ -98,12 +98,15 @@ No magic. No black boxes.
 
 ### From TestPyPI
 
+#### Stable version
 ```bash
-  pip install -i https://test.pypi.org/simple/tilegrab
+  pip install -i tilegrab
 ````
 
-> [!NOTE]
-> A stable PyPI release will follow once the API is finalized.
+#### Beta version
+```bash
+  pip install tilegrab==1.2.0b2
+````
 
 ---
 
@@ -134,76 +137,55 @@ tilegrab \
 ## CLI Usage
 
 ```bash
-usage: tilegrab [-h] --source SOURCE (--shape | --bbox) (--osm | --google_sat | --esri_sat | --key KEY) --zoom ZOOM [--out OUT] [--download-only] [--mosaic-only] [--no-progress] [--quiet]
+usage: tilegrab [-h] --source SOURCE (--shape | --bbox) (--osm | --google_sat | --esri_sat | --key KEY) (--jpg | --png | --tiff) --zoom ZOOM [--tiles-out TILES_OUT] [--download-only] [--mosaic-only]
+                [--group-tiles GROUP_TILES] [--group-overlap] [--tile-limit TILE_LIMIT] [--workers WORKERS] [--no-parallel] [--no-progress] [--quiet] [--debug]
 
 Download and mosaic map tiles
 
 options:
-  -h, --help       show this help message and exit
-  --zoom ZOOM      Zoom level (integer)
-  --out OUT        Output directory (default: ./saved_tiles)
-  --download-only  Only download tiles; do not run mosaicking or postprocessing
-  --mosaic-only    Only mosaic tiles; do not download
-  --no-progress    Hide download progress bar
-  --quiet          Hide all prints
+  -h, --help            show this help message and exit
+  --zoom ZOOM           Zoom level (integer between 1 and 22)
+  --tiles-out TILES_OUT
+                        Output directory for downloaded tiles (default: ./saved_tiles)
+  --download-only       Only download tiles; do not run mosaicking or postprocessing
+  --mosaic-only         Only mosaic tiles; do not download
+  --group-tiles GROUP_TILES
+                        Mosaic tiles but according to given WxH into ./grouped_tiles
+  --group-overlap       Overlap with the next consecutive tile when grouping
+  --tile-limit TILE_LIMIT
+                        Override maximum tile limit that can download (use with caution)
+  --workers WORKERS     Max number of threads to use when parallel downloading
+  --no-parallel         Download tiles sequentially, no parallel downloading
+  --no-progress         Hide tile download progress bar
+  --quiet               Hide all prints
+  --debug               Enable debug logging
 
 Source options(Extent):
   Options for the vector polygon source
 
-  --source SOURCE  The vector polygon source for filter tiles
-  --shape          Use actual shape to derive tiles
-  --bbox           Use shape's bounding box to derive tiles
+  --source SOURCE       The vector polygon source for filter tiles
+  --shape               Use actual shape to derive tiles
+  --bbox                Use shape's bbox to derive tiles
 
 Source options(Map tiles):
   Options for the map tile source
 
-  --osm            OpenStreetMap
-  --google_sat     Google Satellite
-  --esri_sat       ESRI World Imagery
-  --key KEY        API key where required by source
-```
-
----
-<!-- 
-## Required Arguments
-
-| Argument   | Description                               |
-| ---------- | ----------------------------------------- |
-| `--source` | Vector dataset used to derive tile extent |
-| `--shape`  | Use exact geometry to select tiles        |
-| `--bbox`   | Use geometry bounding box                 |
-| `--zoom`   | Web map zoom level                        |
+  --osm                 OpenStreetMap
+  --google_sat          Google Satellite
+  --esri_sat            ESRI World Imagery
+  --key KEY             API key where required by source
 
----
-
-## Tile Sources (CLI)
+Mosaic export formats:
+  Formats for the output mosaic image
 
-| Flag           | Source             |
-| -------------- | ------------------ |
-| `--osm`        | OpenStreetMap      |
-| `--google_sat` | Google Satellite   |
-| `--esri_sat`   | ESRI World Imagery |
+  --jpg                 JPG image; no geo-reference
+  --png                 PNG image; no geo-reference
+  --tiff                GeoTiff image; with geo-reference
 
-Optional API key:
-
-```bash
---key YOUR_API_KEY
 ```
 
 ---
 
-## Output & Processing Options
-
-| Option            | Description                                 |
-| ----------------- | ------------------------------------------- |
-| `--out <dir>`     | Output directory (default: `./saved_tiles`) |
-| `--download-only` | Download tiles only                         |
-| `--mosaic-only`   | Mosaic existing tiles only                  |
-| `--no-progress`   | Disable progress bar                        |
-| `--quiet`         | Suppress console output                     |
-
---- 
--->
 
 ## Supported Vector Formats
 
@@ -222,9 +204,6 @@ Any format readable by **GeoPandas**, including:
 
 If a tile service follows the standard `{z}/{x}/{y}` pattern, you can add it in **one small class** by extending `TileSource`.
 
-No registration. No plugin system. No magic.
-
----
 
 ### Example
 
@@ -234,12 +213,9 @@ from tilegrab.sources import TileSource
 class MyCustomSource(TileSource):
     name = "MyCustomSource name"
     description = "MyCustomSource description"
-    URL_TEMPLATE = "https://MyCustomSource/{z}/{x}/{y}.png"
+    url_template = "https://MyCustomSource/{z}/{x}/{y}.png"
 ```
 
-That’s it.
-
-Once instantiated, the source works exactly like built-in providers.
 
 ---
 
@@ -251,28 +227,19 @@ You can change how the url is generate by override `get_url` function, inside yo
 ```python
 def get_url(self, z: int, x: int, y: int) -> str:
   assert self.api_key
-  return self.URL_TEMPLATE.format(x=x, y=y, z=z, token=self.api_key)
+  return self.url_template.format(x=x, y=y, z=z, token=self.api_key)
 ```
 
 ### URL Template Rules
 
 Your tile source **must** define:
-
-* `URL_TEMPLATE`
+* `url_template`
   Must contain `{z}`, `{x}`, `{y}` placeholders.
 
 Optional but recommended:
-
 * `name` – Human-readable name
 * `description` – Short description of the imagery
 
-Example templates:
-
-```text
-https://server/{z}/{x}/{y}.png
-https://tiles.example.com/{z}/{x}/{y}.jpg
-https://api.provider.com/tiles/{z}/{x}/{y}?key={token}
-```
 
 ---
 
@@ -284,8 +251,6 @@ If your provider requires an API key, pass it during instantiation:
 source = MyCustomSource(api_key="YOUR_KEY")
 ```
 
-`TileSource` already handles key injection — you don’t need to reinvent it.
-
 ---
 
 
@@ -299,10 +264,9 @@ from tilegrab.tiles import TilesByShape
 from tilegrab.dataset import GeoDataset
 
 dataset = GeoDataset("area.gpkg")
-tiles = TilesByShape(dataset, zoom=16)
-
-source = MyCustomSource(api_key="XYZ")
-downloader = Downloader(tiles, source, "output")
+tile_collection = TilesByShape(dataset, zoom=16)
+tile_source = MyCustomSource(api_key="XYZ")
+downloader = Downloader(tile_collection, tile_source, "output")
 downloader.run()
 ```
 
@@ -321,7 +285,7 @@ If you need full flexibility, use the Python API.
 
 ---
 
-## Project Structure
+<!-- ## Project Structure
 
 ```text
 tilegrab/
@@ -331,11 +295,12 @@ tilegrab/
 ├── downloader.py   # Tile download engine
 ├── mosaic.py       # Tile mosaicking
 └── sources.py      # Tile providers
-```
+``` 
 
 ---
+-->
 
-## Who This Is For
+<!-- ## Who This Is For
 
 * GIS analysts automating basemap generation
 * Remote sensing workflows needing tiled imagery
@@ -345,7 +310,7 @@ tilegrab/
 If you want a GUI, this isn’t it.
 If you want control, repeatability, and speed — it is.
 
----
+--- -->
 
 ## Roadmap
 
@@ -353,9 +318,9 @@ Planned (not promises):
 
 * Additional tile providers
 * Parallel download tuning
-* Cloud-optimized raster output
 * Raster reprojection and resampling options
 * Expanded Python API documentation
+* Test implementation
 
 ---
 

tilegrab-1.2.0b2.dist-info/RECORD

@@ -0,0 +1,15 @@
+tilegrab/__init__.py,sha256=Ti-EFZrLJA9WtEN3ZwvstVIBAsceEuZgjV7gw9JOoyk,295
+tilegrab/__main__.py,sha256=wT62aXCuN7iwRPQoswnmeGiBS5Cou0CIBvMxbOTfvFs,33
+tilegrab/cli.py,sha256=XaSC-qhANE7Y_73k18Izjpi_pGiZu7Qey1s4zP_JQAU,8099
+tilegrab/dataset.py,sha256=kzLMBbLLjdnlKN7Ac-qB7k7e63VCDs3T23CweRdvKLQ,2709
+tilegrab/downloader.py,sha256=ApQLgDjBo-RYrUuaavbulGbHaZ__G9xVQvkPO35RoP4,5371
+tilegrab/images.py,sha256=RAv_gsW5HYOk7cAcu00tHILEFBpF4tKmQ-xDXPtaNmw,11991
+tilegrab/logs.py,sha256=serS8_0bhxoTO0F03t-BDSdkMYR_eX78vI2y1sSVpUk,2151
+tilegrab/sources.py,sha256=rQshFLjzbJu4x0AXTLa3YXhfK07719bMoZrSoOiAWG8,2344
+tilegrab/tiles.py,sha256=XeFxO1i4kXokyK0mg_6f7FeHOkPXOMk8n2m-4C6H87Y,9044
+tilegrab-1.2.0b2.dist-info/licenses/LICENSE,sha256=bcZProekTTcPtnEpRKB2i1kUJ6ujlaxBZchNWKeoXc8,1094
+tilegrab-1.2.0b2.dist-info/METADATA,sha256=363_bNbE-ONRebVSiEX1TGwsmT0KQ4uRowALZhKsVs8,9684
+tilegrab-1.2.0b2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+tilegrab-1.2.0b2.dist-info/entry_points.txt,sha256=z-WoKN8NnA5_ZsWXucSeq-r4TeEscu0xjWYu560uNTk,47
+tilegrab-1.2.0b2.dist-info/top_level.txt,sha256=lVio8bCk3r4Bu_INLgaj4PZCrhFY2UcxHjnFBdHwyPo,9
+tilegrab-1.2.0b2.dist-info/RECORD,,

tilegrab-1.2.0b1.dist-info/RECORD

@@ -1,15 +0,0 @@
-tilegrab/__init__.py,sha256=unu6CU3corZS1SmNsFCi-o6od2C-yIzCfVm82ADJTXM,295
-tilegrab/__main__.py,sha256=wT62aXCuN7iwRPQoswnmeGiBS5Cou0CIBvMxbOTfvFs,33
-tilegrab/cli.py,sha256=RH787UzO4pGpjPMq_BHnTO_A9qhuJnurtvn2LG4sn4U,6395
-tilegrab/dataset.py,sha256=tmbvR7wd9NYWCPsDLo9SP0x0_3edyRURQHo-6EnEIAM,2623
-tilegrab/downloader.py,sha256=ge3o4PS0v3_npaiOvFmlNSx62VqL8nwjcefy4Jr_UQo,5120
-tilegrab/images.py,sha256=VUE9Wsswkl2wAzkQnwDtncgKVU-wl3xGWagmx3u6Dk8,9278
-tilegrab/logs.py,sha256=serS8_0bhxoTO0F03t-BDSdkMYR_eX78vI2y1sSVpUk,2151
-tilegrab/sources.py,sha256=GzldtFGndziw9NNB1YMG4WUrD0fTRET1FjGCfIMMDlQ,2188
-tilegrab/tiles.py,sha256=nCJL4tOKKQoZPJbGgDfL-I1DxYjo2Ajk69McvtAoEWM,8960
-tilegrab-1.2.0b1.dist-info/licenses/LICENSE,sha256=bcZProekTTcPtnEpRKB2i1kUJ6ujlaxBZchNWKeoXc8,1094
-tilegrab-1.2.0b1.dist-info/METADATA,sha256=UHVyRZO5L1yo1Upe7jQoig0KG4Af_p6gzv6cJAfl4AA,10197
-tilegrab-1.2.0b1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-tilegrab-1.2.0b1.dist-info/entry_points.txt,sha256=z-WoKN8NnA5_ZsWXucSeq-r4TeEscu0xjWYu560uNTk,47
-tilegrab-1.2.0b1.dist-info/top_level.txt,sha256=lVio8bCk3r4Bu_INLgaj4PZCrhFY2UcxHjnFBdHwyPo,9
-tilegrab-1.2.0b1.dist-info/RECORD,,