vectortileserver 0.1.0__py3-none-any.whl

vectortileserver/__init__.py

@@ -0,0 +1,8 @@
+__title__ = "vectortileserver"
+__summary__ = "Local vector tile server for visualizing PMTiles in Jupyter"
+__version__ = "0.1.0"
+
+__author__ = "Daniel Guerrero"
+__email__ = "dfgm2006@gmail.com"
+
+__license__ = "MIT"

vectortileserver/app.py

@@ -0,0 +1,32 @@
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.routing import Route
+
+from vectortileserver.endpoints import pmtiles_endpoint, shutdown_endpoint
+
+
+def create_app(tile_server_instance):
+    """Create the Starlette application with routes and middleware."""
+
+    async def shutdown_wrapper(request):
+        return await shutdown_endpoint(request, tile_server_instance)
+
+    async def pmtiles_wrapper(request):
+        return await pmtiles_endpoint(request, tile_server_instance)
+
+    routes = [
+        Route("/shutdown", shutdown_wrapper),
+        Route("/pmtiles", pmtiles_wrapper),
+    ]
+
+    middleware = [
+        Middleware(
+            CORSMiddleware,
+            allow_origins=tile_server_instance.config.cors_origins,
+            allow_methods=["GET"],
+            allow_headers=["*"],
+        )
+    ]
+
+    return Starlette(debug=tile_server_instance.config.debug, routes=routes, middleware=middleware)

vectortileserver/client.py

