backing up Stellarium - Macintosh

Here are my backup/restore testing notes for Stellarium on an Apple Macintosh.

The purpose of this document is to help anyone know where custom user data is stored by the Stellarium program. This can helpful in a variety scenarios such as recovering from a reinstall, reinstating data after an upgrade, and transferring to a different computer.

It's too bad we can't just backup everything in the Stellarium library folder. That'd be quick and easy but that would backup the large star catalogue files and other unnecessary files.

Testing was performed on my Mom's iMac computer, running OS X, 10.13 High Sierra, using her profile in which Stellarium 0.18.3 was installed.

Note: {NAME} in the folder path refers to the Apple Mac account name attached to the logged in user. 

The primary storage drive was assumed, Macintosh HD, but adjust accordingly if you have used a secondary or tertiary drive.

preamble on hidden files

Remember, the Library folder under a user's home folder is normally hidden. You'll need to enable the display of hidden files and folders in a Finder window or in a file dialogue.

This describes how to access the hidden files and folders in the context of Stellarium.

1. open a new Finder window on the Macintosh HD
2. press Cmd Shift . (period) to toggle on the display of hidden items (shown in light grey)
3. click the Users folder
4. click your profile folder (with the house icon) 
5. click the Library folder (hidden, shown in a light grey font)
6. click the Application Support folder
7. click the Stellarium folder; note the various folders used by Stellarium:

• data 
• modules  
• stars / default  
• landscapes

scenario - uninstalling/reinstalling

Perhaps you are doing a refresh. Or migrating to a new computer. There's an assumption we're using the same version or near to the same version. 

* landscapes

This refers to custom landscapes, aka backgrounds or surroundings. A landscape is made up of one or more image files plus a text initialisation file.

Now, one shouldn't bother backing up the "stock" landscape files from the Stellarium website; of course, you can always get those again.

However, if you made your own custom landscape, you'll want to be sure to keep those related files. The INI file is where the hard work is done, configuring the landscape texture load.

folder:

Macintosh HD / Users / {NAME} / Library / Application Support / Stellarium / landscapes 

file(s):

Within the "landscapes" folder there should be unzipped subfolders here, e.g. "my back yard" or "Carr Observatory," one for each of the added landscape profiles.

landscape.ini

Each landscape profile has the all-important INI file and then PNG image file(s).

* additions to SSO objects

If you have added comets and asteroids to Stellarium, they are all saved in a particular file. Arguably, these can always be reloaded from official sources such as the MPC. Additionally, downloading and installing from the online source would accommodate for updated ephemeris data. The main rationale for backing up this file is when you have many modifications, when you made a significant number of adds, edits, and deletes. 

folder: 

Macintosh HD / Users / {NAME} / Library / Application Support / Stellarium / data

file:

ssystem_minor.ini

* star catalogues

I recommend you do NOT backup the catalogue files proper as they are too large. And they are downloaded from a Stellarium repository. 

What you should do is note or record the file with the highest catalogue number. Then, inside Stellarium, you can load in the necessary catalogues after a restore.

Remember to offset given the first catalogue file Stellarium uses has the number 0 (zero). 

folder: 

Macintosh HD / Users / {NAME} / Library / Application Support / Stellarium / stars / default

file(s):

stars_4_1v0_2.cat

starsConfig.json

The example "stars" file shown here means the catalogue file number 4 has been added. In other words, file number 4 is the 5th catalogue loaded.

The "stars config" file indicates which catalogues are active but this is a system generated file and does not need to be backed up. 

Again, none of the files in the \stars folder need to be saved...

* general settings

User settings and preferences are captured in a general configuration file. 

folder: 

Macintosh HD / Users / {NAME} / Library / Application Support / Stellarium

file(s):

config.ini

* telescope-mount config

All the telescope-mount profiles as managed by the Telescope Control [SIC!] plug-in. And for each mount profile, its particulars and parameters, you'll want to backup.

folder: 

Macintosh HD / Users / {NAME} / Library / Application Support / Stellarium  / modules / TelescopeControl

file(s):

telescopes.json

device_models.json

The "telescope" file is critical. It contains mount details, the communication ports, driver references, etc. Ensure this file is saved.

The other file here, "device models," is a system-generated file with the "standard" built-in drivers. It does not need to be backed up.

* custom equipment

All the data in the oculars module of Stellarium is saved in one file. All your custom eyepieces, telescopes, camera lenses, cameras/sensors, magnifiers, etc. and their parameters can be easily backed up. The user preferences for the oculars tool itself, such as mask transparency, is captured.

folder: 

Macintosh HD / Users / {NAME} / Library / Application Support / Stellarium  / modules / Oculars

file(s):

ocular.ini

* custom locations

If you create custom locations for your different observing sites, especially if you have several, you will want to back them up.

folder: 

Macintosh HD / Users / {NAME} / Library / Application Support / Stellarium / data

file(s): 

user_locations.txt

* observing lists

If you have created you own custom observing lists (formerly bookmarks) e.g. "tonight's campaign 7 Dec 2022," you will want to back them up. Pre-defined observing lists you have downloaded, presumably you don't need to copy them as you can procure them from the original source.

folder: 

Macintosh HD / Users / {NAME} / Library / Application Support / Stellarium / data

file(s): 

observingList.json

A note for users with older version of Stellarium, still using the Bookmarks feature. The implementation of bookmarks only allowed for one to be open and active. Multiple lists were supported via distinct files. If a user has many bookmark lists, such the four separate seasonal lists for the RASC Finest NGC, or extracts from the Astronomical Calculations window, then the user may want to back up all these JSON files. Their location is arbitrary so one most proactively seek them out.

a backup plan

The notes above shows that there are a handful of files to backup to safeguard one's custom data and the application's settings. 

Assuming you use these features in Stellarium, the files to back up (with rather obvious names) are:

• ssystem_minor.ini 
• config.ini 
• telescopes.json
• ocular.ini
• user_locations.txt
• observingList.json
• custom landscape folders (with the image and INI files)

And make a note of the highest star catalogue loaded.

It's pretty easy to jump into the Finder and copy the individual files somewhere for safe keeping. 

the restore

A restoration process was attempted as part of this test. The following steps were performed:

1. the user data was backed up/copied
2. the Stellarium software was uninstalled with the option to remove all user data
3. the software (same version) was reinstalled, i.e. "clean install"
4. the program was launched and examined, where it was observed that no custom settings were preserved, there were no custom locations, landscapes, observing lists, solar system objects, custom oculars, etc.
5. the program was shut down
6. the user data was reinstated to the specific folders
7. Stellarium was launched and examined, where it was noted that all the customisations were back! 
8. the missing star catalogues were loaded

 

summary

It is quite easy and quick to manually backup the handful of files on the Mac, as needed, to protect for customised, personalised data in Stellarium and one's preferences for the appearance and operation of the software.