Celestia/Celx Scripting/CELX Lua Methods/Celx celestia

= Celx Scripting: Celestia object =

celestia
This object is predefined and gives access to all the celestia-related functionality available for Lua-scripts, either directly by methods of celestia, or indirectly by creating other objects which offer more functionality.

Methods
This chapter contains a list of all available celestia methods, which can be used on the predefined celestia object.

print
( [,, , , , ])

Print text on screen. Celestia supports UTF-8 encoded text strings for showing non-ASCII characters.

Notes:
 * 1) By default, text is printed in white. Celestia also has the possibility to set the text color prior to this method, using the  celestia:settextcolor method.

Example-1: Position text on the screen:

celestia:print("Middle", 3.0, 0, 0, -3, 0) wait(3.0) celestia:print("Bottom left", 3.0, -1, -1, 2, 4) wait(3.0) celestia:print("Top right", 3.0, 1, 1, -10, -4) wait(3.0)

Example-2: Print on more than 1 line and use text and variables:

rearth = celestia:find("Sol/Earth"):radius rmars = celestia:find("Sol/Mars"):radius celestia:print("Earth radius is: " .. rearth .. " km.\nMars radius is: " .. rmars .. " km.", 5.0, -1, -1, 2, 4) wait(5.0)

Example-3: Print text and formatted variables:

rearth = celestia:find("Sol/Earth"):radius celestia:print(string.format("The radius of Earth is: %10.0f km.", rearth ), 5.0, -1, -1, 2, 4) wait(5.0)

note: the duration of the celestia: print method is contained in the duration of the wait method which follows it.The two do not add up. The duration of wait must be at least equal to that of print  method.

Return to the celestia method index.

flash
( [, ])

Print text on screen, similar to print.

Example:

celestia:flash("This string is flashed on your screen for 10 seconds.", 10.0) wait(10.0)

Return to the celestia method index.

show


Enable one or many rendering features. This method exists for backward compatibility with older scripts.

The celestia:setrenderflags method should be used instead.

Notes:
 * 1) Multiple features can be enabled at once by giving multiple arguments to this method, separated by a comma.

Example: Enable the rendering of comet-tails

celestia:show("comettails")

Return to the celestia method index.

hide


Disable one or many rendering features. This method exists for backward compatibility with older scripts.

The celestia:setrenderflags method should be used instead.

Notes:
 * 1) Multiple features can be enabled at once by giving multiple arguments to this method, separated by a comma.

Example: Disable the rendering of nightmaps

celestia:hide("nightmaps")

Return to the celestia method index.

getrenderflags
table

Return a table with all known renderflags (see celestia:setrenderflags method) as keys, and a boolean as value indicating whether a specific renderflag is enabled or disabled.

Notes:
 * 1) This method is especially useful to save all renderflags at the beginning of a script, so these values can be reset at script end or script termination, by using the function celestia_cleanup_callback.

Example:

actual_renderflags = celestia:getrenderflags

Return to the celestia method index.

setrenderflags


You can use celestia:show and celestia:hide or this celestia:setrenderflags method, both have equivalent functionality.

The main reason for the existence of this method is as a counterpart of the celestia:getrenderflags method.

Example: Enable the rendering of comet-tails and disable the rendering of nightmaps

-- create and initialize table t = {} t.nightmaps = false t.comettails = true celestia:setrenderflags(t)

or shorter:

-- note the curly braces celestia:setrenderflags{nightmaps = false, comettails = true}

Return to the celestia method index.

showlabel


Enable the rendering of labels.

Notes:
 * 1) Multiple label features can be enabled at once by giving multiple arguments to this method, separated by a comma.

Example: Enable the labeling of planets and moons

celestia:showlabel("planets", "moons")

Return to the celestia method index.

hidelabel


Disable the rendering of labels.

Notes:
 * 1) Multiple label features can be disabled at once by giving multiple arguments to this method, separated by a comma.

Example: Enable the labeling of constellations in local an Latin names respectively

celestia:showlabel("constellations") -- Show local translated names for constellations celestia:showlabel("i18nconstellations") wait(5.0) -- Show Latin names for constellations celestia:hidelabel("i18nconstellations") wait(5.0) celestia:hidelabel("constellations")

Return to the celestia method index.

getlabelflags
table

Return a table with all known labelflags (see celestia:setlabelflags method) as keys, and a boolean as value indicating whether a specific labelflag is enabled or disabled.

Notes:
 * 1) This method is especially useful to save all labelflags at the beginning of a script, so these values can be reset at script end or script termination, by using the function celestia_cleanup_callback.
 * 2) To enable or disable a specific labelflag, the celestia:setlabelflags method can be used.

Example:

actual_labelflags = celestia:getlabelflags

Return to the celestia method index.

setlabelflags


Enable or disable the rendering of labels.

You can use celestia:showlabel and celestia:hidelabel or this celestia:setlabelflags method, both have equivalent functionality.

Notes:
 * 1) To obtain the current status for the rendering of labels, the celestia:getlabelflags method can be used.

Example: Enable the labeling of planets and dwarfplanets and disable the labeling of moons

-- create and initialize table table = {} table.planets = true table.dwarfplanets = true table.moons = false celestia:setlabelflags(table)

or shorter:

-- note the curly braces celestia:setlabelflags{planets = true, dwarfplanets = true, moons = false}

Return to the celestia method index.

getorbitflags
table

Return a table with all known orbitflags (see the celestia:setorbitflags method) as keys, and a boolean as value, indicating whether a specific orbit is enabled or disabled, when orbits are turned on using the celestia:setrenderflags method.

Notes:
 * 1) To enable or disable the rendering of specific orbits, the celestia:setorbitflags method can be used.

Example:

actual_orbitflags = celestia:getorbitflags

Return to the celestia method index.

setorbitflags


Enable or disable the rendering of specific orbits, when orbits are turned on using the celestia:setrenderflags method.

Notes:
 * 1) To obtain the current status for the rendering of specific orbits, the celestia:getorbitflags method can be used.

Example: Enable the rendering of the orbits of planets and dwarfplanets only:

-- create and initialize table first table = {} table.Planet = true table.Moon = false table.Asteroid = false table.Comet = false table.Spacecraft = false table.Invisible = false table.Unknown = false table.DwarfPlanet = true table.MinorMoon = false table.Star = false celestia:setorbitflags(table) celestia:setrenderflags{orbits = true}

or shorter:

-- note the curly braces celestia:setorbitflags{Planet = true, Moon = false, Asteroid = false, Comet = false, Spacecraft = false, Invisible = false, Unknown = false, DwarfPlanet = true, MinorMoon = false, Star = false} celestia:setrenderflags{orbits = true}

Return to the celestia method index.

getambient
number

Return the current brightness level of ambient light as a number.

Notes:
 * 1) To set the brightness level of ambient light, the celestia:setambient method can be used.

Example:

actual_ambient = celestia:getambient

Return to the celestia method index.

setambient


Set the brightness level of ambient light.

Notes:
 * 1) To obtain the current brightness level of ambient light, the celestia:getambient method can be used.

Example:

celestia:setambient(0.0)

Return to the celestia method index.

getfaintestvisible
number

Return the current faintest visible magnitude of stars as a number.

If AutoMag has been enabled (see the celestia:setrenderflags method), this method returns the faintest magnitude of stars at 45° instead.

Notes:
 * 1) To set the faintest visible magnitude of stars or the faintest magnitude of stars at 45°, the celestia:setfaintestvisible method can be used.

Example:

actual_faintest = celestia:getfaintestvisible

Return to the celestia method index.

setfaintestvisible


Set the faintest visible magnitude of stars.

If AutoMag has been enabled (see the celestia:setrenderflags method), set the faintest magnitude of stars at 45° instead.

Notes:
 * 1) When Galaxies are turned on, using the celestia:setrenderflags method, Galaxy brightness will also respond to setting the faintest visible magnitude of stars, using this celestia:setfaintestvisible method. This method is linked with the  celestia:setgalaxylightgain method.
 * 2) To obtain the current faintest visible magnitude of stars or the current faintest magnitude of stars at 45°, the celestia:getfaintestvisible method can be used.

Example-1: Set the faintest maginute of stars at 45° to 9.0

celestia:setrenderflags{automag = true} celestia:setfaintestvisible(9.0)

Example-2: Set the faintest visible magnitude of stars to 7.0

