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

celestia:print(string:text [, number:duration, number:horig, number:vorig, number:hoffset, number:voffset])

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

Arguments:

text

A string containing the message to be printed.

The string can contain newlines "\n" to break lines, or many special characters encoded in UTF-8.

It is also possible to use variables and text strings within the same print command.

This can be done by concatenating text strings and variables as follows:

• "String1 " .. variable1 .. "String2 " .. variable2

For the more experienced CELX writer, it’s also possible to use Lua string functions on text,

for instance to merge and format text and variables (see Lua Reference Manual).

duration [optional]

Number of seconds the text is shown. Default is 5.

Negative duration values are considered to be 1.5 seconds.

horig [optional]

Horizontal origin of the text, -1 is left, 0 center, 1 right

vorig [optional]

Vertical origin of the text, -1 is bottom, 0 center, 1 top

hoffset [optional]

Horizontal offset relative to origin.

voffset [optional]

Vertical Offset relative to origin.

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 1.6.1 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

celestia:flash(string:text [, number:duration])

Print text on screen, similar to print.

Arguments:

text

A string containing the message to be printed. The string can contain newlines "\n" to break lines, or many special characters encoded in UTF-8.

duration [optional]

Number of seconds the text is shown. Default is 5.

Negative duration values are considered to be 1.5 seconds.

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

celestia:show(string:renderflag)

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

The celestia:setrenderflags() method should be used instead.

Arguments:

renderflag

String describing the render-feature to be enabled. Must be one of:

• orbits
• cloudmaps
• constellations
• galaxies
• planets
• stars
• nightmaps
• eclipseshadows
• ringshadows
• comettails
• boundaries
• markers
• automag
• atmospheres
• grid
• smoothlines
• lightdelay
• partialtrajectories
• 1.5.0 cloudshadows
• 1.5.0 nebulae
• 1.5.0 openclusters
• 1.6.0 globulars
• 1.6.0 ecliptic
• 1.6.0 equatorialgrid
• 1.6.0 galacticgrid
• 1.6.0 eclipticgrid
• 1.6.0 horizontalgrid

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

celestia:hide(string:renderflag)

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

The celestia:setrenderflags() method should be used instead.

Arguments:

renderflag

String describing the render-feature to be disabled.

• See the celestia:show() method.

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 celestia:getrenderflags()

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

celestia:setrenderflags(table:renderflags)

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.

Arguments:

renderflags

A table which contains the renderflags as keys, and booleans as values for each key. Valid renderflag keys are:

• orbits
• cloudmaps
• constellations
• galaxies
• planets
• stars
• nightmaps
• eclipseshadows
• ringshadows
• comettails
• boundaries
• markers
• automag
• atmospheres
• grid
• smoothlines
• lightdelay
• partialtrajectories
• 1.5.0 cloudshadows
• 1.5.0 nebulae
• 1.5.0 openclusters
• 1.6.0 globulars
• 1.6.0 ecliptic
• 1.6.0 equatorialgrid
• 1.6.0 galacticgrid
• 1.6.0 eclipticgrid
• 1.6.0 horizontalgrid

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

1.3.2 celestia:showlabel(string:labelflag)

Enable the rendering of labels.

Arguments:

labelflag

String describing the type of labels to enable, must be one of:

• planets
• moons
• spacecraft
• asteroids
• comets
• stars
• galaxies
• locations
• constellations
• 1.5.0 i18nconstellations
  • used to display either the Latin or the translated label names of constellations when the labeling of constellations is enabled.
• 1.5.0 openclusters
• 1.5.0 nebulae
• 1.6.0 dwarfplanets
• 1.6.0 minormoons
• 1.6.0 globulars

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

1.3.2 celestia:hidelabel(string:labelflag)

Disable the rendering of labels.

Arguments:

labelflag

String describing the type of labels to disable.

• See the celestia:showlabel() method.

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

1.3.2 table celestia:getlabelflags()

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

1.3.2 celestia:setlabelflags(table:labelflags)

Enable or disable the rendering of labels.

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

Arguments:

labelflags

A table which contains the labelflags as keys, and booleans as values for each key. Valid labelflag keys are:

• planets
• moons
• spacecraft
• asteroids
• comets
• stars
• galaxies
• locations
• constellations
• 1.5.0 i18nconstellations
  • used to display either the Latin or the translated label names of constellations when the labeling of constellations is enabled.
• 1.5.0 openclusters
• 1.5.0 nebulae
• 1.6.0 dwarfplanets
• 1.6.0 minormoons
• 1.6.0 globulars

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

1.3.2 table celestia:getorbitflags()

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