@@ -0,0 +1,212 @@
+import json
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import httpx
+
+from vectortileserver.handler import get_metadata
+from vectortileserver.logger import logger
+from vectortileserver.styles import generate_default_map_style
+
+from .converter import TileConverter
+from .server import TileServer
+from .utils import is_port_in_use
+
+
+class TileClient:
+    """
+    A client for accessing PMTiles from a local server.
+
+    This class triggers the lazy initialization of the server if needed.
+    """
+
+    def __init__(
+        self,
+        data_source: Union[str, Path] | None = None,
+        host: str = "localhost",
+        port: Optional[int] = None,
+        converter: Optional[TileConverter] = None,
+        conversion_options: Dict[str, Any] | None = None,
+        allowed_directories: List[Union[str, Path]] | None = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ):
+        """
+        Initialize the tile client.
+
+        Args:
+            data_source: Path to the vector data source (GeoJSON, Shapefile, PMTiles, etc.)
+            host: Host where the server is running.
+            port: Port where the server is running.
+            converter: Custom TileConverter instance to use.
+            conversion_options: Options to pass to the tile converter.
+            allowed_directories: List of directories that can be accessed by the server.
+            http_client: Custom HTTP client for testing.
+        """
+        logger.debug(f"Initializing tile client with data source: {data_source}")
+
+        self.data_source = Path(data_source) if data_source else None
+        self.host = host
+        self.port = port
+        self.converter = converter
+        self.conversion_options = conversion_options or {}
+        self.pmtiles_path = None
+        self.allowed_directories = allowed_directories
+        self._http_client = http_client
+
+        self.pmtiles_directory = self.data_source.parent
+        self.metadata = None
+
+        self._process_data_source()
+
+        if self.pmtiles_path is None:
+            raise ValueError(
+                "PMTiles file is not available. Ensure that a valid data_source is "
+                "provided or that the pmtiles_directory contains a PMTiles file."
+            )
+
+        # Ensure the server is running
+        self._ensure_server_running()
+
+        # Store the server URL
+        self.server_url = f"http://{self.host}:{self.port}"
+
+    @property
+    def pmtiles_url(self) -> str:
+        """Get the URL for the PMTiles file with its filePath."""
+        return f"{self.server_url}/pmtiles?filePath={self.pmtiles_path}"
+
+    @property
+    def bounds(self) -> List:
+        """Get the bounds of the PMTiles file."""
+        return self.metadata.get("bounds", [])
+
+    @property
+    def center(self) -> Tuple:
+        """Get the center of the PMTiles file."""
+        return self.metadata.get("center", [])
+
+    def get_metadata(self) -> Dict[str, Any]:
+        """Get metadata for the PMTiles file."""
+        return get_metadata(self.pmtiles_path)
+
+    def list_layers(self):
+        """Return a list of available vector layer IDs from the metadata."""
+        return [layer.get("id") for layer in self.metadata.get("vector_layers", [])]
+
+    def _process_data_source(self) -> None:
+        """Process the data source file."""
+
+        if self.data_source.suffix.lower() == ".pmtiles":
+            self._handle_pmtiles()
+
+        elif existing_pmtiles := self._find_pmtiles_files(self.pmtiles_directory):
+            if self.data_source.with_suffix(".pmtiles") in existing_pmtiles:
+                self.pmtiles_path = self.data_source.with_suffix(".pmtiles")
+                logger.debug(f"Found PMTiles file in provided directory: {self.pmtiles_path}")
+        else:
+            self._convert_vector_data()
+
+        self.metadata = self.get_metadata()
+
+    def _handle_pmtiles(self) -> None:
+        """Handle a PMTiles file directly without conversion.
+
+        If the metadata file is not present in the same folder as the PMTiles file,
+        create it.
+        """
+        logger.debug(f"Using PMTiles file directly: {self.data_source}")
+
+        if not self.data_source.exists():
+            raise FileNotFoundError(f"PMTiles file not found: {self.data_source}")
+
+        dest_file = self.pmtiles_directory / self.data_source.name
+        if not dest_file.exists() or dest_file.stat().st_mtime < self.data_source.stat().st_mtime:
+            logger.debug(f"Copying PMTiles file to {dest_file}")
+            shutil.copy2(self.data_source, dest_file)
+
+        self.pmtiles_path = dest_file
+
+    def _convert_vector_data(self) -> None:
+        """
+        Process vector data formats and convert to PMTiles if needed.
+        """
+        logger.debug(f"Processing vector data: {self.data_source} -> {self.pmtiles_directory}")
+
+        # Use provided converter or create a new one
+        converter = self.converter
+        if not converter:
+            converter = TileConverter(self.data_source, self.pmtiles_directory)
+
+        # Convert the data
+        if pmtiles_path := converter.convert(**self.conversion_options):
+            logger.debug(f"Converted data to PMTiles: {self.pmtiles_path}")
+            self.pmtiles_path = pmtiles_path
+
+        else:
+            raise RuntimeError(f"No PMTiles file was generated in {self.pmtiles_directory}")
+
+    def _ensure_server_running(self) -> None:
+        """
+        Ensure the tile server is running.
+        """
+        if self.port is not None and is_port_in_use(self.port):
+            logger.debug(f"Using existing server at port {self.port}")
+            return
+
+        server = TileServer.get_instance(
+            host=self.host,
+            port=self.port,
+            allowed_directories=[self.pmtiles_directory] + (self.allowed_directories or []),
+        )
+        self.port = server.config.port
+
+    def create_leaflet_layer(
+        self,
+        style: Optional[Dict[str, Any]] = None,
+        layers_to_show: Optional[List[str]] = None,
+    ) -> Any:
+        """Create a PMTiles layer for ipyleaflet.
+
+        Args:
+            style: Optional custom style for the layer
+
+        """
+        try:
+            from vectortileserver.pmtiles_layer import LeafletPMTilesLayer
+
+            style_json = generate_default_map_style(self.metadata, self.pmtiles_url)
+
+            logger.debug(f"Generated style JSON: {json.dumps(style_json, indent=2)}")
+
+            if layers_to_show:
+                if not all(layer in self.list_layers() for layer in layers_to_show):
+                    raise ValueError(
+                        f"Invalid layer IDs provided. Available layers: {self.list_layers()}"
+                    )
+                style_json["layers"] = [
+                    layer
+                    for layer in style_json["layers"]
+                    if layer["source-layer"] in layers_to_show
+                ]
+
+                logger.debug(f"Filtered style JSON: {json.dumps(style_json, indent=2)}")
+
+            return LeafletPMTilesLayer(
+                url=self.pmtiles_url,
+                style=style or style_json,
+                attribution="Vector Tile Server",
+                visible=True,
+            )
+        except Exception as e:
+            raise e
+            raise ImportError(
+                "ipyleaflet is required to create a leaflet layer. "
+                "Install it with 'pip install ipyleaflet'."
+            )
+
+    @staticmethod
+    def _find_pmtiles_files(directory: Path) -> List[Path]:
+        """Find PMTiles files in a directory."""
+
+        return list(directory.glob("*.pmtiles"))

