lunar-toolkit 0.1.0.dev2__py3-none-any.whl

lunar_toolkit/cli/build_db.py

@@ -0,0 +1,130 @@
+"""build-db - download CUMINDEX files and build local Parquet databases."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from ..constants import DATASETS, DEFAULT_CACHE_DIR
+
+COMMAND = "build-db"
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        COMMAND,
+        help="Build the local Parquet index database(s).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples
+--------
+  lunar build-db              # EDR only (default)
+  lunar build-db edr cdr      # EDR and CDR
+  lunar build-db --all        # EDR, CDR, and RDR
+  lunar build-db edr --force  # rebuild even if exists
+  lunar build-db edr --update # append PDS volumes newer than the built release
+  lunar build-db edr --release LROLRC_0066C --volume-only   # one volume (~20k rows)
+""",
+    )
+    p.add_argument(
+        "datasets",
+        nargs="*",
+        metavar="DATASET",
+        help="Datasets to build: edr, cdr, rdr (default: edr if none given).",
+    )
+    p.add_argument(
+        "--all",
+        action="store_true",
+        help="Build all three datasets: edr, cdr, rdr.",
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Rebuild even if the Parquet already exists.",
+    )
+    p.add_argument(
+        "--update",
+        action="store_true",
+        help="Append newer per-volume INDEX.TABs to an existing database.",
+    )
+    p.add_argument(
+        "--release",
+        default=None,
+        metavar="VOLUME",
+        help="Build from this PDS volume, e.g. LROLRC_0066C (default: newest on the server).",
+    )
+    p.add_argument(
+        "--volume-only",
+        action="store_true",
+        help="Use the volume's own INDEX/INDEX.TAB instead of the cumulative CUMINDEX.TAB.",
+    )
+    p.add_argument(
+        "--wkt",
+        action="store_true",
+        help="Also store an FP_WKT footprint polygon column.",
+    )
+    p.add_argument(
+        "--memory-limit",
+        default="4GB",
+        metavar="SIZE",
+        help="DuckDB memory limit; sorting spills to disk beyond it (default: 4GB).",
+    )
+    p.add_argument(
+        "--threads",
+        type=int,
+        default=None,
+        metavar="N",
+        help="DuckDB worker threads (default: all cores).",
+    )
+    p.add_argument(
+        "--data-dir",
+        type=Path,
+        default=None,
+        metavar="DIR",
+        help="Where to write Parquet files (default: LUNAR_DATA_DIR or the user data dir).",
+    )
+    p.add_argument(
+        "--cache-dir",
+        default=str(DEFAULT_CACHE_DIR),
+        metavar="DIR",
+        help=f"Where to cache raw TAB/LBL downloads (default: {DEFAULT_CACHE_DIR}).",
+    )
+
+
+def run(args: argparse.Namespace) -> int:
+    from ..lroc.cumindex import CumIndex
+
+    if args.all:
+        datasets = list(DATASETS)
+    elif args.datasets:
+        invalid = [d for d in args.datasets if d not in DATASETS]
+        if invalid:
+            print(
+                f"Unknown dataset(s): {', '.join(invalid)}. Choose from: {', '.join(DATASETS)}",
+                file=sys.stderr,
+            )
+            return 1
+        datasets = args.datasets
+    else:
+        datasets = ["edr"]
+
+    cache_dir = Path(args.cache_dir)
+
+    for dataset in datasets:
+        ds = DATASETS[dataset]
+        print(f"\n{ds['label']}")
+        ci = CumIndex(dataset=dataset, data_dir=args.data_dir, cache_dir=cache_dir)
+        print(f"   Parquet : {ci.parquet_path}")
+        print(f"   Cache   : {cache_dir}")
+        if args.update and ci.parquet_path.exists() and not args.force:
+            ci.update_db(memory_limit=args.memory_limit, threads=args.threads)
+            continue
+        ci.build_db(
+            force=args.force,
+            release=args.release,
+            volume_only=args.volume_only,
+            memory_limit=args.memory_limit,
+            threads=args.threads,
+            wkt=args.wkt,
+        )
+
+    return 0