1.3.2 celestia:setorbitflags(table:orbitflags)

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

Arguments:

orbitflags

A table which contains the orbitflags as keys, and booleans as values for each key.

Each orbitflag must be one of:

• Planet
• Moon
• Asteroid
• Comet
• Spacecraft
• Invisible
• Unknown
• 1.6.0 DwarfPlanet
• 1.6.0 MinorMoon
• 1.6.0 Star

Note: Mind the case sensitivity of celestia, regarding the keys for this celestia 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

1.3.2 number celestia:getambient()

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

1.3.2 celestia:setambient(number:ambient)

Set the brightness level of ambient light.

Arguments:

ambient

The new level of ambient light, must be between 0 and 1, otherwise it will be adjusted to the nearest valid value (0 or 1).

• For realism, this number should be set to 0.0. The side of the body facing away from the Sun will be totally dark.
• Setting this number to 1.0 will cause the side of the body facing away from the Sun to appear as bright as the lit side.

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

1.3.2 number celestia:getfaintestvisible()

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

1.3.2 celestia:setfaintestvisible(number:faintest)

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.

Arguments:

faintest

The new faintest visible magnitude of stars.

The Celestia user interface allows a range from about 1.0 to 15.0.

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 1.5.0 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

1.3.2 number celestia:getminorbitsize()

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

1.3.2 celestia:setminorbitsize(number:orbitsize)

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.

Arguments:

orbitsize

The minimum size of an orbit to be rendered.

A negative orbitsize value is considered to be zero.

The size is measured in pixels and is related to the radius of the orbit.

• Note: When the size is greater than 50% of the screen dimensions, no orbits will be rendered at all.

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

1.3.2 number celestia:getstardistancelimit()

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

1.3.2 celestia:setstardistancelimit(number:distance)

Set the furthest distance at which Celestia will display stars.

Arguments:

distance

The maximum star distance in light years 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

1.3.2 number celestia:getminfeaturesize()

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

1.3.2 celestia:setminfeaturesize(number:size)

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.

Arguments:

size

The minimum feature size for locations to be labeled.

A negative size value is considered to be zero.

Locations with a defined size of less than this size will not be labeled.

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

1.3.2 string celestia:getstarstyle()

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

1.3.2 celestia:setstarstyle(string:starstyle)

Set the rendering style for stars.

Arguments:

starstyle

The new rendering style for stars.

Must 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: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 celestia:find(string:name)

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

Arguments:

name

String describing the wanted planet, moon, asteroid, comet, galaxy, spacecraft, etc.

• Stars and space objects are named by their common names or Bayer and Flamsteed designations and HD or HIP catalog numbers
  (e.g. "Polaris", "HIP 21589", "41 ari").
• Galaxies are named by their common names or through their Messier numbers, NGC, UGC or MCG catalog numbers
  (e.g. "M 33", "Milky way").
• Planets, moons, asteroids and artificial satellites may be named by their common names
  (e.g. "Mir", "Jupiter", "Io", "Cassini")

Note: If you are currently positioned outside of our solar system, and want to seek an object inside of our solar system,
you must include "Sol/" in the name string (e.g. "Sol/Mars").

Note: If you are seeking a named Location on a planet or moon, you must include the name of the planet or moon where the location is found,
as well as the location itself, separated by a slash / mark (e.g. "Earth/Amsterdam" or "Sol/Earth/Amsterdam").

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 celestia:getselection()

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

celestia:select(object:obj)

Set the current selection to the specified object.

Arguments:

obj

The object which will be the new selection.

If not a valid object, the selection will be cleared.

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

celestia:mark(object:obj)

Mark the specified object.

Arguments:

obj

The object to be marked.

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

celestia:unmark(object:obj)

Remove marker from the specified object.

Arguments:

obj

The object whose marker should be removed.

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

celestia: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 celestia:gettime()

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 1.5.0, 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 1.6.0 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 1.5.0 celestia:utctotdb() and 1.5.0 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

celestia:settime(number:time)

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 1.5.0, although Celestia still displays UTC on the screen,
it uses the TDB time scale internally for everything else, so for CELX scripting !!!

Arguments:

time

Number giving the time as a TDB Julian date.
Celestia versions prior to version 1.5.0 use the UTC Julian date number.

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 1.5.0 celestia:utctotdb() and 1.5.0 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 celestia:gettimescale()

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

celestia:settimescale(number:timescale)

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

Arguments:

timescale

The new timespeed.

Defines the time multiplier (i.e. 100x).

Special values are:

• 0: Pause time
• 1: Reset to Real Time
• Negative values reverse 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 celestia:getscripttime()

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 celestia:getobserver()

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 1.6.0 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

