occultations 0.1.0__tar.gz

occultations-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.3
+Name: occultations
+Version: 0.1.0
+Summary: Lunar occultation timings and visibility maps
+Author: trice
+Author-email: trice <rtphokie@gmail.com>
+Requires-Dist: cartopy>=0.26.0
+Requires-Dist: geopy>=2.5.0
+Requires-Dist: matplotlib>=3.11.2
+Requires-Dist: skyfield>=1.55
+Requires-Dist: timezonefinder>=9.0.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# occultations
+
+Predicts lunar occultations — the Moon passing in front of a planet or bright star — for a
+given location and date, draws maps and Google Earth files of where on Earth an occultation
+can be seen, and
+forecasts the occultations visible from a location over the coming months.
+
+Positions come from [Skyfield](https://rhodesmill.org/skyfield/) using the JPL DE421 ephemeris,
+computed topocentrically (as seen from the observer's spot on Earth, not Earth's center).
+
+## Installation
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync
+```
+
+Data files are stored in `/var/data` (the directory must exist and be writable):
+
+- `de421.bsp` — JPL ephemeris (~17 MB), downloaded on first run
+- `cartopy/` — Natural Earth coastlines and borders, downloaded the first time a map is drawn
+
+## Usage
+
+```
+occultations TARGET DATE [LOCATION] [options]      # timing for one date, optional map
+occultations forecast LOCATION [options]           # upcoming visible occultations
+```
+
+| Argument   | Description |
+|------------|-------------|
+| `TARGET`   | A planet (`mercury` … `pluto`), a bright star (see below), or coordinates as `"RA_hours,Dec_deg"` |
+| `DATE`     | `YYYY-MM-DD` — the local date at `LOCATION`, or the UTC date when only mapping |
+| `LOCATION` | `"City, ST"` (looked up via OpenStreetMap) or `"lat,lon"` in decimal degrees, west negative. Optional when `--map` is given |
+
+Built-in stars: Aldebaran, Alcyone (Pleiades), Antares, Elnath, Mebsuta, Nunki, Pollux,
+Regulus, Spica, Zubenelgenubi.
+
+### Timing options
+
+| Option | Description |
+|--------|-------------|
+| `--elevation M` | Observer elevation in meters (defaults to the geocoder's value, or 0) |
+| `--timezone TZ` | Override the IANA time zone (normally derived from the coordinates) |
+| `--prev-next` | Also show the date and target of the previous and next occultation visible from `LOCATION`, of any built-in planet or star (searches up to 20 years each way) |
+| `--planets-only` | With `--prev-next`, consider only planets |
+
+### Map and Google Earth options
+
+| Option | Description |
+|--------|-------------|
+| `--map [PATH]` | Also draw a visibility map as a PNG. Without `PATH` it is named `occultation_<target>_<date>[_<region>].png` in the current directory. A second, clean copy with no title, legend or labels is written alongside it as `<name>_clean.png` |
+| `--region NAME` | Limit the map to a preset: `north-america`, `conus`, `europe`, `africa` |
+| `--extent W E S N` | Limit the map to a longitude/latitude box (degrees, west/south negative) |
+| `--resolution DEG` | Map grid spacing in degrees (default `0.25`; smaller is slower) |
+| `--kmz [PATH]` | Also write a Google Earth file (KMZ). Without `PATH` it is named `occultation_<target>_<date>[_<region>].kmz` |
+| `--mark-location` | Put a marker at `LOCATION` on the map / in the KMZ |
+
+`--region`, `--extent`, `--resolution` and `--mark-location` apply to both `--map` and `--kmz`;
+use both flags together to get a PNG and a KMZ from one calculation. Without `--region` or
+`--extent`, the area is chosen automatically around where the event is visible.
+
+> **Note:** `--map` and `--kmz` take an optional path, so put them *after* `LOCATION` (or give
+> them a path). `occultations jupiter 2026-10-06 --map "Raleigh, NC"` would treat
+> `"Raleigh, NC"` as the filename.
+
+### Forecast options
+
+`occultations forecast LOCATION` searches a span of dates for every occultation of the
+built-in planets and stars that can actually be seen from `LOCATION`.
+
+| Option | Description |
+|--------|-------------|
+| `--start DATE` | First local date to search (default today) |
+| `--days N` | Number of days to search (default 365) |
+| `--end DATE` | Last local date to search, instead of `--days` |
+| `--targets T [T ...]` | Only these targets (default: all planets and built-in stars) |
+| `--planets-only` | Only planets, no stars (cannot be combined with `--targets`) |
+| `--include-daylight` | Also list events of bright planets (Mercury–Saturn) with the Sun up or in civil twilight |
+| `--elevation M`, `--timezone TZ` | As for timing |
+
+An occultation is listed when its disappearance or reappearance happens with the Moon above
+the horizon and the Sun at least 6° below it (or, with `--include-daylight`, at any Sun
+altitude for bright planets).
+
+## Examples
+
+Contact times for Jupiter from Raleigh:
+
+```sh
+uv run occultations jupiter 2026-10-06 "Raleigh, NC"
+```
+
+```
+Lunar occultation of Jupiter
+Location: Raleigh, NC (35.7804°, -78.6391°), 0 m
+Date:     2026-10-06 (America/New_York)
+Moon:     20% illuminated, radius 16.05'; Jupiter radius 16.8"
+
+Event                                Local time  UTC     Moon alt/az         PA  Sky
+----------------------------------------------------------------------------------------------------
+Disappearance begins (1st contact)   04:18 EDT  08:18    15.2° E    82°   113°  dark
+Fully hidden (2nd contact)           04:19 EDT  08:19    15.4° E    82°   113°  dark
+Reappearance begins (3rd contact)    05:21 EDT  09:21    27.6° E    91°   288°  dark
+Reappearance ends (4th contact)      05:23 EDT  09:23    27.9° E    91°   288°  dark
+
+Duration (first to last contact): 65 min
+```
+
+Using coordinates instead of a city:
+
+```sh
+uv run occultations jupiter 2026-10-06 "35.78,-78.64"
+```
+
+Contact times plus a North America visibility map:
+
+```sh
+uv run occultations jupiter 2026-10-06 "Raleigh, NC" --region north-america --map
+```
+
+Map only, framed automatically, saved to a chosen path:
+
+```sh
+uv run occultations jupiter 2026-10-06 --map jupiter.png
+```
+
+Google Earth file of the whole visibility path (open it in Google Earth or Google Earth Web):
+
+```sh
+uv run occultations jupiter 2026-10-06 --kmz
+```
+
+PNG map and KMZ together, with the observer marked:
+
+```sh
+uv run occultations jupiter 2026-10-06 "Raleigh, NC" --region north-america --mark-location --map --kmz
+```
+
+Map of a custom area with the observer marked:
+
+```sh
+uv run occultations jupiter 2026-10-06 "Raleigh, NC" --extent -95 -65 25 45 --mark-location --map
+```
+
+Visible occultations from Raleigh over the next year:
+
+```sh
+uv run occultations forecast "Raleigh, NC" --start 2026-10-01
+```
+
+```
+Visible lunar occultations from Raleigh, NC (35.7804°, -78.6391°)
+2026-10-01 to 2027-09-30, times in America/New_York
+
+Date            Target         Disappears                                           Reappears                                            Moon
+----------------------------------------------------------------------------------------------------------------------------------------------
+Tue 2026-10-06 Jupiter        04:18   15° E   dark                  bright limb    05:23   28° E   dark                  dark limb       20%
+Sun 2027-06-20 Nunki          03:21   26° SSW dark                  bright limb    04:07   23° SSW dark                  dark limb       98%
+```
+
+Only Jupiter and Regulus over the rest of the year, including daytime events:
+
+```sh
+uv run occultations forecast "Raleigh, NC" --end 2026-12-31 --targets jupiter regulus --include-daylight
+```
+
+## Reading the output
+
+**Timing table**
+
+- Planets show four contacts, since they have a visible disk; stars disappear and reappear
+  instantly, so they show a single disappearance and reappearance.
+- **Moon alt/az** — the Moon's altitude and compass direction at that moment. Events with the
+  Moon below the horizon are flagged.
+- **PA** — position angle on the Moon's limb where the event happens, in degrees measured from
+  celestial north through east (90° is the Moon's eastern edge).
+- **Sky** — daylight, civil/nautical/astronomical twilight, or dark, from the Sun's altitude.
+- Times are rounded to the nearest minute.
+- If there is no occultation, the closest approach to the Moon's center is reported instead.
+
+**Forecast table**
+
+- One row per occultation, with the local date and time it starts and ends. For planets these
+  are the first and last contacts.
+- Each event shows the Moon's altitude and compass direction, the sky condition, and whether
+  it happens on the Moon's **bright limb** (sunlit edge) or **dark limb**. Dark-limb events are
+  much easier to watch; a star vanishing at the dark limb seems to blink out.
+- "Moon below horizon" means that half of the event can't be seen, but the other half can.
+- **Moon** is the percentage of the Moon's disk that is illuminated.
+- Targets marked `*` (Uranus, Neptune, Pluto) need a telescope.
+- Only the built-in planets and ten bright stars are searched, so fainter-star occultations
+  that dedicated services such as [IOTA](https://occultations.org) list are not included.
+
+**Map**
+
+| Color | Meaning |
+|-------|---------|
+| Dark blue | Visible with the Sun more than 12° below the horizon |
+| Light blue | Visible in twilight |
+| Gold | Visible in daylight (bright planets only, with a telescope) |
+| Gray | The occultation happens there, but the Moon is below the horizon |
+
+A lighter shade of each color marks where only one contact happens with the Moon above the
+horizon: only the disappearance where the Moon sets while the target is hidden, or only the
+reappearance where it rises. Full-strength areas see both.
+
+The title's "global event window" is the span during which the occultation is happening
+anywhere on Earth.
+
+**Google Earth (KMZ)**
+
+The KMZ shows translucent polygons in the colors above, including the lighter shades
+(folder *Visibility*), and
+disappearance-time lines labeled in UTC (folder *Disappearance
+times*), plus the observer if `--mark-location` is used. Each folder can be toggled in
+Google Earth's sidebar. With `--region` or `--extent`, the shapes extend somewhat past the
+requested box; without either, they cover the whole path where the Moon is up.
+
+## Accuracy
+
+For the 2026-10-06 Jupiter occultation, computed times agree with published predictions for
+Atlanta, Boston, Chicago, Miami, New York, and Winnipeg to within about a minute.
+
+- The Moon is treated as a smooth sphere, so lunar mountains and valleys are ignored. This
+  shifts times by only seconds in most places, but near the northern or southern edge of the
+  path (a *graze*) predictions are less reliable and the target may blink in and out several times.
+- Map boundaries use the target's center, so for planets they are accurate to about the
+  planet's apparent radius.
+- Atmospheric refraction is not modeled.

occultations-0.1.0/README.md

@@ -0,0 +1,231 @@
+# occultations
+
+Predicts lunar occultations — the Moon passing in front of a planet or bright star — for a
+given location and date, draws maps and Google Earth files of where on Earth an occultation
+can be seen, and
+forecasts the occultations visible from a location over the coming months.
+
+Positions come from [Skyfield](https://rhodesmill.org/skyfield/) using the JPL DE421 ephemeris,
+computed topocentrically (as seen from the observer's spot on Earth, not Earth's center).
+
+## Installation
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync
+```
+
+Data files are stored in `/var/data` (the directory must exist and be writable):
+
+- `de421.bsp` — JPL ephemeris (~17 MB), downloaded on first run
+- `cartopy/` — Natural Earth coastlines and borders, downloaded the first time a map is drawn
+
+## Usage
+
+```
+occultations TARGET DATE [LOCATION] [options]      # timing for one date, optional map
+occultations forecast LOCATION [options]           # upcoming visible occultations
+```
+
+| Argument   | Description |
+|------------|-------------|
+| `TARGET`   | A planet (`mercury` … `pluto`), a bright star (see below), or coordinates as `"RA_hours,Dec_deg"` |
+| `DATE`     | `YYYY-MM-DD` — the local date at `LOCATION`, or the UTC date when only mapping |
+| `LOCATION` | `"City, ST"` (looked up via OpenStreetMap) or `"lat,lon"` in decimal degrees, west negative. Optional when `--map` is given |
+
+Built-in stars: Aldebaran, Alcyone (Pleiades), Antares, Elnath, Mebsuta, Nunki, Pollux,
+Regulus, Spica, Zubenelgenubi.
+
+### Timing options
+
+| Option | Description |
+|--------|-------------|
+| `--elevation M` | Observer elevation in meters (defaults to the geocoder's value, or 0) |
+| `--timezone TZ` | Override the IANA time zone (normally derived from the coordinates) |
+| `--prev-next` | Also show the date and target of the previous and next occultation visible from `LOCATION`, of any built-in planet or star (searches up to 20 years each way) |
+| `--planets-only` | With `--prev-next`, consider only planets |
+
+### Map and Google Earth options
+
+| Option | Description |
+|--------|-------------|
+| `--map [PATH]` | Also draw a visibility map as a PNG. Without `PATH` it is named `occultation_<target>_<date>[_<region>].png` in the current directory. A second, clean copy with no title, legend or labels is written alongside it as `<name>_clean.png` |
+| `--region NAME` | Limit the map to a preset: `north-america`, `conus`, `europe`, `africa` |
+| `--extent W E S N` | Limit the map to a longitude/latitude box (degrees, west/south negative) |
+| `--resolution DEG` | Map grid spacing in degrees (default `0.25`; smaller is slower) |
+| `--kmz [PATH]` | Also write a Google Earth file (KMZ). Without `PATH` it is named `occultation_<target>_<date>[_<region>].kmz` |
+| `--mark-location` | Put a marker at `LOCATION` on the map / in the KMZ |
+
+`--region`, `--extent`, `--resolution` and `--mark-location` apply to both `--map` and `--kmz`;
+use both flags together to get a PNG and a KMZ from one calculation. Without `--region` or
+`--extent`, the area is chosen automatically around where the event is visible.
+
+> **Note:** `--map` and `--kmz` take an optional path, so put them *after* `LOCATION` (or give
+> them a path). `occultations jupiter 2026-10-06 --map "Raleigh, NC"` would treat
+> `"Raleigh, NC"` as the filename.
+
+### Forecast options
+
+`occultations forecast LOCATION` searches a span of dates for every occultation of the
+built-in planets and stars that can actually be seen from `LOCATION`.
+
+| Option | Description |
+|--------|-------------|
+| `--start DATE` | First local date to search (default today) |
+| `--days N` | Number of days to search (default 365) |
+| `--end DATE` | Last local date to search, instead of `--days` |
+| `--targets T [T ...]` | Only these targets (default: all planets and built-in stars) |
+| `--planets-only` | Only planets, no stars (cannot be combined with `--targets`) |
+| `--include-daylight` | Also list events of bright planets (Mercury–Saturn) with the Sun up or in civil twilight |
+| `--elevation M`, `--timezone TZ` | As for timing |
+
+An occultation is listed when its disappearance or reappearance happens with the Moon above
+the horizon and the Sun at least 6° below it (or, with `--include-daylight`, at any Sun
+altitude for bright planets).
+
+## Examples
+
+Contact times for Jupiter from Raleigh:
+
+```sh
+uv run occultations jupiter 2026-10-06 "Raleigh, NC"
+```
+
+```
+Lunar occultation of Jupiter
+Location: Raleigh, NC (35.7804°, -78.6391°), 0 m
+Date:     2026-10-06 (America/New_York)
+Moon:     20% illuminated, radius 16.05'; Jupiter radius 16.8"
+
+Event                                Local time  UTC     Moon alt/az         PA  Sky
+----------------------------------------------------------------------------------------------------
+Disappearance begins (1st contact)   04:18 EDT  08:18    15.2° E    82°   113°  dark
+Fully hidden (2nd contact)           04:19 EDT  08:19    15.4° E    82°   113°  dark
+Reappearance begins (3rd contact)    05:21 EDT  09:21    27.6° E    91°   288°  dark
+Reappearance ends (4th contact)      05:23 EDT  09:23    27.9° E    91°   288°  dark
+
+Duration (first to last contact): 65 min
+```
+
+Using coordinates instead of a city:
+
+```sh
+uv run occultations jupiter 2026-10-06 "35.78,-78.64"
+```
+
+Contact times plus a North America visibility map:
+
+```sh
+uv run occultations jupiter 2026-10-06 "Raleigh, NC" --region north-america --map
+```
+
+Map only, framed automatically, saved to a chosen path:
+
+```sh
+uv run occultations jupiter 2026-10-06 --map jupiter.png
+```
+
+Google Earth file of the whole visibility path (open it in Google Earth or Google Earth Web):
+
+```sh
+uv run occultations jupiter 2026-10-06 --kmz
+```
+
+PNG map and KMZ together, with the observer marked:
+
+```sh
+uv run occultations jupiter 2026-10-06 "Raleigh, NC" --region north-america --mark-location --map --kmz
+```
+
+Map of a custom area with the observer marked:
+
+```sh
+uv run occultations jupiter 2026-10-06 "Raleigh, NC" --extent -95 -65 25 45 --mark-location --map
+```
+
+Visible occultations from Raleigh over the next year:
+
+```sh
+uv run occultations forecast "Raleigh, NC" --start 2026-10-01
+```
+
+```
+Visible lunar occultations from Raleigh, NC (35.7804°, -78.6391°)
+2026-10-01 to 2027-09-30, times in America/New_York
+
+Date            Target         Disappears                                           Reappears                                            Moon
+----------------------------------------------------------------------------------------------------------------------------------------------
+Tue 2026-10-06 Jupiter        04:18   15° E   dark                  bright limb    05:23   28° E   dark                  dark limb       20%
+Sun 2027-06-20 Nunki          03:21   26° SSW dark                  bright limb    04:07   23° SSW dark                  dark limb       98%
+```
+
+Only Jupiter and Regulus over the rest of the year, including daytime events:
+
+```sh
+uv run occultations forecast "Raleigh, NC" --end 2026-12-31 --targets jupiter regulus --include-daylight
+```
+
+## Reading the output
+
+**Timing table**
+
+- Planets show four contacts, since they have a visible disk; stars disappear and reappear
+  instantly, so they show a single disappearance and reappearance.
+- **Moon alt/az** — the Moon's altitude and compass direction at that moment. Events with the
+  Moon below the horizon are flagged.
+- **PA** — position angle on the Moon's limb where the event happens, in degrees measured from
+  celestial north through east (90° is the Moon's eastern edge).
+- **Sky** — daylight, civil/nautical/astronomical twilight, or dark, from the Sun's altitude.
+- Times are rounded to the nearest minute.
+- If there is no occultation, the closest approach to the Moon's center is reported instead.
+
+**Forecast table**
+
+- One row per occultation, with the local date and time it starts and ends. For planets these
+  are the first and last contacts.
+- Each event shows the Moon's altitude and compass direction, the sky condition, and whether
+  it happens on the Moon's **bright limb** (sunlit edge) or **dark limb**. Dark-limb events are
+  much easier to watch; a star vanishing at the dark limb seems to blink out.
+- "Moon below horizon" means that half of the event can't be seen, but the other half can.
+- **Moon** is the percentage of the Moon's disk that is illuminated.
+- Targets marked `*` (Uranus, Neptune, Pluto) need a telescope.
+- Only the built-in planets and ten bright stars are searched, so fainter-star occultations
+  that dedicated services such as [IOTA](https://occultations.org) list are not included.
+
+**Map**
+
+| Color | Meaning |
+|-------|---------|
+| Dark blue | Visible with the Sun more than 12° below the horizon |
+| Light blue | Visible in twilight |
+| Gold | Visible in daylight (bright planets only, with a telescope) |
+| Gray | The occultation happens there, but the Moon is below the horizon |
+
+A lighter shade of each color marks where only one contact happens with the Moon above the
+horizon: only the disappearance where the Moon sets while the target is hidden, or only the
+reappearance where it rises. Full-strength areas see both.
+
+The title's "global event window" is the span during which the occultation is happening
+anywhere on Earth.
+
+**Google Earth (KMZ)**
+
+The KMZ shows translucent polygons in the colors above, including the lighter shades
+(folder *Visibility*), and
+disappearance-time lines labeled in UTC (folder *Disappearance
+times*), plus the observer if `--mark-location` is used. Each folder can be toggled in
+Google Earth's sidebar. With `--region` or `--extent`, the shapes extend somewhat past the
+requested box; without either, they cover the whole path where the Moon is up.
+
+## Accuracy
+
+For the 2026-10-06 Jupiter occultation, computed times agree with published predictions for
+Atlanta, Boston, Chicago, Miami, New York, and Winnipeg to within about a minute.
+
+- The Moon is treated as a smooth sphere, so lunar mountains and valleys are ignored. This
+  shifts times by only seconds in most places, but near the northern or southern edge of the
+  path (a *graze*) predictions are less reliable and the target may blink in and out several times.
+- Map boundaries use the target's center, so for planets they are accurate to about the
+  planet's apparent radius.
+- Atmospheric refraction is not modeled.

occultations-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "occultations"
+version = "0.1.0"
+description = "Lunar occultation timings and visibility maps"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "cartopy>=0.26.0",
+    "geopy>=2.5.0",
+    "matplotlib>=3.11.2",
+    "skyfield>=1.55",
+    "timezonefinder>=9.0.0",
+]
+
+[[project.authors]]
+name = "trice"
+email = "rtphokie@gmail.com"
+
+[project.scripts]
+occultations = "occultations:main"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"

occultations-0.1.0/pyproject.toml.orig

@@ -0,0 +1,23 @@
+[project]
+name = "occultations"
+version = "0.1.0"
+description = "Lunar occultation timings and visibility maps"
+readme = "README.md"
+authors = [
+    { name = "trice", email = "rtphokie@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "cartopy>=0.26.0",
+    "geopy>=2.5.0",
+    "matplotlib>=3.11.2",
+    "skyfield>=1.55",
+    "timezonefinder>=9.0.0",
+]
+
+[project.scripts]
+occultations = "occultations:main"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"