besselian2shape 0.1.0__tar.gz

besselian2shape-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Rice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

besselian2shape-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: besselian2shape
+Version: 0.1.0
+Summary: Generate ESRI Shapefiles and Google Earth KML/KMZ files describing a solar eclipse's path from NASA Besselian elements
+Keywords: eclipse,astronomy,gis,shapefile,kml,besselian-elements
+Author: Tony Rice
+Author-email: Tony Rice <rtphokie@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: platformdirs>=4.11.15
+Requires-Dist: pyshp>=3.1.6
+Requires-Dist: requests>=2.34.2
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/rtphokie/besselian2shape
+Project-URL: Repository, https://github.com/rtphokie/besselian2shape
+Description-Content-Type: text/markdown
+
+# besselian2shape
+
+Generate ESRI Shapefiles and Google Earth KML/KMZ files describing a solar
+eclipse's visibility from NASA's Besselian elements dataset: the central
+line, the umbral/antumbral path of totality or annularity, and the
+penumbral region from which at least a partial eclipse is visible.
+
+Besselian elements are downloaded once from NASA's [Five Millennium Canon
+of Solar Eclipses](https://eclipse.gsfc.nasa.gov/) and cached locally.
+
+## Installation
+
+```bash
+pip install besselian2shape
+```
+
+Requires Python 3.11+.
+
+## CLI usage
+
+```bash
+besselian2shape YEAR MONTH DAY [options]
+```
+
+`YEAR` uses astronomical numbering for BCE dates (1 BCE is year `0`, 2 BCE
+is year `-1`, etc.).
+
+```bash
+# Shapefiles (default) for the 2024 total eclipse, written to ./eclipse_2024-04-08
+besselian2shape 2024 4 8
+
+# KMZ file in a custom directory
+besselian2shape 2017 8 21 -o out/ -f kmz
+
+# Every format at once
+besselian2shape 2024 10 2 -f all
+```
+
+Options:
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `-o, --output DIR` | `./eclipse_YYYY-MM-DD` | Output directory |
+| `-f, --format {shp,kml,kmz,all}` | `shp` | Output format; may be repeated |
+| `--step-minutes MINUTES` | `0.5` | Time resolution for sampling the central line and umbral path |
+| `--penumbral-resolution DEGREES` | `0.25` | Grid resolution for the penumbral visibility boundary |
+| `--penumbral-step-minutes MINUTES` | `1.5` | Time step for the penumbral visibility raster scan |
+| `--refresh-cache` | | Re-download the Besselian elements dataset even if already cached |
+
+Negative-year (BCE) example:
+
+```bash
+besselian2shape -1999 6 12 -f kml
+```
+
+Shapefile output writes up to three layers into the output directory:
+
+- `penumbral_path.shp` -- polygon (all eclipse types)
+- `central_line.shp` -- polyline (total/annular/hybrid only)
+- `umbral_path.shp` -- polygon (total/annular/hybrid only)
+
+KML/KMZ output writes a single file (`eclipse.kml` or `eclipse.kmz`)
+containing the same layers as separate placemarks.
+
+## Python API
+
+```python
+from besselian2shape import generate_eclipse_shapefiles, generate_eclipse_kml
+
+# Shapefiles
+written = generate_eclipse_shapefiles(2024, 4, 8, "output_dir")
+# {"penumbral_path": Path(...), "central_line": Path(...), "umbral_path": Path(...)}
+
+# KML/KMZ (format is inferred from the output path's suffix)
+generate_eclipse_kml(2024, 4, 8, "output_dir/eclipse.kmz")
+```
+
+Both functions raise `LookupError` if no eclipse occurred on the given
+date. Both accept the same optional keyword arguments:
+
+- `csv_path`: use a specific Besselian elements CSV instead of the cached
+  download.
+- `step_minutes` (default `0.5`): sampling density along the central
+  line/umbral path.
+- `penumbral_resolution_deg` / `penumbral_step_minutes` (defaults `0.25`,
+  `1.5`): grid resolution and time step for the penumbral coverage
+  raster -- lower values are more accurate but slower.
+- `elements`: an already-looked-up `BesselianElements` instance, to avoid
+  parsing the CSV twice when generating more than one format for the same
+  eclipse:
+
+```python
+from besselian2shape import find_by_date, generate_eclipse_shapefiles, generate_eclipse_kml
+
+e = find_by_date(2024, 4, 8)
+generate_eclipse_shapefiles(2024, 4, 8, "output_dir", elements=e)
+generate_eclipse_kml(2024, 4, 8, "output_dir/eclipse.kmz", elements=e)
+```
+
+### Other public functions
+
+- `find_by_date(year, month, day, csv_path=None) -> BesselianElements`
+- `load_all(csv_path=None) -> list[BesselianElements]`
+- `download_besselian_csv(force=False) -> Path`
+- `get_cache_dir() -> Path`
+- `get_cached_csv_path() -> Path`
+
+`BesselianElements` is a frozen dataclass holding one eclipse's metadata
+(date, Saros number, gamma, magnitude, path width, etc.) and its raw
+Besselian polynomial coefficients (`x0..x3`, `y0..y3`, `d0..d2`,
+`mu0..mu2`, `l10..l12`, `l20..l22`, `tan_f1`, `tan_f2`, `t0`, `tmin`,
+`tmax`), as published in NASA's dataset.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```

besselian2shape-0.1.0/README.md

@@ -0,0 +1,119 @@
+# besselian2shape
+
+Generate ESRI Shapefiles and Google Earth KML/KMZ files describing a solar
+eclipse's visibility from NASA's Besselian elements dataset: the central
+line, the umbral/antumbral path of totality or annularity, and the
+penumbral region from which at least a partial eclipse is visible.
+
+Besselian elements are downloaded once from NASA's [Five Millennium Canon
+of Solar Eclipses](https://eclipse.gsfc.nasa.gov/) and cached locally.
+
+## Installation
+
+```bash
+pip install besselian2shape
+```
+
+Requires Python 3.11+.
+
+## CLI usage
+
+```bash
+besselian2shape YEAR MONTH DAY [options]
+```
+
+`YEAR` uses astronomical numbering for BCE dates (1 BCE is year `0`, 2 BCE
+is year `-1`, etc.).
+
+```bash
+# Shapefiles (default) for the 2024 total eclipse, written to ./eclipse_2024-04-08
+besselian2shape 2024 4 8
+
+# KMZ file in a custom directory
+besselian2shape 2017 8 21 -o out/ -f kmz
+
+# Every format at once
+besselian2shape 2024 10 2 -f all
+```
+
+Options:
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `-o, --output DIR` | `./eclipse_YYYY-MM-DD` | Output directory |
+| `-f, --format {shp,kml,kmz,all}` | `shp` | Output format; may be repeated |
+| `--step-minutes MINUTES` | `0.5` | Time resolution for sampling the central line and umbral path |
+| `--penumbral-resolution DEGREES` | `0.25` | Grid resolution for the penumbral visibility boundary |
+| `--penumbral-step-minutes MINUTES` | `1.5` | Time step for the penumbral visibility raster scan |
+| `--refresh-cache` | | Re-download the Besselian elements dataset even if already cached |
+
+Negative-year (BCE) example:
+
+```bash
+besselian2shape -1999 6 12 -f kml
+```
+
+Shapefile output writes up to three layers into the output directory:
+
+- `penumbral_path.shp` -- polygon (all eclipse types)
+- `central_line.shp` -- polyline (total/annular/hybrid only)
+- `umbral_path.shp` -- polygon (total/annular/hybrid only)
+
+KML/KMZ output writes a single file (`eclipse.kml` or `eclipse.kmz`)
+containing the same layers as separate placemarks.
+
+## Python API
+
+```python
+from besselian2shape import generate_eclipse_shapefiles, generate_eclipse_kml
+
+# Shapefiles
+written = generate_eclipse_shapefiles(2024, 4, 8, "output_dir")
+# {"penumbral_path": Path(...), "central_line": Path(...), "umbral_path": Path(...)}
+
+# KML/KMZ (format is inferred from the output path's suffix)
+generate_eclipse_kml(2024, 4, 8, "output_dir/eclipse.kmz")
+```
+
+Both functions raise `LookupError` if no eclipse occurred on the given
+date. Both accept the same optional keyword arguments:
+
+- `csv_path`: use a specific Besselian elements CSV instead of the cached
+  download.
+- `step_minutes` (default `0.5`): sampling density along the central
+  line/umbral path.
+- `penumbral_resolution_deg` / `penumbral_step_minutes` (defaults `0.25`,
+  `1.5`): grid resolution and time step for the penumbral coverage
+  raster -- lower values are more accurate but slower.
+- `elements`: an already-looked-up `BesselianElements` instance, to avoid
+  parsing the CSV twice when generating more than one format for the same
+  eclipse:
+
+```python
+from besselian2shape import find_by_date, generate_eclipse_shapefiles, generate_eclipse_kml
+
+e = find_by_date(2024, 4, 8)
+generate_eclipse_shapefiles(2024, 4, 8, "output_dir", elements=e)
+generate_eclipse_kml(2024, 4, 8, "output_dir/eclipse.kmz", elements=e)
+```
+
+### Other public functions
+
+- `find_by_date(year, month, day, csv_path=None) -> BesselianElements`
+- `load_all(csv_path=None) -> list[BesselianElements]`
+- `download_besselian_csv(force=False) -> Path`
+- `get_cache_dir() -> Path`
+- `get_cached_csv_path() -> Path`
+
+`BesselianElements` is a frozen dataclass holding one eclipse's metadata
+(date, Saros number, gamma, magnitude, path width, etc.) and its raw
+Besselian polynomial coefficients (`x0..x3`, `y0..y3`, `d0..d2`,
+`mu0..mu2`, `l10..l12`, `l20..l22`, `tan_f1`, `tan_f2`, `t0`, `tmin`,
+`tmax`), as published in NASA's dataset.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```

besselian2shape-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "besselian2shape"
+version = "0.1.0"
+description = "Generate ESRI Shapefiles and Google Earth KML/KMZ files describing a solar eclipse's path from NASA Besselian elements"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "eclipse",
+    "astronomy",
+    "gis",
+    "shapefile",
+    "kml",
+    "besselian-elements",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=2.4.6",
+    "platformdirs>=4.11.15",
+    "pyshp>=3.1.6",
+    "requests>=2.34.2",
+]
+
+[[project.authors]]
+name = "Tony Rice"
+email = "rtphokie@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/rtphokie/besselian2shape"
+Repository = "https://github.com/rtphokie/besselian2shape"
+
+[project.scripts]
+besselian2shape = "besselian2shape:main"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]

besselian2shape-0.1.0/pyproject.toml.orig

@@ -0,0 +1,45 @@
+[project]
+name = "besselian2shape"
+version = "0.1.0"
+description = "Generate ESRI Shapefiles and Google Earth KML/KMZ files describing a solar eclipse's path from NASA Besselian elements"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Tony Rice", email = "rtphokie@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["eclipse", "astronomy", "gis", "shapefile", "kml", "besselian-elements"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=2.4.6",
+    "platformdirs>=4.11.15",
+    "pyshp>=3.1.6",
+    "requests>=2.34.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/rtphokie/besselian2shape"
+Repository = "https://github.com/rtphokie/besselian2shape"
+
+[project.scripts]
+besselian2shape = "besselian2shape:main"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

besselian2shape-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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())