Visualizations

The same chart object renders as more than a flat wheel. The engine feeds three dependency-free SVG views: a 3D celestial sphere, an astrocartography world map, and a graphic ephemeris. Every view below is server-rendered on this page from the embedded engine.

3D chart sphere

A flat wheel places every planet on the ecliptic. The sphere keeps each body at its true ecliptic latitude, so the Moon rides above the ecliptic and Pluto swings well off it. The ecliptic and equator draw as great-circle rings, solid on the near hemisphere and faded on the far one. The matching 3D aspect angle in the engine is angularSeparation3d, which accounts for latitude rather than longitude alone.

import { Engine } from "caelus";
import { embeddedData } from "caelus/data-embedded";
import { ChartSphere } from "caelus-wheel";

const engine = new Engine(embeddedData);
const chart = engine.chart(2026, 6, 13, 12, 0, 0, 40.71, -74.01, "placidus");

// The chart's bodies already carry ecliptic latitude, so the sphere can
// lift each planet off the ecliptic plane (a flat wheel collapses that to 0).
export function Sphere() {
  return <ChartSphere chart={chart} size={360} tilt={64} />;
}

Astrocartography map

For one instant, each planet sits on an angle along a curve across the Earth. astrocartography returns those lines from each body's right ascension and declination and the moment's sidereal time: the MC and IC meridians and the curved ASC and DSC rising and setting tracks. AstroMap draws them on an equirectangular graticule; layer your own coastline paths under the lines as children.

import { Engine, astrocartography, julianDay } from "caelus";
import { embeddedData } from "caelus/data-embedded";
import { AstroMap } from "caelus-wheel";

const engine = new Engine(embeddedData);
const jd = julianDay(2026, 6, 13, 12); // one instant, UT
const lines = astrocartography(engine, jd, ["sun", "moon", "venus", "mars", "jupiter"]);

// MC/IC are meridians; ASC/DSC are the curved rising and setting tracks.
// The basemap is a graticule; pass coastline paths as children to layer a map.
export function Map() {
  return <AstroMap lines={lines} width={680} height={340} />;
}

Graphic ephemeris

A graphic ephemeris plots one value per body over time. ephemeris samples longitude, latitude, declination, right ascension, or speed across a range, and EphemerisGraph draws the series, splitting each line where longitude wraps from 360 back to 0. Below: the longitude of Mars, Jupiter, and Saturn over two years at weekly steps.

import { Engine, ephemeris, julianDay } from "caelus";
import { embeddedData } from "caelus/data-embedded";
import { EphemerisGraph } from "caelus-wheel";

const engine = new Engine(embeddedData);
const series = ephemeris(engine, ["mars", "jupiter", "saturn"], {
  start: julianDay(2026, 1, 1),
  end: julianDay(2028, 1, 1),
  step: 7,            // weekly samples
  value: "longitude", // or latitude, declination, rightAscension, speed
});

// wrap=360 splits each line where longitude rolls 360 back to 0.
export function Graph() {
  return <EphemerisGraph series={series} width={680} height={340} wrap={360} />;
}

Sky View

Sky View frames the visible sky from a place and moment, then writes a prompt for an AI image model. Give it a compass aim (azimuth and altitude), a lens preset, and an image size; it returns each in-frame body at exact pixels, its apparent size and a brightness cue from magnitude, the Moon’s phase and which way the crescent points, the twilight stage and limiting magnitude, the horizon row, the Milky Way band, and a deep field of naked-eye stars. Caelus computes the geometry and photometry; it does not render the image.

Reference frames project on request: the ecliptic, the zodiac signs, the house cusps and angles, and the constellation figures, each as exact pixels. skyViewSequence steps the same frame through time for an animation, returning the celestial pole and the sky’s rotation per frame. Try it on the playground Sky View tab, with a play control and overlay toggles.

Next steps

These render the same engine output as the flat ChartWheel in the Architecture guide. See Recipes for event search and the when() query language, and Electional Search for scanning a window for the best moment.