Skip to content

Command line (pyramids)#

Installing pyramids adds a pyramids command — a thin CLI over the same API, for quick jobs and scripts without writing Python. Every command has -h/--help:

pyramids --help                 # list all commands
pyramids <command> --help       # options for one command

Commands that write a file refuse to clobber an existing output unless you pass --overwrite. A handful take spatial options: bounds, warp, georeference, orthorectify, and edit-info accept a CRS as an EPSG code, WKT, or PROJ string; warp, overview, georeference, and orthorectify accept a --resampling method (nearest, bilinear, cubic, average, mode, …).

Inspect & edit metadata#

pyramids info dem.tif                 # human-readable metadata (add --json for machine output)
pyramids info dem.tif --json
pyramids bounds dem.tif               # bounding box; --crs 4326 reprojects the corners; --json for JSON
pyramids edit-info dem.tif --crs 4326 --nodata -9999 --tag units=m   # edit CRS / nodata / tags in place
  • info — print raster metadata (--json for a machine-readable dump).
  • bounds — print the bounding box; --crs reprojects the corners; --json emits JSON.
  • edit-info — set --crs, --nodata, and/or repeatable --tag KEY=VALUE on a raster in place.

Convert, warp, clip, merge, overviews#

pyramids convert in.asc out.tif                       # re-encode; --driver GTiff to force a driver
pyramids warp in.tif out.tif --crs 4326 --resampling bilinear
pyramids clip in.tif out.tif --bbox 440000 475000 480000 515000    # or: --vector aoi.geojson
pyramids merge tileA.tif tileB.tif tileC.tif mosaic.tif            # two or more inputs, last arg = output
pyramids merge tileA.tif tileB.tif aoi.tif --bbox 4.1 51.9 4.6 52.2 --bbox-crs 4326   # read only the window
pyramids overview dem.tif --levels 2 4 8 --resampling average      # build image pyramids IN PLACE
  • convert — re-save a raster in another format (driver inferred from the extension, or --driver).
  • warp — reproject to --crs with an optional --resampling.
  • clip — crop by --bbox MINX MINY MAXX MAXY (in the raster CRS) or by a polygon --vector.
  • merge — mosaic two-or-more rasters; the last positional argument is the output. --bbox MINX MINY MAXX MAXY restricts the mosaic to that window and reads only it, which is what makes a small area of interest cheap to pull from remote sources instead of transferring every source in full. The window is in the mosaic's own CRS unless --bbox-crs names another.
  • overview — build power-of-two overviews (--levels 2 4 8 …) into the file itself.

Cloud-Optimized GeoTIFF#

pyramids cog create in.tif out.cog.tif --profile zstd --blocksize 512   # write + auto-validate
pyramids cog validate out.cog.tif --strict                              # --strict: warnings are errors
pyramids cog info out.cog.tif                                           # structured COG layout / overviews

cog create profiles: deflate, zstd, lzw, webp, jpeg, lerc, lerc_deflate, lerc_zstd, packbits, raw. Pass --compress/--blocksize to override, --no-validate to skip the post-write check. See the COG CLI reference for the full option set.

Band math#

pyramids calc '(A - B) / (A + B)' nir.tif red.tif ndvi.tif --dtype float32
  • calc — evaluate an expression over inputs A, B, … (the operands, in order) into a new raster; the last operand is the output path. --dtype sets the output NumPy dtype. Every input must already sit on the first one's grid — calc does not resample, and refuses a mismatch rather than writing the answer on a grid the inputs never agreed on. Warp them onto a common grid first (pyramids warp). An input carrying no CRS tag at all is compared on its pixel grid alone, so an untagged mask or QA layer that sits on the template's cells still works. The output's no-data value is -9999 whatever the inputs declare — or, when the output dtype cannot hold -9999, that dtype's own fallback (255 for uint8, 65535 for uint16), which calc reports on stderr. The in-process equivalent is Dataset.combine and the - / + / * / / operators, which do apply no-data masking — calc evaluates over the raw arrays.

Georeferencing#

# Fit a transform through ground-control points (pixel/line -> map x/y)
pyramids georeference raw.tif out.tif \
    --gcp 0 0 100000 500000 --gcp 512 0 105000 500000 --gcp 0 512 100000 495000 \
    --gcp-crs 32636 --transform polynomial --order 1 --to-crs 4326

# Orthorectify from the raster's RPC sensor model (needs a DEM or a constant height)
pyramids orthorectify scene.tif ortho.tif --dem dem.tif --to-crs 4326
  • georeference — warp from repeatable --gcp PIXEL LINE X Y points (with --gcp-crs); --transform polynomial (order 1–3 via --order) or tps; optional --to-crs.
  • orthorectify — apply the raster's RPC model using --dem (or a constant --rpc-height).

Raster ↔ vector#

pyramids rasterize parcels.geojson parcels.tif --cell-size 10 --column value   # or --like template.tif
pyramids shapes classes.tif classes.geojson --geometry polygon                 # vectorize (one feature/cell)
pyramids sample dem.tif --points "440000,510000;450000,505000" --json          # read values at points
  • rasterize — burn a vector into a new raster; set --cell-size or adopt a template grid with --like; --column selects the attribute to burn (default: all non-geometry columns).
  • shapes — vectorize a raster to a vector file, one feature per cell (--geometry polygon|point, --driver); guarded for huge rasters — pass --allow-large to override the ~4M-cell safety limit.
  • sample — read band values at --points ('x,y' pairs separated by ;); --json for JSON output.

The CLI mirrors the API

Each command maps to a Dataset / FeatureCollection method — e.g. warp → to_crs, clip → crop, rasterize → Dataset.from_features, shapes → to_geodataframe. Reach for Python when you need to compose steps or stay in-memory; reach for the CLI for one-off file jobs.