Creating a Personalised scripts for Stellarium
Creating Scripts for Stellarium
by Barry Gerdes and the Stellarium team, 2013-08-19S!
Although this procedure is based on the Microsoft Windows System the basics will apply to any platform that can run the programs mentioned or similar programs on the preferred system.
A most important part of Stellarium has been the ability to make and run presentations of astronomical events using the display power of Stellarium. The original script engine that was part of the early versions was very limited in what it could do. Commencing with verion 0.10.2 a new script engine has been under development that is very powerful and can be expanded as necessary.
After five years of development the new script engine has reached a stage where it can cater fror almost every requirement. However it can now have new commands implemented as necessary using the basic Stellarium core.
A script is a text file that can be prepared with any text editor and read by Stellarium to display an astronomical event such as a past or future eclipse or a display of features of Stellarium with sound and video. The possibilities are extensive and only limited by what commands are available in the Stellarium core code.
Here is an example of a simple script that displays a lunar eclpse from 2006. Note that each command ends with “;” It has been modfied from the original to return the screen to the starting state when finished
// // Name: Partial Lunar Eclispe // License: Public Domain // Author: Matthew Gates. Modified B.Gerdes 09/02/2009 // Description: Attempt to re-implement simple script from the old // scripting engine. Each old style command is shown // first as a command with OLD: at the start of the line // to help users of the old scripting engine learn how // to use the new one. // core.debug("Starting Partial Lunar Eclispe script"); core.wait(1); core.debug("OK, let's go..."); // OLD: clear core.clear("natural"); LandscapeMgr.setFlagLandscape(false); LandscapeMgr.setFlagAtmosphere(false); LandscapeMgr.setFlagFog(false); core.wait(1); // OLD: date utc 2006:03:14T21:21:32 core.setDate("2006:03:14T21:21:32"); // OLD: select planet Moon pointer off core.selectObjectByName("Moon", false); StelMovementMgr.setFlagTracking(true); // OLD: wait duration 2 core.wait(2); // OLD: zoom auto in StelMovementMgr.autoZoomIn(2); // OLD: wait duration 2 core.wait(2); // OLD: timerate rate 500 // .00001157407407407407 julian days = 1 second. // we want 500 seconds per second. // good candidate for aforementioned include system // function although it's not so bad now we can do // arithmetic in scripts :-) core.setTimeRate(500); // core wait time is a multiple of the TimeRate that is set core.wait (60); // set the time back to normal StelMovementMgr.autoZoomOut(2); core.setTimeRate(1); core.clear("natural") // set the date back to today core.setDate("now"); //Return screen to original positiion so that we know the script is over LandscapeMgr.setFlagLandscape(True); LandscapeMgr.setFlagAtmosphere(false); LandscapeMgr.setFlagFog(false);
This script has been programmed to store the starting position. and return at the end of the show - LandscapeMgr.xxx commands
Note the format of each line and command. the command first “core.clear” with how the command will act with its options “("natural")” enclosed in brackets followed by a ”;”
A comment line is preceded with :”//”
Writing Your Own Scripts
With a little practice most users of Stellarium shold be able to write scripts using the simplified table of commands by modifying existing scripts or starting from scratch as your knowledge increases. Look at the sample script in the previous section.
tables to be added
Program Architecture The code of Stellarium is split into several main blocks:
- The main loop and main widget classes StelMainWindow, StelMainGraphicsView and StelAppGraphicsWidget. Those classes have a single instance created at startup by the ::main() function. They perform tasks such as creating of the main window and renderer, creating the stellarium core, creating the GUI. After initialization, they manage user's input event propagation and event loop. They are heavily based on Qt features.
- The core which provides generic services and features to the other components. The main class is the StelApp singleton which is used everywhere in the code to access other elements. The StelApp instance creates all the main core services and modules at initialization. Example services are sky layer management (e.g. images which have a fixed position in the sky) with the StelSkyLayerMgr, drawing with StelRenderer etc. . Two especially important manager classes are the StelModuleMgr and StelCore: the former manages the collection of StelModule instances registered in the program (see next point for more info on what a StelModule is). The latter provides performance critical features for computing coordinate transformation and other mathematical services.
- A collection of StelModule instances which display the main elements of the program such as planets and stars. Each StelModule should be registered to the StelModuleMgr. Because many Stellarium components derive from the StelModule class, the main loop is able to treat them generically by calling their standard methods such StelModule::update() and StelModule::draw() at each program iteration. This also allows other program components to access them by name. StelModule can also be loaded dynamically by Stellarium, which is the standard way of creating Plugins.
- The Graphical User Interface (StelGui). It is based on styled Qt widgets which are rendered directly in the graphics window. User actions trigger signals connected to core and StelModules slots.
- The script engine (StelScriptMgr) allows scripts to calls slots from the core and StelModule slots.
diagram to be added
The details of the scripting engine for developing can be found in the API documentation and is beyond the scope of the User manual
See the full API documentation at http://stellarium.org/doc/head/ and go to the section on Scripting.
This section is under contruction