Metadata-Version: 2.3
Name: occultations
Version: 0.2.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, ana
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, borders and ocean names, downloaded the first time a map is drawn or a region is named

## 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"`. Optional: without it, every built-in planet and star the Moon occults somewhere on Earth on `DATE` is reported (and mapped), one after another |
| `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` |

When `TARGET` is omitted and more than one occultation happens that day, the target is added to
a given `PATH` (e.g. `map.png` → `map_mars.png` and `map_jupiter.png`).
| `--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, listing first those that can actually be seen from `LOCATION`, then
those happening elsewhere on Earth that can't.

| 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 counts as visible 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
```

Without a target, whatever the Moon occults that day (here Jupiter, and Regulus later that
evening, which isn't visible from Raleigh):

```sh
uv run occultations 2026-10-06 "Raleigh, NC"
```

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
```

```
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%

Altitude and compass direction are the Moon's. Planet times are first and last contact.

Occurring elsewhere on Earth, not visible from here
Date            Target         Time   Why not                              Moon   Visible from
----------------------------------------------------------------------------------------------------------------------
Fri 2026-10-02 Elnath         03:59  path misses this location             64%   South America
Mon 2026-10-05 Mars           02:12  path misses this location             31%   northern Canada, Russian Far East, Alaska
Tue 2026-10-06 Regulus        23:08  path misses this location             14%   Eastern Africa, Middle Africa, Southern Africa
...
Fri 2026-12-11 Nunki          00:12  Moon below horizon                     4%   North Pacific Ocean
...
```

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,
  along with where on Earth the occultation can be seen, if it happens anywhere.

**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.
- **Occurring elsewhere** lists occultations seen somewhere on Earth but not from `LOCATION`,
  with the reason: the occultation's path misses the location, the Moon is below the horizon,
  or the sky is too bright. When the path reaches the location, the time is when the
  occultation starts there; otherwise it is the Moon's closest approach to the target as seen
  from Earth's center.
- **Visible from** names up to three regions where the occultation can be seen with the Moon
  up and the Sun below the horizon (or "daylight only" if nowhere better), largest first. Regions are
  UN subregions such as "Western Europe" or "Eastern Africa", with large countries split up:
  US regions ("midwestern and southern US"), Alaska, Hawaii, Canada, China, European Russia,
  Siberia and the Russian Far East. Paths over water name the ocean or sea. Use `--map` on that
  date to see the exact area.
- 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**

The 2026-10-06 Jupiter occultation, framed on North America (`--region north-america`) and
across its whole path (no `--region`):

![Jupiter occultation of 2026-10-06 over North America](https://raw.githubusercontent.com/rtphokie/occultations/main/docs/jupiter_2026-10-06.png)

![Whole path of the Jupiter occultation of 2026-10-06](https://raw.githubusercontent.com/rtphokie/occultations/main/docs/jupiter_2026-10-06_path.png)

| 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.