celestia:setrenderflags{automag = false} celestia:setfaintestvisible(7.0)

Return to the celestia method index.

getminorbitsize
number

Return the current minimum size for an orbit to be rendered, as a number.

This value is used when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags method. The size is measured in pixels and is related to the radius of the orbit.

Notes:
 * 1) The actual screen dimensions in pixels can be obtained using the celestia:getscreendimension method.
 * 2) To set minimum size for an orbit to be rendered, the celestia:setminorbitsize method can be used.

Example:

actual_orbitsize = celestia:getminorbitsize

Return to the celestia method index.

setminorbitsize


Set the minimum size of an orbit to be rendered.

This value is used when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags method.

Notes:
 * 1) Using this method, you can for instance influence the moment to fade out the inner orbits of planets, when zooming out of a Solar System (or vice versa, to fade in when zooming in on a Solar System).
 * 2) Screen dimensions can differ on different computers, so can be the effect of this method.
 * 3) To obtain the current minimum size for an orbit to be rendered, the celestia:getminorbitsize method can be used.

Example: Set the minimum radius size of an orbit to be rendered at 30 pixels and render the orbits of planets

celestia:setrenderflags{orbits = true} celestia:setorbitflags{Planet = true} celestia:setminorbitsize(30)

Return to the celestia method index.

getstardistancelimit
number

Return the furthest distance, measured in light years, at which Celestia will display stars, as a number.

The default value is 1,000,000, however, as of version 1.3.1, Celestia only uses a distance out to 16,000 light years.

Notes:
 * 1) To set the furthest distance at which Celestia will display stars, the celestia:setstardistancelimit method can be used.

Example:

actual_stardistancelimit = celestia:getstardistancelimit

Return to the celestia method index.

setstardistancelimit


Set the furthest distance at which Celestia will display stars.

Notes:
 * 1) To obtain the current furthest distance at which Celestia will display stars, the celestia:getstardistancelimit method can be used.

Example: only show stars which are less than 100 ly away

celestia:setstardistancelimit(100)

Return to the celestia method index.

getminfeaturesize
number

Return the minimum size for locations to be labeled.

This value is used when Celestia's locations labelflag option is turned on, using the celestia:setlabelflags or celestia:showlabel method.

Notes:
 * 1) When observing a planet or moon from far away, the largest or important locations are shown first from a certain distance. As you approach the planet or moon, more location labels will appear.
 * 2) The sizes of defined locations are determined in the locations files that are stored within the Celestia subdirectories. Locations with a defined size less than the minimum size for locations, will not be labeled.
 * 3) The celestia:setminfeaturesize method can be used to set the minimum size for locations to be labeled.
 * 4) The observer:getlocationflags can be used to obtain a table with keys that indicate whether a specific locationflag is enabled or disabled.

Example:

actual_minfeaturesize = celestia:getminfeaturesize

Return to the celestia method index.

setminfeaturesize


Set the minimum size for locations to be labeled.

This value is used when Celestia's locations labelflag option is turned on, using the celestia:setlabelflags or celestia:showlabel method.

Notes:
 * 1) When observing a planet or moon from far away, the largest or important locations are shown first from a certain distance. As you approach the planet or moon, more location labels will appear.
 * 2) The sizes of defined locations are determined in the locations files that are stored within the Celestia subdirectories.
 * 3) The celestia:getminfeaturesize method can be used to obtain the current minimum size for locations to be labeled.
 * 4) The observer:setlocationflags can be used to determine whether a specific locationflag is enabled or disabled.

Example: Set the minimum featuresize to 1, to display all available location labels

celestia:setlabelflags{locations = true} celestia:setminfeaturesize(1)

Return to the celestia method index.

getstarstyle
string

Return the current rendering style for stars as a string.

The string will be one of:
 * disc Celestia draws a prominent circular disc that varies in both diameter and brightness, based upon the actual size, magnitude and distance of the star.
 * fuzzy Celestia draws a smaller, more realistic “point” that varies in size and brightness.
 * point Celestia draws stars as points of light of varying brightness.

Notes:
 * 1) The celestia:setstarstyle method can be used to set the rendering style for stars.

Example:

actual_starstyle = celestia:getstarstyle

Return to the celestia method index.

setstarstyle


Set the rendering style for stars.

Notes:
 * 1) The celestia:getstarstyle method can be used to obtain the current rendering style for stars.

Example: The uncommented line sets the starstyle

-- celestia:setstarstyle("disc") -- celestia:setstarstyle("fuzzy") celestia:setstarstyle("point")

Return to the celestia method index.

find
object

This celestia method can be used to create a CELX "object" object.

Notes:
 * 1) A CELX "object" object does refer to a celestial object like a planet or a star, but it can also be a location or spacecraft.
 * 2) The object methods can be used on a CELX "object" object. "Object" objects can also be used in other methods, requiring an "object" object as an argument.

Example:

-- Find Earth and store in object with name "planet_earth", when in our Solar System planet_earth = celestia:find("Earth")

-- Find Earth and store in object with name "planet_earth", when outside of our Solar System planet_earth = celestia:find("Sol/Earth")

-- Find Galaxy M33 and store in object with name "galaxy_m33" galaxy_m33 = celestia:find("M 33")

-- Find Jupiter's moon Callisto and store in object with name "callisto" callisto = celestia:find("Sol/Jupiter/Callisto")

Return to the celestia method index.

getselection
object

Return the current selection in a CELX "object" object.

Notes:
 * 1) A CELX "object" object does refer to a celestial object like a planet or a star, but it can also be a location or spacecraft.
 * 2) The object methods can be used on a CELX "object" object. "Object" objects can also be used in other methods, requiring an "object" object as an argument.

Example: Get the current selection. If nothing is selected, the Sun will be selected

actual_selection = celestia:getselection if actual_selection:type == "null" then actual_selection = celestia:find("Sol") celestia:select(actual_selection) end

Return to the celestia method index.

select


Set the current selection to the specified object.

Example: Find and select our Moon

moon = celestia:find("Sol/Earth/Moon") celestia:select(moon)

Or shorter

celestia:select(celestia:find("Sol/Earth/Moon"))

Return to the celestia method index.

mark


Mark the specified object.

Notes:
 * 1) You may want to use the object:mark method instead, because it has more possibilities.
 * 2) Markers are only shown when Celestia's markers renderflag option is turned on, using the celestia:setrenderflags method.

Example: Find, center end mark star Aldebaran

selection = celestia:find("Aldebaran") celestia:getobserver:center(selection) celestia:setrenderflags{markers = true} celestia:mark(selection)

Return to the celestia method index.

unmark


Remove marker from the specified object.

Notes:
 * 1) If you don't unmark objects and turn the markers renderflag off, using the celestia:setrenderflags method, Celestia still remembers the marked objects. Next time turning the markers renderflag on, all the objects will be marked again.
 * 2) You may want to use the object:unmark method instead.

Example: Find, center end mark star Polaris with a blinking marker for 10 seconds

selection = celestia:find("Polaris") celestia:getobserver:center(selection) celestia:setrenderflags{markers = true} for i = 1, 10 do   celestia:mark(selection) wait(0.5) celestia:unmark(selection) wait(0.5) end celestia:setrenderflags{markers = false}

Return to the celestia method index.

unmarkall
This celestia method removes any previously assigned marks from all objects.

Using this method prevents unmarking all previously marked objects individually.

Notes:
 * 1) If you don't unmark objects and turn the markers renderflag off, using the celestia:setrenderflags method, Celestia still remembers the marked objects. Next time turning the markers renderflag on, all the objects will be marked again.

Example: Find, center end mark stars Pollux and Castor and unmark them again after 5 seconds

pollux = celestia:find("Pollux") castor = celestia:find("Castor") celestia:getobserver:center(pollux) celestia:setrenderflags{markers = true} celestia:mark(pollux) celestia:mark(castor) wait(5) celestia:unmarkall celestia:setrenderflags{markers = false}

Return to the celestia method index.

gettime
number

Get the current simulation time as a TDB (Barycentric Dynamical Time) Julian date.

Older Celestia versions use UTC (Coordinated Universal Time) to calculate times and positions. Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!!

