# 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:
* 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:
Example-2: Print on more than 1 line and use text and variables:
Example-3: Print text and formatted variables:
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:
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:
* 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
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:
* Multiple features can be enabled at once by giving multiple arguments to this method, separated by a comma.
Example: Disable the rendering of 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:
* 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:
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
or shorter:
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:
* 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
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:
* 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
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:
* 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.
* To enable or disable a specific labelflag, the celestia:setlabelflags method can be used.
Example:
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:
* 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
or shorter:
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:
* To enable or disable the rendering of specific orbits, the celestia:setorbitflags method can be used.
Example:
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:
* 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:
or shorter:
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:
* To set the brightness level of ambient light, the celestia:setambient method can be used.
Example:
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:
* To obtain the current brightness level of ambient light, the celestia:getambient method can be used.
Example:
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:
* To set the faintest visible magnitude of stars or the faintest magnitude of stars at 45°, the celestia:setfaintestvisible method can be used.
Example:
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:
* 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.
* 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
Example-2: Set the faintest visible magnitude of stars to 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:
* The actual screen dimensions in pixels can be obtained using the celestia:getscreendimension method.
* To set minimum size for an orbit to be rendered, the celestia:setminorbitsize method can be used.
Example:
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:
* 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).
* Screen dimensions can differ on different computers, so can be the effect of this method.
* 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
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:
* To set the furthest distance at which Celestia will display stars, the celestia:setstardistancelimit method can be used.
Example:
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:
* 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
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:
* 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.
* 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.
* The celestia:setminfeaturesize method can be used to set the minimum size for locations to be labeled.
* The observer:getlocationflags can be used to obtain a table with keys that indicate whether a specific locationflag is enabled or disabled.
Example:
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:
* 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.
* The sizes of defined locations are determined in the locations files that are stored within the Celestia subdirectories.
* The celestia:getminfeaturesize method can be used to obtain the current minimum size for locations to be labeled.
* 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
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:
* The celestia:setstarstyle method can be used to set the rendering style for stars.
Example:
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:
* The celestia:getstarstyle method can be used to obtain the current rendering style for stars.
Example: The uncommented line sets the starstyle
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:
* 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.
* 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:
Return to the celestia method index.

### getselection

object celestia:getselection
Return the current selection in a CELX "object" object.
Notes:
* 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.
* 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
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
Or shorter
Return to the celestia method index.

### mark

celestia:mark(object:obj)
Mark the specified object.
Arguments:

#### obj

    The object to be marked.
