Give satellite imagery, terrain data, buildings, streetview photos to your LLM
Update CLI docs
Belluxxb40bcb675a47
diff --git a/README.md b/README.mdindex b0f004f..ff16ead 100644--- a/README.md+++ b/README.md@@ -53,7 +53,15 @@ The dashboard opens in your browser at `http://127.0.0.1:8100`. Your captures wi<img src="resources/show_video.gif" alt="Aleph dashboard demo" width="640"></p>-> [!TIP]-> Want to use it from the command line (or let an LLM use it)?-> See the [CLI docs](docs/cli.md) for examples and details.+## Use the CLI+Download a Street View photo or satellite image by place name:++```sh+alephgeo streetview --place "Colosseum, Rome" --best-match -o captures+alephgeo satellite --place "Colosseum, Rome" --best-match -o captures+```++`--best-match` selects the first match. Each download is saved in a new folder inside `captures`.++See the [CLI docs](docs/cli.md) for examples and details.diff --git a/docs/cli.md b/docs/cli.mdindex 6fdd498..5855d8b 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -1,79 +1,103 @@# CLI guide-[Back to the README](../README.md)+[Install Aleph](../README.md#install)-Each operation has its own command. Run `alephgeo COMMAND --help` for its options. Coordinates are always `LAT LON`, distances are in meters, and headings are clockwise from north.--Without `--json`, output is a compact summary: place choices show IDs, names, and types; route choices show lengths and endpoints; downloads show what was saved and its path. `resolve` also shows coordinates and nearby distances. Add `--json` for full metadata, source links, and error details.--| Command | Purpose |-| --- | --- |-| `resolve` | Search for places, reverse geocode, or list nearby POIs |-| `streetview` | Save one view or an ordered sequence along a named street |-| `satellite` | Save a satellite patch or an exact tile |-| `capture` | Create, resume, or export an area capture |-| `dashboard` | Open the visual interface |--## Find a place+## Download a photo or satellite image```sh-alephgeo resolve "Colosseum, Rome" --json-alephgeo resolve --at 41.8902 12.4922 --json-alephgeo resolve --at 41.8902 12.4922 --nearby --radius 100 --limit 10 --json+# Street View near a named place+alephgeo streetview --place "Colosseum, Rome" --best-match -o captures++# A satellite image covering a 200 × 200 meter square+alephgeo satellite --place "Colosseum, Rome" --best-match --size 200 -o captures```-Reverse lookup returns the nearest address or named place. Nearby search lists places by distance, using the center of buildings and other areas.+`--best-match` picks the first search result. Omit it to see a list of matching places, then choose it with `--match TYPE/ID`.++`-o captures` saves each download in the `captures` dir. Otherwise the results folders are created in the current directory.-Name lookup uses [Photon](https://github.com/komoot/photon). Set `ALEPH_GEOCODER_URL` or `--geocoder URL` to use another Photon server. Nearby places and streets use Geofabrik map data.+## Use coordinates-## Quick imagery+Coordinates are `LAT LON`; distances are in meters.```sh-alephgeo streetview --at 41.8902 12.4922 --heading 90 -o captures --json-alephgeo streetview --at 41.8902 12.4922 --look-at 41.8903 12.4924 --json-alephgeo streetview --pano-id PANORAMA_ID --pitch 10 --fov 75 --json-alephgeo satellite --at 41.8902 12.4922 --size 200 --zoom 19 -o captures --json-alephgeo satellite --tile 19/280337/194891 -o captures --json+# Street View facing east (0 = north, 90 = east, 180 = south, 270 = west)+alephgeo streetview --at 41.8902 12.4922 --heading 90 -o captures++# Aim the camera at a specific point+alephgeo streetview --at 41.8902 12.4922 --look-at 41.8903 12.4924 -o captures++# Satellite image around a point+alephgeo satellite --at 41.8902 12.4922 --size 500 -o captures++# Satellite image of a rectangle: south west north east+alephgeo satellite --bbox 41.8895 12.4910 41.8910 12.4940 -o captures```-Both commands accept `--place "Colosseum, Rome"` instead of `--at LAT LON`. If several places match, they are listed. Repeat the command with `--match` followed by your chosen result's `id`.+Street View searches within 50 meters. Add `--radius 200` to search farther away if no panorama is found.-Use `--best-match` to automatically choose the first result in the geocoder's ranking:+## Find places```sh-alephgeo satellite --place "Colosseum, Rome" --best-match+# Look up a name and its coordinates+alephgeo resolve "Colosseum, Rome"++# Find the address or place at these coordinates+alephgeo resolve --at 41.8902 12.4922++# List nearby points of interest+alephgeo resolve --at 41.8902 12.4922 --nearby --radius 200```-The selected name and ID appear in plain-text output and in the JSON `place` field. `--best-match` also works with `streetview --place` and `streetview --street`. It cannot be combined with `--match`; street branches still require `--route N` when ambiguous.+## Take photos along a street-Street View finds the nearest panorama within 50 meters; change this with `--radius`. Results include the camera position, distance, viewing direction, and photo date when available.+```sh+# Request photos at ten stops, looking forward along the street+alephgeo streetview --street "Via del Corso, Rome" --best-match --stops 10 -o captures-For satellite images, `--size 200` requests a square 200 meters wide around your location. Use `--bbox SOUTH WEST NORTH EAST` for a rectangle.+# Photograph both sides at each stop+alephgeo streetview --street "Via del Corso, Rome" --best-match --stops 10 --view both -o captures+```-## Follow a street+`--view` accepts `forward`, `backward`, `left`, `right`, or `both`. Add `--reverse` to travel in the opposite direction. If the street has multiple branches, repeat with `--route N` using a returned route number. Stops without coverage are skipped.++## Download an area++Capture all available data inside a rectangle (Street View, satellite imagery, OSM data, and terrain):```sh-alephgeo resolve "Via del Corso, Rome" --streets --json-alephgeo streetview --street "Via del Corso, Rome" --stops 10 --view forward -o captures --json+alephgeo capture create --bbox 41.8895 12.4910 41.8910 12.4940 -o captures```-For example, `--stops 10` requests ten positions along the street. Choose a viewing direction with `--view forward`, `backward`, `left`, or `right`; `both` takes left and right photos at each stop. Use `--reverse` to go in the opposite direction.+The command shows an estimate and asks before downloading. Add `--no-plan` to skip the prompt, or `--plan` to save a plan for later.-If several results match, use `--match ID` to pick a place or `--route N` to pick a street branch.+To download only map data and terrain:-> [!TIP]-> Images and Photon results are cached for one week. Geofabrik files are kept until refreshed. Use `--refresh` to fetch new data or `--cache-dir PATH` to choose the cache folder (default: `$XDG_CACHE_HOME/aleph` or `~/.cache/aleph`).+```sh+alephgeo capture create --bbox 41.8895 12.4910 41.8910 12.4940 --sources osm -o captures+```-## Capture an area+`--sources` accepts one or more of `streetview`, `satellite`, and `osm` (which includes terrain).-Use the capture feature when you need to download a large piece of land. It supports many square kilometers of land.+Resume an interrupted capture or start a saved plan; replace `captures/RUN_FOLDER` with the printed folder containing `manifest.json`:```sh-alephgeo capture create --bbox 41.8895 12.4910 41.8910 12.4940 --no-plan -o captures+alephgeo capture resume captures/RUN_FOLDER```-`--bbox` takes two opposite corners: `lat1 lon1 lat2 lon2`. All sources are included; use `--sources satellite osm` to download only satellite imagery, map data, and terrain.+Rebuild outputs from downloaded files, offline:-`capture create` and `capture resume` also accept `--cache-dir PATH` and `--refresh`. Time estimates do not include the first Geofabrik download.+```sh+alephgeo capture export captures/RUN_FOLDER+```++## Use in scripts++Add `--json` for one JSON result on stdout; progress stays on stderr.++```sh+alephgeo satellite --at 41.8902 12.4922 -o captures --json > result.json+alephgeo capture create --bbox 41.8895 12.4910 41.8910 12.4940 -o captures --no-plan --json+```-`--no-plan` starts downloading without confirmation (not recommended, as it may take a lot of time). Omit it to review the estimate first, or use `--plan` to save a plan without downloading. See `alephgeo capture create --help` for resolution and spacing options.+For all options, run `alephgeo COMMAND --help` (for example, `alephgeo streetview --help` or `alephgeo capture create --help`).