Notes:
 * 1) The simulation time can be set by using the celestia:settime method.
 * 2) To get the current system time instead of the current simulation time, the  celestia:getsystemtime method should be used instead.
 * 3) The TDB time scale is a bit different from the more familiar UTC. By using TDB, Celestia places objects much more accurately. As of January 1, 2008, the difference between the two is about 65 seconds. For more information, see Celestia/Time_Scales.
 * 4) To convert between UTC and TDB times, you can use the  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 5) To convert between normal calender dates and julian days, you can use the celestia:tojulianday and celestia:fromjulianday methods.

Example:

actual_tdbtime = celestia:gettime

Return to the celestia method index.

settime


Set the time for the simulation as a TDB (Barycentric Dynamical Time) Julian date.

Older Celestia versions use UTC (Coordinated Universal Time) to calculate times and positions. Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!!

Notes:
 * 1) The current simulation time can be obtained by using the celestia:gettime or observer:gettime method.
 * 2) The TDB time scale is a bit different from the more familiar UTC. By using TDB, Celestia places objects much more accurately. As of January 1, 2008, the difference between the two is about 65 seconds. For more information, see Celestia/Time_Scales.
 * 3) To convert between UTC and TDB times, you can use the  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 4) To convert between normal calender dates and julian days, you can use the celestia:tojulianday and celestia:fromjulianday methods.

Example: Set the date and time exactly to UTC: October 6, 2009, 19 hr 15 min 30 sec

tdb_dt = celestia:utctotdb(2009, 10, 06, 19, 15, 30) celestia:settime(tdb_dt)

Return to the celestia method index.

gettimescale
number

Get the current multiplier (speed) at which time changes, i.e. how many seconds of simulation time equal one second of real time, as a number.

Notes:
 * 1) The multiplier (speed) at which time changes can be set by using the celestia:settimescale method.

Example:

actual_timespeed = celestia:gettimescale

Return to the celestia method index.

settimescale


Set the multiplier (speed) at which time changes, i.e. how many seconds of simulation time equal one second of real time.

Notes:
 * 1) The current multiplier (speed) at which time changes can be obtained by using the celestia:gettimescale method.

Example: Set the time multiplier to "1000x faster"

celestia:settimescale(1000)

Return to the celestia method index.

getscripttime
number

Return the elapsed time in seconds (with fractions) since the script has been started, as a number.

Notes:
 * 1) This method can be useful for timing purposes.

Example: Print the elapsed script time on the screen.

-- Note: The elapsed time in this example increments with a bit more --      than 1 second (as defined in the wait(1.0)). This beacause --      the CELX methods themselves also take time to process. for i = 1, 20 do  actual_scripttime = celestia:getscripttime celestia:print("Elapsed script time: " .. actual_scripttime, 1.0, -1, -1, 2, 4) wait(1.0) end

Return to the celestia method index.

getobserver
observer

Return the current active observer instance in a CELX "observer" object.

A CELX "observer" object is used to access properties specific to a view, such as viewer position, viewer orientation, frame of reference, and tracking status. The observer methods can be used on a CELX "observer" object. "Observer" objects can also be used in other methods, requiring an "observer" object as an argument.

Notes:
 * 1) This method returns the observer of the active view, which can be changed by the user in case of a multiview, using the  observer:makeactiveview method.

Example: Get observer instance of the active view and store in obs.

obs = celestia:getobserver

Return to the celestia method index.

getobservers
table

Return a list of all used observers, i.e. one observer instance for each view in case of a multiview, in a CELX table of "observer" objects.

A CELX "observer" object is used to access properties specific to a view, such as viewer position, viewer orientation, frame of reference, and tracking status. The observer methods can be used on a CELX "observer" object. "Observer" objects can also be used in other methods, requiring an "observer" object as an argument.

Notes:
 * 1) Each time you change the number of observer instances with the observer:splitview or observer:deleteview methods in a multiview, you need to update the table of "observer" objects again with this celestia:getobservers method.

Example: Split the actual view in the middle vertically. Left goto Venus, right goto Mars and restore singleview after 10 seconds again.

obs = celestia:getobserver obs:splitview("V", 0.5) observers = celestia:getobservers venus = celestia:find("Sol/Venus") observers[1]:goto(venus) mars = celestia:find("Sol/Mars") observers[2]:goto(mars) wait(10.0) obs:singleview

Return to the celestia method index.

tojulianday
number

Convert a UTC calendar date/time to a UTC Julian date and return this Julian date as a number.

The UTC Julian date is the interval of time in days and fractions of a day since January 1, 4712 BC Greenwich noon (12:00:00).

Notes:
 * 1) Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!! For these newer Celestia versions, using the UTC Julian date (as a result of this celestia:tojulianday method) in the celestia:settime method, will cause the WRONG setting of the simutation time. To set the simulation time, using Julian date for these newer Celestia versions, the  celestia:utctotdb method should be used instead of this celestia:tojulianday method.
 * 2) For more information on TDB, UTC, and how time is used in Celestia, see Celestia/Time Scales.

Example-1: Using a later version of Celestia than version, this example-1 will set the WRONG simulation time, which can be checked by reading out the date time in the upper right corner off your screen after running this example-1 script. This example-1 only works correct for Celestia versions prior to version.

utc_juliandate = celestia:tojulianday(2009, 10, 06, 12, 00, 0.0) celestia:settime(utc_juliandate) celestia:settimescale(0)

Example-2: Using a later version of Celestia than version, the next example-2 will set the RIGHT simulation time, which can be checked by reading out the date time in the upper right corner off your screen after running this example-2 script.

tdb_juliandate = celestia:utctotdb(2009, 10, 06, 12, 00, 0.0) celestia:settime(tdb_juliandate) celestia:settimescale(0)

Return to the celestia method index.

fromjulianday
table

Convert a UTC Julian date to a UTC calendar date/time. The returned table contains the keys:
 * year
 * month
 * day
 * hour
 * minute
 * seconds

The UTC Julian date is the interval of time in days and fractions of a day since January 1, 4712 BC Greenwich noon (12:00:00).

Notes:
 * 1) Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!! For these newer Celestia versions, using the celestia:gettime method to obtain a Julian date, and convert that to a Calender date/time with this celestia:fromjulianday method, will cause to obtain the WRONG Calender date/time. To obtain the right Calender date/time, using the Julian date from the celestia:gettime method, for these newer Celestia versions, the  celestia:tdbtoutc method should be used instead.
 * 2) For more information on TDB, UTC, and how time is used in Celestia, see Celestia/Time Scales.

Example-1: Using a later version of Celestia than version, this example-1 will obtain the WRONG TDB Calender date/time, instead of the mentioned UTC Calender date/time. This can be checked by comparing the result of the print statement with the UTC date/time displayed in the upper right corner of your screen. This example-1 only works correct for Celestia versions prior to version.

celestia:settimescale(0) utc_juliandate = celestia:gettime ut = celestia:fromjulianday(utc_juliandate) celestia:print("Date/time: " .. ut.year .. " " .. ut.month .. " " .. ut.day .. " "                .. ut.hour .. " " .. ut.minute .. " " .. ut.seconds, 10.0, -1, -1, 2, 4) wait(10.0)

Example-2: Using a later version of Celestia than version, the next example-2 will set the RIGHT UTC Calender date/time. This can be checked by comparing the result of the print statement with the UTC date/time displayed in the upper right corner of your screen.

celestia:settimescale(0) tdb_juliandate = celestia:gettime ut = celestia:tdbtoutc(tdb_juliandate) celestia:print("Date/time: " .. ut.year .. " " .. ut.month .. " " .. ut.day .. " "                .. ut.hour .. " " .. ut.minute .. " " .. ut.seconds, 10.0, -1, -1, 2, 4) wait(10.0)

Return to the celestia method index.

getscreendimension
x, y

Return the width (=x) and height (=y) of the current Celestia window in pixels, as 2 numbers.

Example:

x,y = celestia:getscreendimension celestia:print("Width: " .. x .. " pixels.\nHeight: " .. y .. " pixels.", 10.0, -1, -1, 4, 4) wait (10.0)

Return to the celestia method index.

newvector
vector

This celestia method can be used to create a new CELX "vector" object from numbers.

Notes:
 * 1) When you have vector components defined in km or miles, you first have to convert those components to millionths of a light year. Therefore, you can use a constant, which must be initialized first within your script:
 * 2) * From km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
 * 3) * From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
 * 4) Next you can convert km or miles to millionths of a light year as follows:
 * 5) * millionths_of_a_light_year = number:km / uly_to_km
 * 6) * millionths_of_a_light_year = number:miles / uly_to_mls
 * 7) A CELX "vector" object is a geometric object that has both a length and direction [X, Y, Z] in a 3 dimensional coordinate system.
 * 8) The vector methods can be used on a CELX "vector" object. "Vector" objects can also be used in other methods, requiring a "vector" object as an argument.

