planetarypy 0.76.2__tar.gz → 0.77.0__tar.gz

{planetarypy-0.76.2 → planetarypy-0.77.0}/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.77.0] - 2026-06-18
+
+A geospatial-discovery release: search the PDS registry by area, ask "what data is at this coordinate?" from the terminal, and read lon/lat windows straight out of remote cloud-optimised GeoTIFFs.
+
+### Added
+
+- **Spatial search of the NASA PDS registry.** `planetarypy.search_products(bbox=(west, south, east, north))` filters by footprint overlap via the registry's `cart:Bounding_Coordinates` fields (degrees; shapely/GeoJSON order). `planetarypy.search.bbox_from_point(lon, lat, radius_deg)` builds a box around a point, and `planetarypy.search.count(**filters)` returns the number of matching products without fetching any rows — handy to size a query first. Spatial fields are only populated where the archive added them (common for derived/calibrated products, often absent for raw/EDR), and a footprint crossing a pole or the anti-meridian can have a degenerate bounding box.
+- **`plp search at BODY LON LAT`** — "what PDS data exists at this coordinate?" from the command line, with `--radius`, `--instrument`, `--count`, and `--limit`. `BODY` is a planet name (mapped to its target LID) or a full target LID; negative coordinates are accepted as positionals.
+- **`planetarypy.datasets` — body-namespaced access to remote reference rasters.** A registry of non-PDS institutional mosaics/DEMs read by lon/lat window straight from cloud-optimised GeoTIFFs over HTTP, with no full download. Two kinds: `RemoteRaster` (one fixed global COG — the FU Berlin / DLR HRSC level-3 mosaic) and `StacCollection` (a STAC collection of many COGs resolved by location — the USGS Astrogeology `mo_themis_controlled_mosaics` and `mro_ctx_controlled_usgs_dtms` for Mars, `lunar_orbiter_laser_altimeter` for the Moon). `read_window(lon, lat, size, anchor="center"|"sw"|"nw"|"se"|"ne")` and `read_bbox(west, south, east, north)` accept a `RemoteRaster`, a `StacItem`, a registry key or a bare COG URL, transform the box into the file's own CRS via pyproj (so any body/projection works), and return a georeferenced rioxarray `DataArray` (or write a GeoTIFF with `out=`). Access is by body: `datasets.mars.hrsc_level3`, `datasets.moon.lola_dtms`, …. This is the first slice of the `planetarypy.datasets` design; a remote-refreshed registry, a download mode, and a `plp datasets` CLI are planned.
+
+## [0.76.3] - 2026-06-17
+
+### Fixed
+
+- **PDS registry search: multi-filter queries no longer fail with HTTP 400.** `planetarypy.search` built its query string by joining clauses with ` and `, but the NASA PDS registry API requires the whole query wrapped in outer parentheses — so any search combining two or more filters (e.g. `target` + `observationals`, or a spatial bounding-box) returned `400 UnparsableQParamException` and only single-clause lookups worked. The query builder now wraps the joined clauses in `(...)`, matching what `pds.peppi` does. This also unblocks spatial searches via the `cart:Bounding_Coordinates.cart:*_bounding_coordinate` fields.
+- **Archived SPICE metakernels with non-`'./data'` path conventions now load.** `archived_kernels.get_metakernel()` rewrote kernel paths by matching the literal `'./data'` in `PATH_VALUES`, which most NAIF archives use — but some (e.g. Hayabusa2's PDS4 archive) ship `'..'` instead. The rewrite silently no-opped on those, leaving an unresolvable relative path that broke `furnsh`. The rewrite is now convention-agnostic: it repoints whatever value the `PATH_VALUES` block holds to the absolute local kernel directory, leaving `KERNELS_TO_LOAD` symbol references intact.
+- **`plotting.add_sun_indicator` no longer rescales the image.** The sun-direction glyph was drawn in data coordinates anchored in a corner; for any azimuth pointing past that corner, plotting the off-bounds marker triggered matplotlib autoscale, adding whitespace and pushing the indicator outside the frame. It is now drawn in axes-fraction coordinates with an inset anchor, so it stays inside the panel for any azimuth and never touches the data limits (this also removes a latent `origin='upper'`-only assumption).
+
+### Changed
+
+- **`plotting.add_sun_indicator` / `imshow_with_sun` are marked experimental.** They now carry an experimental note and emit a one-shot `UserWarning`. The azimuth-convention handoff is not yet validated end-to-end: these helpers expect azimuth clockwise-from-image-top (PDS `SUB_SOLAR_AZIMUTH`), whereas `Spicer.solar_azimuth_at` returns clockwise-from-north — they agree only when image-north points up.
+
 ## [0.76.2] - 2026-06-12
 
 ### Fixed

{planetarypy-0.76.2 → planetarypy-0.77.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: planetarypy
-Version: 0.76.2
+Version: 0.77.0
 Summary: Core package for planetary data tools. Includes PDS index utilities, SPICE integrations, and more.
 Project-URL: Homepage, https://github.com/planetarypy/planetarypy
 Project-URL: Repository, https://github.com/planetarypy/planetarypy

{planetarypy-0.76.2 → planetarypy-0.77.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "planetarypy"
-version = "0.76.2"
+version = "0.77.0"
 description = "Core package for planetary data tools. Includes PDS index utilities, SPICE integrations, and more."
 readme = "README.md"
 requires-python = ">= 3.11, <4"
@@ -185,6 +185,7 @@ DEP001 = [
 # DEP002 = "declared dependency is not used in the codebase"
 DEP002 = [
     "lxml",          # used at call time by pandas.read_html in spice/archived_kernels.py
+    "pyarrow",       # parquet engine loaded internally by pandas to_parquet/read_parquet; never imported directly
     "pytest",        # CLI tool used in CI / dev; not imported from src
     "pytest-cov",
     "pytest-xdist",
@@ -201,7 +202,7 @@ DEP003 = [
 ]
 
 [tool.bumpversion]
-current_version = "0.76.2"
+current_version = "0.77.0"
 commit = true
 tag = true
 

{planetarypy-0.76.2 → planetarypy-0.77.0}/src/planetarypy/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = """PlanetaryPy Developers"""
 __email__ = "kmichael.aye@gmail.com"
-__version__ = "0.76.2"
+__version__ = "0.77.0"
 
 __all__ = [
     "enable_logging",

{planetarypy-0.76.2 → planetarypy-0.77.0}/src/planetarypy/cli.py

@@ -876,6 +876,86 @@ def search_get_cmd(
     typer.echo(f"  ({len(props)} properties)")
 
 
+@search_app.command(
+    "at",
+    # Let negative coordinates (e.g. lat -85, lon -120) be parsed as positional
+    # arguments rather than mistaken for short option flags ("-8").
+    context_settings={"ignore_unknown_options": True},
+)
+def search_at_cmd(
+    ctx: typer.Context,
+    body: str = typer.Argument(None, help="Body name (e.g. Mars) or full target LID."),
+    lon: float = typer.Argument(None, help="Longitude, degrees (PDS cart convention)."),
+    lat: float = typer.Argument(None, help="Latitude, degrees North."),
+    radius: float = typer.Option(
+        1.0, "--radius", "-r", help="Half-box size in degrees around the point."
+    ),
+    instrument: str = typer.Option(
+        None, "--instrument", help="Restrict to this instrument LID."
+    ),
+    count_only: bool = typer.Option(
+        False, "--count", help="Print only the number of matching products."
+    ),
+    limit: int = typer.Option(20, "--limit", "-n", help="Max products to list."),
+):
+    """What PDS data exists at a coordinate on a body.
+
+    Spatial search of the NASA PDS registry by a bounding box around a point.
+    BODY is a planet name (mapped to its target LID) or a full target LID.
+
+    Examples:
+        plp search at Mars 77.4 18.4              # ~Jezero crater
+        plp search at Mars 77.4 18.4 -r 0.5 --count
+
+    Note: only products whose archive populated ``cart:Bounding_Coordinates`` can
+    match — common for derived/calibrated products, often missing for raw/EDR.
+    """
+    if body is None or lon is None or lat is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+    from planetarypy import search as _search
+
+    target = body if body.startswith("urn:") else (
+        f"urn:nasa:pds:context:target:planet.{body.lower()}"
+    )
+    bbox = _search.bbox_from_point(lon, lat, radius)
+    kw = dict(target=target, instrument=instrument, observationals=True, bbox=bbox)
+
+    n = _search.count(**kw)
+    typer.echo(
+        f"{n} product(s) overlap {lat}°N {lon}°E ±{radius}° on "
+        f"{body} (cart-indexed products only)", err=True,
+    )
+    if count_only:
+        typer.echo(n)
+        return
+    if n == 0:
+        return
+
+    from rich.console import Console
+    from rich.table import Table
+
+    df = _search.search_products(
+        **kw,
+        fields=["ref_lid_instrument", "pds:Time_Coordinates.pds:start_date_time"],
+        limit=limit,
+    )
+    table = Table(
+        title=f"{body}: data at {lat}°N {lon}°E (showing {len(df)} of {n})",
+        header_style="bold magenta", pad_edge=False,
+    )
+    table.add_column("lidvid", overflow="fold")
+    table.add_column("instrument", overflow="fold")
+    table.add_column("start_time")
+    for lidvid, row in df.iterrows():
+        instr = row.get("ref_lid_instrument")
+        instr = str(instr).rsplit(":", 1)[-1] if instr is not None else ""
+        start = row.get("pds:Time_Coordinates.pds:start_date_time") or ""
+        table.add_row(str(lidvid), instr, str(start))
+    Console().print(table)
+
+
 @search_app.command("fetch", rich_help_panel=_PANEL_FETCH)
 def search_fetch_cmd(
     ctx: typer.Context,

planetarypy-0.77.0/src/planetarypy/datasets/__init__.py

@@ -0,0 +1,432 @@
+"""Body-namespaced access to remote (non-PDS) reference rasters.
+
+First slice of the design in ``Plans/datasets_subpackage_design.qmd``: a
+baked-in registry of remote data products, namespaced **by body**, with windowed
+``/vsicurl/`` reads of cloud-optimised GeoTIFFs by lon/lat box — no full
+download. Raster + vsicurl only for now; the remote-refreshed registry, download
+mode, and ``plp datasets`` CLI from the design doc are deferred.
+
+    from planetarypy import datasets
+
+    datasets.bodies()                       # ['mars']
+    datasets.mars.hrsc_level3               # a RemoteRaster
+    da = datasets.mars.hrsc_level3.read_window(lon=0, lat=0, size=1.0)   # DataArray
+    datasets.mars.hrsc_level3.read_window(0, 0, 1.0, out="patch.tif")    # + GeoTIFF
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+__all__ = [
+    "RemoteRaster", "StacCollection", "StacItem",
+    "list_datasets", "bodies", "read_window", "read_bbox", "stac_search",
+]
+
+# GDAL options that make /vsicurl/ COG reads fast (no directory listing, only
+# fetch the byte ranges the window needs).
+_GDAL_ENV = {
+    "GDAL_DISABLE_READDIR_ON_OPEN": "EMPTY_DIR",
+    "CPL_VSIL_CURL_ALLOWED_EXTENSIONS": ".tif",
+    "GDAL_HTTP_MAX_RETRY": "3",
+    "GDAL_HTTP_RETRY_DELAY": "1",
+}
+
+
+def _set_gdal_env() -> None:
+    import os
+
+    for k, v in _GDAL_ENV.items():
+        os.environ.setdefault(k, v)
+
+
+@dataclass(frozen=True)
+class RemoteRaster:
+    """A remote reference raster, accessed by streaming (``/vsicurl/``).
+
+    ``crs`` is informational metadata (the read uses the file's own CRS); the
+    other fields document provenance. See the design doc for the fuller
+    ``DatasetConfig`` this will grow into.
+    """
+
+    key: str               # dotted: "dlr.mars.hrsc.level3_eqc"
+    short: str             # body-namespace attribute, e.g. "hrsc_level3"
+    name: str
+    body: str              # lower-case body name, e.g. "mars"
+    provider: str
+    url: str
+    crs: str               # e.g. "IAU_2015:49910"
+    kind: str = "vsicurl"
+    nodata: "Optional[float]" = None
+    pixel_scale_m: "Optional[float]" = None
+    version: "Optional[str]" = None
+    homepage: "Optional[str]" = None
+    citation: "Optional[str]" = None
+
+    @property
+    def vsicurl(self) -> str:
+        """The GDAL ``/vsicurl/`` URL for streaming reads."""
+        return self.url if self.url.startswith("/vsicurl/") else f"/vsicurl/{self.url}"
+
+    def open(self):
+        """Open the remote COG as a ``rasterio`` dataset (streamed, not downloaded)."""
+        import rasterio
+
+        _set_gdal_env()
+        return rasterio.open(self.vsicurl)
+
+    def read_window(self, lon: float, lat: float, size: float = 1.0, *,
+                    anchor: str = "center",
+                    out: "Optional[Union[str, Path]]" = None):
+        """Read a ``size``-degree lon/lat box positioned at ``(lon, lat)``.
+
+        ``anchor`` says where ``(lon, lat)`` sits on the box:
+        ``"center"`` (default), or a corner — ``"lower-left"``/``"sw"``,
+        ``"upper-left"``/``"nw"``, ``"lower-right"``/``"se"``,
+        ``"upper-right"``/``"ne"`` (degree-square tiling conventions use the SW
+        corner; raster/array origin is the NW corner).
+
+        Returns a georeferenced :class:`xarray.DataArray` (rioxarray). If ``out``
+        is given, the window is also written to that GeoTIFF. Reads only the byte
+        ranges the window needs over HTTP — no full download.
+        """
+        return read_window(self, lon, lat, size, anchor=anchor, out=out)
+
+    def read_bbox(self, west: float, south: float, east: float, north: float, *,
+                  out: "Optional[Union[str, Path]]" = None):
+        """Read an explicit lon/lat box (degrees). See :func:`read_bbox`."""
+        return read_bbox(self, west, south, east, north, out=out)
+
+
+@dataclass(frozen=True)
+class StacItem:
+    """One STAC item resolved to its COG asset — reads like a RemoteRaster."""
+
+    id: str
+    cog_url: str
+    collection: str
+    bbox: tuple = ()                 # raw STAC bbox (USGS reports it in projected m)
+    datetime: "Optional[str]" = None
+    nodata: "Optional[float]" = None
+    short: str = "stac_item"
+
+    @property
+    def vsicurl(self) -> str:
+        u = self.cog_url
+        return u if u.startswith("/vsicurl/") else f"/vsicurl/{u}"
+
+    def read_window(self, lon, lat, size=1.0, *, anchor="center", out=None):
+        return read_window(self, lon, lat, size, anchor=anchor, out=out)
+
+    def read_bbox(self, west, south, east, north, *, out=None):
+        return read_bbox(self, west, south, east, north, out=out)
+
+
+@dataclass(frozen=True)
+class StacCollection:
+    """A STAC-backed dataset: query a collection by location → COG items.
+
+    Unlike :class:`RemoteRaster` (one fixed COG), a collection holds many COGs
+    (per quad / per observation); :meth:`search` / :meth:`at` resolve a location
+    to the matching :class:`StacItem` (s), which then read like any COG.
+    """
+
+    key: str
+    short: str
+    name: str
+    body: str
+    provider: str
+    stac_url: str                    # STAC API root, e.g. ".../api"
+    collection: str                  # STAC collection id
+    kind: str = "stac"
+    asset_key: "Optional[str]" = None  # which asset to read; None = first COG asset
+    homepage: "Optional[str]" = None
+
+    def search(self, *, bbox=None, lon=None, lat=None, limit: int = 20):
+        """Items overlapping a bbox ``(west, south, east, north)`` deg, or a point."""
+        return stac_search(self, bbox=bbox, lon=lon, lat=lat, limit=limit)
+
+    def at(self, lon: float, lat: float, *, limit: int = 20):
+        """Items covering a lon/lat point."""
+        return stac_search(self, lon=lon, lat=lat, limit=limit)
+
+    def read_window(self, lon, lat, size=1.0, *, anchor="center", out=None):
+        """Convenience: read from the first item covering ``(lon, lat)``."""
+        items = self.at(lon, lat, limit=1)
+        if not items:
+            raise ValueError(
+                f"no {self.collection!r} item covers lon={lon}, lat={lat}"
+            )
+        return items[0].read_window(lon, lat, size, anchor=anchor, out=out)
+
+
+def _pick_cog_asset(assets: dict, asset_key: "Optional[str]") -> "Optional[str]":
+    """Href of the COG asset: the named one, else the first GeoTIFF/COG asset."""
+    if asset_key and asset_key in assets:
+        return assets[asset_key].get("href")
+    for a in assets.values():
+        typ = str(a.get("type", "")).lower()
+        href = a.get("href", "")
+        if "cloud-optimized" in typ or "geotiff" in typ or href.lower().endswith(".tif"):
+            return href
+    return None
+
+
+def stac_search(coll: "StacCollection", *, bbox=None, lon=None, lat=None,
+                limit: int = 20) -> "list[StacItem]":
+    """Query a STAC collection; return its COG-bearing items as StacItems.
+
+    ``bbox`` is ``(west, south, east, north)`` in degrees; or pass ``lon``/``lat``
+    for a point (expanded to a tiny box, since STAC rejects a zero-area bbox).
+    """
+    import requests
+
+    if bbox is None:
+        if lon is None or lat is None:
+            raise ValueError("provide bbox=(west, south, east, north) or lon= and lat=")
+        eps = 1e-4
+        bbox = (lon - eps, lat - eps, lon + eps, lat + eps)
+    params = {
+        "collections": coll.collection,
+        "bbox": ",".join(str(v) for v in bbox),
+        "limit": int(limit),
+    }
+    resp = requests.get(f"{coll.stac_url}/search", params=params, timeout=60)
+    resp.raise_for_status()
+    items: "list[StacItem]" = []
+    for f in resp.json().get("features", []):
+        href = _pick_cog_asset(f.get("assets", {}), coll.asset_key)
+        if not href:
+            continue
+        items.append(StacItem(
+            id=f.get("id"),
+            cog_url=href,
+            collection=coll.collection,
+            bbox=tuple(f.get("bbox", ()) or ()),
+            datetime=(f.get("properties", {}) or {}).get("datetime"),
+            short=coll.short,
+        ))
+    return items
+
+
+# ── baked-in registry (the remote-refreshed TOML from the design doc is deferred) ──
+_USGS_STAC = "https://stac.astrogeology.usgs.gov/api"
+
+_REGISTRY: dict = {
+    r.key: r
+    for r in [
+        # ── single global COG (FU Berlin / DLR) ──
+        RemoteRaster(
+            key="dlr.mars.hrsc.level3_eqc",
+            short="hrsc_level3",
+            name="HRSC level-3 global mosaic (equirectangular, IAU 49910)",
+            body="mars",
+            provider="FU Berlin / DLR (HRSC)",
+            url="https://maps.planet.fu-berlin.de/level3/level3-iau-eqc.tif",
+            crs="IAU_2015:49910",
+            kind="vsicurl",
+            nodata=-32768.0,
+            pixel_scale_m=50.0,
+            homepage="https://maps.planet.fu-berlin.de/",
+        ),
+        # ── USGS Astrogeology STAC collections (astrogeo-ard COGs) ──
+        StacCollection(
+            key="usgs.mars.themis.controlled_mosaics",
+            short="themis_mosaics",
+            name="THEMIS controlled IR mosaics (per MC quad)",
+            body="mars",
+            provider="USGS Astrogeology",
+            stac_url=_USGS_STAC,
+            collection="mo_themis_controlled_mosaics",
+            homepage="https://stac.astrogeology.usgs.gov/",
+        ),
+        StacCollection(
+            key="usgs.mars.ctx.controlled_dtms",
+            short="ctx_dtms",
+            name="CTX controlled USGS DTMs",
+            body="mars",
+            provider="USGS Astrogeology",
+            stac_url=_USGS_STAC,
+            collection="mro_ctx_controlled_usgs_dtms",
+            asset_key="geoid_adjusted_dem",
+            homepage="https://stac.astrogeology.usgs.gov/",
+        ),
+        StacCollection(
+            key="usgs.moon.lola.dtms",
+            short="lola_dtms",
+            name="Lunar Orbiter Laser Altimeter DTMs",
+            body="moon",
+            provider="USGS Astrogeology",
+            stac_url=_USGS_STAC,
+            collection="lunar_orbiter_laser_altimeter",
+            homepage="https://stac.astrogeology.usgs.gov/",
+        ),
+    ]
+}
+
+
+def list_datasets(body: "Optional[str]" = None) -> "list[RemoteRaster]":
+    """Registered rasters, optionally filtered to one body (case-insensitive)."""
+    out = list(_REGISTRY.values())
+    if body is not None:
+        out = [r for r in out if r.body == body.lower()]
+    return out
+
+
+def bodies() -> "list[str]":
+    """Sorted list of bodies that have at least one registered raster."""
+    return sorted({r.body for r in _REGISTRY.values()})
+
+
+# anchor name (and aliases) -> internal code: where (lon, lat) sits on the box.
+_ANCHOR_ALIASES = {
+    "center": "center", "centre": "center", "c": "center",
+    "lower-left": "ll", "lower left": "ll", "ll": "ll", "sw": "ll", "southwest": "ll",
+    "upper-left": "ul", "upper left": "ul", "ul": "ul", "nw": "ul", "northwest": "ul",
+    "lower-right": "lr", "lower right": "lr", "lr": "lr", "se": "lr", "southeast": "lr",
+    "upper-right": "ur", "upper right": "ur", "ur": "ur", "ne": "ur", "northeast": "ur",
+}
+
+
+def _box_lonlat(lon: float, lat: float, size: float, anchor: str):
+    """``(lon, lat, size, anchor)`` → geographic ``(west, south, east, north)``."""
+    a = _ANCHOR_ALIASES.get(str(anchor).strip().lower())
+    if a is None:
+        raise ValueError(
+            "anchor must be center / lower-left / upper-left / lower-right / "
+            f"upper-right (or sw/nw/se/ne); got {anchor!r}"
+        )
+    if a == "center":
+        h = size / 2.0
+        return (lon - h, lat - h, lon + h, lat + h)
+    if a == "ll":   # (lon, lat) is the SW corner
+        return (lon, lat, lon + size, lat + size)
+    if a == "ul":   # NW corner
+        return (lon, lat - size, lon + size, lat)
+    if a == "lr":   # SE corner
+        return (lon - size, lat, lon, lat + size)
+    return (lon - size, lat - size, lon, lat)  # "ur": NE corner
+
+
+@dataclass(frozen=True)
+class _UrlSource:
+    """Minimal readable source for a bare COG URL (no registry entry)."""
+
+    url: str
+    nodata: "Optional[float]" = None
+    short: str = "window"
+
+    @property
+    def vsicurl(self) -> str:
+        return self.url if self.url.startswith("/vsicurl/") else f"/vsicurl/{self.url}"
+
+
+def _as_source(source):
+    """Resolve a RemoteRaster / StacItem / registry key / URL to a readable source."""
+    if hasattr(source, "vsicurl"):
+        return source
+    if isinstance(source, str):
+        if source in _REGISTRY and hasattr(_REGISTRY[source], "vsicurl"):
+            return _REGISTRY[source]
+        if source.startswith(("http://", "https://", "/vsicurl/")):
+            return _UrlSource(source)
+        raise KeyError(f"{source!r} is not a readable registry key or URL")
+    raise TypeError(f"cannot read from {type(source).__name__}")
+
+
+def read_bbox(source, west: float, south: float, east: float, north: float, *,
+              out: "Optional[Union[str, Path]]" = None):
+    """Read an explicit lon/lat box (degrees) from a raster source.
+
+    ``source`` is a :class:`RemoteRaster`, a :class:`StacItem`, a registry key,
+    or a bare COG URL. The box is transformed into the file's own CRS via pyproj
+    (so this works for any body / projection, not just equirectangular), then
+    read with a single rasterio window. Returns a georeferenced
+    :class:`xarray.DataArray`; writes a GeoTIFF too when ``out`` is given. Reads
+    only the byte ranges the window needs.
+    """
+    import rasterio
+    import xarray as xr
+    from pyproj import CRS, Transformer
+    from rasterio.windows import from_bounds
+
+    import rioxarray  # noqa: F401  (registers the .rio accessor)
+
+    src = _as_source(source)
+    _set_gdal_env()
+    with rasterio.open(src.vsicurl) as ds:
+        geodetic = CRS.from_user_input(ds.crs).geodetic_crs
+        tf = Transformer.from_crs(geodetic, ds.crs, always_xy=True)
+        xs, ys = tf.transform([west, east, west, east], [south, south, north, north])
+        win = from_bounds(
+            min(xs), min(ys), max(xs), max(ys), ds.transform
+        ).round_offsets().round_lengths()
+        data = ds.read(window=win)
+        transform = ds.window_transform(win)
+        crs = ds.crs
+        nodata = src.nodata if src.nodata is not None else ds.nodata
+
+    da = xr.DataArray(
+        data, dims=("band", "y", "x"),
+        coords={"band": list(range(1, data.shape[0] + 1))},
+        name=getattr(src, "short", "window"),
+    )
+    da.rio.write_crs(crs, inplace=True)
+    da.rio.write_transform(transform, inplace=True)
+    if nodata is not None:
+        da.rio.write_nodata(nodata, inplace=True)
+    if out is not None:
+        da.rio.to_raster(str(out))
+    return da
+
+
+def read_window(source, lon: float, lat: float, size: float = 1.0, *,
+                anchor: str = "center", out: "Optional[Union[str, Path]]" = None):
+    """Read a ``size``-degree lon/lat box positioned at ``(lon, lat)``.
+
+    ``source`` is anything :func:`read_bbox` accepts (RemoteRaster, StacItem,
+    registry key, or COG URL). ``anchor`` places ``(lon, lat)`` on the box:
+    ``"center"`` (default) or a corner — ``"lower-left"``/``"sw"`` (degree-square
+    tiling convention), ``"upper-left"``/``"nw"`` (raster origin),
+    ``"lower-right"``/``"se"``, ``"upper-right"``/``"ne"``. Thin wrapper over
+    :func:`read_bbox`.
+    """
+    west, south, east, north = _box_lonlat(lon, lat, size, anchor)
+    return read_bbox(source, west, south, east, north, out=out)
+
+
+class _BodyNamespace:
+    """``datasets.mars`` — exposes that body's rasters as attributes."""
+
+    def __init__(self, body: str, rasters: "list[RemoteRaster]"):
+        self._body = body
+        self._by_short = {r.short: r for r in rasters}
+
+    def __getattr__(self, name: str) -> RemoteRaster:
+        try:
+            return self._by_short[name]
+        except KeyError:
+            raise AttributeError(
+                f"{self._body!r} has no dataset {name!r}; "
+                f"available: {sorted(self._by_short)}"
+            ) from None
+
+    def __dir__(self):
+        return list(super().__dir__()) + list(self._by_short)
+
+    def __repr__(self):
+        return f"<datasets.{self._body}: {sorted(self._by_short)}>"
+
+
+def __getattr__(name: str):
+    """``datasets.<body>`` → a body namespace (e.g. ``datasets.mars``)."""
+    rasters = [r for r in _REGISTRY.values() if r.body == name.lower()]
+    if rasters:
+        return _BodyNamespace(name.lower(), rasters)
+    raise AttributeError(f"module 'planetarypy.datasets' has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(list(globals()) + bodies()))

{planetarypy-0.76.2 → planetarypy-0.77.0}/src/planetarypy/instruments/mro/hirise.py

@@ -398,6 +398,14 @@ try:
 except ImportError:
     pass  # catalog not available
 
+# Register the HiRISE meta-display handler with the PDS meta dispatcher
+try:
+    from planetarypy.pds.meta_display import register_meta_handler
+    register_meta_handler("mro.hirise.edr", format_meta)
+    register_meta_handler("mro.hirise.rdr", format_meta)
+except ImportError:
+    pass  # pds.meta_display not available
+
 
 def _edr_base_url() -> URL:
     """Resolve EDR base URL from config."""

{planetarypy-0.76.2 → planetarypy-0.77.0}/src/planetarypy/plotting.py

@@ -4,8 +4,14 @@ Provides common visualization helpers for planetary science:
 percentile stretching, grayscale image display, sun direction indicators.
 """
 
+import warnings
+
 import numpy as np
 
+# One-shot guard so a multi-panel figure doesn't emit the experimental
+# warning once per subplot.
+_SUN_INDICATOR_WARNED = False
+
 
 def percentile_stretch(image, lo=1, hi=99):
     """Compute display limits from percentiles, ignoring zeros and NaN.
@@ -76,27 +82,34 @@ def imshow_gray(image, stretch="1,99", title=None, ax=None, **imshow_kwargs):
 
 def add_sun_indicator(ax, sun_azimuth_deg, position="upper right",
                       length=0.12, color="yellow", inner_color="orange"):
-    """Add a sun direction indicator to an image plot.
+    """Add a sun direction indicator to an image plot. **Experimental.**
+
+    .. warning::
+
+       Experimental. The azimuth-convention handoff is not fully validated:
+       this function expects **clockwise-from-image-top** (the PDS
+       ``SUB_SOLAR_AZIMUTH`` convention for *unprojected* images), but
+       :meth:`planetarypy.spice.spicer.Spicer.solar_azimuth_at` returns
+       **clockwise-from-north** (geographic). They agree only when image-north
+       points up; otherwise you must rotate by the image's north azimuth before
+       passing the value here. Placement and appearance may change.
 
-    The indicator shows a circle (sun) with a line pointing in the
-    direction of illumination. The azimuth is measured clockwise from
-    the top of the image.
+    The indicator is a small compass glyph (sun ball + arrow) drawn in a corner,
+    pointing toward the sun. It is rendered in **axes-fraction coordinates**, so
+    it neither rescales the image nor depends on the image's ``origin``.
 
     Parameters
     ----------
     ax : matplotlib.axes.Axes
         The axes containing the image.
     sun_azimuth_deg : float
-        Solar azimuth in degrees, clockwise from image top.
-        This matches the PDS `SUB_SOLAR_AZIMUTH` convention for
-        unprojected images.
+        Solar azimuth in degrees, clockwise from image top (see warning).
     position : str
-        Where to place the indicator: "upper right", "upper left",
-        "lower right", "lower left".
+        "upper right", "upper left", "lower right", "lower left".
     length : float
-        Line length as fraction of image size (default 0.12).
+        Arrow length as a fraction of the axes (default 0.12).
     color : str
-        Outer circle and line color.
+        Outer circle and arrow color.
     inner_color : str
         Inner circle color (smaller, overlaid on outer).
 
@@ -104,56 +117,62 @@ def add_sun_indicator(ax, sun_azimuth_deg, position="upper right",
     -------
     ax : matplotlib.axes.Axes
     """
-    xlim = ax.get_xlim()
-    ylim = ax.get_ylim()
-    # Image extent (works for both origin='upper' and data coords)
-    width = abs(xlim[1] - xlim[0])
-    height = abs(ylim[1] - ylim[0])
-
-    # Position the indicator
-    margin = 0.08
-    positions = {
-        "upper right": (xlim[0] + width * (1 - margin), min(ylim) + height * margin),
-        "upper left":  (xlim[0] + width * margin, min(ylim) + height * margin),
-        "lower right": (xlim[0] + width * (1 - margin), min(ylim) + height * (1 - margin)),
-        "lower left":  (xlim[0] + width * margin, min(ylim) + height * (1 - margin)),
+    global _SUN_INDICATOR_WARNED
+    if not _SUN_INDICATOR_WARNED:
+        warnings.warn(
+            "add_sun_indicator is experimental: the azimuth convention "
+            "(clockwise-from-top vs Spicer's clockwise-from-north) is not fully "
+            "validated, and placement/appearance may change.",
+            UserWarning,
+            stacklevel=2,
+        )
+        _SUN_INDICATOR_WARNED = True
+
+    L = float(length)
+    # Inset the anchor by at least the arrow length so the glyph stays inside the
+    # axes for *any* azimuth. Axes-fraction coords (y up, independent of image
+    # origin); drawing here never touches the data limits, so the image is not
+    # rescaled — the bug the old data-coordinate corner placement had.
+    inset = L + 0.06
+    corners = {
+        "upper right": (1 - inset, 1 - inset),
+        "upper left":  (inset,     1 - inset),
+        "lower right": (1 - inset, inset),
+        "lower left":  (inset,     inset),
     }
-    cx, cy = positions.get(position, positions["upper right"])
-
-    line_len = length * max(width, height)
-    az_rad = np.radians(sun_azimuth_deg)
-    # CW from top: dx = sin(az), dy = -cos(az) for origin='upper'
-    dx = line_len * np.sin(az_rad)
-    dy = -line_len * np.cos(az_rad)
+    cx, cy = corners.get(position, corners["upper right"])
 
-    # Sun circle in the sun direction, arrow points outward toward sun
+    az = np.radians(sun_azimuth_deg)
+    # Clockwise from top in axes-fraction space (y increases upward):
+    # 0deg -> up (+y), 90deg -> right (+x).
+    dx = L * np.sin(az)
+    dy = L * np.cos(az)
     sx, sy = cx + dx, cy + dy
 
-    # Shorten arrow slightly so the tip doesn't overlap the sun ball
-    shrink = 0.08 * line_len
-    norm = np.hypot(dx, dy)
-    ax_dx = dx / norm * shrink
-    ax_dy = dy / norm * shrink
+    # Stop the arrow just short of the sun ball.
+    shrink = 0.12 * L
+    norm = np.hypot(dx, dy) or 1.0
+    tipx, tipy = sx - dx / norm * shrink, sy - dy / norm * shrink
 
     ax.annotate("",
-                xy=(sx - ax_dx, sy - ax_dy),  # arrow tip (gap before sun ball)
-                xytext=(cx, cy),               # arrow tail (interior)
+                xy=(tipx, tipy), xytext=(cx, cy),
+                xycoords="axes fraction", textcoords="axes fraction",
                 arrowprops=dict(arrowstyle="-|>", color=color, lw=2.5,
                                 mutation_scale=20),
-                zorder=5)
-
-    # Sun symbol just past the arrow tip
-    ax.plot(sx, sy, "o", color=color, markersize=14, zorder=8)
-    ax.plot(sx, sy, "o", color=inner_color, markersize=9, zorder=9)
-
+                zorder=5, annotation_clip=False)
+    ax.plot(sx, sy, "o", color=color, markersize=14, zorder=8,
+            transform=ax.transAxes, clip_on=False)
+    ax.plot(sx, sy, "o", color=inner_color, markersize=9, zorder=9,
+            transform=ax.transAxes, clip_on=False)
     return ax
 
 
 def imshow_with_sun(image, sun_azimuth_deg, title=None, ax=None,
                     stretch="1,99", sun_position="upper right", **imshow_kwargs):
-    """Display a grayscale image with a sun direction indicator.
+    """Display a grayscale image with a sun direction indicator. **Experimental.**
 
-    Combines `imshow_gray` with `add_sun_indicator`.
+    Combines `imshow_gray` with `add_sun_indicator` (see that function's
+    experimental warning about the azimuth convention).
 
     Parameters
     ----------

{planetarypy-0.76.2 → planetarypy-0.77.0}/src/planetarypy/search.py

@@ -27,6 +27,8 @@ if TYPE_CHECKING:
 
 __all__ = [
     "search_products",
+    "count",
+    "bbox_from_point",
     "get_product",
     "product_file_urls",
     "fetch_pds_product",
@@ -82,6 +84,7 @@ def _build_q(
     observationals: bool,
     lidvid: Optional[str],
     query: Optional[str],
+    bbox: "Optional[tuple[float, float, float, float]]" = None,
 ) -> Optional[str]:
     """Translate keyword filters into a PDS API ``q`` clause string.
 
@@ -115,11 +118,28 @@ def _build_q(
     if lidvid:
         field = "lidvid" if "::" in lidvid else "lid"
         clauses.append(f'{field} eq "{lidvid}"')
+    if bbox is not None:
+        west, south, east, north = bbox
+        c = "cart:Bounding_Coordinates.cart:"
+        # Footprint *overlaps* the query box (intersection), not strict
+        # containment: product.west<=qe and product.east>=qw and
+        # product.south<=qn and product.north>=qs. Only matches products whose
+        # archive populated the cart:Bounding_Coordinates fields.
+        clauses += [
+            f"{c}west_bounding_coordinate le {east}",
+            f"{c}east_bounding_coordinate ge {west}",
+            f"{c}south_bounding_coordinate le {north}",
+            f"{c}north_bounding_coordinate ge {south}",
+        ]
     if query:
         clauses.append(query)
     if not clauses:
         return None
-    return " and ".join(clauses)
+    # The PDS registry API requires the whole q wrapped in outer parentheses:
+    # a bare ``A and B`` returns HTTP 400 (UnparsableQParamException), while
+    # ``(A and B)`` parses. (peppi does the same in its ResultSet before sending.)
+    # Wrapping a single clause is harmless.
+    return "(" + " and ".join(clauses) + ")"
 
 
 def _flatten(value: Any) -> Any:
@@ -151,6 +171,7 @@ def search_products(
     observationals: bool = False,
     lidvid: Optional[str] = None,
     query: Optional[str] = None,
+    bbox: "Optional[tuple[float, float, float, float]]" = None,
     fields: Optional[list[str]] = None,
     limit: int = 100,
     host: str = _DEFAULT_HOST,
@@ -176,6 +197,14 @@ def search_products(
         Raw PDS API query clause, AND-combined with the other filters — the
         escape hatch for anything the keyword filters don't cover (e.g.
         ``query='lid like "urn:nasa:pds:cassini_iss_saturn*"'``).
+    bbox : (west, south, east, north), optional
+        Spatial filter: keep products whose footprint **overlaps** this
+        longitude/latitude box (degrees), via the
+        ``cart:Bounding_Coordinates`` fields. Order matches shapely's
+        ``.bounds`` / GeoJSON bbox. Note: only products whose archive populated
+        those fields can match (often present for derived/calibrated products,
+        absent for many raw/EDR), and a product's bounding box can be degenerate
+        for polar/long-track or anti-meridian-crossing footprints.
     fields : list[str], optional
         Restrict the returned columns to these registry property names.
     limit : int
@@ -202,6 +231,7 @@ def search_products(
         observationals=observationals,
         lidvid=lidvid,
         query=query,
+        bbox=bbox,
     )
     resp = _api(host).product_list(q=q, fields=fields, limit=limit)
     rows = [
@@ -214,6 +244,61 @@ def search_products(
     return df
 
 
+def count(
+    *,
+    target: Optional[str] = None,
+    instrument: Optional[str] = None,
+    instrument_host: Optional[str] = None,
+    investigation: Optional[str] = None,
+    processing_level: Optional[str] = None,
+    before: "Optional[Union[str, _dt.datetime]]" = None,
+    after: "Optional[Union[str, _dt.datetime]]" = None,
+    observationals: bool = False,
+    lidvid: Optional[str] = None,
+    query: Optional[str] = None,
+    bbox: "Optional[tuple[float, float, float, float]]" = None,
+    host: str = _DEFAULT_HOST,
+) -> int:
+    """Number of products matching the filters, without fetching any rows.
+
+    Takes the same filter keywords as :func:`search_products`; issues a single
+    ``limit=0`` request and reads the registry's total-hit count. Useful to size
+    a result set (which :func:`search_products` would otherwise truncate at
+    ``limit``) before deciding how to page through it.
+    """
+    q = _build_q(
+        target=target,
+        instrument=instrument,
+        instrument_host=instrument_host,
+        investigation=investigation,
+        processing_level=processing_level,
+        before=before,
+        after=after,
+        observationals=observationals,
+        lidvid=lidvid,
+        query=query,
+        bbox=bbox,
+    )
+    return int(_api(host).product_list(q=q, limit=0).summary.hits)
+
+
+def bbox_from_point(
+    lon: float, lat: float, radius_deg: float
+) -> "tuple[float, float, float, float]":
+    """Build a ``(west, south, east, north)`` box of ``±radius_deg`` around a point.
+
+    Convenience for the ``bbox=`` filter of :func:`search_products` — e.g. "data
+    within 1° of Jezero". Latitude is clamped to ``[-90, 90]``; longitude is
+    returned as-is (no anti-meridian wrapping), so use small radii near ±180°.
+    """
+    return (
+        lon - radius_deg,
+        max(-90.0, lat - radius_deg),
+        lon + radius_deg,
+        min(90.0, lat + radius_deg),
+    )
+
+
 def get_product(lidvid: str, *, host: str = _DEFAULT_HOST) -> dict:
     """Return one product's registry properties by LIDVID (or LID).
 

{planetarypy-0.76.2 → planetarypy-0.77.0}/src/planetarypy/spice/archived_kernels.py

@@ -20,6 +20,7 @@ __all__ = [
     "list_cached_kernels",
 ]
 
+import re
 import zipfile
 from datetime import timedelta
 from io import BytesIO
@@ -516,18 +517,35 @@ class Subsetter:
             else self.save_location
         )
         savepath = basepath / self.metakernel_file
-        with (
-            open(savepath, "w") as outfile,
-            self.z.open(self.metakernel_file) as infile,
-        ):
-            for line in infile:
-                linestr = line.decode()
-                if "'./data'" in linestr:
-                    linestr = linestr.replace("'./data'", f"'{savepath.parent}'")
-                outfile.write(linestr)
+        text = self.z.read(self.metakernel_file).decode()
+        savepath.write_text(_repoint_path_values(text, str(savepath.parent)))
         return savepath
 
 
+def _repoint_path_values(text: str, abspath: str) -> str:
+    """Rewrite a metakernel's ``PATH_VALUES`` to the local kernel directory.
+
+    NAIF archive metakernels use different relative conventions for
+    ``PATH_VALUES`` — most missions ship ``'./data'``, but some (e.g. Hayabusa2's
+    PDS4 archive) ship ``'..'``. Replace whatever single-quoted value the
+    ``PATH_VALUES = ( … )`` block holds with ``abspath``, leaving every other line
+    (notably ``KERNELS_TO_LOAD``'s ``$SYMBOL/…`` references) untouched. The old
+    code matched the ``'./data'`` literal only, so it silently no-opped on ``'..'``
+    and left an unresolvable path that broke ``furnsh``.
+    """
+    out = []
+    in_path_values = False
+    for line in text.splitlines(keepends=True):
+        if "PATH_VALUES" in line:
+            in_path_values = True
+        if in_path_values:
+            line = re.sub(r"'[^']*'", f"'{abspath}'", line)
+            if ")" in line:
+                in_path_values = False
+        out.append(line)
+    return "".join(out)
+
+
 def get_metakernel_and_files(
     mission: str, start: str, stop: str, save_location: str = None, quiet: bool = False
 ) -> str: