A cross-platform desktop planetarium app made using the ImGui library. https://github.com/ocornut/imgui
The stars are alien suns.
Alienorum can be built and run on Linux, Mac, and Windows. Before building, please make sure to install all the dependency packages:
Linux: apt-get install -y libsdl2-dev libsdl2-image-dev libjpeg-dev libpng-dev build-essential libcurl4-openssl-dev
Mac OS: brew install sdl2 sdl2_image jpeg png
MSYS2 (Run in MINGW64 environment): pacman -S mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_image mingw-w64-x86_64-libjpeg-turbo mingw-w64-x86_64-libpng mingw-w64-x86_64-curl
Additionally, for those running Windows, since the star catalogs all download as compressed .gz files and Windows has incomplete support for gzip, Alienorum will require 7zip (https://www.7-zip.org/download.html) to be installed.
- OpenGL rendering;
- Sky atlas with pan and zoom, RA/dec grid, and constellation lines;
- Automatic downloading and use of professional star catalogs;
- Spaceflight feature with time dilation and warp speed capability;
- View space from any vantage point;
- Time travel (in-universe only) - set the view for any date by stepping forward/backward;
- Information shown when hovering over a celestial object, including names, coordinates, distance, and magnitude;
- Realtime satellite positions;
- Exoplanets;
- Ability to select an individual star/planet/moon/satellite and teleport to its position;
- Universe saved to portable, customizable JSON file, allowing defining your own planets/stars;
- Custom texture map generation;
- More coming soon...
The first time you run Alienorum, you will see a splash screen featuring our alien mascot (maybe the alien should have a name?) and a dynamic loading message. The application will begin by downloading star catalogs; if you run it in a terminal you'll be able to see the download process. This might take a while, but it's a one-time thing.
After downloading finishes, the application will load a selection of stars from the catalogs. When displaying stars and during spaceflight, Alienorum dynamically hides stars that are too far away or too dim, that way it can load hundreds of thousands of stars and still smoothly animate views of space.
To begin a spaceflight, point the view in the direction you wish to go, and press the + (plus sign) key. You can monitor your speed using the status pane at left. Most likely you will want to zoom past the stars, so just hold the + key down until you get very very close to the speed of light. Notice the clock in the status pane speeds up.
As you're speeding up, you can use the mouse to have a look around. Once you press the + key the first time, it sets your direction of travel and any further use of + or - will affect only your speed and not your direction. You can see the Sun and inner planets zooming away behind you as you keep accelerating.
Notice that due to time dilation, it takes a long time to get up to interstellar speeds. A really really long time! You would be forgiven for wondering how the developer of this app can be so cruel, but it's relativity that's this cruel. The universe is really really really big. Even worse, relativity says the closer you get to the cosmic speed limit, the more energy you have to dump into your engines to keep accelerating.
At least there's unlimited in-app spaceflight fuel. If you have some way to hold down that + key, the simulation will eventually reach interstellar speed. But we're not going to make you go through all that trouble - we've added a cheat code.
Point the view in the direction you want to go and press W. Notice that you are now traveling at slightly over warp 1, and that the clock is keeping normal time. Press + several more times until you see the stars begin to move. Warp speed is a frequent sci-fi trope to get around the limitations of relativity, often involving some kind of astrophysics shortcut that bypasses actually moving through normal space. For our purposes, we can just ignore relativity and show what spaceflight and flyby sequences would look like without it.
Even with the help of warp speed, it still takes getting up to a few million to a few tens of millions of times the speed of light just to see the stars rush by. Space is really really really really REALLY big.
Sublight speed can be useful for moving between nearby solar system objects, while warp is useful for longer trips up to and including interstellar flight.
To stop spaceflight, press X.
Hovering the mouse over a celestial object displays information about that object in the right hand pane. Clicking will select the object, resulting in a green circle around it. To clear object selection, press Shift+S.
After slecting an object, pressing O will teleport to that object. The local reference plane will update in the view, so you might be looking in a different direction than before.
You can also use the search box in the left pane to find objects. You can search by friendly name (e.g. Polaris), Bayer-Flamsteed name (Alp UMi or 1 UMi), HD designation, HIP designation, or Gliese number. It uses a fuzzy search algorithm that sometimes gets caught on names with similar letters - if you search Proxima it returns Porrima (Gam Vir), but "proxima cent" finds the right star. After clicking Find or pressing Enter, the search result will be selected.
To track an object, first select it then press T. The view will remain centered on the object, its info will remain in the right pane, and it will not be possible to hover over any other object for info. To stop tracking, press Shift+T.
One trick that can make for an impressive display is to do a flyby. Start by finding the object of interest, and use the mouse to point the view just off center of the object. (Dragging with the left button gives coarse panning; with the right button, fine panning; and with the middle button, ultrafine panning). Press + or W, then select the object of interest and track it with T.
Then speed up to approach the object, watching its distance in the right pane. Try not to come in too fast; as long as you are tracking the object, the app will automatically slow your approach as you get closer to the target. Otherwise it's very easy to overshoot and zip right past it. If your speed is just right, you can float by the target and watch it seem to roll across the background stars.
Note to include exoplanets, the catalog must be downloaded manually:
- First, open https://exoplanetarchive.ipac.caltech.edu/cgi-bin/TblView/nph-tblView?app=ExoTbls&config=PSCompPars in a web browser;
- Then manually select to include the following columns:
- HD ID
- Inclination
- Epoch of Periastron
- Argument of Periastron
- True Obliquity
- RA[deg]
- Dec[deg]
- Distance[pc]
- V Magnitude
- Then click Update.
- Then click the download (save icon) button, choose CSV format, and click the green Download Table arrow.
- Save the resulting file in the alienorum/catalogs/ folder.
After completing these steps, every time you run Alienorum it will load the exoplanets file.
Exoplanets will not automatically update; if you wish to loop at a new planet discovered since your last download, please follow the above steps to obtain a new exoplanet catalog. The filenames are timestamped and Alienorum will only use the file with the most recent datetime.
To add a satellite, press ^ (Shift+6 on US keyboards). A searchable list will appear; you can search by satellite name, e.g. ISS or HST, or by category, e.g. gps-ops or iridium-next. The search is not case sensitive. Once a satellite has been loaded, it will be selected and, if having clicked the first button, the satellite will be centered in the view. Pressing O takes you to the satellite, where the orbit center (usually Earth) appears at the nadir of the view. The resulting effect is if you choose an LEO (low Earth orbit) satellite and O to it, you will see the Earth along the bottom of the view as if you were up in the satellite positioned so that Earth is "down". LEO views make great background views to leave open; they slowly change over time and you can enable realism mode by pressing ! (Shift+1 on US keyboards) and close all dialog windows for maximum immersion.
Alienorum auto-downloads satellite data from CelesTrak (https://celestrak.org/). Automatic download is set to only
happen at most once per day. You can override this by opening catalogs/sat/sources.json and changing one of the
"LastAccessed" days to a date in the past like "2000-01-01 00:00:00", then deleting whichever local .csv file that
JSON entry is for. The next time you run Alienorum it will re-fetch the file. CAUTION: CelesTrak's data only update
every two hours, and the site admin has limited bandwidth. Fetching the same file(s) too frequently may result in
CelesTrak blocking your IP. This can be avoided by letting Alienorum manage the downloads.
To edit a celestial object, select it and press Shift+E. An edit window will appear at lower right, offering several object properties that can be set in-program. All changes will take effect right away.
To add a new object, first select its center of orbit and then press Shift+A. A dialog will ask what kind of object to create. Currently, only Star, Planet, and Moon will work. After clicking Go, the new object will be added with a few default parameters and you will see an edit window to fill in all its other properties.
Alienorum generates fictitious texture maps of objects that don't have a map file in the maps/ folder. While
editing, you can save, refresh, and regenerate these fictitious maps. Save creates file with the object's name in
maps/, and refresh reloads the existing file or creates a new texture if the file is absent. The regenerate
button creates a high resolution texture, never the same as the existing texture, but suitable for world building
(10000 x 5000 pixels). This will take a moment to complete so be sure to let it finish before saving or retrying.
To export your objects you've created or modified, press U. To load them again next session, first rename your
universe.json file to something else, let's say my_universe.json, then the next time you run Alienorum, run it
from the command line with the load argument like this: ./bin/alienorum load my_universe.json. Note Alienorum
will not touch your custom file; any changes made will be written to universe.json only, so make sure to either
copy them to your custom universe file or rename the default universe.json to your filename.
Any object properties not included in the edit window can be edited in the .json file.
You can also edit the universe JSON files to modify other parameters not included in the window. Just make sure the file is still valid JSON after any edits. There are third party apps that will check a .json file to make sure it's valid and find any errors.
The default lat/lon coordinates are those for Babylon, where archaeological evidence exists for astronomical knowledge
in ancient times. To set your own location as the default, create a file in the alienorum root folder called user.json
and add the following lines, changing the numbers to your own location:
{
"Latitude": 45.52,
"Longitude": -122.68
}
The current full list of keyboard shortcuts is:
B Increase brightness
Shift+B Decrease brightness
` Increase gamma
~ Decrease gamma
* Zoom in
/ Zoom out
{scroll} Zoom
% Reset default brightness and zoom
Shift+R Toggle red light mode
Q Increase texture rendering quality. WARNING: Use cautiously; the value can get too high quickly and render the app unusable!
Shift+Q Improve performance by decreasing texture rendering quality
F11 Toggle fullscreen
& Sky atlas mode
_ Horizon mode
{click} Select object
Shift+S Clear selection
T Track selected object / cease tracking and select
Shift+T Clear tracking
C Show/hide constellation lines (only within 10 l.y. of Sun)
G Show/hide RA/Dec lines
L Show/hide labels
Shift+O Show/hide orbits
N Show/hide info panel
S Show/hide status panel
! Hide all annotations (realism mode)
, Hide mouse cursor until next mouse move (e.g. for taking screenshots)
O Go to object (selected or tracked)
R Return to default view, from Earth, at current time
W Warp speed
X Full stop
+ Increase speed
- Decrease speed (no effect if already stopped)
{arrows} Steering
{Home} Accelerate backward
{End} Accelerate forward
Z Advance one century
Shift+Z Rewind one century
Y Advance one year
Shift+Y Rewind one year
M Advance one month
Shift+M Rewind one month
D Advance one day
Shift+D Rewind one day
H Advance one hour
Shift+H Rewind one hour
I Advance one minute
Shift+I Rewind one minute
@ Return to present moment
Shift+A Add new object in orbit around current object ^ Add satellite from downloaded lists . Add asteroid/minor planet from astorb Shift+E Edit current object U Export user-added and user-modified objects to universe.json F4 Load user objects from an external JSON file
IMPORTANT: After loading a universe with F4, subsequently saving your changes with U will not overwrite the external file; it will save to universe.json. Make sure to either copy your changes to the external JSON file or back up your old file and rename universe.json to the working filename. It's also a good idea to check universe.json to make sure it has all the custom celestial objects.
Some of Alienorum's status messages and error mesages are output to the terminal (the command line), so it is recommended to run the app in a command prompt if you notice any unexpected behavior.
If a JSON file fails to load, you can use any third party JSON syntax checker to find and fix whatever might be wrong with it. JSON files can be edited in any text editor.
If you see a message in your terminal that reads Bump map must have same resolution as surface map., check
and see if you have both the normal maps/Moon_surf.png map and the full sized maps/Moon_surf.jpg map. If
so, then it's safe to delete the .jpg file. Alternatively, if you wish to keep the higher resolution, you can
delete the .png instead (it's just a scaled down version of the .jpg) and use your favorite image editor to
resample the maps/Moon_bump.jpg map up to 2048x1024 resolution.