1.3.2 table celestia:getobservers()

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 celestia:tojulianday(number:year [, number:month, number:day, number:hour, number:minute, number:seconds])

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).

Arguments:

year

Integer value for the year of this date

month [optional]

Integer value (1 - 12) for the month within the year of this date. Default is 1.

day [optional]

Integer value (1 - 31) for the day within the month of this date. Default is 1.

hour[optional]

Integer value for the hour within the day of this date. Default is 0.

minute [optional]

Integer value for the minute within the hour of this date. Default is 0.

seconds [optional]

Float value for the seconds within the minute of this date. Default is 0.0.

Notes:

1. Starting with version 1.5.0, 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 1.5.0 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 1.5.0, 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 1.5.0.

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 1.5.0, 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

1.3.2 table celestia:fromjulianday(number:jd)

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).

Arguments:

jd

The UTC Julian date number.

Special values:

• 0 is the day at the above-mentioned reference date
• Negative values can be used for preceding dates
• The Julian day number (JDN) is the integral part of the Julian date (JD).
  • The Julian day number of January 1, 2010 is 2455198.
• The decimal parts of a Julian date:
  • 0.1 is 2.4 hours or 144 minutes or 8640 seconds
  • 0.01 is 0.24 hours or 14.4 minutes or 864 seconds
  • 0.001 is 0.024 hours or 1.44 minutes or 86.4 seconds
  • 0.0001 is 0.0024 hours or 0.144 minutes or 8.64 seconds
  • 0.00001 is 0.00024 hours or 0.0144 minutes or 0.864 seconds.

Notes:

1. Starting with version 1.5.0, 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 1.5.0 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 1.5.0, 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 1.5.0.

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 1.5.0, 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

1.3.2 x, y celestia:getscreendimension()

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 celestia:newvector(number:x, number:y, number:z)

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

Arguments:

x

The X-component of the new vector, as a number in millionths of a light year.

y

The Y-component of the new vector, as a number in millionths of a light year.

z

The Z-component of the new vector, as a number in millionths of a light year.

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:
   • From km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
   • From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
2. Next you can convert km or miles to millionths of a light year as follows:
   • millionths_of_a_light_year = number:km / uly_to_km
   • millionths_of_a_light_year = number:miles / uly_to_mls
3. A CELX "vector" object is a geometric object that has both a length and direction [X, Y, Z] in a 3 dimensional coordinate system.
4. 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

1.3.2 position celestia:newposition(number:x, number:y, number:z)

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

Arguments:

x

The X-component of the new position, as a number in millionths of a light year.

y

The Y-component of the new position, as a number in millionths of a light year.

z

The Z-component of the new position, as a number in millionths of a light year.

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:
   • From km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
   • From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
2. Next you can convert km or miles to millionths of a light year as follows:
   • millionths_of_a_light_year = number:km / uly_to_km
   • millionths_of_a_light_year = number:miles / uly_to_mls
3. 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.
4. 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)

1.3.2 position celestia:newposition(string:x, string:y, string:z)

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

Arguments:

x

The X-component of the new position, as a string-value, taken from a cel-style URL.

y

The Y-component of the new position, as a string-value, taken from a cel-style URL.

z

The Z-component of the new position, as a string-value, taken from a cel-style URL.

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 1.6.0 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 celestia:newrotation(vector:axis, number:angle)

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

Arguments:

axis

Vector describing the [x,y,z] axis of this rotation. Must be a "vector" object.

angle

The angle of this rotation in radians. Must be a number.

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:
   • radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
   • degrees = math.deg( number:radians ) = ( number:radians * 180 / math.pi) = ( number:radians * 180 / 3.14159265).
2. 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.
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-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 celestia:newrotation(number:ow, number:ox, number:oy, number:oz)

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).

Arguments:

ow

The OW-component of the new rotation, as a number-value taken from a cel-style URL.

ox

The OX-component of the new rotation, as a number-value taken from a cel-style URL.

oy

The OY-component of the new rotation, as a number-value taken from a cel-style URL.

oz

The OZ-component of the new rotation, as a number-value taken from a cel-style URL.

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 1.6.0 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 celestia:newframe(string:coordsysname [, object:reference, object:target])

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

Arguments:

coordsysname

String describing the type of the frame. It must be one of the following:

• universal
• ecliptic
  Also see the observer:follow() method.
• equatorial
• planetographic
  Also see the observer:synchronous() method.
• observer (deprecated)
• lock
  Also see the observer:lock() method.
• chase
  Also see the observer:chase() method.
