Skip to content

armgit / Aleph

Public Imported from GitHub
0

Give satellite imagery, terrain data, buildings, streetview photos to your LLM

10.7 KB
Raw Blame
"""Command-line arguments, grouped by command and scope."""

import argparse
import os
from pathlib import Path

from . import capture, places
from .common import DEFAULT_CACHE, WORKERS, RequestError


class Parser(argparse.ArgumentParser):
    def error(self, message):
        raise RequestError("invalid_arguments", message)


def tile_coordinates(value):
    try:
        values = tuple(int(part) for part in value.split("/"))
        if len(values) == 3:
            return values
    except ValueError:
        pass
    raise argparse.ArgumentTypeError("use Z/X/Y, for example 19/280337/194891")


def parser():
    root = Parser(prog="alephgeo", description="Download chunks of the earth with 'capture', get specific data with 'streetview' and 'satellite', search for places with 'resolve'.")
    commands = root.add_subparsers(dest="command", required=True)
    _resolve_command(commands)
    _streetview_command(commands)
    _satellite_command(commands)
    _capture_command(commands)
    _dashboard_command(commands)
    return root


def _json_option(command):
    command.add_argument("--json", action="store_true", help="one JSON result on stdout; progress on stderr")


def _output_options(command):
    command.add_argument("-o", "--output", type=Path, default=Path("."), help="parent output directory")
    _json_option(command)


def _cache_options(command):
    command.add_argument("--cache-dir", type=Path, default=DEFAULT_CACHE, help="data cache directory (default: %(default)s)")
    command.add_argument("--refresh", action="store_true", help="refresh responses and Geofabrik regional files")


def _network_options(command):
    command.add_argument("--geocoder", default=os.environ.get("ALEPH_GEOCODER_URL", places.GEOCODER), metavar="URL", help="Photon server URL (or ALEPH_GEOCODER_URL)")
    command.add_argument("--delay", type=float, default=0, help="pause between requests in seconds (default: 0)")
    _cache_options(command)


def _workers_option(command, flag, requests):
    command.add_argument(flag, type=int, metavar="N", help=f"{requests}, 1–64 (default: {WORKERS}); --delay makes them sequential")


def _sphere_options(command):
    command.add_argument("--full-sphere", action="store_true", help="save one full 360° panorama per stop; camera direction and fov do not apply")
    command.add_argument("--sphere-zoom", type=int, choices=range(6), default=3,
                         help="panorama resolution level, 0–5 (default: 3); capped at the highest available")


def _locations(command):
    group = command.add_mutually_exclusive_group(required=True)
    group.add_argument("--at", nargs=2, type=float, metavar=("LAT", "LON"), help="coordinates")
    group.add_argument("--place", help="place name, including city or country")

    selection = command.add_mutually_exclusive_group()
    selection.add_argument("--match", metavar="TYPE/ID", help="choose an OSM ID returned for an ambiguous name")
    selection.add_argument("--best-match", action="store_true", help="automatically select the geocoder's highest-ranked place")
    return group


def _resolve_command(commands):
    resolve = commands.add_parser("resolve", help="Find places, reverse geocode, or list nearby POIs")
    source = resolve.add_mutually_exclusive_group(required=True)
    source.add_argument("query", nargs="?", help="place name, including city or country")
    source.add_argument("--at", nargs=2, type=float, metavar=("LAT", "LON"))

    # Search filters and result limits.
    resolve.add_argument("--streets", action="store_true", help="restrict a name search to streets")
    resolve.add_argument("--nearby", action="store_true", help="list nearby POIs instead of reverse geocoding")
    resolve.add_argument("--radius", type=float, help="nearby POI radius in meters (default: 100; max: 5000)")
    resolve.add_argument("--limit", type=int, default=10, help="maximum results (default: 10; max: 50)")

    _network_options(resolve)
    _json_option(resolve)


def _streetview_command(commands):
    street = commands.add_parser("streetview", help="Get one view or an ordered street sequence")
    source = _locations(street)
    source.add_argument("--pano-id", help="exact panorama ID")
    source.add_argument("--street", help="named street to follow from end to end")

    # Single-view search and orientation.
    street.add_argument("--radius", type=float, help="maximum panorama search distance in meters (default: 50)")
    angle = street.add_mutually_exclusive_group()
    angle.add_argument("--heading", type=float, help="single-view heading clockwise from north, any finite float32 degrees (default: 0)")
    angle.add_argument("--look-at", nargs=2, type=float, metavar=("LAT", "LON"), help="turn a single view toward this point")

    # Street route, sampling, and orientation.
    street.add_argument("--route", type=int, help="capture only this numbered street section (default: all sections)")
    street.add_argument("--reverse", action="store_true", help="reverse traversal within each street section")
    sampling = street.add_mutually_exclusive_group()
    sampling.add_argument("--stops", type=int, help="total number of positions across the selected street sections")
    sampling.add_argument("--step", type=float, help="target spacing between street positions in meters")
    street.add_argument("--view", choices=("forward", "backward", "left", "right", "both"), help="street orientation; both saves left and right (default: forward)")

    # Camera settings shared by single views and street sequences.
    street.add_argument("--pitch", type=float, default=0, help="vertical angle, positive up and negative down; any finite float32 degrees (default: 0)")
    street.add_argument("--fov", type=int, default=75, help="horizontal field of view, 5–175 whole degrees (default: 75)")
    _sphere_options(street)

    _network_options(street)
    _workers_option(street, "--workers", "parallel coverage and sphere tile requests")
    street.add_argument("--streetview-format", choices=("jpg", "png"), default="jpg")
    _output_options(street)


