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.