• 1.6.0 bodyfixed
  Also see the observer:synchronous() method.

reference [optional]

The reference object for the new frame. Must be an "object" object.

• Not needed for the coordinate system "universal".

target [optional]

The target object for this frame. Must be an "object" object.

• Only needed for the coordinate system "lock".

Notes:

1. In Celestia version 1.6.0, 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

1.3.2 celestia:requestkeyboard(boolean:enable)

Enable or disable callback for keyboard input.

Arguments:

enable

Boolean to determine if keyboard-input should be enabled/disabled.

• true if keyboard-input should be enabled
• false to let celestia handle the keyboard.

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

1.3.2 celestia: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

1.3.2 string celestia:getscriptpath()

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

1.3.2 boolean celestia:takescreenshot([string:filetype, string:name])

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

Arguments:

filetype [optional]

Define the filetype (extension) of the screenshot, default is "png"

Must be one of:

• "png"
• "jpg"

name [optional]

A string which will be used in the filename for this screenshot, default is "".

This name-part is restricted to A-z, 0-9 and _ (underscore) with a maximum length of eight chars.

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 1.3.2 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 celestia:createcelscript(string:CELsource)

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

Arguments:

CELsource

A string containing the sourcecode of a valid CEL script.
Note: If the string doesn't contain a valid CEL script, this method will cause an error.

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 celestia:getstarcount()

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 celestia:getstar(number:index_number)

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

Arguments:

index_number

Number of star in star-catalogue.

Must be between 0 (zero) and the total number of stars in the star catalogue minus 1.

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

1.5.0 number celestia:getdsocount()

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

1.5.0 object celestia:getdso(number:index_number)

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

Arguments:

index_number

Number of Deep Space Object (DSO) in the DSO-catalogue.

Must be between 0 (zero) and the total number of DSOs in the DSO catalogue minus 1.

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 1.5.0 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

1.5.0 iterator celestia:stars()

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:

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).

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.

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

1.5.0 iterator celestia:dsos()

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:

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).

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.

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

1.5.0 number celestia:utctotdb(number:year [, number:month, number:day, number:hour, number:minute, number:seconds])

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

Arguments:

year

Integer value for the year of this date

month [optional]

Integer value (1 - 12) for the month within the year of this date. Default is 1.

day [optional]

Integer value (1 - 31) for the day within the month of this date. Default is 1.

hour[optional]

Integer value for the hour within the day of this date. Default is 0.

minute [optional]

Integer value for the minute within the hour of this date. Default is 0.

seconds [optional]

Float value for the seconds within the minute of this date. Default is 0.0.

Notes:

1. Starting with version 1.5.0, 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 1.5.0 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

1.5.0 table celestia:tdbtoutc(number:tdb)

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.

Arguments:

tdb

The TDB Julian date number.

Special values:

• 0 is the day at the above-mentioned reference date
• Negative values can be used for preceding dates
• The Julian day number (JDN) is the integral part of the Julian date (JD).
  • The Julian day number of January 1, 2010 is 2455198.
• The decimal parts of a Julian date:
  • 0.1 is 2.4 hours or 144 minutes or 8640 seconds
  • 0.01 is 0.24 hours or 14.4 minutes or 864 seconds
  • 0.001 is 0.024 hours or 1.44 minutes or 86.4 seconds
  • 0.0001 is 0.0024 hours or 0.144 minutes or 8.64 seconds
  • 0.00001 is 0.00024 hours or 0.0144 minutes or 0.864 seconds.

Notes:

1. Starting with version 1.5.0, 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 1.5.0 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

1.5.0 boolean celestia:getaltazimuthmode()

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:
   • altitude (Alt), that is the angle between an object and the observer's local horizon.
   • azimuth (Az), that is the angle of an object around the horizon, relative to an origin.
2. 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:
   • "Yaw" if alt-azimuth mode is enabled (true).
   • "Roll" if alt-azimuth mode is disabled (false).
3. The alt-azimuth mode can be set, using the 1.5.0 celestia:setaltazimuthmode() method.

Example:

actual_altaz = celestia:getaltazimuthmode()

Return to the celestia method index.

setaltazimuthmode

1.5.0 celestia:setaltazimuthmode(boolean:altaz)

Enable or disable alt-azimuth mode.

Arguments:

altaz

Boolean that indicates if alt-azimuth mode must be enabled or disabled:

• true if alt-azimuth mode must be enabled.
• false if alt-azimuth mode must be 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:
   • altitude (Alt), that is the angle between an object and the observer's local horizon.
   • azimuth (Az), that is the angle of an object around the horizon, relative to an origin.
