Command line — pyramids cog

pyramids ships a small command-line interface (the pyramids console script, registered on pip install pyramids-gis) built on the standard-library argparse — no extra dependency. The cog command group mirrors the common write / validate / inspect workflow.

# Write a COG (validates the output unless --no-validate)
pyramids cog create input.tif scene_cog.tif --profile zstd
pyramids cog create input.tif scene_cog.tif --compress DEFLATE --blocksize 256

# Validate (exit code 1 for a non-COG; --strict promotes warnings to errors)
pyramids cog validate scene_cog.tif --strict

# Print structured metadata + the overview pyramid
pyramids cog info scene_cog.tif

The functions are also callable in-process for scripting/testing:

from pyramids.cli import main
exit_code = main(["cog", "info", "scene_cog.tif"])

API

pyramids.cli

Command-line interface for pyramids.

Thin, scriptable wrappers over the library's primitives, built on the standard-library :mod:argparse (no extra dependency):

• pyramids cog create|validate|info ... — the Cloud Optimized GeoTIFF group
• pyramids info FILE [--json] — raster metadata at a glance
• pyramids bounds FILE [--crs CRS] [--json] — bounding box
• pyramids clip SRC DST (--bbox MINX MINY MAXX MAXY | --vector PATH) — crop
• pyramids warp SRC DST --crs CRS [--resampling M] — reproject
• pyramids merge SRC... DST — mosaic
• pyramids overview FILE [--resampling M] [--levels N...] — build overviews
• pyramids sample FILE --points "x,y;x,y..." [--json] — point sampling
• pyramids convert SRC DST [--driver NAME] — format conversion
• pyramids georeference SRC DST --gcp PIXEL LINE X Y ... --gcp-crs CRS — warp from ground-control points
• pyramids orthorectify SRC DST [--dem PATH | --rpc-height H] — RPC orthorectification
• pyramids edit-info FILE [--crs CRS] [--nodata V] [--tag K=V...] — edit CRS / nodata / tags in place
• pyramids calc EXPR SRC... DST [--dtype T] — evaluate a band expression (safe AST evaluator, no eval)
• pyramids shapes SRC DST [--geometry polygon|point] — vectorize a raster
• pyramids rasterize SRC DST (--cell-size S | --like RASTER) [--column C] — burn a vector into a raster

Every command maps 1:1 onto an existing library call — no business logic lives here. Expected user errors (missing file, bad CRS, unknown driver) exit non-zero with a one-line message instead of a traceback. The entry point is registered as the pyramids console script; the functions here are also callable in-process (main([...])) for testing.

main(argv=None)

Entry point for the pyramids console script.

Parameters:

Name	Type	Description	Default
argv	Sequence[str] | None	Argument list (excluding the program name). Defaults to :data:sys.argv when None.	None

Returns:

Name	Type	Description
int	int	Process exit code (0 success, non-zero failure).

Examples:

• Inspect a COG from the shell:

  >>> main(["cog", "info", "scene.tif"])  # doctest: +SKIP
  0
  

Source code in src/pyramids/cli.py

def main(argv: Sequence[str] | None = None) -> int:
    """Entry point for the `pyramids` console script.

    Args:
        argv: Argument list (excluding the program name). Defaults to
            :data:`sys.argv` when `None`.

    Returns:
        int: Process exit code (`0` success, non-zero failure).

    Examples:
        - Inspect a COG from the shell:
            ```python
            >>> main(["cog", "info", "scene.tif"])  # doctest: +SKIP
            0

            ```
    """
    parser = _build_parser()
    args = parser.parse_args(argv)
    try:
        result = args.func(args)
    except (
        ValueError,
        TypeError,
        OSError,
        RuntimeError,
        _PyramidsError,
    ) as exc:
        # Expected user errors (missing file, bad CRS, unknown driver, ...)
        # exit non-zero with a one-line message instead of a traceback.
        print(f"error: {exc}", file=sys.stderr)
        result = 1
    except Exception as exc:  # noqa: BLE001
        # An unexpected internal error (a bug, or a GDAL error type not listed
        # above) still gets a one-line message for the CLI user rather than a raw
        # traceback — unless PYRAMIDS_DEBUG is set, which re-raises the full stack.
        if os.environ.get("PYRAMIDS_DEBUG"):
            raise
        print(f"error: unexpected failure: {exc}", file=sys.stderr)
        result = 1
    return result