Example-1: Make a vector, pointing in the Y-direction with length 1.

up_vector = celestia:newvector(0, 1, 0)

Example-2: Make a vector, pointing in the X-direction with length 5000 km.

uly_to_km =  9460730.4725808 x5k_vector = celestia:newvector(5000/uly_to_km, 0, 0)

Return to the celestia method index.

newposition
position

This celestia method can be used to create a new CELX "position" object from numbers.

Notes:
 * 1) When you have position components defined in km or miles, you first have to convert those components to millionths of a light year. Therefore, you can use a constant, which must be initialized first within your script:
 * 2) * From km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
 * 3) * From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
 * 4) Next you can convert km or miles to millionths of a light year as follows:
 * 5) * millionths_of_a_light_year = number:km / uly_to_km
 * 6) * millionths_of_a_light_year = number:miles / uly_to_mls
 * 7) A CELX "position" object contains the exact coordinates of a point in space. A position is relative to a coordinate system and may need to be converted to or from universal coordinates before further use.
 * 8) The position methods can be used on a CELX "position" object. "Position" objects can also be used in other methods, requiring a "position" object as an argument.

Example: Goto a position 20,000 km away in the X-direction of the "Universal" coordinate system, from the center of Mars and display the position of Mars in the lower left corner of your screen.

uly_to_km = 9460730.4725808 -- Set frame of reference to "universal" obs = celestia:getobserver obs:setframe(celestia:newframe("universal")) -- Find and select Mars mars = celestia:find("Sol/Mars") celestia:select(mars) -- Obtain and print actual position of Mars now = celestia:gettime posmars = mars:getposition(now) posmars_x = posmars:getx posmars_y = posmars:gety posmars_z = posmars:getz celestia:print("Actual position of Mars:\nX = " .. posmars_x ..                "\nY = " .. posmars_y .. "\nZ = " ..  posmars_z, 15, -1, -1, 1, 6) -- Determine and goto specified position pos = celestia:newposition((posmars_x + (20000/uly_to_km)), posmars_y, posmars_z ) obs:goto(pos,5.0) -- Follow Mars and wait until the goto has finished obs:follow(mars) wait(5.0) -- you are on the right position now, but probably Mars -- may not be visible yet, so center Mars on your screen. obs:center(mars,2.0) wait(10.0)

Return to the celestia method index.

newposition (base64)
position

This celestia method can be used to create a new CELX "position" object from URL-style Base64-encoded values.

Notes:
 * 1) The string-values can be found after the "x=", "y=" and "z=" and before the next following "&" in a celURL.
 * 2) A CELX "position" object contains the exact coordinates of a point in space. A position is relative to a coordinate system and may need to be converted to or from universal coordinates before further use.
 * 3) The position methods can be used on a CELX "position" object. "Position" objects can also be used in other methods, requiring a "position" object as an argument.

Example: Position above the Earth’s North Pole, according the following Celestia version celURL:
 * cel://SyncOrbit/Sol:Earth/2009-11-18T22:32:34.46583?x=Z7PNuA&y=sP9vw0j/+w&z=/P7//////////////////w&ow=-0.5&ox=-0.5&oy=0.5&oz=0.5&select=Sol:Earth&fov=26.5729&ts=1&ltd=0&p=0&rf=3987&lm=52864&tsrc=0&ver=3

-- First simulate some essential celURL settings. earth = celestia:find("Sol/Earth") obs = celestia:getobserver obs:synchronous(earth) celestia:select(earth) -- Then create and goto new position earth_np_pos = celestia:newposition("Z7PNuA", "sP9vw0j/+w", "/P7//////////////////w") obs:goto(earth_np_pos,2.0) wait(2.0) -- you are on the right position now, but probably Earth may not be visible yet, -- so center Earth on your screen. obs:center(earth,2.0) wait(2.0) -- (Mind the observer orientation may differ from the celURL above).

Return to the celestia method index.

newrotation (axis-angle)
rotation

This celestia method can be used to create a new rotation (i.e. a quaternion) of angle radians about the specified axis.

Notes:
 * 1) Angles in CELX are defined in radians instead of degrees. 180 degrees (half a circle) is the same as π radians = 3.14159265 radians = math.pi radians (LUA). You can convert degrees to radians and vice versa as follows:
 * 2) * radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
 * 3) * degrees = math.deg( number:radians ) = ( number:radians  * 180 / math.pi) = ( number:radians  * 180 / 3.14159265).
 * 4) This method is equivalent to rotation:setaxisangle method. Only by using this method, the "rotation" object is created and need NOT to be present first.
 * 5) A CELX "rotation" object is internally a Quaternion, which is one possibility to mathematically describe a rotation in 3 dimensions (i.e. it can be converted to a rotation matrix). A rotation can also be used to describe the orientation of objects or the observer (i.e. where the observer is looking to, and where "up" is).
 * 6) The rotation methods can be used on a CELX "rotation" object. "Rotation" objects can also be used in other methods, requiring a "rotation" object as an argument.

Example-1: Change the current camera view by 180 degrees (like a rear-view mirror).

-- Define the UP vector for the rotation (Y-axis). -- Define a rotation object "lookback" with an angle of 180 degrees -- (= math.pi radians), along the specified Y-axis in the UP vector. -- Rotate the observer according the specified rotation. up_vec = celestia:newvector(0,1,0) lookback = celestia:newrotation(up_vec,math.pi) obs = celestia:getobserver obs:rotate(lookback)

Example-2: Rotate the current camera view by 360 degrees during about 10 seconds.

up_vec = celestia:newvector(0,1,0) obs_rotation = celestia:newrotation(up_vec, 2*math.pi/500) for i = 1, 500 do   celestia:getobserver:rotate(obs_rotation) wait(10/500) end

Return to the celestia method index.

newrotation
rotation

This celestia method can be used to create a new rotation (i.e. a quaternion) from four scalar values (the values used in a celURL).

Notes:
 * 1) The number-values can be found after the "ow=", "ox=", "oy=" and "oz=" and before the next following "&" in a celURL.
 * 2) Passing the components of a vector as ox-, oy-, oz-values is NOT the same as passing the vector. If you pass a vector, a quaternion must be created by using the newrotation (axis-angle) method.
 * 3) A CELX "rotation" object is internally a Quaternion, which is one possibility to mathematically describe a rotation in 3 dimensions (i.e. it can be converted to a rotation matrix). A rotation can also be used to describe the orientation of objects or the observer (i.e. where the observer is looking to, and where "up" is).
 * 4) The rotation methods can be used on a CELX "rotation" object. "Rotation" objects can also be used in other methods, requiring a "rotation" object as an argument.

Example:Position above the Earth’s North Pole, according the following Celestia version celURL:
 * cel://SyncOrbit/Sol:Earth/2009-11-18T22:32:34.46583?x=Z7PNuA&y=sP9vw0j/+w&z=/P7//////////////////w&ow=-0.5&ox=-0.5&oy=0.5&oz=0.5&select=Sol:Earth&fov=26.5729&ts=1&ltd=0&p=0&rf=3987&lm=52864&tsrc=0&ver=3

-- First simulate some essential celURL settings. earth = celestia:find("Sol/Earth") obs = celestia:getobserver obs:synchronous(earth) celestia:select(earth) -- Set the observer orientation according the celURL values. rot = celestia:newrotation(-0.5, -0.5, 0.5, 0.5) obs:setorientation(rot) -- Then create and goto new position earth_np_pos = celestia:newposition("Z7PNuA", "sP9vw0j/+w", "/P7//////////////////w") obs:goto(earth_np_pos,2.0) wait(2.0)

Return to the celestia method index.

newframe
frame

This celestia method can be used to create a new reference frame as a "frame" object.

Notes:
 * 1) In Celestia version, the name bodyfixed will replace planetographic, although for compatibility reasons, the name planetographic will continue to work.
 * 2) A CELX reference "frame" is an origin and set of axes which define the coordinate system used for a body's trajectory and orientation. The origin is some other body defined in a catalog file. There are a number of ways to set the coordinate system axes.
 * 3) The frame methods can be used on a CELX "frame" object. This section also gives more information about using reference frames. "Frame" objects can also be used in other methods, requiring a "frame" object as an argument.