2. 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:
   • "Yaw" if alt-azimuth mode is enabled (true).
   • "Roll" if alt-azimuth mode is disabled (false).
3. The current alt-azimuth mode can be obtained, using the 1.5.0 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

1.5.0 table celestia:getoverlayelements()

Return a table with all known overlay elements (see 1.5.0 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 1.5.0 celestia:setoverlayelements() method can be used.

Example:

actual_overlaytab = celestia:getoverlayelements()

Return to the celestia method index.

setoverlayelements

1.5.0 celestia:setoverlayelements(table:overlayelements)

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.

Arguments:

overlayelements

A table which contains the overlay elements as keys, and booleans as values for each key. Each overlay element must be one of:

• Time
  The overlay element in the upper right corner of your screen.
• Velocity
  The overlay element in the lower left corner of your screen.
• Selection
  The overlay element in the upper left corner of your screen.
• Frame
  The overlay element in the lower right corner of your screen.

Note: Mind the case sensitivity of celestia, regarding the keys for this celestia method !!!

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 1.5.0 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

1.5.0 number celestia:getgalaxylightgain()

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 1.5.0 celestia:setgalaxylightgain() method.

Example:

actual_galaxylightgain = celestia:getgalaxylightgain()

Return to the celestia method index.

setgalaxylightgain

1.5.0 celestia:setgalaxylightgain(number:lightgain)

Set the level of Galaxy light gain (brightness).

Arguments:

lightgain

Number that defines the new level of Galaxy light gain (brightness).

Must be between 0 (0%) and 1 (100%), otherwise it will be adjusted to the nearest valid value (0 or 1).

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 1.5.0 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

1.5.0 number celestia:gettextwidth(string:text)

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

1.5.0 celestia:log(string:text)

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

Arguments:

text

A string containing the message to be written to the Celestia log.

It is also possible to use variables and text strings within the same log command.

This can be done by concatenating text strings and variables as follows:

• "String1 " .. variable1 .. "String2 " .. variable2

Note: Unlike the celestia:print() method, this string argument CANNOT contain newlines "\n" to break lines.

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

1.5.0 boolean celestia:registereventhandler(string:eventtype, function:eventhandler)

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

Arguments:

eventtype

A string specifying the event type. Must be one of:

• "key":
• "mouseup":
• "mousedown":
• "tick":

eventhandler

A function that accepts a single table parameter containing the event properties and returns a boolean indicating whether or not it handled the event.

Use nil to unbind event type from the event handler.

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:
   1. Celestia is restarted
   2. A new binding is specified between the event type and another event handler (possibly in another script)
   3. By unbinding the event type from the event handler, using:
      celestia:registereventhandler(string:eventtype, nil)

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

1.5.0 boolean celestia:geteventhandler(string:eventtype)

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.

Arguments:

eventtype

A string specifying the event type. Must be one of:

• "key":
• "mouseup":
• "mousedown":
• "tick":

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

1.5.0 celestia:setlabelcolor(string:label, number:red, number:green, number:blue)

Set the colors of the labels palette.

Arguments:

label

A string describing the label whose color must change. Must be one of:

• stars
• planets
• moons
• asteroids
• comets
• spacecraft
• locations
• galaxies
• constellations
• equatorialgrid
• 1.5.0 nebulae
• 1.5.0 openclusters
• 1.6.0 globulars
• 1.6.0 dwarfplanets
• 1.6.0 minormoons
• 1.6.0 planetographicgrid
• 1.6.0 galacticgrid
• 1.6.0 eclipticgrid
• 1.6.0 horizontalgrid

red

The Red part of the RGB values of the color, must be between 0 and 1.

green

The Green part of the RGB values of the color, must be between 0 and 1.

blue

The Blue part of the RGB values of the color, must be between 0 and 1.

Notes:

1. The current colors of specific labels can be obtained by using the 1.6.0 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

1.5.0 celestia:setlinecolor(string:line, number:red, number:green, number:blue)

Set the colors of the lines palette.

Arguments:

line

A string describing the line whose color must change. Must be one of:

• starorbits
• planetorbits
• moonorbits
• asteroidorbits
• cometorbits
• spacecraftorbits
• constellations
• boundaries
• equatorialgrid
• 1.6.0 dwarfplanetorbits
• 1.6.0 minormoonorbits
• 1.6.0 planetographicgrid
• 1.6.0 planetequator
• 1.6.0 galacticgrid
• 1.6.0 eclipticgrid
• 1.6.0 horizontalgrid
• 1.6.0 ecliptic

red

The Red part of the RGB values of the color, must be between 0 and 1.

green

The Green part of the RGB values of the color, must be between 0 and 1.

blue

The Blue part of the RGB values of the color, must be between 0 and 1.

Notes:

1. The current colors of specific lines can be obtained by using the 1.6.0 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 1.6.0 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

1.6.0 number, number, number celestia:getlabelcolor(string:label)

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.

Arguments:

label

A string describing the label whose color must be returned. Must be one of:

• stars
• planets
• moons
• asteroids
• comets
• spacecraft
• locations
• galaxies
• constellations
• equatorialgrid
• 1.5.0 nebulae
• 1.5.0 openclusters
• 1.6.0 globulars
• 1.6.0 dwarfplanets
• 1.6.0 minormoons
• 1.6.0 planetographicgrid
• 1.6.0 galacticgrid
• 1.6.0 eclipticgrid
• 1.6.0 horizontalgrid

Notes:

1. The colors of specific labels can be set by using the 1.5.0 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

1.6.0 number, number, number celestia:getlinecolor(string:line)

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.

Arguments:

line

A string describing the line whose color must be returned. Must be one of:

• starorbits
• planetorbits
• moonorbits
• asteroidorbits
• cometorbits
• spacecraftorbits
• constellations
• boundaries
• equatorialgrid
• 1.6.0 dwarfplanetorbits
• 1.6.0 minormoonorbits
• 1.6.0 planetographicgrid
• 1.6.0 planetequator
• 1.6.0 galacticgrid
• 1.6.0 eclipticgrid
• 1.6.0 horizontalgrid
• 1.6.0 ecliptic

Notes:

1. The colors of specific lines can be set by using the 1.5.0 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 1.6.0 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

1.6.0 number celestia:getsystemtime()

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 1.5.0, 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 1.5.0 celestia:utctotdb() and 1.5.0 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

1.6.0 boolean celestia:ispaused()

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

1.6.0 celestia:showconstellations([table:constellation_names])

Enable the rendering of one or many constellations.

Arguments:

constellation_names [optional]

A table which contains the names of constellations to be shown. Must be one of:

• "Andromeda", "Antlia", "Apus", "Aquarius", "Aquila", "Ara", "Aries", "Auriga", "Boötes", "Caelum", "Camelopardalis", "Cancer", "Canes Venatici", "Canis Major", "Canis Minor", "Capricornus", "Carina", "Cassiopeia", "Centaurus", "Cepheus", "Cetus", "Chamaeleon", "Circinus", "Columba", "Coma Berenices", "Corona Australis", "Corona Borealis", "Corvus", "Crater", "Crux", "Cygnus", "Delphinus", "Dorado", "Draco", "Equuleus", "Eridanus", "Fornax", "Gemini", "Grus", "Hercules", "Horologium", "Hydra", "Hydrus", "Indus", "Lacerta", "Leo", "Leo Minor", "Lepus", "Libra", "Lupus", "Lynx", "Lyra", "Mensa", "Microscopium", "Monoceros", "Musca", "Norma", "Octans", "Ophiuchus", "Orion", "Pavo", "Pegasus", "Perseus", "Phoenix", "Pictor", "Pisces", "Piscis Austrinus", "Puppis", "Pyxis", "Reticulum", "Sagitta", "Sagittarius", "Scorpius", "Sculptor", "Scutum", "Serpens Caput", "Serpens Cauda", "Sextans", "Taurus", "Telescopium", "Triangulum", "Triangulum Australe", "Tucana", "Ursa Major", "Ursa Minor", "Vela", "Virgo", "Volans", "Vulpecula".
• If no constellation_names is passed, all constellations are shown.
• If the asterisms.dat file in the ..\celestia\data directory contains alternative asterisms and/or constellation names, the mentioned names in this file can be used too in this parameter.

Note: Mind the case sensitivity of celestia, regarding the constellation names for this method !!!

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

1.6.0 celestia:hideconstellations([table:constellation_names])

Disable the rendering of one or many constellations.

Arguments:

constellation_names [optional]

A table which contains the names of constellations to be hidden. Must be one of:

• "Andromeda", "Antlia", "Apus", "Aquarius", "Aquila", "Ara", "Aries", "Auriga", "Boötes", "Caelum", "Camelopardalis", "Cancer", "Canes Venatici", "Canis Major", "Canis Minor", "Capricornus", "Carina", "Cassiopeia", "Centaurus", "Cepheus", "Cetus", "Chamaeleon", "Circinus", "Columba", "Coma Berenices", "Corona Australis", "Corona Borealis", "Corvus", "Crater", "Crux", "Cygnus", "Delphinus", "Dorado", "Draco", "Equuleus", "Eridanus", "Fornax", "Gemini", "Grus", "Hercules", "Horologium", "Hydra", "Hydrus", "Indus", "Lacerta", "Leo", "Leo Minor", "Lepus", "Libra", "Lupus", "Lynx", "Lyra", "Mensa", "Microscopium", "Monoceros", "Musca", "Norma", "Octans", "Ophiuchus", "Orion", "Pavo", "Pegasus", "Perseus", "Phoenix", "Pictor", "Pisces", "Piscis Austrinus", "Puppis", "Pyxis", "Reticulum", "Sagitta", "Sagittarius", "Scorpius", "Sculptor", "Scutum", "Serpens Caput", "Serpens Cauda", "Sextans", "Taurus", "Telescopium", "Triangulum", "Triangulum Australe", "Tucana", "Ursa Major", "Ursa Minor", "Vela", "Virgo", "Volans", "Vulpecula".
• If no constellation_names is passed, all constellations are hidden.
• If the asterisms.dat file in the ..\celestia\data directory contains alternative asterisms and/or constellation names, the mentioned names in this file can be used too in this parameter.

Note: Mind the case sensitivity of celestia, regarding the constellation names for this method !!!

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

1.6.0 celestia:setconstellationcolor(number:red, number:green, number:blue [, table:constellation_names])

Set the color of individual constellations.

Arguments:

red

The Red component of the RGB values of the color, must be between 0 and 1.

green

The Green component of the RGB values of the color, must be between 0 and 1.

blue

The Blue component of the RGB values of the color, must be between 0 and 1.

constellation_names [optional]

A table which contains the names of constellations on which color change are applied. Must be one of:

• "Andromeda", "Antlia", "Apus", "Aquarius", "Aquila", "Ara", "Aries", "Auriga", "Boötes", "Caelum", "Camelopardalis", "Cancer", "Canes Venatici", "Canis Major", "Canis Minor", "Capricornus", "Carina", "Cassiopeia", "Centaurus", "Cepheus", "Cetus", "Chamaeleon", "Circinus", "Columba", "Coma Berenices", "Corona Australis", "Corona Borealis", "Corvus", "Crater", "Crux", "Cygnus", "Delphinus", "Dorado", "Draco", "Equuleus", "Eridanus", "Fornax", "Gemini", "Grus", "Hercules", "Horologium", "Hydra", "Hydrus", "Indus", "Lacerta", "Leo", "Leo Minor", "Lepus", "Libra", "Lupus", "Lynx", "Lyra", "Mensa", "Microscopium", "Monoceros", "Musca", "Norma", "Octans", "Ophiuchus", "Orion", "Pavo", "Pegasus", "Perseus", "Phoenix", "Pictor", "Pisces", "Piscis Austrinus", "Puppis", "Pyxis", "Reticulum", "Sagitta", "Sagittarius", "Scorpius", "Sculptor", "Scutum", "Serpens Caput", "Serpens Cauda", "Sextans", "Taurus", "Telescopium", "Triangulum", "Triangulum Australe", "Tucana", "Ursa Major", "Ursa Minor", "Vela", "Virgo", "Volans", "Vulpecula".
• If no constellation_names table is passed, all constellations will be set to the specified color.
• If the asterisms.dat file in the ..\celestia\data directory contains alternative asterisms and/or constellation names, the mentioned names in this file can be used too in this parameter.

Note: Mind the case sensitivity of Celestia, regarding the constellation names for this method !!!

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

1.6.0 number celestia:gettextureresolution()

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

1.6.0 celestia:settextureresolution(number:resolution)

Set the texture resolution.

• Arguments:

resolution

number that corresponds with one of the available texture resolutions:

• 0 for low resolution (lores)
• 1 for medium resolution (medres)
• 2 for high resolution (hires)

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

1.6.0 boolean celestia:windowbordersvisible()

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

1.6.0 celestia:setwindowbordersvisible(boolean:visible)

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

Arguments:

visible

Boolean, indicating wether or not the window borders are visible around each view in case of a Multiview scene:

• true: window borders are visible.
• flase: window borders are NOT visible.

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

1.6.1 celestia:synchronizetime(boolean:synched)

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

Arguments:

synched

Boolean indicating wether or not the time is synchronized between all views in case of a Multiview scene.

• true: time is the same in each view.
• false: a different time can be set in each view independently.

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

1.6.1 boolean celestia:istimesynchronized()

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

1.6.1 celestia:seturl(string:celURL [, observer:obs])

Make an observer goto the a specified celURL.

Arguments:

celURL

A string of text (a hyperlink) that contains a position, orientation, time, render options and field of view.

celURL strings do have a specific Celestia recognizable format:

1. The string always start with "cel://";
2. Then: "Follow", "SyncOrbit", "Chase", "PhaseLock" or "Freeflight"
   • Followed by the object between two "/" caharacters (e.g. "/Sol:Earth/");
   • --OR-- only one "/" character in case of "Freeflight".
3. Date in the format: yyyy-mm-dd
   • The year may be preceded by a "-" character, to indicate a year BC.
4. Time starting with character "T" and ending with character "?" in the format:
   • hh:mm:ss.sssss TDB-time, which is slighty different from UTC-time.
     For more information on TDB, UTC, and how time is used in Celestia, see Celestia/Time Scales.
5. The observer's position (x,y,z) in space in the current reference frame:
   • "x=" ,followed by X-position (e.g. "AKknXYYNARE")
   • "&y=" ,followed by Y-position (e.g. "ACb9ForuURI")
   • "&z=", followed by Z-position (e.g. "AJLCIRc5vuz//////////w")
6. The observer's orientation (ow, ox, oy, oz):
   • "ow=" ,followed by the OW-component of the rotation (e.g. "0.429893")
   • "&ox=" ,followed by the OX-component of the rotation (e.g. "0.319956")
   • "&oy=" ,followed by the OY-component of the rotation (e.g. "-0.786188")
   • "&oz=" ,followed by the OZW-component of the rotation (e.g. "-0.307779")
7. Then other options are possible in a row, like:
   • "&track=" objectname
   • "&select=" objectname
   • "&fov=" Field of View in degrees
   • "&ts=" timescale
   • "&ltd=" light time delay (0 = off, 1 = on)
   • "&p=" paused (0 = off, 1 = on)
   • "&rf=" renderflags. The rf number is made by the sum of these individual flags:
     1 = stars
     2 = planets
     4 = galaxies
     8 = constellation lines
     16 = clouds
     32 = orbits
     64 = celestial grid
     128 = night lights
     256 = atmospheres
     512 = smooth lines for orbits
     1024 = eclipes shadows
     2048 = light travel ???
     4096 = ring shadows
     8192 = constellation boundaries
     16384 = auto magnitude
     32768 = comet tails
     65536 = marks
     131072 = partial trajectories (not implemented yet)
     262144 = nebulae
     524288 = open clusters
     1048576 = globulars
     2097152 = cloud shadows
     4194304 = galactic grid
     8388608 = ecliptic grid
     16777216 = horizontal grid
     33554432 = ecliptic
   • "&lm=" labelflags. The lm number is made by the sum of these individual flags that indicates the labels that are shown:
     1 = stars
     2 = planets
     4 = moons
     8 = constellations
     16 = galaxies
     32 = asteroids
     64 = vessels
     128 = localities
     256 = comets
     512 = nebulae
     1024 = open clusters
     2048 = local names for constellations
     4096 = dwarf planets
     8192 = minor moons
     16384 = globulars
   • "&tsrc=" ???
   • "&ver=3" for celestia 1.6 and above (at this time)

obs [optional]

The "observer" object on which this celestia:seturl() method takes effect.

If no observer is precised, the seturl applies to the current active view.

Notes:

1. celURLs for Celestia 1.6.0 and 1.6.1 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 1.6.0 and 1.6.1, 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 1.6.1 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

1.6.1 string celestia:geturl([observer:obs])

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 1.6.1 celestia:seturl() method.

Arguments:

obs [optional]

The "observer" object on which this celestia:geturl() method takes effect.

If no observer is precised, the celURL of the active observer will be returned.

Notes:

1. celURLs for Celestia 1.6.0 and 1.6.1 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 1.6.0 and 1.6.1, compared to earlier versions of Celestia.
2. To set a celURL from within a CELX script, the 1.6.1 celestia:seturl() method must be used.

Example:

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

Return to the celestia method index.

settextcolor

1.6.1 celestia:settextcolor(number:red, number:green, number:blue)

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

Arguments:

red

The red part of the RGB values of the color, must be between 0 and 1.

green

The green part of the RGB values of the color, must be between 0 and 1.

blue

The blue part of the RGB values of the color, must be between 0 and 1.

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 1.6.1 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

1.6.1 number, number, number celestia:gettextcolor()

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 1.6.1 celestia:settextcolor() method.

Example:

r, g, b = celestia:gettextcolor()

Return to the celestia method index.

runscript

1.6.1 celestia:runscript(string:scriptname)

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

Arguments:

scriptname

A string of text that contains the name of the celx or cel script to be launched.

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.