zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/cli.py

@@ -0,0 +1,367 @@
+"""Command-line interface: ``zero2geospatial3d <command> ...``.
+
+Commands:
+    sun        sunrise, sunset and noon elevation for a place and date
+    stations   nearest TMYx weather stations from the bundled index
+    epw        download a station's EPW file (climate.onebuilding.org)
+    comfort    UTCI and PET for one set of conditions
+    osm        download OSM buildings/trees/roads and write a scene package
+    demo       write a small synthetic scene package
+    analyze    run a raster analysis on a scene package
+    view       open a scene package in the bundled browser viewer
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import os
+import sys
+from typing import Optional, Sequence
+
+import numpy as np
+
+from . import __version__
+
+ANALYSES = (
+    "sun-hours",
+    "shadow",
+    "svf",
+    "viewshed",
+    "irradiation",
+    "slope",
+    "aspect",
+    "hillshade",
+    "flood",
+)
+
+
+def _date(text: str) -> _dt.date:
+    try:
+        return _dt.date.fromisoformat(text)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"invalid date {text!r}; use YYYY-MM-DD") from exc
+
+
+def _fmt_hour(h: Optional[float]) -> str:
+    if h is None:
+        return "-"
+    m = int(round(h * 60))
+    return f"{m // 60:02d}:{m % 60:02d}"
+
+
+def _cmd_sun(args: argparse.Namespace) -> int:
+    from . import geo, solar
+
+    tz = geo.utc_offset_guess(args.lon) if args.tz is None else args.tz
+    doy = args.date.timetuple().tm_yday
+    rise, sset = solar.sunrise_sunset(doy, args.lat, args.lon, tz)
+    best = max(
+        (solar.solar_position(doy, h / 60, args.lat, args.lon, tz) for h in range(0, 24 * 60, 2)),
+        key=lambda p: p.elevation,
+    )
+    out = {
+        "date": args.date.isoformat(),
+        "utc_offset": tz,
+        "sunrise": _fmt_hour(rise),
+        "sunset": _fmt_hour(sset),
+        "day_length_h": round(sset - rise, 2) if rise is not None and sset is not None else None,
+        "max_elevation_deg": round(float(np.degrees(best.elevation)), 2),
+    }
+    print(json.dumps(out, indent=1))
+    return 0
+
+
+def _cmd_stations(args: argparse.Namespace) -> int:
+    from . import epw
+
+    for row in epw.nearest_stations(args.lat, args.lon, args.count):
+        print(
+            f"{row['distance_km']:8.1f} km  UTC{row['utc']:+g}  {row['station']}\n           {row['url']}"
+        )
+    return 0
+
+
+def _cmd_epw(args: argparse.Namespace) -> int:
+    from . import epw
+
+    url = args.url
+    if url is None:
+        if args.lat is None or args.lon is None:
+            print("error: give --url or --lat/--lon", file=sys.stderr)
+            return 2
+        url = epw.nearest_stations(args.lat, args.lon, 1)[0]["url"]
+    path = epw.download_station(url, args.out, timeout=args.timeout)
+    print(json.dumps(epw.read_header(path), indent=1))
+    return 0
+
+
+def _cmd_comfort(args: argparse.Namespace) -> int:
+    from . import comfort
+
+    tr = args.tr if args.tr is not None else args.ta
+    u = float(comfort.utci(args.ta, tr, args.v, args.rh))
+    p = float(comfort.pet(args.ta, tr, args.v, args.rh))
+    uc = comfort.utci_category(u)
+    pc = comfort.pet_category(p)
+    print(
+        json.dumps(
+            {
+                "utci_c": round(u, 2),
+                "utci_class": uc["label"] if uc else None,
+                "pet_c": round(p, 2),
+                "pet_class": pc["label"] if pc else None,
+            },
+            indent=1,
+        )
+    )
+    return 0
+
+
+def _cmd_osm(args: argparse.Namespace) -> int:
+    from . import geo, osm
+    from .scene import Scene
+
+    bbox = geo.bbox_around(args.lon, args.lat, args.half_size)
+    payload = osm.fetch(*bbox, progress=lambda m: print(m, file=sys.stderr), timeout=args.timeout)
+    feats = osm.payload_to_features(payload, bbox)
+    scene = Scene.from_osm(
+        feats,
+        lat=args.lat,
+        lon=args.lon,
+        half_size=args.half_size,
+        cell=args.cell,
+        utc_offset=args.tz,
+        title=args.title,
+    )
+    scene.export(args.out)
+    print(
+        f"{len(feats['buildings'])} buildings, {len(feats['trees'])} trees, "
+        f"{len(feats['roads'])} roads -> {args.out}"
+    )
+    return 0
+
+
+def _demo_scene(size: float = 200.0, cell: float = 2.0):
+    from .scene import Building, Scene, Tree
+
+    scene = Scene.flat(size, size, cell, lat=38.42, lon=27.14, utc_offset=3.0, title="Demo block")
+    xx, yy = scene.terrain.coords()
+    scene.terrain.values[:] = 10 + 4 * np.exp(-((xx - 40) ** 2 + (yy - 30) ** 2) / (2 * 60.0**2))
+    k = 0
+    for i, cx in enumerate((-60, -20, 20, 60)):
+        for j, cy in enumerate((-60, -20, 20, 60)):
+            if (i, j) in ((1, 1), (2, 2)):
+                continue
+            k += 1
+            h = 6.0 + 3.2 * ((i * 3 + j * 5) % 8)
+            ring = [
+                [cx - 12, cy - 9],
+                [cx + 12, cy - 9],
+                [cx + 12, cy + 9],
+                [cx - 12, cy + 9],
+                [cx - 12, cy - 9],
+            ]
+            scene.buildings.append(Building([[ring]], height=h, id=k, properties={"name": f"B{k}"}))
+    for t in range(8):
+        scene.trees.append(Tree(-20 + 6 * t, -20 + 3 * (t % 3), 8.0, 3.0))
+    return scene
+
+
+def _cmd_demo(args: argparse.Namespace) -> int:
+    scene = _demo_scene(args.size, args.cell)
+    scene.export(args.out)
+    print(f"demo scene with {len(scene.buildings)} buildings -> {args.out}")
+    return 0
+
+
+def _save(values: np.ndarray, grid, path: str, origin) -> None:
+    from .results import write_ascii_grid, write_grid_npy
+
+    if path.lower().endswith(".asc"):
+        write_ascii_grid(path, grid, values, origin=origin)
+    elif path.lower().endswith((".tif", ".tiff")):
+        from .results import write_geotiff
+
+        write_geotiff(path, grid, values, origin=origin)
+    else:
+        write_grid_npy(path, grid, values)
+
+
+def _cmd_analyze(args: argparse.Namespace) -> int:
+    from . import shading, terrain
+    from .results import grid_stats
+    from .scene import load_scene
+
+    scene = load_scene(args.scene)
+    surface = scene.surface(include_trees=args.trees)
+    date = args.date
+    kind = args.analysis
+    if kind == "sun-hours":
+        values = shading.sun_hours(
+            surface,
+            scene.lat,
+            scene.lon,
+            scene.utc_offset,
+            month=date.month,
+            day=date.day,
+            start_hour=args.start,
+            end_hour=args.end,
+            step_minutes=args.step,
+        )
+    elif kind == "shadow":
+        from .solar import solar_position
+
+        p = solar_position(
+            date.timetuple().tm_yday, args.hour, scene.lat, scene.lon, scene.utc_offset
+        )
+        values = (~shading.shadow_mask(surface, p.elevation, p.azimuth)).astype(float)
+    elif kind == "svf":
+        values = shading.sky_view_factor(surface, args.azimuths)
+    elif kind == "viewshed":
+        if args.x is None or args.y is None:
+            print("error: viewshed needs --x and --y (local metres)", file=sys.stderr)
+            return 2
+        values = shading.viewshed(surface, (args.x, args.y), radius=args.radius)
+    elif kind == "irradiation":
+        from .weather import annual_sun_bins, clear_sky_year, read_epw
+
+        w = (
+            read_epw(args.epw)
+            if args.epw
+            else clear_sky_year(scene.lat, scene.lon, scene.utc_offset)
+        )
+        bins = annual_sun_bins(w, scene.lat, scene.lon, scene.utc_offset)
+        res = shading.solar_irradiation(
+            surface,
+            [(d["dir"], d["weight"]) for d in bins["directions"]],
+            bins["dhi_sum"],
+            bins["ghi_sum"],
+            n_azimuths=args.azimuths,
+        )
+        values = res.total
+    elif kind in ("slope", "aspect"):
+        slope, aspect = terrain.slope_aspect(scene.terrain)
+        values = np.asarray(slope if kind == "slope" else aspect, dtype=float)
+    elif kind == "hillshade":
+        values = np.asarray(terrain.hillshade(scene.terrain), dtype=float)
+    else:  # flood
+        if args.level is None:
+            print("error: flood needs --level (m)", file=sys.stderr)
+            return 2
+        flooded = terrain.flood(scene.terrain, args.level)
+        values = np.asarray(flooded.depth, dtype=float)
+    values = np.asarray(values, dtype=float).reshape(scene.terrain.shape)
+    stats = grid_stats(values)
+    if args.out:
+        _save(values, scene.terrain, args.out, scene.origin)
+        stats["file"] = args.out
+    stats["analysis"] = kind
+    print(json.dumps(stats, indent=1))
+    return 0
+
+
+def _cmd_view(args: argparse.Namespace) -> int:
+    from .server import serve_scene
+
+    serve_scene(
+        args.scene, open_browser=not args.no_browser, results_dir=args.results or "", port=args.port
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="zero2geospatial3d",
+        description="Headless 3D terrain and building analysis (sun, shade, comfort, terrain).",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("sun", help="sunrise, sunset and noon elevation")
+    p.add_argument("--lat", type=float, required=True)
+    p.add_argument("--lon", type=float, required=True)
+    p.add_argument("--date", type=_date, default=_dt.date(2026, 3, 21))
+    p.add_argument("--tz", type=float, default=None, help="UTC offset of the clock (h)")
+    p.set_defaults(func=_cmd_sun)
+
+    p = sub.add_parser("stations", help="nearest TMYx weather stations")
+    p.add_argument("--lat", type=float, required=True)
+    p.add_argument("--lon", type=float, required=True)
+    p.add_argument("-n", "--count", type=int, default=5)
+    p.set_defaults(func=_cmd_stations)
+
+    p = sub.add_parser("epw", help="download an EPW weather file")
+    p.add_argument("--url", default=None, help="station zip URL (from 'stations')")
+    p.add_argument("--lat", type=float, default=None)
+    p.add_argument("--lon", type=float, default=None)
+    p.add_argument("--out", required=True, help="target .epw path")
+    p.add_argument("--timeout", type=float, default=120.0)
+    p.set_defaults(func=_cmd_epw)
+
+    p = sub.add_parser("comfort", help="UTCI and PET for one set of conditions")
+    p.add_argument("--ta", type=float, required=True, help="air temperature (C)")
+    p.add_argument("--tr", type=float, default=None, help="mean radiant temperature (C)")
+    p.add_argument("--v", type=float, default=1.0, help="wind speed at 10 m (m/s)")
+    p.add_argument("--rh", type=float, default=50.0, help="relative humidity (%%)")
+    p.set_defaults(func=_cmd_comfort)
+
+    p = sub.add_parser("osm", help="download OSM data and write a scene package")
+    p.add_argument("--lat", type=float, required=True)
+    p.add_argument("--lon", type=float, required=True)
+    p.add_argument("--half-size", type=float, default=250.0, help="half side of the square (m)")
+    p.add_argument("--cell", type=float, default=2.0)
+    p.add_argument("--tz", type=float, default=None)
+    p.add_argument("--title", default="OSM scene")
+    p.add_argument("--timeout", type=float, default=105.0)
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=_cmd_osm)
+
+    p = sub.add_parser("demo", help="write a synthetic demo scene package")
+    p.add_argument("--out", required=True)
+    p.add_argument("--size", type=float, default=200.0)
+    p.add_argument("--cell", type=float, default=2.0)
+    p.set_defaults(func=_cmd_demo)
+
+    p = sub.add_parser("analyze", help="run a raster analysis on a scene package")
+    p.add_argument("scene", help="folder with scene.json")
+    p.add_argument("analysis", choices=ANALYSES)
+    p.add_argument("--out", default=None, help=".npy, .asc or .tif (rasterio) output")
+    p.add_argument("--date", type=_date, default=_dt.date(2026, 3, 21))
+    p.add_argument("--hour", type=float, default=12.0, help="clock hour for 'shadow'")
+    p.add_argument("--start", type=float, default=0.0)
+    p.add_argument("--end", type=float, default=24.0)
+    p.add_argument("--step", type=float, default=10.0, help="sun-path step (min)")
+    p.add_argument("--azimuths", type=int, default=36, help="horizon sectors for svf/irradiation")
+    p.add_argument("--trees", action="store_true", help="tree crowns block the sun")
+    p.add_argument("--x", type=float, default=None)
+    p.add_argument("--y", type=float, default=None)
+    p.add_argument("--radius", type=float, default=None)
+    p.add_argument("--level", type=float, default=None, help="water level for 'flood' (m)")
+    p.add_argument("--epw", default=None, help="EPW file for 'irradiation' (default: clear sky)")
+    p.set_defaults(func=_cmd_analyze)
+
+    p = sub.add_parser("view", help="open a scene package in the browser viewer")
+    p.add_argument("scene")
+    p.add_argument("--port", type=int, default=8640)
+    p.add_argument("--no-browser", action="store_true")
+    p.add_argument("--results", default=None, help="folder for results sent from the viewer")
+    p.set_defaults(func=_cmd_view)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if getattr(args, "out", None) and args.command in ("osm", "demo"):
+        os.makedirs(args.out, exist_ok=True)
+    try:
+        return int(args.func(args) or 0)
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())