Example-1: Tell Celestia to set the active Coordinate System to UNIVERSAL:

frame = celestia:newframe("universal") obs = celestia:getobserver obs:setframe(frame)

Example-2: The following example selects the Moon, then sets the active Coordinate System to CHASE and goes to the Moon:

moon = celestia:find("Sol/Earth/Moon") celestia:select(moon) frame = celestia:newframe("chase", moon) obs = celestia:getobserver obs:setframe(frame) obs:goto(moon, 2.0) wait(2.0)

Example-3: Tell Celestia to set the active Coordinate System to LOCK the Earth with the Sun. The example will maintain your position with respect to the center of the Earth, and keep both the Sun (Sol) and the Earth in view when time passes. Before running this example, be sure both the Earth and the Sun are already in the view of the observer.

earth = celestia:find("Sol/Earth") celestia:select(earth) sun = celestia:find("Sol") frame = celestia:newframe("lock", earth, sun) obs = celestia:getobserver obs:setframe(frame) celestia:settimescale(50000)

Return to the celestia method index.

requestkeyboard


Enable or disable callback for keyboard input.

Notes:
 * 1) If keyboard-input has been enabled, celestia will execute the function with the name "celestia_keyboard_callback" for each keypress. This function must exist when calling this celestia:requestkeyboard method.
 * 2) The pressed key is given the function as a string-argument, containing the UTF-8 encoding of this key (which for ASCII-chars will simply be the string containing the normal char).
 * 3) The "celestia_keyboard_callback" function can return a boolean indicating whether the keypress has been handled ( true ) or if the normal processing should continue ( false ), no return value is taken as true.
 * 4) These callbacks can only happen while the script is executing wait.

Example: You can use the following example in your CELX script to handle keyboard input:

-- Initialize variable to have no content: last_pressed_key = nil -- -- Define functions section: -- function celestia_keyboard_callback(key) last_pressed_key = key return true end -- function get_pressed_key last_pressed_key = nil celestia:requestkeyboard(true) while true do      if last_pressed_key ~= nil then key = last_pressed_key last_pressed_key = nil celestia:requestkeyboard(false) return key end wait(0.1) end end

-- -- Main CELX script section: --

-- Section within your script, where you want to handle keyboard input: while true do   local key = get_pressed_key if key == string:key1 then valid_key = true -- specify your own CELX code here, about what to do if key matches string:key1. elseif key == string:key2 then valid_key = true -- specify your own CELX code here, about what to do if key matches string:key2. else valid_key = false end if valid_key then -- specify your own CELX code here, about what to do if a valid key has been pressed. end wait(0) end

Return to the celestia method index.

requestsystemaccess
Request permission to access the io and os libraries of Lua, which provide file-writing and program-execution. See the Lua: Documentation Reference Manual for more details.

Notes:
 * 1) If the ScriptSystemAccessPolicy parameter in the celestia.cfg file is set to "ask" (default), the user will be asked whether (s)he wants to allow this. This question will appear with the next wait, so you must call wait before the request can have an effect.
 * 2) Keyboard handling is disabled after calling the celestia:requestsystemaccess method, so if you need it, you must reenable keyboard handling again, using celestia:requestkeyboard(true). This behaviour may change in future Celestia versions (but reenabling it won't hurt then either).

Example: To write information from within a CELX script to a file, you first need access to the LUA os & io functions. If the request was successful, the LUA os & io functions can be used like this:

celestia:requestsystemaccess wait(0) -- Use LUA function to open a file with name "LUAtest.txt" -- in the Celestia main directory in write mode. test_file = io.open ("LUAtest.txt", "w") -- Write some text to the just opened file. io.output(test_file):write("This is a test") -- Close the file. io.close (test_file)

Return to the celestia method index.

getscriptpath
string

Return the path, including the filename to the actual running script, as a string.

The path will possibly be relative to the current working directory.

Example:

pathname = celestia:getscriptpath celestia:print("The path to this script is: " .. pathname, 10.0, -1, -1, 2, 4) wait(10.0)

Return to the celestia method index.

takescreenshot
boolean

Take a screenshot and save it to disk (if allowed by your system). Return boolean true if successful.

Notes:
 * 1) To avoid overwriting other files (i.e. non-screenshots), the filename is always something like "screenshot-000001.png" or "screenshot-string:name-000001.png", where the number is counting from 1 on for each time you start a script, and name can be chosen by the script - see above.
 * 2) Taking screenshots takes some time, but any flash, print, goto or center command in progress won't wait. This may change in future, but OTOH nobody has complained yet.
 * 3) The limitations which were put in place for security reasons in Celestia version  have been somewhat lifted in Celestia version 1.4.0, because CEL-scripting also offers less secure screenshot taking. This means that security can be circumvented by using a CEL script anyway :-(
 * 4) However screenshots still are written to the directory set by the config option "ScriptScreenshotDirectory" in the celestia.cfg file, defaulting to the main celestia directory (typically something like C:\Program Files\Celestia\), depending on your system, Celestia may not be allowed to write files there.

Example: Take a screenshot of the actual scene and store it in filename: "screenshot-test-000001.jpg". If this filename already exist, the number-part will be incremented until the first free number.

screenshot = celestia:takescreenshot("jpg", "test")

Return to the celestia method index.

createcelscript
celscript

Create a "celscript" object from a string, containing valid CEL commands, and execute the CEL script within the current CELX script.

Notes:
 * 1) Lua supports a syntax for long strings using double brackets which is useful here. Using this you can in nearly all cases simply copy and paste complete CEL-scripts without modification into the CELX script.
 * 2) During the execution of the CEL script, the celscript:tick method is called repeatedly until it returns false, indicating that the CEL script has terminated.

Example: The following example selects the Earth, travels to it, and then spends 2-1/2 seconds changing your display distance to be further away from the Earth. This all by using CEL commands embedded in a CELX script.

celsource =               {               select { object "Sol/Earth" }               goto   { time 3 }               wait   { duration 3 }               changedistance { duration 2.5 rate 0.5 }               wait   { duration 2.5 }               } celscript = celestia:createcelscript(celsource) while celscript:tick do    wait(0) end

Return to the celestia method index.

getstarcount
number

Return the total number of stars in the star catalogue, as a number.

Example:

number_of_stars = celestia:getstarcount celestia:print("The total number of stars in the star catalogue: " .. number_of_stars, 10.0, -1, -1, 2, 4) wait(10.0)

Return to the celestia method index.

getstar
object

Return a star, identified by its index number in the star catalogue, as an "object" object.

Notes:
 * 1) Up to 1.6.1, this method is incorrectly implemented and treats its argument as very internal index, not catalogue number. So, negative numbers or numbers greater than or equal to the total number of stars in the star catalogue, may result in a Celestia error! The total number of stars in the star catalogue may be obtained by using the celestia:getstarcount method.
 * 2) A CELX "object" object does refer to a celestial object like a planet or a star, but it can also be a location or spacecraft.
 * 3) The object methods can be used on a CELX "object" object. "Object" objects can also be used in other methods, requiring an "object" object as an argument.

Example: Select a star by catalogue number and goto that star, while displaying its number and name on the screen.

number = 12345 star = celestia:getstar(number) starname = star:name celestia:select(star) obs = celestia:getobserver obs:goto(star,5.0) celestia:print("The name of star number " .. number .. " is: " .. starname, 10.0, -1, -1, 2, 4) wait(10.0)

Return to the celestia method index.

getdsocount
number

Return the total number of Deep Space Objects (DSOs) in the DSO catalogue, as a number.

Example:

number_of_dsos = celestia:getdsocount celestia:print("Total number of Deep Space Objects in DSO catalogue: " .. number_of_dsos, 10.0, -1, -1, 2, 4) wait(10.0)

Return to the celestia method index.

getdso
object

Return a Deep Space Object (DSO), identified by its index number in the DSO catalogue, as an "object" object.

Notes:
 * 1) Up to 1.6.1, this method is incorrectly implemented and treats its argument as very internal index, not catalogue number. So, negative numbers or numbers greater than or equal to the total number of DSOs in the DSO catalogue, may result in a Celestia error! The total number of DSOs in the DSO catalogue may be obtained by using the  celestia:getdsocount method.
 * 2) A CELX "object" object does refer to a celestial object like a planet or a star, but it can also be a location or spacecraft.
 * 3) The object methods can be used on a CELX "object" object. "Object" objects can also be used in other methods, requiring an "object" object as an argument.

