besselian2shape 0.1.0__py3-none-any.whl

besselian2shape/__init__.py

@@ -0,0 +1,16 @@
+from .cache import download_besselian_csv, get_cache_dir, get_cached_csv_path
+from .cli import main
+from .elements import BesselianElements, find_by_date, load_all
+from .export import generate_eclipse_kml, generate_eclipse_shapefiles
+
+__all__ = [
+    "BesselianElements",
+    "download_besselian_csv",
+    "find_by_date",
+    "generate_eclipse_kml",
+    "generate_eclipse_shapefiles",
+    "get_cache_dir",
+    "get_cached_csv_path",
+    "load_all",
+    "main",
+]

besselian2shape/cache.py

@@ -0,0 +1,51 @@
+"""Download and local caching of NASA's Besselian elements dataset."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import requests
+from platformdirs import user_cache_dir
+
+BESSELIAN_ELEMENTS_URL = (
+    "https://eclipse.gsfc.nasa.gov/eclipse_besselian_from_mysqldump2.csv"
+)
+
+APP_NAME = "besselian2shape"
+
+
+def get_cache_dir() -> Path:
+    """Return the local cache directory, creating it if necessary."""
+    cache_dir = Path(user_cache_dir(APP_NAME))
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def get_cached_csv_path() -> Path:
+    """Return the path where the Besselian elements CSV is (or will be) cached."""
+    return get_cache_dir() / "eclipse_besselian_from_mysqldump2.csv"
+
+
+def download_besselian_csv(force: bool = False) -> Path:
+    """Ensure the NASA Besselian elements CSV is cached locally, downloading it
+    if it is not already present (or if `force` is True).
+
+    Returns the path to the cached file.
+    """
+    dest = get_cached_csv_path()
+    if dest.exists() and not force:
+        return dest
+
+    response = requests.get(BESSELIAN_ELEMENTS_URL, stream=True, timeout=60)
+    response.raise_for_status()
+
+    tmp_path = dest.with_suffix(dest.suffix + ".part")
+    try:
+        with open(tmp_path, "wb") as f:
+            shutil.copyfileobj(response.raw, f)
+        tmp_path.replace(dest)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+    return dest

besselian2shape/cli.py

@@ -0,0 +1,127 @@
+"""Command-line interface for besselian2shape."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .cache import download_besselian_csv
+from .elements import find_by_date
+from .export import generate_eclipse_kml, generate_eclipse_shapefiles
+
+_ALL_FORMATS = ("shp", "kml", "kmz")
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="besselian2shape",
+        description="Generate ESRI shapefiles and/or KML/KMZ files for a solar eclipse's path.",
+    )
+    parser.add_argument(
+        "year",
+        type=int,
+        help="eclipse year, astronomical numbering (1 BCE = 0, 2 BCE = -1, ...)",
+    )
+    parser.add_argument("month", type=int, help="eclipse month (1-12)")
+    parser.add_argument("day", type=int, help="eclipse day of month")
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        metavar="DIR",
+        help="output directory (default: ./eclipse_YYYY-MM-DD)",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        dest="formats",
+        action="append",
+        choices=(*_ALL_FORMATS, "all"),
+        metavar="{shp,kml,kmz,all}",
+        help="output format to generate; may be repeated (default: shp)",
+    )
+    parser.add_argument(
+        "--step-minutes",
+        type=float,
+        default=0.5,
+        metavar="MINUTES",
+        help="time resolution used to sample the eclipse path (default: 0.5)",
+    )
+    parser.add_argument(
+        "--penumbral-resolution",
+        type=float,
+        default=0.25,
+        metavar="DEGREES",
+        help="grid resolution for the penumbral visibility boundary (default: 0.25)",
+    )
+    parser.add_argument(
+        "--penumbral-step-minutes",
+        type=float,
+        default=1.5,
+        metavar="MINUTES",
+        help="time step for the penumbral visibility raster scan (default: 1.5)",
+    )
+    parser.add_argument(
+        "--refresh-cache",
+        action="store_true",
+        help="re-download the Besselian elements dataset even if already cached",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+
+    formats = list(dict.fromkeys(args.formats or ["shp"]))  # de-dupe, preserve order
+    if "all" in formats:
+        formats = list(_ALL_FORMATS)
+
+    if args.refresh_cache:
+        print("Refreshing cached Besselian elements dataset...", file=sys.stderr)
+        download_besselian_csv(force=True)
+
+    try:
+        elements = find_by_date(args.year, args.month, args.day)
+    except LookupError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    output_dir = args.output or Path(f"eclipse_{args.year:04d}-{args.month:02d}-{args.day:02d}")
+
+    if "shp" in formats:
+        written = generate_eclipse_shapefiles(
+            args.year,
+            args.month,
+            args.day,
+            output_dir,
+            step_minutes=args.step_minutes,
+            elements=elements,
+            penumbral_resolution_deg=args.penumbral_resolution,
+            penumbral_step_minutes=args.penumbral_step_minutes,
+        )
+        for name, path in written.items():
+            print(f"wrote {name}: {path}")
+
+    for fmt in ("kml", "kmz"):
+        if fmt not in formats:
+            continue
+        out_path = output_dir / f"eclipse.{fmt}"
+        written_path = generate_eclipse_kml(
+            args.year,
+            args.month,
+            args.day,
+            out_path,
+            step_minutes=args.step_minutes,
+            elements=elements,
+            penumbral_resolution_deg=args.penumbral_resolution,
+            penumbral_step_minutes=args.penumbral_step_minutes,
+        )
+        print(f"wrote {fmt}: {written_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

besselian2shape/elements.py

@@ -0,0 +1,138 @@
+"""Parsing of NASA's Besselian elements CSV and lookup by date."""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass, fields
+from pathlib import Path
+
+from .cache import download_besselian_csv
+
+_INT_FIELDS = {
+    "year", "month", "day", "luna_num", "saros", "cat_no", "canon_plate",
+    "etype", "PNS", "UNS", "NCN", "nSer", "nSeq", "nJLE",
+}
+
+_FLOAT_FIELDS = {
+    "dt", "gamma", "magnitude", "lat_dd_ge", "lng_dd_ge", "sun_alt", "sun_azm",
+    "path_width", "duration_secs", "julian_date", "t0",
+    "x0", "x1", "x2", "x3", "y0", "y1", "y2", "y3", "d0", "d1", "d2",
+    "mu0", "mu1", "mu2", "l10", "l11", "l12", "l20", "l21", "l22",
+    "tan_f1", "tan_f2", "tmin", "tmax",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class BesselianElements:
+    """Besselian elements and metadata for a single solar eclipse.
+
+    Field names and units follow NASA's Five Millennium Canon of Solar
+    Eclipses mysqldump export: x/y are the coordinates of the shadow axis
+    on the fundamental plane, d/mu describe the axis's declination and
+    hour angle, l1/l2 are the penumbral/umbral radii, and tan_f1/tan_f2
+    are the penumbral/umbral cone angles. All are polynomials in time (in
+    hours) measured from t0 (TDT), valid over [tmin, tmax].
+    """
+
+    year: int
+    month: int
+    day: int
+    td_ge: str
+    dt: float
+    luna_num: int
+    saros: int
+    eclipse_type: str
+    gamma: float
+    magnitude: float
+    lat_ge: str
+    lng_ge: str
+    lat_dd_ge: float
+    lng_dd_ge: float
+    sun_alt: float
+    sun_azm: float
+    path_width: float
+    central_duration: str
+    duration_secs: float
+    cat_no: int
+    canon_plate: int
+    julian_date: float
+    t0: float
+    x0: float
+    x1: float
+    x2: float
+    x3: float
+    y0: float
+    y1: float
+    y2: float
+    y3: float
+    d0: float
+    d1: float
+    d2: float
+    mu0: float
+    mu1: float
+    mu2: float
+    l10: float
+    l11: float
+    l12: float
+    l20: float
+    l21: float
+    l22: float
+    tan_f1: float
+    tan_f2: float
+    tmin: float
+    tmax: float
+    etype: int
+    PNS: int
+    UNS: int
+    NCN: int
+    nSer: int
+    nSeq: int
+    nJLE: int
+
+    @classmethod
+    def from_row(cls, row: dict[str, str]) -> "BesselianElements":
+        kwargs = {}
+        for f in fields(cls):
+            raw = row[f.name]
+            if f.name in _INT_FIELDS:
+                kwargs[f.name] = int(float(raw))
+            elif f.name in _FLOAT_FIELDS:
+                kwargs[f.name] = float(raw)
+            else:
+                kwargs[f.name] = raw
+        return cls(**kwargs)
+
+
+def load_all(csv_path: Path | None = None) -> list[BesselianElements]:
+    """Load every eclipse's Besselian elements from the (cached) CSV.
+
+    Downloads and caches the CSV first if `csv_path` is not given and no
+    cached copy exists yet.
+    """
+    path = csv_path if csv_path is not None else download_besselian_csv()
+    with open(path, newline="", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        return [BesselianElements.from_row(row) for row in reader]
+
+
+def find_by_date(
+    year: int, month: int, day: int, csv_path: Path | None = None
+) -> BesselianElements:
+    """Return the Besselian elements for the solar eclipse on the given
+    (proleptic Gregorian, astronomical-numbered) calendar date.
+
+    Use astronomical year numbering for BCE dates (e.g. 1 BCE is year 0,
+    2 BCE is year -1). Raises LookupError if no eclipse occurred on that
+    date in the dataset.
+    """
+    matches = [
+        e for e in load_all(csv_path)
+        if e.year == year and e.month == month and e.day == day
+    ]
+    if not matches:
+        raise LookupError(f"No solar eclipse found for {year:04d}-{month:02d}-{day:02d}")
+    if len(matches) > 1:
+        raise LookupError(
+            f"Multiple eclipses found for {year:04d}-{month:02d}-{day:02d}: {matches}"
+        )
+    return matches[0]

besselian2shape/export.py

@@ -0,0 +1,178 @@
+"""Top-level API: generate ESRI shapefiles or KML/KMZ for a solar eclipse
+by date.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import kml as kml_writer
+from .elements import BesselianElements, find_by_date
+from .geometry import central_line, is_central, limits_to_ring, umbral_limits
+from .raster import penumbral_coverage_rings
+from .shapefiles import (
+    write_polygon_shapefile,
+    write_polygon_shapefile_with_holes,
+    write_polyline_shapefile,
+)
+
+# Grid resolution and time step for the penumbral visibility raster scan
+# (see raster.py). The path/umbral computation's own `step_minutes` isn't
+# reused here -- it controls sampling density along a 1-D analytic curve,
+# a different kind of parameter from a 2-D grid's resolution.
+_PENUMBRAL_RESOLUTION_DEG = 0.25
+_PENUMBRAL_STEP_MINUTES = 1.5
+
+
+class _Layers:
+    def __init__(
+        self,
+        e: BesselianElements,
+        step_minutes: float,
+        penumbral_resolution_deg: float,
+        penumbral_step_minutes: float,
+    ):
+        self.penumbral_polygons = penumbral_coverage_rings(
+            e,
+            lambda s: (s.l1, s.l1p),
+            resolution_deg=penumbral_resolution_deg,
+            step_minutes=penumbral_step_minutes,
+        )
+        self.central_line: list[tuple[float, float]] = []
+        self.umbral_ring: list[tuple[float, float]] = []
+        if is_central(e):
+            self.central_line = central_line(e, step_minutes)
+            self.umbral_ring = limits_to_ring(umbral_limits(e, step_minutes))
+
+
+def _load_layers(
+    year: int,
+    month: int,
+    day: int,
+    csv_path: Path | None,
+    step_minutes: float,
+    elements: BesselianElements | None,
+    penumbral_resolution_deg: float,
+    penumbral_step_minutes: float,
+) -> tuple[BesselianElements, _Layers]:
+    e = elements if elements is not None else find_by_date(year, month, day, csv_path=csv_path)
+    layers = _Layers(e, step_minutes, penumbral_resolution_deg, penumbral_step_minutes)
+    if not layers.penumbral_polygons:
+        raise RuntimeError(
+            f"Could not compute a penumbral path for {year:04d}-{month:02d}-{day:02d}"
+        )
+    return e, layers
+
+
+def generate_eclipse_shapefiles(
+    year: int,
+    month: int,
+    day: int,
+    output_dir: Path | str,
+    csv_path: Path | None = None,
+    step_minutes: float = 0.5,
+    elements: BesselianElements | None = None,
+    penumbral_resolution_deg: float = _PENUMBRAL_RESOLUTION_DEG,
+    penumbral_step_minutes: float = _PENUMBRAL_STEP_MINUTES,
+) -> dict[str, Path]:
+    """Generate ESRI shapefiles for the solar eclipse on the given
+    (proleptic Gregorian, astronomical-numbered) calendar date.
+
+    Writes into `output_dir`:
+      - "penumbral_path.shp": polygon (possibly multi-part, e.g. a main
+        region plus separate disjoint loops for a shadow path that passes
+        close to a pole) of the region on Earth from which at least a
+        partial eclipse is visible (all eclipse types).
+      - "central_line.shp": polyline of the path of totality/annularity's
+        central line (total/annular/hybrid eclipses only).
+      - "umbral_path.shp": polygon of the path of totality/annularity
+        (total/annular/hybrid eclipses only).
+
+    Each shapefile is written as a single-feature .shp/.shx/.dbf/.prj set
+    in WGS84 geographic coordinates. `step_minutes` controls how finely
+    the umbral/central-line path is sampled along its length.
+    `penumbral_resolution_deg`/`penumbral_step_minutes` control the
+    coverage-grid resolution and time step used to compute the penumbral
+    boundary (see `raster.penumbral_coverage_rings`); the defaults are a
+    reasonable accuracy/runtime balance, coarsened here mainly for fast
+    tests.
+
+    If `elements` is given, it is used directly instead of looking `year`,
+    `month`, `day` up in the (cached) CSV -- useful when generating more
+    than one output format for the same eclipse, to avoid re-parsing the
+    dataset each time.
+
+    Raises LookupError if no eclipse occurred on that date. Returns a dict
+    mapping each layer name written to its .shp path.
+    """
+    e, layers = _load_layers(
+        year, month, day, csv_path, step_minutes, elements,
+        penumbral_resolution_deg, penumbral_step_minutes,
+    )
+    output_dir = Path(output_dir)
+
+    written: dict[str, Path] = {
+        "penumbral_path": write_polygon_shapefile_with_holes(
+            output_dir / "penumbral_path.shp", layers.penumbral_polygons, e
+        )
+    }
+
+    if layers.central_line or layers.umbral_ring:
+        path_fields = [("duration", "C", 8, 0), ("path_km", "F", 10, 2)]
+        path_record = {"duration": e.central_duration, "path_km": e.path_width}
+
+        if layers.central_line:
+            written["central_line"] = write_polyline_shapefile(
+                output_dir / "central_line.shp",
+                layers.central_line,
+                e,
+                extra_fields=path_fields,
+                extra_record=path_record,
+            )
+        if layers.umbral_ring:
+            written["umbral_path"] = write_polygon_shapefile(
+                output_dir / "umbral_path.shp",
+                layers.umbral_ring,
+                e,
+                extra_fields=path_fields,
+                extra_record=path_record,
+            )
+
+    return written
+
+
+def generate_eclipse_kml(
+    year: int,
+    month: int,
+    day: int,
+    output_path: Path | str,
+    csv_path: Path | None = None,
+    step_minutes: float = 0.5,
+    elements: BesselianElements | None = None,
+    penumbral_resolution_deg: float = _PENUMBRAL_RESOLUTION_DEG,
+    penumbral_step_minutes: float = _PENUMBRAL_STEP_MINUTES,
+) -> Path:
+    """Generate a single KML (or, if `output_path` ends in .kmz, KMZ) file
+    for the solar eclipse on the given date, containing the same layers as
+    `generate_eclipse_shapefiles` as separate Placemarks in one Document:
+    the penumbral path (all eclipse types), and, for total/annular/hybrid
+    eclipses, the central line and umbral path.
+
+    See `generate_eclipse_shapefiles` for the other parameters.
+
+    Raises LookupError if no eclipse occurred on that date.
+    """
+    e, layers = _load_layers(
+        year, month, day, csv_path, step_minutes, elements,
+        penumbral_resolution_deg, penumbral_step_minutes,
+    )
+    output_path = Path(output_path)
+
+    doc = kml_writer.build_document(e)
+    kml_writer.add_penumbral_path(doc, e, layers.penumbral_polygons)
+    if layers.central_line:
+        kml_writer.add_central_line(doc, e, layers.central_line)
+    if layers.umbral_ring:
+        kml_writer.add_umbral_path(doc, e, layers.umbral_ring)
+
+    return kml_writer.write_kml(doc, output_path)