Notes:
* You may want to use the object:mark method instead, because it has more possibilities.
* 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
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:
* 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.
* You may want to use the object:unmark method instead.
Example: Find, center end mark star Polaris with a blinking marker for 10 seconds
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:
* 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
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:
* The simulation time can be set by using the celestia:settime method.
* To get the current system time instead of the current simulation time, the 1.6.0 celestia:getsystemtime method should be used instead.
* 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.
* To convert between UTC and TDB times, you can use the 1.5.0 celestia:utctotdb and 1.5.0 celestia:tdbtoutc methods.
* To convert between normal calender dates and julian days, you can use the celestia:tojulianday and celestia:fromjulianday methods.
Example:
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:
* The current simulation time can be obtained by using the celestia:gettime or observer:gettime method.
* 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.
* To convert between UTC and TDB times, you can use the 1.5.0 celestia:utctotdb and 1.5.0 celestia:tdbtoutc methods.
* 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
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:
* The multiplier (speed) at which time changes can be set by using the celestia:settimescale method.
Example:
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:
* 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"
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:
* This method can be useful for timing purposes.
Example: Print the elapsed script time on the screen.
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:
* 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.
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:
* 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.
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:
* 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.
* 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.
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.
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:
* 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.
* 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.
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.
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:
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:
* 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.
* 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
* A CELX "vector" object is a geometric object that has both a length and direction [X, Y, Z] in a 3 dimensional coordinate system.
* 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.
Example-2: Make a vector, pointing in the X-direction with length 5000 km.
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:
* 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.
* 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
* 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.
* 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.
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:
* The string-values can be found after the "x=", "y=" and "z=" and before the next following "&" in a celURL.
* 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.
* 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
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:
* 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).
* 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.
* 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).
* 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).
Example-2: Rotate the current camera view by 360 degrees during about 10 seconds.
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:
* The number-values can be found after the "ow=", "ox=", "oy=" and "oz=" and before the next following "&" in a celURL.
* 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.
* 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).
* 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
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:
* In Celestia version 1.6.0, the name bodyfixed will replace planetographic, although for compatibility reasons, the name planetographic will continue to work.
* 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.
* 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:
Example-2: The following example selects the Moon, then sets the active Coordinate System to CHASE and goes to the Moon:
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.
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:
* 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.
* 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).
* 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.
* 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:
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:
* 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.
* 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:
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:
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:
* 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.
* 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.
* 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 :-(
* 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.
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:
* 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.
* 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.
Return to the celestia method index.

### getstarcount

number celestia:getstarcount
Return the total number of stars in the star catalogue, as a number.
Example:
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:
* 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.
* 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.
* 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.
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:
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:
* 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.
* 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.
* 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.
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:
* referencing one particular element in an object collection (called element access),
* 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:
* 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:
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:
* referencing one particular element in an object collection (called element access),
* 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:
* 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:
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:
* 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.
* 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.
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.
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:
* 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.
* 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.
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:
* 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.
* 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).
* The alt-azimuth mode can be set, using the 1.5.0 celestia:setaltazimuthmode method.
Example:
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:
* 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.
* 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).
* 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.
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:
* To turn on/of the rendering of the different overlay elements, the 1.5.0 celestia:setoverlayelements method can be used.
Example:
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:
* 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.
* 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.
Or shorter
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:
* Galaxies can be turned on/off using the celestia:setrenderflags method.
* The level of Galaxy light gain (brightness) can be set by using the 1.5.0 celestia:setgalaxylightgain method.
Example:
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:
* Galaxies can be turned on/off using the celestia:setrenderflags method.
* The current level of Galaxy light gain (brightness) can be obtained by using the 1.5.0 celestia:getgalaxylightgain method.
* 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..
* 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.
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:
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:
* This method is very useful for debugging Lua/CELX scripts.
* 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.
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:
* If no event handler is registered, or if the registered event handler returns false, Celestia reverts to the default behavior for that event.
* The binding between the event type and event handler will remain until either:
** Celestia is restarted
** A new binding is specified between the event type and another event handler (possibly in another script)
** 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.
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.
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:
* The current colors of specific labels can be obtained by using the 1.6.0 celestia:getlabelcolor method.
* 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.
Example2: Alternate Label Colors from ElChristou.
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:
* The current colors of specific lines can be obtained by using the 1.6.0 celestia:getlinecolor method.
* Specific orbits can be turned on/off using the celestia:setorbitflags method.
* Orbits, Grids, Constellations and Boundaries can be turned on/off using the celestia:setrenderflags method.
* 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.
Example2: Alternate Line Colors from ElChristou.
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:
* The colors of specific labels can be set by using the 1.5.0 celestia:setlabelcolor method.
* Specific labels can be turned on/off using the celestia:showlabel and celestia:hidelabel or celestia:setlabelflags method.
Example:
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:
* The colors of specific lines can be set by using the 1.5.0 celestia:setlinecolor method.
* Specific orbits can be turned on/off using the celestia:setorbitflags method.
* Orbits, Grids, Constellations and Boundaries can be turned on/off using the celestia:setrenderflags method.
* 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:
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:
* To get the current simulation time instead of the current system time, the celestia:gettime or observer:gettime method should be used instead.
* 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.
* To convert between UTC and TDB times, you can use the 1.5.0 celestia:utctotdb and 1.5.0 celestia:tdbtoutc methods.
* To convert between normal calender dates and julian days, you can use the celestia:tojulianday and celestia:fromjulianday methods.
Example:
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:
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:
* 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.
* Besides the rendering of the constellations, this celestia:showconstellations method also takes effect on the constellation names.
Example-1: Show Virgo and Libra only
Example-2: Show zodiacal constellations only
Example-3: Show all constellations
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:
* 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.
* 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
Example-2: Hide all constellations, except Virgo and 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:
* Constellations can be turned on/off using the celestia:setrenderflags method.
* To render specific constellations only, you can use the celestia:showconstellations and celestia:hideconstellations methods.
* 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
Example-2: Show all zodiacal constellations in yellow
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:
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.
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:
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.
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:
* 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.
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:
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:
   * The string always start with "cel://";
   * 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".
   * Date in the format: yyyy-mm-dd
   ** The year may be preceded by a "-" character, to indicate a year BC.
   * 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.
   * 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")
   * 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")
   * 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:
* 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.
* 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.
* 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.
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:
* 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.
* To set a celURL from within a CELX script, the 1.6.1 celestia:seturl method must be used.
Example:
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:
* 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.
* It is not possible to change the text color within the same text message.
* 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
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:
* The colors of text messages can be set by using the 1.6.1 celestia:settextcolor method.
Example:
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:
* This method uses relative script names.
* In a celx script, this method should be always followed by a wait(0) command.
* Using this method you can do a "chain" of scripts.
* 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.
Example 2: The script "myscriptname.celx" is located in a different directory named "myDir2".
Return to the celestia method index.