Guides

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.

ChartSphere.tsx

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.

AstroMap.tsx

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.

EphemerisGraph.tsx

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} />;
}

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.