lunar_toolkit/cli/download.py

@@ -0,0 +1,111 @@
+"""download - download LROC image files by product ID, text file, or URL."""
+
+import argparse
+import sys
+from pathlib import Path
+
+COMMAND = "download"
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        COMMAND,
+        help="Download LROC image files to a local directory.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples
+--------
+  lunar download M1096757719LE M1096757719RE
+  lunar download M1096757719LE --output-dir ./raw
+  lunar download --from-file ids.txt --output-dir ./raw
+  lunar download https://pds.lroc.im-ldi.com/data/.../M1096757719LE.IMG
+  lunar download M1096757719LC --dataset cdr  # CDR image
+
+Files already in --output-dir are skipped (use --force to download them again);
+interrupted downloads resume from their .part file.
+""",
+    )
+    p.add_argument(
+        "sources",
+        nargs="*",
+        metavar="SOURCE",
+        help="Product IDs (e.g. M1096757719LE) or PDS URLs.",
+    )
+    p.add_argument(
+        "--from-file",
+        metavar="FILE",
+        help="Text file of product IDs or URLs, one per line (#comments ignored).",
+    )
+    p.add_argument(
+        "--output-dir",
+        default=None,
+        metavar="DIR",
+        help="Destination directory (default: current working directory).",
+    )
+    p.add_argument(
+        "--dataset",
+        choices=["edr", "cdr"],
+        default="edr",
+        help="Download each image's raw EDR or calibrated CDR file (default: edr); "
+        "IDs are looked up in the index matching their LE/RE or LC/RC suffix.",
+    )
+    p.add_argument("--force", action="store_true", help="Download again even if the file exists.")
+    p.add_argument(
+        "--workers",
+        type=int,
+        default=8,
+        metavar="N",
+        help="Parallel download workers (default: 8).",
+    )
+    p.add_argument(
+        "--data-dir",
+        type=Path,
+        default=None,
+        metavar="DIR",
+        help="Override Parquet data directory.",
+    )
+
+
+def run(args: argparse.Namespace) -> int:
+    from ..downloader import PdsDownloader
+    from ..lroc.nac import NacImageCollection
+    from ._utils import load_sources
+
+    sources = load_sources(args)
+    if not sources:
+        print("No sources provided. Pass product IDs, URLs, or --from-file.", file=sys.stderr)
+        return 1
+
+    output_dir = Path(args.output_dir) if args.output_dir else Path.cwd()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    raw_urls = [s.strip() for s in sources if s.strip().startswith(("http://", "https://"))]
+    id_sources = [s for s in sources if not s.strip().startswith(("http://", "https://"))]
+
+    ok = fail = 0
+
+    if id_sources:
+        collection = NacImageCollection.from_sources(id_sources, data_dir=args.data_dir)
+        if not collection:
+            print("No product IDs found in the index.", file=sys.stderr)
+        else:
+            if args.dataset == "cdr":
+                results = collection.download_cdrs(output_dir, workers=args.workers, force=args.force)
+            else:
+                results = collection.download_edrs(output_dir, workers=args.workers, force=args.force)
+            ok += sum(1 for p in results.values() if p is not None)
+            fail += sum(1 for p in results.values() if p is None)
+
+    if raw_urls:
+        print(f"Downloading {len(raw_urls)} URL(s) to {output_dir} ...")
+        dl = PdsDownloader(max_workers=args.workers)
+        url_results = dl.download_urls(raw_urls, output_dir, force=args.force)
+        ok += sum(1 for p in url_results.values() if p is not None)
+        fail += sum(1 for p in url_results.values() if p is None)
+
+    if ok == 0 and fail == 0:
+        print("Nothing to download.", file=sys.stderr)
+        return 1
+
+    print(f"Done: {ok} succeeded{f', {fail} failed' if fail else ''}.")
+    return 0 if fail == 0 else 1

lunar_toolkit/cli/kaguya.py

@@ -0,0 +1,253 @@
+"""kaguya - download Kaguya TC (Level 2B0) or MI (Level 2B2) products and import them into ISIS."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+COMMAND = "kaguya"
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        COMMAND,
+        help="Download Kaguya TC / MI images and import them into ISIS (cube + CSM camera).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples
+--------
+  lunar kaguya TC1W2B0_01_02936N034E0938 TC2W2B0_01_02936N036E0938 -o ./tc
+  lunar kaguya --point 34.0 93.8 --radius-km 2 --limit 4 -o ./tc
+  lunar kaguya --bbox 93.5 33.9 94.0 34.1 --product-type mono --inc 40 70 -o ./tc
+  lunar kaguya ./tc/TC1W2B0_01_02936N034E0938.lbl --mapproject --resolution 10
+  lunar kaguya TC1W2B0_01_02936N034E0938 --download-only
+  lunar kaguya TC1W2B0_01_02936N034E0938 --dry-run
+  lunar kaguya MVA_2B2_01_01935N340E0939 MNA_2B2_01_01935N339E0939 -o ./mi
+  lunar kaguya --instrument mi --point 34.0 93.9 --product-type nir --limit 2 -o ./mi
+
+Per product, <output-dir> gets <id>.lbl, <id>.cub (kaguyatc2isis / kaguyami2isis
++ spiceinit), <id>.json (CSM camera from isd_generate) and, with --mapproject,
+<id>.tif.  MI cubes hold all VIS (5) or NIR (4) bands; ALE's MI drivers need
+local kernels, so MI CSM cameras default to --no-web runs only (--csm forces).
+The instrument is inferred from the product IDs (MI: M[VN]A_2B2_...) unless
+--instrument is given.
+Steps whose output exists are skipped (use --force to redo them).
+--bbox is WEST SOUTH EAST NORTH, longitudes positive east.
+""",
+    )
+    p.add_argument(
+        "sources",
+        nargs="*",
+        metavar="SOURCE",
+        help="TC / MI product IDs (e.g. TC1W2B0_01_02936N034E0938) or local .lbl files.",
+    )
+    p.add_argument(
+        "--instrument",
+        "-i",
+        choices=("tc", "mi"),
+        default=None,
+        help="Terrain Camera or Multiband Imager (default: from SOURCE, else tc).",
+    )
+    p.add_argument(
+        "--from-file", metavar="FILE", help="Text file of sources, one per line (#comments ignored)."
+    )
+    p.add_argument(
+        "--output-dir",
+        "-o",
+        default=None,
+        metavar="DIR",
+        help="Output directory (default: current working directory).",
+    )
+
+    search = p.add_argument_group("ODE search (instead of / in addition to SOURCE)")
+    region = search.add_mutually_exclusive_group()
+    region.add_argument(
+        "--bbox",
+        nargs=4,
+        type=float,
+        metavar=("WEST", "SOUTH", "EAST", "NORTH"),
+        help="Bounding box in degrees.",
+    )
+    region.add_argument(
+        "--point",
+        nargs=2,
+        type=float,
+        metavar=("LAT", "LON"),
+        help="Search around a point (use with --radius-km).",
+    )
+    search.add_argument(
+        "--radius-km", type=float, default=1.0, metavar="KM", help="Radius for --point (default: 1 km)."
+    )
+    search.add_argument(
+        "--product-type",
+        "-t",
+        default=None,
+        metavar="PT",
+        help="TC: stereo (TCWL2B, default) or mono (TCSL2B); MI: vis (VIS2B, default) or nir (NIR2B).",
+    )
+    search.add_argument("--inc", nargs=2, type=float, metavar=("MIN", "MAX"), help="Incidence angle range.")
+    search.add_argument("--emi", nargs=2, type=float, metavar=("MIN", "MAX"), help="Emission angle range.")
+    search.add_argument("--phase", nargs=2, type=float, metavar=("MIN", "MAX"), help="Phase angle range.")
+    search.add_argument("--time", nargs=2, metavar=("START", "END"), help="Observation time range (UTC).")
+    search.add_argument(
+        "--limit",
+        type=int,
+        default=10,
+        metavar="N",
+        help="Maximum number of products from the search (default: 10).",
+    )
+
+    isis = p.add_argument_group("ISIS import")
+    isis.add_argument(
+        "--no-web",
+        dest="web",
+        action="store_false",
+        help="spiceinit with local kernels ($ISISDATA/kaguya) instead of the web service.",
+    )
+    isis.add_argument(
+        "--shape",
+        default="system",
+        metavar="SHAPE",
+        help="spiceinit shape: system (LOLA DEM in $ISISDATA/base/dems, default) or ellipsoid.",
+    )
+    isis.add_argument(
+        "--csm",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Write a CSM camera (.json) with isd_generate (default: TC always, MI with --no-web).",
+    )
+    isis.add_argument(
+        "--only-naif-spice",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="TC: pass --only_naif_spice to isd_generate (default: with --no-web; MI always).",
+    )
+    isis.add_argument("--mapproject", action="store_true", help="Also cam2map and write <id>.tif.")
+    isis.add_argument(
+        "--projection",
+        default="equirectangular",
+        metavar="PROJ",
+        help="ISIS projection for --mapproject (default: equirectangular).",
+    )
+    isis.add_argument(
+        "--resolution",
+        type=float,
+        default=None,
+        metavar="M",
+        help="Map resolution in m/pixel for --mapproject.",
+    )
+    isis.add_argument("--keep", action="store_true", help="Keep the PDS .img and the map-projected cube.")
+    isis.add_argument("--force", action="store_true", help="Redo steps whose output exists.")
+    isis.add_argument(
+        "--download-only", action="store_true", help="Download (and gunzip) only; no ISIS processing."
+    )
+    isis.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the ISIS commands without downloading or running anything.",
+    )
+    isis.add_argument(
+        "--workers", type=int, default=1, metavar="N", help="Products processed in parallel (default: 1)."
+    )
+
+
+def run(args: argparse.Namespace) -> int:
+    from ..downloader import url_filename
+    from ..kaguya import mi, tc
+    from ..ode import OdeClient, OdeError
+    from ._utils import load_sources, ode_filters, print_dry_run, region_args
+
+    sources = load_sources(args)
+    if not sources and not (args.bbox or args.point):
+        print("No sources. Pass product IDs, .lbl paths, --from-file, --bbox or --point.", file=sys.stderr)
+        return 1
+
+    instrument = args.instrument or (
+        "mi" if any(mi.is_mi_product_id(Path(s).name.split(".")[0]) for s in sources) else "tc"
+    )
+    steps: dict[str, tuple[Any, Any, Any]] = {
+        "mi": (mi.lookup_mi_products, mi.mi_products, mi.download_mi_product),
+        "tc": (tc.lookup_products, tc.tc_products, tc.download_product),
+    }
+    lookup, select, download = steps[instrument]
+
+    labels = [Path(s) for s in sources if s.lower().endswith(".lbl")]
+    ids = [s for s in sources if not s.lower().endswith(".lbl")]
+    client = OdeClient()
+    try:
+        products: list[Any] = select(lookup(ids, client)) if ids else []
+        if args.bbox or args.point:
+            products += select(
+                client.search(
+                    f"kaguya_{instrument}",
+                    args.product_type,
+                    max_results=args.limit,
+                    **region_args(args),
+                    **ode_filters(args),
+                )
+            )
+    except (OdeError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    products = list({p.product_id: p for p in products}.values())
+    seen = {p.product_id for p in products}
+    for missing in sorted({i.upper() for i in ids} - seen):
+        print(f"  {missing}  -  not found on ODE", file=sys.stderr)
+
+    output_dir = Path(args.output_dir) if args.output_dir else Path.cwd()
+    print(f"{len(products) + len(labels)} Kaguya {instrument.upper()} product(s) -> {output_dir}")
+    for p in products:
+        size = f"  ({p.image_kbytes / 1024:.0f} MB)" if p.image_kbytes else ""
+        print(f"  {p.product_id}{size}")
+
+    if args.download_only:
+        failed = 0
+        for p in products:
+            try:
+                print(f"  {p.product_id}  ->  {download(p, output_dir, force=args.force)}")
+            except Exception as exc:
+                print(f"  {p.product_id}  -  FAILED: {exc}", file=sys.stderr)
+                failed += 1
+        return 1 if failed else 0
+
+    common: dict[str, Any] = {
+        "web": args.web,
+        "mapproject": args.mapproject,
+        "projection": args.projection,
+        "resolution": args.resolution,
+        "keep": args.keep,
+        "force": args.force,
+        "spiceinit_params": {"shape": args.shape},
+    }
+    proc: tc.TcProcessor | mi.MiProcessor
+    if instrument == "mi":
+        proc = mi.MiProcessor(output_dir, csm=args.csm, **common)
+    else:
+        proc = tc.TcProcessor(
+            output_dir, csm=args.csm is not False, only_naif_spice=args.only_naif_spice, **common
+        )
+    if args.dry_run:
+
+        def import_all() -> None:
+            for p in products:
+                proc.import_label(output_dir / url_filename(p.label_url))
+            for lbl in labels:
+                proc.import_label(lbl)
+
+        print_dry_run(import_all)
+        return 0
+
+    sources_all: list = [*products, *labels]
+    results = proc.process_batch(sources_all, max_workers=args.workers)
+    ok = 0
+    for src, out in zip(sources_all, results):
+        name = src.name if isinstance(src, Path) else src.product_id
+        if out is None:
+            print(f"  {name}  -  FAILED", file=sys.stderr)
+            continue
+        ok += 1
+        files = [f for f in (out.cube, out.camera, out.geotiff) if f]
+        print(f"  {name}  ->  {', '.join(str(f) for f in files)}")
+    return 0 if ok == len(sources_all) else 1

lunar_toolkit/cli/ode_search.py

@@ -0,0 +1,144 @@
+"""ode-search - search ShadowCam / LROC / Kaguya TC products via ODE REST."""
+
+import argparse
+import sys
+from pathlib import Path
+
+COMMAND = "ode-search"
+
+
+def add_parser(sub: argparse._SubParsersAction) -> None:
+    from ..ode import INSTRUMENTS
+
+    types = "; ".join(f"{k}: {', '.join(v['product_types'])}" for k, v in INSTRUMENTS.items())
+    p = sub.add_parser(
+        COMMAND,
+        help="Search lunar products (ShadowCam, LROC NAC, Kaguya TC) via the ODE REST API.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=f"""
+Examples
+--------
+  lunar ode-search --instrument shadowcam --bbox 0 -90 360 -89 --inc 80 90
+  lunar ode-search --instrument shadowcam --point -89.67 129.8 --radius-km 15
+  lunar ode-search --instrument lroc --product-type cdr --bbox 355 -1 5 1 --csv hits.csv
+  lunar ode-search --instrument shadowcam --point -89.67 129.8 --radius-km 5 \\
+      --download ./shadowcam --kind product
+  lunar ode-search --instrument shadowcam --aoi aoi.geojson   # QuickMap polygon
+
+Product types - {types}
+(raw ODE pt codes such as EDRNAC4 are accepted too).
+--bbox is WEST SOUTH EAST NORTH, longitudes positive east; WEST > EAST crosses 0/360.
+--aoi takes a GeoJSON / WKT file or a WKT string; ODE is queried with its bounding
+box and footprints are then intersected with the polygon.
+""",
+    )
+    p.add_argument(
+        "--instrument",
+        "-i",
+        default="shadowcam",
+        help=f"Instrument: {', '.join(INSTRUMENTS)} (default: shadowcam).",
+    )
+    p.add_argument(
+        "--product-type",
+        "-t",
+        default=None,
+        metavar="PT",
+        help="Product type alias or ODE pt code (default: instrument's default).",
+    )
+    region = p.add_mutually_exclusive_group()
+    region.add_argument(
+        "--bbox",
+        nargs=4,
+        type=float,
+        metavar=("WEST", "SOUTH", "EAST", "NORTH"),
+        help="Bounding box in degrees.",
+    )
+    region.add_argument(
+        "--point",
+        nargs=2,
+        type=float,
+        metavar=("LAT", "LON"),
+        help="Search around a point (use with --radius-km).",
+    )
+    region.add_argument(
+        "--aoi", metavar="FILE_OR_WKT", help="Area of interest: GeoJSON / WKT file or WKT polygon string."
+    )
+    p.add_argument(
+        "--radius-km", type=float, default=1.0, metavar="KM", help="Radius for --point (default: 1 km)."
+    )
+    p.add_argument("--inc", nargs=2, type=float, metavar=("MIN", "MAX"), help="Incidence angle range.")
+    p.add_argument("--emi", nargs=2, type=float, metavar=("MIN", "MAX"), help="Emission angle range.")
+    p.add_argument("--phase", nargs=2, type=float, metavar=("MIN", "MAX"), help="Phase angle range.")
+    p.add_argument(
+        "--time",
+        nargs=2,
+        metavar=("START", "END"),
+        help="Observation time range (UTC, e.g. 2023-01-01 2023-12-31).",
+    )
+    p.add_argument(
+        "--limit",
+        type=int,
+        default=200,
+        metavar="N",
+        help="Maximum number of products to return (default: 200).",
+    )
+    p.add_argument("--count", action="store_true", help="Only print the number of matches.")
+    p.add_argument("--csv", metavar="FILE", help="Write results (common schema) to CSV.")
+    p.add_argument("--download", metavar="DIR", help="Download the selected files to DIR.")
+    p.add_argument(
+        "--kind",
+        default="product",
+        help="Files to download: product, label, browse, referenced, derived, all.",
+    )
+    p.add_argument(
+        "--match",
+        default=None,
+        metavar="TEXT",
+        help="Only download files whose name contains TEXT (e.g. _cog.tif).",
+    )
+    p.add_argument(
+        "--workers", type=int, default=4, metavar="N", help="Parallel download workers (default: 4)."
+    )
+
+
+def run(args: argparse.Namespace) -> int:
+    from ..ode import OdeClient, OdeError
+    from ._utils import ode_filters, region_args
+
+    region, filters = region_args(args), ode_filters(args)
+
+    client = OdeClient()
+    try:
+        if args.count:
+            print(client.count(args.instrument, args.product_type, **region, **filters))
+            return 0
+        df = client.search(args.instrument, args.product_type, max_results=args.limit, **region, **filters)
+    except (OdeError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"{len(df)} product(s)")
+    if not df.empty:
+        cols = [
+            "product_id",
+            "product_type",
+            "start_time",
+            "center_lat",
+            "center_lon",
+            "incidence",
+            "emission",
+            "phase",
+            "pixel_scale",
+        ]
+        print(df[cols].to_string(index=False, max_rows=50))
+    if args.csv:
+        df.drop(columns=["files"]).to_csv(args.csv, index=False)
+        print(f"Wrote {args.csv}")
+    if args.download and not df.empty:
+        results = client.download(
+            df, Path(args.download), kind=args.kind, match=args.match, workers=args.workers
+        )
+        failed = sum(1 for p in results.values() if p is None)
+        print(f"Downloaded {len(results) - failed}/{len(results)} file(s).")
+        return 1 if failed else 0
+    return 0