Gaia Sky

Scripting workshop

Toni Sagristà Sellés, Stefan Jordan

tsagrista@ari.uni-heidelberg.de

DPAC Consortium Meeting, Cambridge (UK)
April 2025

Find this presentation at:

tiny.cc/gaiasky2025

gaia.ari.uni-heidelberg.de/gaiasky/presentation/202504/

Written notes for workshop part:

tiny.cc/workshop-2025

docs.gaiasky.space/master/workshops/dpac-plenary-cambridge-2025

Introduction

What is Gaia Sky?

Gaia Sky

  • 3D Universe software platform similar to Celestia or OpenSpace
  • Multiplatform → Linux, Windows, macOS
  • Open source and libre
  • Focus on Gaia and its data
  • Outreach material production

Gaia Sky Features


  • 4 camera modes
  • Seamless navigation
  • 6D exploration → $x$ + $\mu$
  • VR support (Windows) → OpenXR
  • Interactivity with Gaia data
  • Panorama, planetarium, orthosphere
  • Stereoscopic mode (3D)
  • Sparse virtual textures
  • Elevation representation
  • Ray-marched objects and volumes
  • External datasets → VOTable, FITS, csv
  • Filtering and color mapping
  • SAMP integration
  • Camera paths and keyframing
  • Scripting API
  • Many more...

What's new (since Nice)


  • Support for exoplanet catalogs (NASA Exoplanet Archive)
  • Procedural generation of planetary surfaces
    • CPU → GPU
    • Divide computation into multiple frames
  • Automatic DPI scaling
  • New in-app console (more later)
  • Improve volume rendering infrastructure
  • Volume nebulae in NGC2000 dataset
  • Aurora borealis/australis dataset
  • Smooth camera transitions (API)
  • New domain: gaiasky.space
    • And website!
  • New verified Flathub package
  • New icon

Operation

Basic Controls and Modes

Welcome Screen

  • Access to dataset manager
    • Download datasets
    • Enable/disable datasets
    • Update datasets
    • Delete datasets
  • Preferences, help, etc.

Basic Movement

Drag mouse to rotate, scroll to move, hold to roll

Also, use the cursors to move:

Object Selection

Select objects by:

  • Double-clicking on them
  • Search by name (press )

User Interface

Control and Information Panes

UI Overview

Control Panes

  • Time   
  • Camera   
  • Visibility   
  • Visual Settings   
  • Datasets   
  • Location Log
  • Bookmarks   

Time Pane

  • Start/pause time   
  • Change time warp    and
  • Set and reset time   +

Camera Pane

Camera modes:

  • Free   
  • Focus   
  • Game   
  • Spacecraft   

Visibility Pane

  • Turn on/off object types
  • Control individual object visibility

Datasets Pane

Datasets Pane

  • Show/hide datasets
  • Highlight datasets
  • Delete datasets
  • Per-dataset point size (when applicable)
  • Dataset preferences

External Information

External Information

  • Wikipedia
  • Gaia Archive
  • Hipparcos Catalog
  • Simbad (opens in browser)

Videos

Video Creation Tools

Frame Output System

  • Export every frame to an image file → +ffmpeg
  • → start/stop recording frames
  • Optional: arbitrary resolution export
  • Warning → SLOW

Camera Paths

Record and play back camera paths

Camera Paths

  • Record camera paths to .gsc files
  • Play back camera path files

Keyframes System

  • Define camera paths visually
  • Smoothing, time normalization, etc.
  • Save keyframes file to .gkf file
  • Export to .gsc file

Keyframes System

Scripting

Python scripting workshop

Scripting

  • Gaia Sky API → Python via Py4j
  • Modify settings
  • Manipulate camera
  • Control time
  • Add, remove, modify objects and datasets
  • Run code snippets after every frame
  • Much more: scripting docs

Scripting workshop

Now we move to
workshop notes

Wrapping up

Documentation, Repository, etc.

Interested in Gaia Sky?

Workshop scripts
Video tutorials
Mastodon
Bluesky

Home Page

gaiasky.space

Documentation

docs.gaiasky.space

Source Repository

codeberg.org/gaiasky/gaiasky

Thank You

System

and Internal Tech

System Overview

  • User interface
  • Event manager
  • Object model
  • Rendering system
  • Scripting engine

Language Breakdown

As of November 2023

            --------------------------------------------------------------------------------------
            Language files blank comment code
            --------------------------------------------------------------------------------------
            Java 1174 27765 40274 172917
            GLSL 150 2546 2175 10026
            Properties 18 1130 8537 8618
            JSON 11 6 0 7124
            XML 4 2 4 6277
            Python 87 1744 1037 4779
            Markdown 12 765 0 3065
            YAML 4 46 744 640
            Gradle 3 113 76 621
            Bourne Again Shell 9 102 137 286
            Bourne Shell 6 45 134 171
            HTML 2 7 0 91
            --------------------------------------------------------------------------------------
            SUM: 1493 34350 53164 217137
            --------------------------------------------------------------------------------------

LOD Datasets

Problem: billions of stars in real time!

Our approach: MS-LOD (Magnitude-Space LOD)

  • Star flux decreases with $r^2$
  • Organize stars in an (oc)tree
    • Sorted by magnitude, descending
    • Brighter stars at top levels
    • Fainter stars deep down

Physical node size proprotional to magnitude

Use solid angle from camera $\phi$ to determine visibility

Octree Traversal

  • Visibility condition: $\theta_i \leq \Theta$
    • $\theta_i$ — solid angle of octant $i$
    • $\Theta$ — user-defined draw distance setting
  • Octant size proportional to brightness of contained stars
  • Pop-ins avoided via magnitude-based star shading and small $\Theta$ setting
  • Otherwise, avoided by $\theta$-based linearly interpolated blending

Octree Traversal

  • Different distance to camera
  • Same octant size
  • Same distance to camera
  • Different octant size

MS-LOD Octree

DR3 default dataset (15M stars)

Camera – Challenges

  • Seamless navigation over vast range of distances
    • From spacecraft to high-$z$ galaxies

Camera – Challenges

  • Limited floating-point precision
    • Subtraction of similar large values → catastrophic cancellation
  • Gaia at only 1200 km from the origin
  • Jittering due to catastrophic cancellation

Camera – Our Approach

  • Floating camera
  • Maintain camera at origin $\vec{0}$
  • Move rest of scene in reverse
  • Typical approach: transform camera
  • Our approach: transform scene

Camera – Our Approach

  • Compute $\mathbf{M}_{mv}$ on CPU with arbitrary precision
  • Instead of $\mathbf{M}_{model}$ and $\mathbf{M}_{view}$, send $\mathbf{M}_{mv}$ to GPU
$\mathbf{p}_{clip} = \mathbf{M}_{proj} \cdot \mathbf{M}_{view} \cdot \mathbf{M}_{model} \cdot p_{obj} = \mathbf{M}_{proj} \cdot \mathbf{M}_{mv} \cdot p_{obj} $

Camera – Our Approach

add node at the top of the scene graph with camera $\vec{pos}^{-1}$

Camera – Caveats

  • $\mathbf{M}_{mv}$ computed on CPU with arbitrary precision
    • Computationally more expensive than using floating point
  • Only for needed objects (panets, asteroids, etc.)
  • Most stars are very far from the camera
    • CPU-based approach for close-by stars
    • Standard approach for remaining stars