Star Atlas

A Crystal/UIng desktop 3D application that lets you travel from Earth orbit through the solar system, nearby stars, star clusters and nebulae, to a full view of the Milky Way. It uses CrImage for image generation and PNG export. No network access is needed at runtime.

This directory is an application independent of UIng. It uses UIng and CrImage as shards. Run it from the root of this project. --release is recommended for smooth sphere rendering.

shards install
crystal run --release src/galaxy.cr

A libui-ng build with ImageBuffer support is required. UIng's postinstall prepares the native library. The UIng version you use must include UIng::ImageBuffer and uing/crimage. On Linux, the GTK 3 development libraries are also required.

You start near Earth. Move with the destinations on the left, the list at the top, or the search box and Find & fly. Guided tour is an automated tour from Earth to the galaxy.

When flying with the keyboard, click the rendering area first. Flight speed and zoom amount adjust to the current scale. Dragging, zooming, or flying interrupts the guided tour.

Display and Saving

• Visit the Sun, the eight planets, the Moon, Alpha Centauri, Sirius, Vega, the Pleiades, the Orion Nebula, and the galactic center.
• Planets use ray-sphere intersection, lighting from the light source, and Earth's surface imagery. Saturn's rings are a 3D ring whose front/back relationship with the planet changes with the viewpoint.
• Planet surfaces are drawn into a CrImage premultiplied RGBA image and transferred to a UIng::ImageBuffer reused per body. When the resolution changes, the image and buffer are recreated; native buffers are freed on exit.
• Coordinates and radii are in AU. Rendering uses the vicinity of each body as the origin, so planetary detail is preserved even after traveling between stars.
• Distant bodies are shown as minimum-sized dots with labels so they can be selected. The diameters of these dots are not to scale.
• Orbits and Labels toggle orbit lines and names.
• Save view saves the current scene as a standalone SVG with the Earth image embedded.

You can also export a scene without opening the window.

crystal run --release src/galaxy.cr -- --view galaxy --snapshot /tmp/milky-way.svg
crystal run --release src/galaxy.cr -- --view saturn --snapshot /tmp/saturn.svg
crystal run src/galaxy.cr -- --list

Astronomical Model

This is a simulator for exploring the distances and 3D structure of the universe. It is not a precision ephemeris for observation or navigation, nor a service equivalent to Google Earth's terrain tiles.

• The initial date/time is 2026-10-27 UTC, paused. Playback speed can be set to 1, 10, or 30 days/second.
• Planets follow Keplerian orbits using JPL's J2000 orbital elements and orbital periods. Perturbations and long-term changes in orbital elements are not computed. Earth approximates the Earth-Moon barycenter. Time is capped at the year 2050.
• The Moon follows an approximate orbit around its parent body, Earth. Stars other than the Sun are shown as representative single spheres; individual orbits of binary stars are not reproduced. Proper motion is also omitted.
• Nearby named bodies use approximate distances and galactic coordinates. The other ~28,000 stars, the galaxy's arms and bar structure, stars within clusters, and nebulae are schematic representations generated from a fixed seed. They are not observational star catalogs or actual nebula imagery.
• Surface patterns other than Earth, cloud bands, and rotation direction/phase are simplified. There is no feature to search for cities or terrain on body surfaces.

Data and sources:

• NASA Planetary Fact Sheet: planet sizes and orbital periods.
• NASA/JPL Approximate Positions of the Planets: J2000 orbital elements and the Kepler equation.
• NASA: Our Milky Way Galaxy, Milky Way in Multiple Wavelengths: approximate scale of the whole galaxy and the Sun's position.
• SIMBAD: Alpha Centauri, Sirius, Vega, Pleiades, Orion Nebula: directions of named bodies.
• Sources and regeneration instructions for the Earth image are in assets/README.md.

Testing

crystal spec
UING_NATIVE_GUI_TESTS=1 UING_IMAGE_BUFFER_TESTS=1 crystal spec spec/image_buffer_spec.cr
crystal run --release src/galaxy.cr -- --smoke-test

The tests cover the camera's perspective projection, precision when traveling between planets and the galaxy, orbital motion, collision avoidance, CrImage image reuse, and PNG transparency embedded in SVG. The ImageBuffer tests and --smoke-test require a desktop environment. The latter renders in a real window for three seconds and then exits.

Build and Local Development

shards build --release
./bin/galaxy

To use a UIng checkout located next to this project, copy shard.override.yml.example to shard.override.yml. That file is for your local environment and is excluded from Git.

dependencies:
  uing:
    path: ../uing

If the native library has already been prepared on the UIng side, you can use the existing library with the following commands.

cp shard.override.yml.example shard.override.yml
shards install --skip-postinstall
crystal run --release src/galaxy.cr

shard.lock is managed on the application side. Committing the one generated by a normal shards install pins the dependency versions.

License

The application code is under the MIT License. For the source and license terms of the Earth image, see assets/README.md.