Example: Select a DSO by catalogue number and goto that DSO, while displaying its number and name on the screen.

number = 0 dso = celestia:getdso(number) dsoname = dso:name celestia:select(dso) obs = celestia:getobserver obs:goto(dso,5.0) celestia:print("The name of DSO number " .. number .. " is: " .. dsoname, 10.0, -1, -1, 2, 4) wait(10.0)

Return to the celestia method index.

stars
iterator

Return an iterator that can be used with Lua's generic "for" statement to enumerate all stars in Celestia's star catalogue.

An iterator is an object that may be thought of as a type of pointer which has two primary operations: There must also be a way to create an iterator so it points to some first element as well as some way to determine when the iterator has exhausted all of the elements in an object collection.
 * 1) referencing one particular element in an object collection (called element access),
 * 2) modifying itself so it points to the next element (called element traversal).

Notes:
 * 1) The object methods can be used on this itarator.

Example: The following code uses the celestia:stars iterator to mark all stars of spectral type B:

celestia:unmarkall celestia:setrenderflags{markers = true} celestia:select(nil) for star in celestia:stars do   first, last = string.find(star:spectraltype, "B", 1, true) if first == 1 then star:mark("#00ff00", "square", 10) end end wait(20.0) celestia:unmarkall celestia:setrenderflags{markers = false}

Return to the celestia method index.

dsos
iterator

Return an iterator that can be used with Lua's generic "for" statement to enumerate all Deep Space Objects (DSOs: objects defined in .DSC files) in Celestia's catalogue.

An iterator is an object that may be thought of as a type of pointer which has two primary operations: There must also be a way to create an iterator so it points to some first element as well as some way to determine when the iterator has exhausted all of the elements in an object collection.
 * 1) referencing one particular element in an object collection (called element access),
 * 2) modifying itself so it points to the next element (called element traversal).

Notes:
 * 1) The object methods can be used on this itarator.

Example: The following code uses the celestia:dsos iterator to mark all galaxies of Hubble type SB:

celestia:unmarkall celestia:setrenderflags{markers = true} celestia:select(nil) for dso in celestia:dsos do   if dso:getinfo.type == "galaxy" then hubbleType = dso:getinfo.hubbleType if string.find(hubbleType, "SB") then dso:mark( "green", "disk", 7, 0.7 ) end end end wait(20.0) celestia:unmarkall celestia:setrenderflags{markers = false}

Return to the celestia method index.

utctotdb
number

Convert a UTC calendar date/time to a TDB Julian date and return this Julian date as a number.

Notes:
 * 1) Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!! To set the simulation time, using Julian date for these newer Celestia versions, this  celestia:utctotdb method should be used instead of the older celestia:tojulianday method.
 * 2) For more information on TDB, UTC, and how time is used in Celestia, see Celestia/Time Scales.

Example-1: Get the TDB Julian date for midnight 12 Aug 2007 UTC, and set this simulation time.

tdb_juliandate = celestia:utctotdb(2007, 8, 12) celestia:settime(tdb_juliandate) celestia:settimescale(0)

Example-2: Get the TDB Julian date for 12:50:00 25 Dec 1492 UTC, and set this simulation time. Mind that in this example, the date in fact is a Julian calendar date (a reform of the Roman calendar date), since the Gregorian calendar date used today, wasn't adopted until 1582.

tdb_juliandate = celestia:utctotdb(1492, 12, 25, 12, 50, 0.0) celestia:settime(tdb_juliandate) celestia:settimescale(0)

Return to the celestia method index.

tdbtoutc
table

Convert a TDB Julian date to a UTC calendar date/time. The returned table contains the keys:
 * year
 * month
 * day
 * hour
 * minute
 * seconds

The TDB Julian date is the interval of time in days and fractions of a day since January 1, 4712 BC at 11:59:17 UTC.

Notes:
 * 1) Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!! For these newer Celestia versions, using the celestia:gettime method to obtain a Julian date, and convert that to a Calender date/time, this  celestia:tdbtoutc method should be used instead of the older celestia:fromjulianday method.
 * 2) For more information on TDB, UTC, and how time is used in Celestia, see Celestia/Time Scales.

Example: Get the actual TDB simulation time and convert it to a UTC calendar date/time. This can be checked by comparing the result of the print statement with the UTC date/time displayed in the upper right corner of your screen.

celestia:settimescale(0) tdb_juliandate = celestia:gettime ut = celestia:tdbtoutc(tdb_juliandate) celestia:print("Date/time: " .. ut.year .. " " .. ut.month .. " " .. ut.day .. " "                .. ut.hour .. " " .. ut.minute .. " " .. ut.seconds, 10.0, -1, -1, 2, 4) wait(10.0)

Return to the celestia method index.

getaltazimuthmode
boolean

Return a boolean, indicating if alt-azimuth mode is enabled or disabled.
 * true: alt-azimuth mode is enabled.
 * false: alt-azimuth mode is disabled.

Notes:
 * 1) The alt-azimuth mode corresponds with the horizontal coordinate system, which is a celestial coordinate system that uses the observer's local horizon as the fundamental plane. The horizontal coordinates are:
 * 2) * altitude (Alt), that is the angle between an object and the observer's local horizon.
 * 3) * azimuth (Az), that is the angle of an object around the horizon, relative to an origin.
 * 4) When the observer is onto the surface of an object (by using the [Ctrl+G] keys or the observer:gotosurface method), pressing the left/right arrow keys rotates the view in:
 * 5) * " Yaw " if alt-azimuth mode is enabled (true).
 * 6) * " Roll " if alt-azimuth mode is disabled (false).
 * 7) The alt-azimuth mode can be set, using the  celestia:setaltazimuthmode method.

Example:

actual_altaz = celestia:getaltazimuthmode

Return to the celestia method index.

setaltazimuthmode


Enable or disable alt-azimuth mode.

Notes:
 * 1) The alt-azimuth mode corresponds with the horizontal coordinate system, which is a celestial coordinate system that uses the observer's local horizon as the fundamental plane. The horizontal coordinates are:
 * 2) * altitude (Alt), that is the angle between an object and the observer's local horizon.
 * 3) * azimuth (Az), that is the angle of an object around the horizon, relative to an origin.
 * 4) When the observer is onto the surface of an object (by using the [Ctrl+G] keys or the observer:gotosurface method), pressing the left/right arrow keys rotates the view in:
 * 5) * " Yaw " if alt-azimuth mode is enabled (true).
 * 6) * " Roll " if alt-azimuth mode is disabled (false).
 * 7) The current alt-azimuth mode can be obtained, using the  celestia:getaltazimuthmode method.

Example: The uncommented line determines if alt-azimuth mode must be enabled/disabled.

-- celestia:setaltazimuthmode(true)    -- alt-azimuth mode must be enabled. celestia:setaltazimuthmode(false)      -- alt-azimuth mode must be disabled.

Return to the celestia method index.

getoverlayelements
table

Return a table with all known overlay elements (see celestia:setoverlayelements method) as keys, and a boolean as value indicating whether a specific overlay element is rendered or not.

The overlay elements concern the information display in the upper/lower, left/right corners of your screen.

Notes:
 * 1) To turn on/of the rendering of the different overlay elements, the  celestia:setoverlayelements method can be used.

Example:

actual_overlaytab = celestia:getoverlayelements

Return to the celestia method index.

setoverlayelements


Enable or disable the rendering on your screen of each overlay element separately.

The overlay elements concern the information display in the upper/lower, left/right corners of your screen.

Notes:
 * 1) Similar to online pressing the [V] key, to toggle the whole information display (all overlay elements together) on or off through two levels of detail. This method however, can enable/disable each overlay element separately, but has no ability to switch between two levels of detail.
 * 2) The current rendering status of each overlay element can be obtained by using the  celestia:getoverlayelements method.

Example: Disable the rendering of all overlay elements.

-- create and initialize table first overlaytab = {} overlaytab.Time = false overlaytab.Velocity = false overlaytab.Selection = false overlaytab.Frame = false celestia:setoverlayelements(overlaytab)

Or shorter

-- Note the curly braces celestia:setoverlayelements{Time = false, Velocity = false, Selection = false, Frame = false}