vectortileserver/converter.py

@@ -0,0 +1,134 @@
+"""
+Converter component for the Vector Tile Server package.
+
+This module provides functionality to convert vector data to PMTiles format.
+"""
+
+import logging
+import os
+import subprocess
+from pathlib import Path
+from typing import Union
+
+import geopandas as gpd
+
+logger = logging.getLogger(__name__)
+
+
+class TileConverter:
+    """
+    Converts vector data to PMTiles format using Tippecanoe or other methods.
+    """
+
+    def __init__(
+        self,
+        input_path: Union[str, Path],
+        output_path: Union[str, Path] | None = None,
+        tippecanoe_path: str = "tippecanoe",
+    ):
+        """
+        Initialize the tile converter.
+
+        Args:
+            input_path: Path to the input vector data
+            output_path: Path to write the output tiles
+            tippecanoe_path: Path to the tippecanoe executable
+        """
+        self.input_path = Path(input_path)
+        self.output_path = (
+            Path(output_path) if output_path else self.input_path.with_suffix(".tiles")
+        )
+        self.tippecanoe_path = tippecanoe_path
+
+        # Validate input file existence
+        if not self.input_path.exists():
+            raise FileNotFoundError(f"Input file not found: {self.input_path}")
+
+    def convert(
+        self,
+        method: str = "auto",
+        max_zoom: int = 14,
+        min_zoom: int = 0,
+        **kwargs,
+    ) -> Path:
+        """
+        Convert the input data to PMTiles.
+
+        Args:
+            method: Conversion method ('tippecanoe', 'python', or 'auto')
+            max_zoom: Maximum zoom level
+            min_zoom: Minimum zoom level
+            **kwargs: Additional options for the converter
+
+        Returns:
+            Path: Path to the output PMTiles file
+        """
+        # Create output directory if it doesn't exist
+        os.makedirs(self.output_path, exist_ok=True)
+        geojson_path = self._ensure_geojson(self.input_path)
+
+        # Define output PMTiles file path
+        pmtiles_path = self.output_path / f"{self.input_path.stem}.pmtiles"
+
+        # Build Tippecanoe command for PMTiles output
+        cmd = [
+            self.tippecanoe_path,
+            "-o",
+            str(pmtiles_path),
+            "-z",
+            str(max_zoom),
+            "-Z",
+            str(min_zoom),
+            "-l",
+            self.input_path.stem,
+            "--force",  # Overwrite existing files
+        ]
+
+        # Add additional options
+        for key, value in kwargs.items():
+            if len(key) == 1:
+                cmd.append(f"-{key}")
+            else:
+                cmd.append(f"--{key.replace('_', '-')}")
+
+            if value is not True:  # Only add value if it's not a boolean flag
+                cmd.append(str(value))
+
+        # Add input file
+        cmd.append(str(geojson_path))
+
+        logger.debug(f"Running command: {' '.join(cmd)}")
+
+        # Run Tippecanoe
+        try:
+            result = subprocess.run(cmd, check=True, capture_output=True, text=True)
+            logger.debug(f"Tippecanoe output: {result.stdout}")
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Tippecanoe error: {e.stderr}")
+            raise RuntimeError(f"Tippecanoe conversion failed: {e.stderr}")
+
+        return self.output_path
+
+    def _ensure_geojson(self, input_path: Path) -> Path:
+        """
+        Ensure the input file is in GeoJSON format, converting if necessary.
+
+        Args:
+            input_path: Path to the input file
+
+        Returns:
+            Path: Path to the GeoJSON file
+        """
+        # If already GeoJSON, return as is
+        if input_path.suffix.lower() in (".geojson", ".json"):
+            return input_path
+
+        # Convert to GeoJSON
+        logger.debug(f"Converting {input_path} to GeoJSON")
+        gdf = gpd.read_file(input_path)
+
+        # Create a temporary GeoJSON file
+        geojson_path = input_path.with_suffix(".geojson")
+        gdf.to_file(geojson_path, driver="GeoJSON")
+
+        return geojson_path

