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:
Written notes for workshop part:
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...
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
.gscfiles - Play back camera path files
Keyframes System
- Define camera paths visually
- Smoothing, time normalization, etc.
- Save keyframes file to
.gkffile - Export to
.gscfile
Keyframes System
Scripting
Python scripting workshop
Scripting
-
Gaia Sky API → Python via Py4j
- Also, see REST API via HTTP
- 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
Wrapping up
Documentation, Repository, etc.
Interested in Gaia Sky?
| Workshop scripts | |
| Video tutorials | |
| Mastodon | |
| Bluesky |
Home Page
Documentation
Source Repository
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