Return to the celestia method index.

getgalaxylightgain
number

Return the current level of Galaxy light gain (brightness), as a number.

Notes:
 * 1) Galaxies can be turned on/off using the celestia:setrenderflags method.
 * 2) The level of Galaxy light gain (brightness) can be set by using the  celestia:setgalaxylightgain method.

Example:

actual_galaxylightgain = celestia:getgalaxylightgain

Return to the celestia method index.

setgalaxylightgain


Set the level of Galaxy light gain (brightness).

Notes:
 * 1) Galaxies can be turned on/off using the celestia:setrenderflags method.
 * 2) The current level of Galaxy light gain (brightness) can be obtained by using the  celestia:getgalaxylightgain method.
 * 3) When visiting Galaxies outside of the Milky Way, boosting brightness can improve your view of distant Galaxies, while within the Milky Way, lowering the brightness can improve your view of stars, planets, moons etc..
 * 4) Galaxy brightness will also respond to setting the faintest visible magnitude of stars, using the celestia:setfaintestvisible method. These methods are linked.

Example: Enable the rendering of Galaxies and maximize their brightness.

celestia:setrenderflags{galaxies = true} celestia:setgalaxylightgain(1)

Return to the celestia method index.

gettextwidth
number

Return the width in pixels of a text string, as a number.

Example:

textwidth = celestia:gettextwidth("This is a text string")

Return to the celestia method index.

log


Write text to the Celestia log file. Celestia supports UTF-8 encoded text strings for writing non-ASCII characters.

Notes:
 * 1) This method is very useful for debugging Lua/CELX scripts.
 * 2) The Celestia log can be brought up on the screen by using the tilde [~] key on the keyboard, (or [~] + [Spacebar] on some systems).

Example: Bring up the Celestia log on the screen, run this example and verify that the text is written to the log.

celestia:log("This message is written to the Celestia log")

Return to the celestia method index.

registereventhandler
boolean

Replace Celestia's default event handling with behavior of the script author's choice, defined in a function.

Notes:
 * 1) If no event handler is registered, or if the registered event handler returns false, Celestia reverts to the default behavior for that event.
 * 2) The binding between the event type and event handler will remain until either:
 * 3) Celestia is restarted
 * 4) A new binding is specified between the event type and another event handler (possibly in another script)
 * 5) By unbinding the event type from the event handler, using:

Example: This sample keyboard handling function binds the [P] and [Q] keys on the keyboard to the handler showmessage, which flashes a message on the screen.

function showmessage celestia:flash("Key pressed") end -- The table mapping key names to handlers keyhandlers = { p = showmessage, q = showmessage } function handlekey(k) -- k is a table containing the event properties; in this simple sample, -- we're only interested in char, the name of the key that was pressed. handler = keyhandlers[k.char] if (handler ~= nil) then handler return true else return false end end celestia:registereventhandler("key", handlekey)

Return to the celestia method index.

geteventhandler
boolean

Return a boolean, indicating whether or not Celestia's default event handling for the specified event type is replaced:
 * true, default event handling is replaced.
 * false, default event handling is NOT replaced.

Example: Test if Celestia's default event handling for the event type "key" is replaced.

handler = celestia:geteventhandler("key") if handler then celestia:flash("Default event handling for the event type 'key' is replaced.", 5.0) else celestia:flash("Default event handling for the event type 'key' is NOT replaced.", 5.0) end

Return to the celestia method index.

setlabelcolor


Set the colors of the labels palette.

Notes:
 * 1) The current colors of specific labels can be obtained by using the  celestia:getlabelcolor method.
 * 2) Specific labels can be turned on/off using the celestia:showlabel and celestia:hidelabel or celestia:setlabelflags method.

Example1: Set the label color for stars to RED and turn star labels on.

celestia:setlabelcolor("stars", 1, 0, 0) celestia:setlabelflags{stars = true}

Example2: Alternate Label Colors from ElChristou.

celestia:setlabelcolor("stars",         0.471, 0.356, 0.682) celestia:setlabelcolor("planets",       0.407, 0.333, 0.964) celestia:setlabelcolor("moons",         0.231, 0.733, 0.792) celestia:setlabelcolor("asteroids",     0.596, 0.305, 0.164) celestia:setlabelcolor("comets",        0.768, 0.607, 0.227) celestia:setlabelcolor("spacecraft",    0.930, 0.930, 0.930) celestia:setlabelcolor("locations",     0.240, 0.890, 0.430) celestia:setlabelcolor("galaxies",      0.000, 0.450, 0.500) celestia:setlabelcolor("nebulae",       0.541, 0.764, 0.278) celestia:setlabelcolor("openclusters",  0.239, 0.572, 0.396) celestia:setlabelcolor("constellations", 0.125, 0.167, 0.200) celestia:setlabelcolor("equatorialgrid", 0.095, 0.196, 0.100)

Return to the celestia method index.

setlinecolor


Set the colors of the lines palette.

Notes:
 * 1) The current colors of specific lines can be obtained by using the  celestia:getlinecolor method.
 * 2) Specific orbits can be turned on/off using the celestia:setorbitflags method.
 * 3) Orbits, Grids, Constellations and Boundaries can be turned on/off using the celestia:setrenderflags method.
 * 4) The  planetequator is part of the planetographic grid, which can be turned on/off for all body-type objects, using the object:addreferencemark method.

Example1: Set the color of the galacticgrid to CYAN and turn galacticgrid on.

celestia:setlinecolor("galacticgrid", 0.0, 1.0, 1.0) celestia:setrenderflags{galacticgrid = true}

Example2: Alternate Line Colors from ElChristou.

celestia:setlinecolor("starorbits",      0.500, 0.500, 0.800) celestia:setlinecolor("planetorbits",    0.300, 0.323, 0.833) celestia:setlinecolor("moonorbits",      0.080, 0.407, 0.392) celestia:setlinecolor("asteroidorbits",  0.580, 0.152, 0.080) celestia:setlinecolor("cometorbits",     0.639, 0.487, 0.168) celestia:setlinecolor("spacecraftorbits", 0.400, 0.400, 0.400) celestia:setlinecolor("constellations",  0.000, 0.120, 0.180) celestia:setlinecolor("equatorialgrid",  0.070, 0.114, 0.073) celestia:setlinecolor("boundaries",      0.100, 0.006, 0.066)

Return to the celestia method index.

getlabelcolor
number, number, number

Return a triple number (between 0 and 1) which corresponds to the red, green, blue components of the RGB values of the color for the specified label.

Notes:
 * 1) The colors of specific labels can be set by using the  celestia:setlabelcolor method.
 * 2) Specific labels can be turned on/off using the celestia:showlabel and celestia:hidelabel or celestia:setlabelflags method.

Example:

r, g, b = celestia:getlabelcolor("planets")

Return to the celestia method index.

getlinecolor
number, number, number

Return a triple number (between 0 and 1), which corresponds to the red, green, blue components of the RGB values of the color for the specified line.

Notes:
 * 1) The colors of specific lines can be set by using the  celestia:setlinecolor method.
 * 2) Specific orbits can be turned on/off using the celestia:setorbitflags method.
 * 3) Orbits, Grids, Constellations and Boundaries can be turned on/off using the celestia:setrenderflags method.
 * 4) The  planetequator is part of the planetographic grid, which can be turned on/off for all body-type objects, using the object:addreferencemark method.

Example:

r, g, b = celestia:getlinecolor("planetorbits")

Return to the celestia method index.

getsystemtime
number

Return the current system time as a TDB Julian Date number.

Older Celestia versions use UTC (Coordinated Universal Time) to calculate times and positions. Starting with version, although Celestia still displays UTC on the screen, it uses the TDB time scale internally for everything else, so for CELX scripting !!!

Notes:
 * 1) To get the current simulation time instead of the current system time, the celestia:gettime or observer:gettime method should be used instead.
 * 2) The TDB time scale is a bit different from the more familiar UTC. By using TDB, Celestia places objects much more accurately. As of January 1, 2008, the difference between the two is about 65 seconds. For more information, see Celestia/Time_Scales.
 * 3) To convert between UTC and TDB times, you can use the  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 4) To convert between normal calender dates and julian days, you can use the celestia:tojulianday and celestia:fromjulianday methods.

Example:

actual_systemtime = celestia:getsystemtime

Return to the celestia method index.

