Astrocartography
At any given timestamp, each planet is rising along one curve across Earth,
setting along another, and crossing the upper or lower meridian along two lines
of longitude. astrocartography computes all four lines for each requested
body, and AstroMap in caelus-wheel renders them directly on the embedded
data tier with no extra downloads.
import { Engine, astrocartography, planetLines, julianDay, gast, DEG, riseSet } from "caelus";
import { embeddedData } from "caelus/data-embedded";
const engine = new Engine(embeddedData);
The four lines
Pass a Julian Day and an array of body identifiers to astrocartography to
compute the lines for each body:
const jd = julianDay(1990, 6, 10, 14, 30); // 10 June 1990, 14:30 UT
const lines = astrocartography(engine, jd, [
"sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn",
]);
lines.venus.mc; // -74.98
mc is the longitude where the body crosses the upper meridian and ic is
the opposite longitude where it crosses the lower meridian. asc and dsc
hold the rising and setting curves as arrays of [longitude, latitude] pairs
spaced at one-degree latitude intervals by default. All longitudes use
east-positive coordinates from −180° to +180°.
| Body | mc | ic | asc at 40°N | dsc at 40°N | Points per track |
|---|---|---|---|---|---|
| Sun | −37.66 | 142.34 | −148.55 | 73.23 | 133 |
| Moon | 168.48 | −11.52 | 101.43 | −124.47 | 131 |
| Mercury | −60.02 | 119.98 | −165.14 | 45.10 | 145 |
| Venus | −74.98 | 105.02 | −176.90 | 26.94 | 153 |
| Mars | −108.52 | 71.48 | 160.49 | −17.53 | 171 |
| Jupiter | −10.06 | 169.94 | −120.71 | 100.59 | 135 |
| Saturn | −180.00 | 0.00 | 108.93 | −108.93 | 137 |
At this chosen timestamp, Saturn's meridian lines align within a hundredth of a degree with the antimeridian and prime meridian.
Rendered with AstroMap, vertical lines mark the MC and IC meridians while the
curves show the rising and setting tracks.
Measuring distance from a location
Because meridian lines lie along constant longitudes, checking how far a city lies from an MC or IC line is simply a difference in longitude. Venus's MC is at −74.98° and New York lies at −74.01°, putting the line 0.97° (about 82 km) west of the city.
Rising and setting tracks curve across latitudes, so evaluating a specific city benefits from finer latitude spacing than the default 1° step. Pass a smaller step size as the sixth argument (following the south and north latitude limits) and match the closest latitude sample:
const fine = astrocartography(engine, jd, ["jupiter"], -85, 85, 0.01);
const [lon] = fine.jupiter.asc.find(([, lat]) => Math.abs(lat - 61.22) < 0.005);
lon; // -149.97
Anchorage sits at 61.22° N, −149.90° E. Jupiter's rising curve crosses that
latitude at −149.97°, just 0.07° (roughly 4 km) west of the city, putting
Jupiter on the eastern horizon at this timestamp. The fourth and fifth
arguments set the southern and northern latitude limits (-85 and 85 by
default).
What a line marks
Astrocartography lines track where the body itself aligns with the local horizon or meridian in equatorial coordinates (right ascension and declination). Whenever a body has nonzero ecliptic latitude, this location differs slightly from where the body's ecliptic longitude matches the Ascendant or Midheaven degree.
These curves are also purely geometric: they place the center of the body's
disc on an unrefracted horizon as seen from Earth's center. Calling riseSet
with { discCenter: true, pressure: 0 } matches that exact timestamp, whereas
default riseSet parameters reveal the offset caused by solar radius and
atmospheric refraction:
const [sunLon] = lines.sun.asc.find(([, lat]) => lat === 40); // -148.55
riseSet(engine, "sun", jd - 0.5, 40, sunLon, "rise", { discCenter: true, pressure: 0 });
// 0.9 s after jd
riseSet(engine, "sun", jd - 0.5, 40, sunLon, "rise");
// 300.0 s before jd
With disc-center geometry and zero refraction, sunrise at that point matches within a second. Visible sunrise (when the upper solar limb clears a refracted horizon) occurs 5 minutes earlier, placing observable sunrise at 40° N roughly 1.25° west of the geometric curve.
Where a track stops
Rising and setting tracks terminate poleward of the latitude where a body becomes circumpolar (never rising or setting). At this timestamp, the Sun's declination is 23.02°, bounding its curves between 66° S and 66° N (133 points). Mars sits close to the celestial equator, so its curves span the entire default range from 85° S to 85° N (171 points). The exact tangent latitude where a track touches its polar limit is omitted because longitude sensitivity becomes numerically ill-conditioned there.
Custom sky coordinates and fixed stars
astrocartography looks up each body's equatorial coordinates and delegates to
planetLines, which accepts right ascension, declination, and Greenwich
apparent sidereal time (all in degrees). Call planetLines directly for fixed
stars or arbitrary sky coordinates, dividing gast (returned in radians) by
DEG:
const star = engine.fixedStar("Sirius", jd);
const g = gast(engine.data, jd) / DEG; // 116.19
const sirius = planetLines(star.ra, star.dec, g);
sirius.mc; // -15.01
sirius.asc.length; // 147, from 73°S to 73°N
planetLines(star.ra, star.dec, g, -60, 60, 5).asc.length; // 25
Rendering with AstroMap
AstroMap accepts the object returned by astrocartography and renders an
equirectangular SVG projection. Because it uses no client-side state or
effects, it renders cleanly in server components.
import { AstroMap } from "caelus-wheel";
<AstroMap lines={lines} width={680} height={340} />
| Prop | Default | Description |
|---|---|---|
lines | required | Output object from astrocartography |
width, height | 720, 360 | SVG dimensions in pixels |
show | all four | Subset of "mc", "ic", "asc", "dsc" to render |
colors | built-in palette | Color mapping keyed by body ID |
graticule | true | Whether to draw meridian and parallel grid lines |
theme | dark | Ink overrides matching ChartWheel |
children | none | Custom SVG elements drawn beneath the lines |
By default, AstroMap draws only the coordinate graticule and planetary lines.
To add coastlines or borders, pass SVG paths in the same equirectangular
projection via children so they render underneath the lines.
Accuracy
Equatorial right ascension and declination hold within 2.6″ of Swiss Ephemeris from 1850 to 2150 (worst case on the Moon, where 2.6″ shifts an equatorial meridian line by roughly 80 m). Full error bounds are published on Validation.
TypeScript geometry routines match the Python reference across 392 checks at a tolerance of 1e-7°. Near a rising or setting track's polar limit, small changes in declination shift the track's longitude substantially.