feat: write ISIS-compatible Mapping PVL sidecar + enable -h for help

Two usability improvements:

1. csm2map now writes a `.pvl` sidecar file alongside every GeoTIFF
   output, containing an ISIS-compatible Mapping group with projection
   name, body radii, lat/lon type/direction/domain, ground range,
   pixel resolution, UpperLeftCornerX/Y, grid dimensions, and an
   AlgorithmName group identifying csm2map. This gives users
   transitioning from cam2map a familiar metadata format — parseable
   by the same tools they use on ISIS cube labels (pvl.load, catlab
   patterns, custom scripts).

2. Added `-h` as a help shortcut alongside `--help` for all commands
   via Typer's context_settings. Matches the convention most CLI
   users expect.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: michaelaye

src/isistools/cli.py

@@ -35,6 +35,7 @@ def _ensure_cwd() -> None:
     name="isistools",
     help="Python review tools for ISIS3 coregistration workflows.",
     no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
 )
 
 

src/isistools/processing/project.py

@@ -23,7 +23,7 @@
     compute_transform_dense,
     validate_coarse_vs_dense,
 )
-from isistools.processing.writers import write_geotiff
+from isistools.processing.writers import write_geotiff, write_mapping_pvl
 
 console = Console()
 
@@ -273,6 +273,8 @@ def project(
     with _stage(timings, "write_output"):
         if output_format == "geotiff":
             result = write_geotiff(output_path, projected, grid, nodata=0.0)
+            pvl_path = write_mapping_pvl(output_path, grid, body)
+            console.print(f"  Mapping sidecar: {pvl_path.name}")
         else:
             msg = "ISIS cube output not yet implemented"
             raise NotImplementedError(msg)

src/isistools/processing/writers.py

@@ -1,12 +1,18 @@
 """Output writers for map-projected data."""
 
+from __future__ import annotations
+
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import numpy as np
 import rasterio
 
 from isistools.processing.grid import OutputGrid
 
+if TYPE_CHECKING:
+    from isistools.processing.camera import TargetBody
+
 
 def write_geotiff(
     output_path: str | Path,
@@ -71,3 +77,105 @@ def write_geotiff(
             dst.write(data[b], b + 1)
 
     return output_path
+
+
+# Reverse map from proj4 identifiers back to ISIS projection names.
+# Only needs to cover what ISIS_TO_PROJ4 in geo/projections.py maps.
+_PROJ4_TO_ISIS = {
+    "eqc": "Equirectangular",
+    "sinu": "Sinusoidal",
+    "merc": "Mercator",
+    "tmerc": "TransverseMercator",
+    "stere": "PolarStereographic",
+    "ortho": "Orthographic",
+    "lcc": "LambertConformal",
+    "laea": "LambertAzimuthalEqualArea",
+    "nsper": "PointPerspective",
+    "moll": "Mollweide",
+    "robin": "Robinson",
+}
+
+
+def write_mapping_pvl(
+    output_path: Path,
+    grid: OutputGrid,
+    body: "TargetBody",
+) -> Path:
+    """Write an ISIS-compatible Mapping PVL sidecar next to a GeoTIFF.
+
+    The sidecar carries the same metadata that ISIS ``cam2map`` writes
+    into a projected cube's ``IsisCube.Mapping`` group: projection name,
+    body radii, lat/lon type and direction, ground range, pixel
+    resolution, and the ``UpperLeftCornerX/Y`` that pin the grid origin.
+    This makes the GeoTIFF interoperable with ISIS workflows that expect
+    a PVL Mapping group — e.g. ``automos``, ``mapmos``, or scripts that
+    parse ``catlab`` output.
+
+    Parameters
+    ----------
+    output_path : Path
+        Path to the GeoTIFF whose sidecar this is. The PVL is written to
+        ``output_path.with_suffix('.pvl')``.
+    grid : OutputGrid
+        Grid definition (CRS, affine, dimensions, ground range).
+    body : TargetBody
+        Target body identity and ellipsoid.
+
+    Returns
+    -------
+    Path to the written ``.pvl`` file.
+    """
+    # Extract the proj4 projection ID from the CRS so we can reverse-map
+    # to the ISIS projection name.
+    proj4 = grid.crs.to_proj4()
+    proj_id = None
+    center_lon = 0.0
+    center_lat = 0.0
+    for part in proj4.split():
+        if part.startswith("+proj="):
+            proj_id = part.split("=", 1)[1]
+        elif part.startswith("+lon_0="):
+            center_lon = float(part.split("=", 1)[1])
+        elif part.startswith("+lat_ts="):
+            center_lat = float(part.split("=", 1)[1])
+        elif part.startswith("+lat_0="):
+            # Some projections use lat_0 instead of lat_ts
+            center_lat = float(part.split("=", 1)[1])
+
+    isis_proj_name = _PROJ4_TO_ISIS.get(proj_id, proj_id or "Unknown")
+
+    pvl_path = output_path.with_suffix(".pvl")
+
+    lines = [
+        "Group = Mapping",
+        f"  ProjectionName     = {isis_proj_name}",
+        f"  TargetName         = {body.name}",
+        f"  EquatorialRadius   = {body.radius_equatorial_m:.1f} <meters>",
+        f"  PolarRadius        = {body.radius_polar_m:.1f} <meters>",
+        "  LatitudeType       = Planetocentric",
+        "  LongitudeDirection = PositiveEast",
+        "  LongitudeDomain    = 360",
+        f"  CenterLatitude     = {center_lat}",
+        f"  CenterLongitude    = {center_lon}",
+        f"  MinimumLatitude    = {grid.lat_min}",
+        f"  MaximumLatitude    = {grid.lat_max}",
+        f"  MinimumLongitude   = {grid.lon_min}",
+        f"  MaximumLongitude   = {grid.lon_max}",
+        f"  PixelResolution    = {grid.resolution} <meters/pixel>",
+        f"  UpperLeftCornerX   = {grid.transform.c} <meters>",
+        f"  UpperLeftCornerY   = {grid.transform.f} <meters>",
+        "End_Group",
+        "",
+        "Group = Dimensions",
+        f"  Samples            = {grid.width}",
+        f"  Lines              = {grid.height}",
+        "End_Group",
+        "",
+        "Group = AlgorithmName",
+        "  Name               = csm2map",
+        "  Version            = isistools",
+        "End_Group",
+    ]
+
+    pvl_path.write_text("\n".join(lines) + "\n")
+    return pvl_path