ispaused
boolean

Return a boolean, indicating whether time is paused or not.
 * true if time is paused
 * false otherwise.

Example:

actual_paused = celestia:ispaused

Return to the celestia method index.

showconstellations


Enable the rendering of one or many constellations.

Notes:
 * 1) When Constellations are turned on, using the celestia:setrenderflags method, all constellations are shown by default. To let this celestia:showconstellations method take effect, you first have to disable the rendering of constellations again, using the celestia:hideconstellations method.
 * 2) Besides the rendering of the constellations, this celestia:showconstellations method also takes effect on the constellation names.

Example-1: Show Virgo and Libra only

-- Note the curly braces celestia:setrenderflags{constellations = true} celestia:hideconstellations celestia:showconstellations{"Virgo", "Libra"}

Example-2: Show zodiacal constellations only

celestia:setrenderflags{constellations = true} celestia:hideconstellations zodiac = {"Pisces", "Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpius", "Ophiuchus", "Sagittarius", "Capricornus", "Aquarius"} celestia:showconstellations(zodiac)

Example-3: Show all constellations

celestia:setrenderflags{constellations = true} celestia:hideconstellations celestia:showconstellations

Return to the celestia method index.

hideconstellations


Disable the rendering of one or many constellations.

Notes:
 * 1) When Constellations are turned on, using the celestia:setrenderflags method, all constellations are shown by default. You first have to disable the rendering of constellations again, using this celestia:hideconstellations method, before the celestia:showconstellations method can take any effect.
 * 2) Besides disabeling the rendering of the constellations, this celestia:hideconstellations method also takes effect on the constellation names.

Example-1: Hide Virgo and Libra only

-- Note the curly braces celestia:setrenderflags{constellations = true} celestia:hideconstellations{"Virgo", "Libra"}

Example-2: Hide all constellations, except Virgo and Libra

-- Note the curly braces celestia:setrenderflags{constellations = true} celestia:hideconstellations celestia:showconstellations{"Virgo", "Libra"}

Return to the celestia method index.

setconstellationcolor


Set the color of individual constellations.

Notes:
 * 1) Constellations can be turned on/off using the celestia:setrenderflags method.
 * 2)  To render specific constellations only, you can use the celestia:showconstellations and celestia:hideconstellations methods.
 * 3) Besides setting the color of the constellations, this celestia:setconstellationcolor method also takes effect on the constellation names.

Example-1: Set the color of all constellations to red

celestia:setrenderflags{constellations = true} celestia:setconstellationcolor(1, 0, 0)

Example-2: Show all zodiacal constellations in yellow

celestia:setrenderflags{constellations = true} zodiac = {"Pisces", "Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpius", "Ophiuchus", "Sagittarius", "Capricornus", "Aquarius"} celestia:setconstellationcolor(1, 1, 0, zodiac)

Return to the celestia method index.

gettextureresolution
number

Return the current texture resolution as a number.
 * 0 is low resolution (lores)
 * 1 is medium resolution (medres)
 * 2 is high resolution (hires)

Example:

actual_textureres = celestia:gettextureresolution

Return to the celestia method index.

settextureresolution


Set the texture resolution.



Example: The non-commented line determines the texture resolution.

-- celestia:settextureresolution(0) -- lores -- celestia:settextureresolution(1) -- medres celestia:settextureresolution(2)    -- hires

Return to the celestia method index.

windowbordersvisible
boolean

Return a boolean, indicating whether or not the window borders are visible around each view in case of a Multiview scene.
 * true if window borders are visible.
 * false if window borders are NOT visible.

Example:

actual_visible = celestia:windowbordersvisible

Return to the celestia method index.

setwindowbordersvisible


Set the visibility of the window borders around each view in case of a Multiview scene.

Example: The non commented line sets the visibility of the window borders around each view in case of a Multiview scene.

celestia:setwindowbordersvisible(true)     -- Window borders visible -- celestia:setwindowbordersvisible(false) -- Window borders NOT visible

Return to the celestia method index.

synchronizetime


Set whether time is synchronized or not between all views, in case of a Multiview scene.

Notes:
 * 1) Turning time synchronization back on, resets the time in all views to that of the active view.

Example: The non commented line determines if time will be synchronised or not between all views, in case of a Multiview scene.

-- celestia:synchronizetime(true)     -- Time is the same in each view celestia:synchronizetime(false)       -- Time can be set in each view independently

Return to the celestia method index.

istimesynchronized
boolean

Return a boolean, indicating whether time is synchronized or not between all views, in case of a Multiview scene.
 * true: time is synchronized between all views.
 * false: time is NOT synchronized between all views.

Example:

actual_synched = celestia:istimesynchronized

Return to the celestia method index.

seturl


Make an observer goto the a specified celURL.

Notes:
 * 1) celURLs for Celestia  and  are of type "ver=3" (last parameter in string:celURL), and not fully compatible with celURLs of earlier version types. So the results of this celestia:seturl method may vary when using a ver=2 celURL in Celestia  and, compared to earlier versions of Celestia.
 * 2) To obtain a celURL online from Celestia, press either the [Ctrl+C] or [Ctrl+Ins] keys.  This will save the celURL to the clipboard on the computer. To paste that celURL into a CELX script, simply position the cursor in the CELX script at the appropriate place and press the [Ctrl+V] keys. To make it a string:celURL, place a double quote before and after.
 * 3) To obtain a celURL from within a CELX script, the  celestia:geturl method must be used.

Example: Position yourself on top of Mount Everest and watch a very special sunrise.

obs=celestia:getobserver celestia:seturl("cel://SyncOrbit/Sol:Earth/2009-07-21T22:47:04.72721? x=N1WRszkGAg&y=R5015O+GFA&z=h+mfTNDb2P///////////w&ow=0.551145&ox=0.273737&oy=- 0.643962&oz=0.454554&select=Sol&fov=29.1666&ts=50.0&ltd=0&p=0&rf=20227&lm=1243136&tsrc=0&ver=3", obs) wait(180.0)

Return to the celestia method index.

geturl
string

Return the position, orientation, time, render options and field of view of the specified observer as a celURL-type string. For a description of the format of the celURL-type string, see the celestia:seturl method.

Notes:
 * 1) celURLs for Celestia  and  are of type "ver=3" (last parameter in string:celURL), and not fully compatible with celURLs of earlier version types. So the results of this celestia:seturl method may vary when using a ver=2 celURL in Celestia  and, compared to earlier versions of Celestia.
 * 2) To set a celURL from within a CELX script, the  celestia:seturl method must be used.

Example:

obs=celestia:getobserver actual_celurl = celestia:geturl(obs)

Return to the celestia method index.

settextcolor


Set the color of the text for Celestia messages and scripting messages (i.e. the celestia:print and celestia:flash methods).

Notes:
 * 1) This method can be very useful when you zoom in on bright objects (i.e. the Sun or Mercury). When your screen is filled with the object, standard white text messages are very difficult to read. In that case changing the text color may help improve the readability of text messages.
 * 2) It is not possible to change the text color within the same text message.
 * 3) The current colors of text messages can be obtained by using the  celestia:gettextcolor method.

Example: Set text color for Celestia and scripting messages to green

celestia:settextcolor(0.0, 1.0, 0.0) celestia:flash("This text is printed GREEN", 5.0) wait(5.0)

Return to the celestia method index.

gettextcolor
number, number, number

Return a triple number (between 0 and 1), which corresponds to the red, green, blue components of the RGB values of the text message color.

Notes:
 * 1) The colors of text messages can be set by using the  celestia:settextcolor method.

Example:

r, g, b = celestia:gettextcolor

Return to the celestia method index.

runscript


Adding this command at the end of a celx script allows launching whatever celx or cel script once the original celx script is done.

Notes:
 * 1) This method uses relative script names.
 * 2) In a celx script, this method should be always followed by a wait(0) command.
 * 3) Using this method you can do a "chain" of scripts.
 * 4) The main script will be terminated as soon as the second script is launched. That means that all extra lines of codes below the celestia:runscript command will be ignored.

Example 1: Launch a celx script named "myscriptname.celx" located in the same directory as the current running script.

celestia:runscript("myscriptname.celx") wait(0)

Example 2: The script "myscriptname.celx" is located in a different directory named "myDir2".

celestia:runscript("../mydir2/myscriptname.celx") wait(0)

Return to the celestia method index.