osm-rasterizer 0.1.0__tar.gz

osm_rasterizer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publisher (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

osm_rasterizer-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+CLAUDE.md
+
+cache/
+*.tif*
+*.png

osm_rasterizer-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

osm_rasterizer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrés Camilo Zúñiga-González
+
+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.

osm_rasterizer-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: osm-rasterizer
+Version: 0.1.0
+Summary: Rasterize OpenStreetMap vector features into GeoTIFF rasters
+Project-URL: Homepage, https://github.com/ancazugo/osm-rasterizer
+Project-URL: Repository, https://github.com/ancazugo/osm-rasterizer
+Author-email: Andrés Camilo Zúñiga-González <ancazugo@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: geospatial,gis,openstreetmap,osm,rasterization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.12
+Requires-Dist: geopandas>=1.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: osmnx>=2.0
+Requires-Dist: pyproj>=3.4
+Requires-Dist: rasterio>=1.4
+Requires-Dist: rich>=13.0
+Requires-Dist: scipy>=1.17.0
+Requires-Dist: shapely>=2.0
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# osm-rasterizer
+
+Convert OpenStreetMap vector features into GeoTIFF rasters. Define feature classes using OSM tags, specify a bounding box and resolution, and get a multi-band or single-layer categorical raster as output.
+
+## Installation
+
+Requires Python 3.12+ and [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/your-org/osm-rasterizer
+cd osm-rasterizer
+uv sync
+```
+
+## Usage
+
+```bash
+uv run main.py \
+    --bbox "minx,miny,maxx,maxy" \
+    --feature 'name:{"osm_key": "value"}' \
+    --output output.tif \
+    --resolution 10
+```
+
+Or using the installed script entry point:
+
+```bash
+osm-rasterizer --bbox ... --feature ... --output ...
+```
+
+### Options
+
+| Option | Short | Default | Description |
+|---|---|---|---|
+| `--bbox` | `-b` | required | Bounding box as `minx,miny,maxx,maxy` in WGS84 (EPSG:4326) |
+| `--feature` | `-f` | required | OSM feature spec (repeatable, see below) |
+| `--output` | `-o` | required | Output GeoTIFF path |
+| `--resolution` | `-r` | `10.0` | Pixel size in metres |
+| `--single-layer` | | `False` | Merge all features into one categorical band |
+| `--fill-nodata` | | `False` | Fill empty pixels from nearest labelled neighbour |
+| `--fill-nodata-distance` | | unlimited | Max fill distance in pixels (prevents border flooding) |
+| `--crs` | | auto | Output CRS, e.g. `EPSG:32630`. Auto-detected as best-fit UTM if omitted |
+
+### Feature spec format
+
+Each `--feature` argument is either a bare JSON tag dict or a named spec:
+
+```
+'{"key": value}'                  # unnamed — name inferred from tags
+'name:{"key": value}'             # named band/category
+```
+
+Tag values follow the [osmnx convention](https://osmnx.readthedocs.io/):
+
+```
+'{"building": true}'              # any feature with a "building" tag
+'{"highway": "residential"}'      # exact value match
+'{"highway": ["primary", "secondary"]}'   # any of these values
+```
+
+### Output modes
+
+**Multi-band** (default): one `uint8` band per feature, values 0 (absent) or 1 (present).
+
+**Single-layer** (`--single-layer`): one `uint8` band with 1-based category indices (0 = no data). Features listed **later** take priority when areas overlap. Order your features from least to most important.
+
+Band names are stored in the GeoTIFF metadata under the `BAND_NAMES` tag. In single-layer mode, category names are stored under `CATEGORIES`.
+
+## Example: Cambridge land cover
+
+```bash
+uv run main.py \
+    --bbox "-0.24786388455006128, 52.242894345312415, 0.10397291341351336, 52.34506356709806" \
+    --feature 'bare_ground:{"natural": ["bare_rock", "sand", "scree"], "landuse": ["quarry", "brownfield"]}' \
+    --feature 'cropland:{"landuse": ["farmland", "orchard", "allotments", "greenhouse_horticulture"]}' \
+    --feature 'grassland:{"natural": "grassland", "landuse": ["grass", "meadow", "village_green"], "leisure": "park"}' \
+    --feature 'forest:{"landuse": "forest", "natural": "wood"}' \
+    --feature 'wetland:{"natural": "wetland"}' \
+    --feature 'infrastructure:{"building": true, "landuse": ["industrial", "commercial", "retail", "residential", "construction", "railway"]}' \
+    --feature 'road:{"highway": ["motorway", "trunk", "primary", "secondary", "tertiary", "unclassified", "residential", "service", "track", "motorway_link", "trunk_link", "primary_link", "secondary_link", "tertiary_link"]}' \
+    --feature 'water:{"natural": "water", "waterway": ["river", "canal", "stream", "drain", "ditch"]}' \
+    --output cambridge_landcover.tif \
+    --resolution 10 \
+    --single-layer \
+    --fill-nodata \
+    --fill-nodata-distance 50
+```
+
+This produces a 10 m resolution single-layer categorical raster with 8 land cover classes, with small gaps filled by propagating the nearest label up to 50 pixels away.
+
+## Python API
+
+```python
+from osm_rasterizer.rasterize import rasterize
+
+result = rasterize(
+    bbox=(-0.15, 51.48, -0.08, 51.52),  # central London
+    features=[
+        ("building", {"building": True}),
+        ("water", {"natural": "water"}),
+        ("park", {"leisure": "park"}),
+    ],
+    resolution=10.0,
+    single_layer=True,
+    fill_nodata=True,
+    fill_nodata_distance=30,
+)
+
+# result.array   — numpy array, shape (1, H, W) in single-layer mode
+# result.crs     — rasterio CRS
+# result.transform — affine transform
+# result.categories — ["building", "water", "park"]
+
+# Or write directly to a file:
+rasterize(
+    bbox=(-0.15, 51.48, -0.08, 51.52),
+    features=[("building", {"building": True})],
+    output_path="buildings.tif",
+)
+```
+
+## How it works
+
+1. **Fetch** — OSM features are downloaded via the Overpass API (using [osmnx](https://osmnx.readthedocs.io/)) and clipped to the exact bounding box.
+2. **Project** — The bbox and geometries are reprojected to the best-fit UTM CRS (or a user-specified CRS).
+3. **Rasterize** — Each feature class is burned into a `uint8` grid using [rasterio](https://rasterio.readthedocs.io/).
+4. **Merge / fill** — Bands are optionally merged into a single categorical layer, and empty pixels optionally filled using a Euclidean distance transform (scipy).
+5. **Write** — Output is a cloud-optimised, LZW-compressed, tiled GeoTIFF.
+
+## Development
+
+```bash
+# Run tests (unit tests only, no network)
+uv run pytest
+
+# Run including integration tests (requires Overpass network access)
+uv run pytest -m integration
+```

osm_rasterizer-0.1.0/README.md

@@ -0,0 +1,138 @@
+# osm-rasterizer
+
+Convert OpenStreetMap vector features into GeoTIFF rasters. Define feature classes using OSM tags, specify a bounding box and resolution, and get a multi-band or single-layer categorical raster as output.
+
+## Installation
+
+Requires Python 3.12+ and [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/your-org/osm-rasterizer
+cd osm-rasterizer
+uv sync
+```
+
+## Usage
+
+```bash
+uv run main.py \
+    --bbox "minx,miny,maxx,maxy" \
+    --feature 'name:{"osm_key": "value"}' \
+    --output output.tif \
+    --resolution 10
+```
+
+Or using the installed script entry point:
+
+```bash
+osm-rasterizer --bbox ... --feature ... --output ...
+```
+
+### Options
+
+| Option | Short | Default | Description |
+|---|---|---|---|
+| `--bbox` | `-b` | required | Bounding box as `minx,miny,maxx,maxy` in WGS84 (EPSG:4326) |
+| `--feature` | `-f` | required | OSM feature spec (repeatable, see below) |
+| `--output` | `-o` | required | Output GeoTIFF path |
+| `--resolution` | `-r` | `10.0` | Pixel size in metres |
+| `--single-layer` | | `False` | Merge all features into one categorical band |
+| `--fill-nodata` | | `False` | Fill empty pixels from nearest labelled neighbour |
+| `--fill-nodata-distance` | | unlimited | Max fill distance in pixels (prevents border flooding) |
+| `--crs` | | auto | Output CRS, e.g. `EPSG:32630`. Auto-detected as best-fit UTM if omitted |
+
+### Feature spec format
+
+Each `--feature` argument is either a bare JSON tag dict or a named spec:
+
+```
+'{"key": value}'                  # unnamed — name inferred from tags
+'name:{"key": value}'             # named band/category
+```
+
+Tag values follow the [osmnx convention](https://osmnx.readthedocs.io/):
+
+```
+'{"building": true}'              # any feature with a "building" tag
+'{"highway": "residential"}'      # exact value match
+'{"highway": ["primary", "secondary"]}'   # any of these values
+```
+
+### Output modes
+
+**Multi-band** (default): one `uint8` band per feature, values 0 (absent) or 1 (present).
+
+**Single-layer** (`--single-layer`): one `uint8` band with 1-based category indices (0 = no data). Features listed **later** take priority when areas overlap. Order your features from least to most important.
+
+Band names are stored in the GeoTIFF metadata under the `BAND_NAMES` tag. In single-layer mode, category names are stored under `CATEGORIES`.
+
+## Example: Cambridge land cover
+
+```bash
+uv run main.py \
+    --bbox "-0.24786388455006128, 52.242894345312415, 0.10397291341351336, 52.34506356709806" \
+    --feature 'bare_ground:{"natural": ["bare_rock", "sand", "scree"], "landuse": ["quarry", "brownfield"]}' \
+    --feature 'cropland:{"landuse": ["farmland", "orchard", "allotments", "greenhouse_horticulture"]}' \
+    --feature 'grassland:{"natural": "grassland", "landuse": ["grass", "meadow", "village_green"], "leisure": "park"}' \
+    --feature 'forest:{"landuse": "forest", "natural": "wood"}' \
+    --feature 'wetland:{"natural": "wetland"}' \
+    --feature 'infrastructure:{"building": true, "landuse": ["industrial", "commercial", "retail", "residential", "construction", "railway"]}' \
+    --feature 'road:{"highway": ["motorway", "trunk", "primary", "secondary", "tertiary", "unclassified", "residential", "service", "track", "motorway_link", "trunk_link", "primary_link", "secondary_link", "tertiary_link"]}' \
+    --feature 'water:{"natural": "water", "waterway": ["river", "canal", "stream", "drain", "ditch"]}' \
+    --output cambridge_landcover.tif \
+    --resolution 10 \
+    --single-layer \
+    --fill-nodata \
+    --fill-nodata-distance 50
+```
+
+This produces a 10 m resolution single-layer categorical raster with 8 land cover classes, with small gaps filled by propagating the nearest label up to 50 pixels away.
+
+## Python API
+
+```python
+from osm_rasterizer.rasterize import rasterize
+
+result = rasterize(
+    bbox=(-0.15, 51.48, -0.08, 51.52),  # central London
+    features=[
+        ("building", {"building": True}),
+        ("water", {"natural": "water"}),
+        ("park", {"leisure": "park"}),
+    ],
+    resolution=10.0,
+    single_layer=True,
+    fill_nodata=True,
+    fill_nodata_distance=30,
+)
+
+# result.array   — numpy array, shape (1, H, W) in single-layer mode
+# result.crs     — rasterio CRS
+# result.transform — affine transform
+# result.categories — ["building", "water", "park"]
+
+# Or write directly to a file:
+rasterize(
+    bbox=(-0.15, 51.48, -0.08, 51.52),
+    features=[("building", {"building": True})],
+    output_path="buildings.tif",
+)
+```
+
+## How it works
+
+1. **Fetch** — OSM features are downloaded via the Overpass API (using [osmnx](https://osmnx.readthedocs.io/)) and clipped to the exact bounding box.
+2. **Project** — The bbox and geometries are reprojected to the best-fit UTM CRS (or a user-specified CRS).
+3. **Rasterize** — Each feature class is burned into a `uint8` grid using [rasterio](https://rasterio.readthedocs.io/).
+4. **Merge / fill** — Bands are optionally merged into a single categorical layer, and empty pixels optionally filled using a Euclidean distance transform (scipy).
+5. **Write** — Output is a cloud-optimised, LZW-compressed, tiled GeoTIFF.
+
+## Development
+
+```bash
+# Run tests (unit tests only, no network)
+uv run pytest
+
+# Run including integration tests (requires Overpass network access)
+uv run pytest -m integration
+```

osm_rasterizer-0.1.0/main.py

@@ -0,0 +1,4 @@
+from osm_rasterizer.cli import app
+
+if __name__ == "__main__":
+    app()

osm_rasterizer-0.1.0/osm_rasterizer/__init__.py

@@ -0,0 +1,7 @@
+"""osm-rasterizer: Rasterize OpenStreetMap features into GeoTIFF rasters."""
+
+from .crs import get_utm_crs
+from .fetch import fetch_features
+from .rasterize import RasterizeResult, rasterize
+
+__all__ = ["rasterize", "RasterizeResult", "fetch_features", "get_utm_crs"]

osm_rasterizer-0.1.0/osm_rasterizer/cli.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import json
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+from .rasterize import rasterize
+
+app = typer.Typer(help="Rasterize OpenStreetMap features into GeoTIFF rasters.")
+console = Console()
+
+
+def _parse_feature(s: str) -> tuple[str, dict] | dict:
+    """Parse a feature string into a (name, tags) tuple or bare tags dict.
+
+    Accepted formats:
+    - ``'{"building": true}'``          → bare dict
+    - ``'name:{"building": true}'``     → named tuple
+    """
+    brace_idx = s.find("{")
+    if brace_idx < 0:
+        raise typer.BadParameter(f"Feature string must contain a JSON object: {s!r}")
+
+    prefix = s[:brace_idx]
+    json_part = s[brace_idx:]
+
+    try:
+        tags = json.loads(json_part)
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Invalid JSON in feature spec {s!r}: {exc}") from exc
+
+    if not isinstance(tags, dict):
+        raise typer.BadParameter(f"Feature JSON must be an object, got: {type(tags).__name__}")
+
+    name = prefix.rstrip(":").strip() if prefix.strip().rstrip(":") else None
+
+    if name:
+        return (name, tags)
+    return tags
+
+
+@app.command()
+def main(
+    bbox: Annotated[str, typer.Option("--bbox", "-b", help="Bounding box as 'minx,miny,maxx,maxy' in WGS84.")],
+    feature: Annotated[list[str], typer.Option("--feature", "-f", help="OSM feature spec. Format: '{\"key\": val}' or 'name:{\"key\": val}'. Repeatable.")],
+    output: Annotated[str, typer.Option("--output", "-o", help="Output GeoTIFF file path.")],
+    resolution: Annotated[float, typer.Option("--resolution", "-r", help="Pixel resolution in metres.")] = 10.0,
+    single_layer: Annotated[bool, typer.Option("--single-layer", help="Merge all features into a single band.")] = False,
+    fill_nodata: Annotated[bool, typer.Option("--fill-nodata", help="Fill empty pixels with the consensus of neighbouring pixels.")] = False,
+    fill_nodata_distance: Annotated[Optional[float], typer.Option("--fill-nodata-distance", help="Max distance in pixels to fill from a labelled pixel. Prevents border flooding. Default: unlimited.")] = None,
+    crs: Annotated[Optional[str], typer.Option("--crs", help="Output CRS, e.g. 'EPSG:32632'. Auto-detected if omitted.")] = None,
+    date: Annotated[Optional[str], typer.Option("--date", help="Point-in-time ISO 8601 date, e.g. '2020-01-01'. Queries OSM as it existed at that date.")] = None,
+) -> None:
+    """Rasterize OSM features for a bounding box into a GeoTIFF."""
+    # Parse bbox
+    try:
+        parts = [float(v.strip()) for v in bbox.split(",")]
+        if len(parts) != 4:
+            raise ValueError
+        bbox_tuple: tuple[float, float, float, float] = (parts[0], parts[1], parts[2], parts[3])
+    except ValueError:
+        raise typer.BadParameter(
+            f"bbox must be 'minx,miny,maxx,maxy' (4 comma-separated floats), got: {bbox!r}",
+            param_hint="--bbox",
+        )
+
+    # Parse features
+    parsed = [_parse_feature(f) for f in feature]
+
+    console.print(f"[bold]Rasterizing {len(parsed)} feature(s)[/bold] → [cyan]{output}[/cyan]")
+    date_info = f", date: {date}" if date else ""
+    console.print(f"  bbox: {bbox_tuple}, resolution: {resolution}m, single_layer: {single_layer}, fill_nodata: {fill_nodata}, fill_nodata_distance: {fill_nodata_distance}{date_info}")
+
+    rasterize(
+        bbox=bbox_tuple,
+        features=parsed,
+        resolution=resolution,
+        single_layer=single_layer,
+        fill_nodata=fill_nodata,
+        fill_nodata_distance=fill_nodata_distance,
+        output_path=output,
+        crs=crs,
+        date=date,
+    )
+
+    console.print(f"[green]Done.[/green] Output written to [cyan]{output}[/cyan]")

osm_rasterizer-0.1.0/osm_rasterizer/crs.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import pyproj
+from pyproj import CRS
+from pyproj.aoi import AreaOfInterest
+from pyproj.database import query_utm_crs_info
+
+
+def get_utm_crs(bbox: tuple[float, float, float, float]) -> CRS:
+    """Auto-detect best UTM CRS for a WGS84 bbox.
+
+    Parameters
+    ----------
+    bbox:
+        ``(minx, miny, maxx, maxy)`` in WGS84 (EPSG:4326).
+
+    Returns
+    -------
+    pyproj.CRS
+        The best-fit UTM CRS for the given bounding box.
+    """
+    minx, miny, maxx, maxy = bbox
+    aoi = AreaOfInterest(
+        west_lon_degree=minx,
+        south_lat_degree=miny,
+        east_lon_degree=maxx,
+        north_lat_degree=maxy,
+    )
+    results = query_utm_crs_info(datum_name="WGS 84", area_of_interest=aoi)
+    if not results:
+        raise ValueError(f"No UTM CRS found for bbox {bbox}")
+    best = results[0]
+    return CRS.from_authority(best.auth_name, best.code)

osm_rasterizer-0.1.0/osm_rasterizer/fetch.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import geopandas as gpd
+import osmnx as ox
+from shapely.geometry import box
+
+try:
+    from osmnx._errors import InsufficientResponseError
+except ImportError:
+    # osmnx < 2.0 fallback name
+    from osmnx.errors import InsufficientResponseError  # type: ignore[no-redef]
+
+
+def fetch_features(
+    bbox: tuple[float, float, float, float],
+    tags: dict,
+    date: str | None = None,
+) -> gpd.GeoDataFrame:
+    """Fetch OSM features for a WGS84 bounding box.
+
+    Parameters
+    ----------
+    bbox:
+        ``(minx, miny, maxx, maxy)`` in WGS84 degrees.
+    tags:
+        OSM tag dict in osmnx convention, e.g. ``{"building": True}``.
+    date:
+        Optional ISO 8601 date string (e.g. ``"2020-01-01"`` or
+        ``"2020-01-01T00:00:00Z"``) to query OSM data as it existed at
+        that point in time.  Uses the Overpass API ``[date:"..."]`` filter.
+
+    Returns
+    -------
+    geopandas.GeoDataFrame
+        Features clipped to the exact bbox polygon.  Returns an empty
+        GeoDataFrame (with a geometry column) if no features are found.
+    """
+    minx, miny, maxx, maxy = bbox
+
+    original_settings = ox.settings.overpass_settings
+    if date:
+        dt = date if "T" in date else f"{date}T00:00:00Z"
+        ox.settings.overpass_settings = f'[out:json][timeout:180][date:"{dt}"]'
+
+    # osmnx 2.x uses (west, south, east, north) = (minx, miny, maxx, maxy),
+    # which matches our convention directly. osmnx 1.x used (north, south, east, west).
+    try:
+        gdf = ox.features_from_bbox(bbox=(minx, miny, maxx, maxy), tags=tags)
+    except InsufficientResponseError:
+        return gpd.GeoDataFrame(geometry=[], crs="EPSG:4326")
+    finally:
+        ox.settings.overpass_settings = original_settings
+
+    if gdf.empty:
+        return gpd.GeoDataFrame(geometry=[], crs="EPSG:4326")
+
+    # Clip to exact bbox to remove any features partially outside
+    clip_poly = box(minx, miny, maxx, maxy)
+    return gdf.clip(clip_poly)