def _satellite_command(commands):
    satellite = commands.add_parser("satellite", help="Get a satellite patch or an exact tile")
    source = _locations(satellite)
    source.add_argument("--bbox", nargs=4, type=float, metavar=("S", "W", "N", "E"))
    source.add_argument("--tile", type=tile_coordinates, metavar="Z/X/Y")

    # Image coverage and resolution.
    satellite.add_argument("--size", type=float, help="square width in meters around a point (default: 200)")
    satellite.add_argument("--zoom", type=int, help="satellite zoom, 1–21 (default: 19)")

    _network_options(satellite)
    _workers_option(satellite, "--workers", "parallel tile requests")
    satellite.add_argument("--tile-format", dest="satellite_format", choices=("jpg", "png"), default="jpg", help="saved tile format; merged PNG and COG are always produced (default: jpg)")
    _output_options(satellite)


def _capture_command(commands):
    captures = commands.add_parser("capture", help="Create, resume, or export an area capture")
    actions = captures.add_subparsers(dest="action", required=True)
    area = actions.add_parser("create", help="Plan and download an area with multiple sources")
    shape = area.add_mutually_exclusive_group(required=True)
    shape.add_argument("--bbox", nargs=4, type=float, metavar=("S", "W", "N", "E"))
    shape.add_argument("--polygon", nargs="+", type=float, metavar="LAT LON", help="polygon corners in order, at least three")
    area.add_argument("--sources", dest="include", nargs="+", choices=capture.SOURCES, help="sources to download (default: streetview satellite osm terrain)")

    # Planning and confirmation.
    planning = area.add_mutually_exclusive_group()
    planning.add_argument("--plan", action="store_true", help="save a plan without downloading imagery")
    yes_help = "start without the confirmation prompt"
    planning.add_argument("--yes", action="store_true", help=yes_help)

    # Street View coverage, camera, and photo format.
    area.add_argument("--depth", choices=("main", "roads", "all"), help="road/path selection (default: roads)")
    area.add_argument("--step", type=float, help="target Street View spacing in meters (default: 30)")
    area.add_argument("--fov", type=int, help="horizontal field of view, 5–175 whole degrees (default: 75)")
    area.add_argument("--streetview-format", choices=("jpg", "png"), help="Street View photo format (default: jpg)")
    _sphere_options(area)

    # Satellite imagery.
    area.add_argument("--satellite-zoom", type=int, help="satellite zoom, 1–21 (default: 18)")
    area.add_argument("--tile-format", dest="satellite_format", choices=("jpg", "png"), help="saved satellite tile format; merged PNG and COG are always produced (default: jpg)")

    # Terrain resolution.
    area.add_argument("--terrain-zoom", type=int, help="terrain zoom, 1–14 (default: 14)")

    # Google Earth 3D mesh detail.
    area.add_argument("--mesh-level", type=int, help="3D mesh detail level, 1–22 (default: 21); each level halves the texel size")

    # Requests, cache, and output shared by all capture sources.
    area.add_argument("--delay", type=float, help="pause between requests in seconds (default: 0)")
    _workers_option(area, "--streetview-workers", "parallel Street View coverage and sphere tile requests")
    _workers_option(area, "--satellite-workers", "parallel satellite tile requests")
    _workers_option(area, "--terrain-workers", "parallel terrain tile requests")
    _workers_option(area, "--mesh-workers", "parallel 3D mesh requests")
    _cache_options(area)
    _output_options(area)
    area.set_defaults(**capture.DEFAULT_OPTIONS)

    resume_help = "Continue a saved or planned run"
    resume = actions.add_parser("resume", help=resume_help, description=resume_help)
    resume.add_argument("folder", type=Path, help="timestamped run directory containing manifest.json")
    resume.add_argument("--yes", action="store_true", help=yes_help)
    _cache_options(resume)
    _json_option(resume)

    export_help = "Rebuild images and metadata from saved files, offline"
    export = actions.add_parser("export", help=export_help, description=export_help)
    export.add_argument("folder", type=Path, help="timestamped run directory containing manifest.json")
    _json_option(export)


def _dashboard_command(commands):
    dashboard = commands.add_parser("dashboard", help="Draw, capture, and explore areas in the browser")
    dashboard.add_argument("-o", "--output", type=Path, default=Path("."), help="folder holding captures (default: current directory)")
    dashboard.add_argument("--port", type=int, default=8100, help="local port (default: %(default)s)")
    dashboard.add_argument("--no-browser", action="store_true", help="do not open a browser tab")
    _cache_options(dashboard)