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.
Testing was performed on the John Kim Chi computer, a Dell laptop running Windows 10.
Note: {NAME} in the folder path refers to the MS account name attached to the logged in user.
The primary storage drive is assumed, C:, but adjust accordingly if you have used a secondary or tertiary drive.
Use %appdata% to quickly land in the Roaming folder...
Also remember, the AppData folder, the parent of Roaming, is normally hidden. You'll need to enable the display of hidden files and folders in Windows Explorer.
scenario 1 - uninstalling/reinstalling
We are doing a refresh. Or perhaps transferring to a new computer. There's an assumption we're using the same version or near to the same version. Stellarium 1.1 was used.
* landscapes
This refers to custom landscapes, aka backgrounds or surroundings. A landscape is made up of one or several 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.
But if you made your own custom landscape, you'll want to be sure to keep those related files. Arguably, the graphic files don't need to be saved, assuming your have your original photographic scenery shots somewhere else. But the INI file is where the hard work is done, configuring the landscape texture load.
folder:
C:\Users\{NAME}\AppData\Roaming\Stellarium\landscapes
file(s):
Within the "landscapes" folder there should be unzipped subfolders here, e.g. "my back yard" or "Mary's cottage," 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 official source would also accommodate for updated ephemeris data. The main rationale for backing up this file is when you have many modifications, made a significant number of adds, edits, and deletes.
folder:
C:\Users\{NAME}\AppData\Roaming\Stellarium\data
file:
ssystem_minor.ini
* star catalogues
It is recommended that you do NOT backup the catalogue files proper as they are too large. And they are system generated or 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).
C:\Users\{NAME}\AppData\Roaming\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.
To recap, none of the files in the \stars folder need to be saved...
* general settings
Toggled settings and user preferences such as cardinal points and sky settings like star scales and the dynamic Moon option are saved by Stellarium in a general configuration file. Meteor radiants visibility, star names visibility. Which buttons show in the horizontal toolbar. Line colours, font colours and size. The start-up direction and FOV. Everything! All the user's preferences.
C:\Users\{NAME}\AppData\Roaming\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:
C:\Users\{NAME}\AppData\Roaming\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. So 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.
C:\Users\{NAME}\AppData\Roaming\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.
C:\Users\{NAME}\AppData\Roaming\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 5 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.
C:\Users\{NAME}\AppData\Roaming\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:
- custom landscape folders (with the image and INI files)
- ssystem_minor.ini
- config.ini
- telescopes.json
- ocular.ini
- user_locations.txt
- observingList.json
And make a note of the highest star catalogue loaded.
It's pretty easy to jump into File Exploder and copy the individual files somewhere for safe keeping. If you were good are scripting and wanted to do it frequently and quickly, you could write a DOS batch file.
Another approach is to back up specific folders. First, get to this starting point:
C:\Users\{NAME}\AppData\Roaming\Stellarium
then back up the subfolders:
- \landscapes for all the custom landscape files
- \data for the SSO content, custom locations, and observing lists
- \modules for all the plug-ins and their settings
All the remains is to back up the config.ini file in the \Roaming\Stellarium folder.
It's too bad we can't just backup everything in \Roaming\Stellarium. That'd be quick and easy but that would absorb the large star catalogue files...
As I consider it, the folder approach is awkward.
* the restore
A restoration process was attempted as part of this test. The following steps were performed:
- the user data was backed up/copied
- the Stellarium software was uninstalled with the option to remove all user data
- the software (same version) was reinstalled, i.e. "clean install"
- 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.
- the program was shut down
- the user data was reinstated to the specific folders
- Stellarium was launched and examined, where it was noted that all the customisations were back!
- the missing star catalogues were loaded
* summary
It is quite easy and quick to manually backup the handful of files in Windows, as needed, to protect for customised, personalised data in Stellarium and one's preferences for the appearance and operation of the software.
scenario 2 - updating/upgrading
The situation simulated here was that a user has an old version of Stellarium on their computer and on the same computer they want to upgrade to the more current version of the software.
The approach tested here was the "place on top of" method. Meaning, the user downloads and installs the new version over top of the existing version. In the hopes of keeping what is already present. One does not uninstall the old version. Again, the new is simply downloaded and installed.
While not tested explicitly, the software uninstall process prompts the human to keep or discard the user data. Not removing the user data may yield the same outcome as the "place on top of" approach.
For testing purposes, Stellarium version 0.20.4 was used as the "starting point." The software was upgraded to version 1.1. While running the installer program, a warning dialogue with Attention! in the title bar appeared:
The existing version of the configuration data for telescopes in the Telescope Control plugin is obsolete.
On launching the new version, there were no apparent on-screen warnings.
The following customisations and features where checked and found to be OK.
- custom landscapes
- added solar system objects
- star catalogues loaded
- equipment lists in the oculars plug-in plus the user preferences
- custom locations
- observing lists/bookmarks
The general settings and preferences were, for the most part, fine. It was noted that the Observing Lists button did show in the horizontal toolbar after the upgrade. While the icon looks exactly the same, the old "bookmarks" button must be considered unique. One will need to add the "new" button.
Speaking of bookmarks... If there was a bookmark list in the old version, the observing lists window will show the items, i.e. the list content is preserved. The list will be titled "bookmarks list."
A significant instance of data loss occurred for the telescope mount configurations. Everything in the Telescope Control plug-in was gone! This is disappointing and means that a user needs to make manual records or take screen snapshots for settings in mount profiles. That said, the mount profile data is inside the telescopes.json file, which is a text file, thus, easily examined...
* summary
Upgrading transfers or keeps many settings in Stellarium for Windows. Don't expect it to be perfect.
It is to be expected that if software features are changed dramatically, it may not be possible to migrate settings. That appears to be the case for the Telescope Control plug-in. So users should bear that in mind when making "big jumps" in the versions.
That suggests taking a good backup before the upgrade, in case one wants to roll back. Or needs to "extract" old settings from the saved files.
No comments:
Post a Comment