vectortileserver/endpoints.py

@@ -0,0 +1,132 @@
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterator, Optional
+
+from starlette.requests import Request
+from starlette.responses import (
+    FileResponse,
+    PlainTextResponse,
+    Response,
+    StreamingResponse,
+)
+
+from vectortileserver.logger import logger
+
+if TYPE_CHECKING:
+    from vectortileserver.server import TileServer
+
+
+def _file_iterator(path: Path, start: int, length: int, chunk_size: int = 8192) -> Iterator[bytes]:
+    """
+    Stream file content in chunks.
+
+    Args:
+        path: Path to the file
+        start: Starting byte position
+        length: Number of bytes to read
+        chunk_size: Size of chunks to read
+
+    Yields:
+        Chunks of file data
+    """
+    with open(path, "rb") as f:
+        f.seek(start)
+        bytes_read = 0
+        while bytes_read < length:
+            chunk = f.read(min(chunk_size, length - bytes_read))
+            if not chunk:
+                break
+            bytes_read += len(chunk)
+            yield chunk
+
+
+def _validate_file_path(file_path: Path, tile_server_instance: "TileServer") -> Optional[str]:
+    """
+    Validate that a file path is within allowed directories.
+
+    Args:
+        file_path: Path to validate
+
+    Returns:
+        Error message if validation fails, None if valid
+    """
+
+    try:
+        resolved_path = file_path.resolve()
+        for allowed_dir in tile_server_instance.config.allowed_directories:
+            try:
+                resolved_path.relative_to(allowed_dir)
+                return None
+            except ValueError:
+                continue
+
+        return "Access denied: File path is outside allowed directories"
+    except Exception as e:
+        return f"Invalid file path: {e!s}"
+
+
+async def pmtiles_endpoint(request: Request, tile_server_instance: "TileServer") -> Response:
+    """
+    Serve a byte-range of the requested PMTiles file.
+    The client must specify the filename in the URL.
+    """
+    logger.debug("Serving PMTiles file from endpoint")
+    file_path_str = request.query_params.get("filePath")
+    if not file_path_str:
+        return PlainTextResponse("Filename not specified", status_code=400)
+
+    file_path = Path(file_path_str)
+    validation_error = _validate_file_path(file_path, tile_server_instance)
+    if validation_error:
+        return PlainTextResponse(validation_error, status_code=403)
+
+    if not file_path.exists():
+        return PlainTextResponse("PMTiles file not found", status_code=404)
+
+    file_size = file_path.stat().st_size
+    range_header = request.headers.get("range")
+
+    if range_header is None:
+        return FileResponse(
+            path=str(file_path),
+            media_type="application/octet-stream",
+            filename=str(file_path.name),
+        )
+
+    range_match = re.match(r"bytes=(\d+)-(\d*)", range_header)
+    if not range_match:
+        return PlainTextResponse("Invalid Range header", status_code=400)
+
+    start = int(range_match.group(1))
+    end_str = range_match.group(2)
+    end = int(end_str) if end_str else file_size - 1
+
+    logger.debug(f"Range request: {start}-{end}")
+
+    if start >= file_size:
+        return PlainTextResponse("Requested Range Not Satisfiable", status_code=416)
+    if end >= file_size:
+        end = file_size - 1
+
+    length = end - start + 1
+
+    headers = {
+        "Content-Range": f"bytes {start}-{end}/{file_size}",
+        "Accept-Ranges": "bytes",
+        "Content-Length": str(length),
+    }
+
+    # Use streaming response for better memory management
+    return StreamingResponse(
+        _file_iterator(file_path, start, length),
+        status_code=206,
+        headers=headers,
+        media_type="application/octet-stream",
+    )
+
+
+async def shutdown_endpoint(request: Request, tile_server_instance: "TileServer") -> Response:
+    """Endpoint to trigger server shutdown."""
+
+    tile_server_instance.shutdown_event.set()
+    return PlainTextResponse("Server shutdown initiated", media_type="text/plain")