# Celx Scripting: Object
## object

An "Object" object in CELX does not refer to a general object (like Object in Java), but to a celestial object like a planet, star, spacecraft, location, etc..
Within a CELX script, the object methods can be used on an "object" object, by separating the "object" object from the object method with a semicolon.
The following methods can be used to obtain an "object" object:
* Using the celestia:find method.
* Using the celestia:getselection method.
* Using the celestia:getstar method.
* Using the 1.5.0 celestia:getdso method.
* Using the 1.5.0 observer:gettrackedobject method.
* Using the frame:getrefobject method.
* Using the frame:gettargetobject method.

## Methods

This chapter contains a list of all available object methods, which can be used on "object" objects.

### radius

number object:radius
Return the radius of the object in kilometers, as a number.
Notes:
* For ellipsoidal objects, the radius is the long semi-axes.
* For irregular objects, the radius is the longest axis of an aligned bounding box.
* The radius of an object can be set by using the 1.5.0 object:setradius method.
Example: Determine and print the radius of our Moon.
Return to the object method index.

### type

string object:type
Return the type of an object as a string. The type can be one of:
* planet
* moon
* asteroid
* comet
* spacecraft
* star
* location
* null (refers to the origin of the universal coordinate system)
* invisible (refers to a reference point)
* diffuse
* deepsky
** 1.5.0 galaxy
** 1.5.0 nebula
** 1.5.0 opencluster
* 1.6.0 surfacefeature
* 1.6.0 component
* 1.6.0 dwarfplanet
* 1.6.0 minormoon
Example: Determine and print the type of M33
Return to the object method index.

### spectraltype

string object:spectraltype
Return the spectral type of a star as a string.
If the object is NOT a star, nil will be returned.
Notes:
* The spectral type tells something about the spectral class, subcategory and luminosity class of stars.
* Celestia knows the following spectral classes for stars:
** The Morgan-Keenan spectral classes: O, B, A, F, G, K, M.
** The following rara/unusual classes: L, T, R, S, N, C, WC, WN, D (white dwarf), Q (neutron star), X (black hole).
* The spectral classes are further divided into subclasses by adding a numerical value between 0 and 9 to the letter.
* Celestia knows the following luminosity classes: I-a0, I-a, I-b, II, III, IV, V, VI, sd and D.
* The STC-Scripting Guide for Celestia contains a lot of additional information about spectral types of stars.
Example:
Return to the object method index.

### absmag

number object:absmag
Return the absolute magnitude of a star as a number.
If the object is NOT a star, nil will be returned.
Notes:
* The absolute magnitude of a star is a measure of its brightness it would have at a standardized distance of 10 parsec (~32.616 light years), so the absolute magnitude of a star will not change with distance.
Example:
Return to the object method index.

### name

string object:name
Return the name of the object as a string.
Example:
Return to the object method index.

### getinfo

table object:getinfo
Return a table with the available information on this object.
The exact contents of the table depend on the type of object. The information returned includes the information available via other object methods.
* For a star the table may include these keys:
** type
** name
** catalogNumber
** stellarClass
** absoluteMagnitude
** luminosity
** radius
** temperature
** rotationPeriod
** bolometricMagnitude
** orbitPeriod
*** orbitPeriod is only available in case of a star in a binary or multiple star system.
* For a body (e.g. a planet) the table may include these keys:
** type
** name
** oblateness
** albedo
** radius
** lifespanStart
** lifespanEnd
** rotationPeriod
** orbitPeriod
** atmosphereHeight
*** Only valid if body has an atmosphere.
** atmosphereCloudHeight
*** Only valid if body has an atmosphere.
** atmosphereCloudSpeed
*** Only valid if body has an atmosphere.
** parent
*** parent is an "object" object, which may be a body or a star (not printable)!
** hasRings
*** hasRings is a Boolean (not printable)!
** The following keys were initially mentioned to be valid for a body, but they return an invalid/nil value or cause a Fatal Error in 1.6.0 or crash in previous releases. When fixed, the documentation of these keys will be adjusted accordingly. Until then, skip the usage of the following keys:
*** mass
*** infoURL
*** rotationOffset
*** rotationEpoch
*** rotationObliquity
*** rotationAscendingNode
*** rotationPrecessionRate
* For a deepsky object, the table may include these keys:
** type
** name
** radius
** 1.5.0 catalogNumber
** 1.5.0 hubbleType
** 1.5.0 absoluteMagnitude
* For a location object, the table may include these keys:
** type
** name
** size
** importance
** infoURL
** featureType
** parent
*** parent is an "object" object, which may be a body (not printable)!
Notes:
* Mind the case sensitivity of celestia, regarding the keys for this object method !!!
* Some keys may not be available because they don't apply to the body in question (e.g. it doesn't have an atmosphere etc.), or contain no useful data. Those keys contain a nil value and can for instance not be printed.
Example:
Return to the object method index.

### mark

object:mark([string:color] [, string:symbolname] [, number:size] [, number:opacity] [, string:label] [, boolean occludable])
Place a marker on an object.
Arguments:

#### color [optional]

    The color to be used for the marker. Default is "#00ff00" (lime).
   * Either use HTML-style hex color strings such as "#ff0000" (red),
   * Or use some predefined color names like "lime", "red", "green", "yellow", "blue", "orange", "white", "black", "brown", "cyan", "gold", "silver" etc.. If the predefined color name does not exist, the result will be the default "lime" marker. A list of supported color names can be found on the HTML Color Names page.

#### symbolname [optional]

    Name of symbol to be used for the marker. Default is "diamond". The available marker symbols are:
   * diamond
   * triangle
   * square
   * plus
   * x
   * 1.5.0 filledsquare
   * 1.5.0 leftarrow
   * 1.5.0 rightarrow
   * 1.5.0 uparrow
   * 1.5.0 downarrow
   * 1.5.0 circle
   * 1.5.0 disk

#### size [optional]

    Size of the marker in pixels. Default is 10.
    If size is smaller than 1, size will be adjusted to 1.
    If size is greater than 10000, size will be adjusted to 10000.

#### opacity [optional]

    A value from 0 to 1 that gives the opacity of marker. Default is 1.0, completely opaque.
    Negative values or values greater than 1 be adjusted to the nearest valid value (0 or 1).

#### 1.5.0 label [optional]

    A text label for the marker. The default is the empty string, indicating no label.

#### 1.6.0 occludable [optional]

    A boolean flag indicating whether the marker will be hidden by objects in front of it. The default is true, the marker will be hidden by objects in front of it.
Notes:
* You can also use the celestia:mark method instead, but that method has much less possibilities.
* Markers are only shown when Celestia's markers renderflag option is turned on, using the celestia:setrenderflags method.
* If you want to change a marker on an object, you have to unmark it first, using the celestia:unmark or object:unmark method and then mark it again with the changed marker.`
* Although all arguments of this method are optional, if you are using an argument that is placed further in the argument list, you need to give the previous arguments to this method too.
Example-1: Place a blue circle marker on Sirius
Example-2: Place a large red 'you are here' arrow on the Earth
Return to the object method index.

### unmark

object:unmark
Remove marker from the object.
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 celestia:unmark method instead.
Example: Find, center end mark star Polaris with a blinking marker for 10 seconds
Return to the object method index.

### getposition

position object:getposition([number:time])
Return the position of the object at the specified time in universal coordinates, as a "position" object.
Arguments:

#### time [optional]

    The time used to determine the position of this object. Default is the current simulation time, if not specified.
Notes:
* Celestia's native coordinate system is based on the J2000 ecliptic, but it's rotated by 90 degrees from the conventional definition.
* Position components (X,Y,Z) in Celestia are stored in millionths of a light year. So when you want your positions defined in km or miles, you have to convert these positions. Therefore, you can use a constant, which must be initialized first within your script:
** From millionths of a light year to km, use a constant uly_to_km = 9460730.4725808.
** From millionths of a light year to miles, use a constant uly_to_mls = 5912956.5453630.
* Next you can convert millionths of a light year to km or miles as follows:
** km = number:millionths_of_a_light_year * uly_to_km
** miles = number:millionths_of_a_light_year * 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: The function retrieves the position of the object 'obj' relative to another object 'center' at time t. The position is in units of kilometers and is in the standard J2000 ecliptic coordinate system (where the z-axis is the northward pointing normal to the J2000 ecliptic plane, and the x axis is out along the ascending node of the ecliptic plane and Earth equator.)
Return to the object method index.

### getchildren

table object:getchildren
Return a table containing all children of this object, as "object" objects.
Notes:
* 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: Goto an overview position on our Solar System and increase the size of all planets for about 20 seconds. Then reset to normal planet sizes again.
Return to the object method index.

### preloadtexture

object:preloadtexture
Load all textures for the object from disk into the memory of your graphic card.
Notes:
* Using this method can be useful for producing smoother running scripts, as preloading textures will reduce delays when approaching an object.
Example: Preload the texture of Titan, before going to this moon of Saturn.
Return to the object method index.

### setradius

1.5.0 object:setradius(number:radius)
Set the new radius of the object.
Arguments:

#### radius

    The new radius of the object, as a number in kilometers.
Notes:
* The actual radius of an object can be obtained by using the object:radius method.
Example1: Goto a position in the Earth–Moon system and make both the Moon and Earth ten times their actual size for about 10 seconds. Then reset the Moon and Earth to their original sizes again.
Example2: Increase the size of Planets for an educational view of our solar system.
Return to the object method index.

### localname

1.5.0 string object:localname
Return the localized name of the object as a string.
Return "?" if there is no localized object name available.
Notes:
* From version 1.5.0, Celestia fully supports internationalization. For each language, all the strings used in the program can be translated and one of them is the name of the object.
* "Sol", along with the name of all other stars and many DSOs are not localized.
Example: Display the localized name of the current selection.
Return to the object method index.

### visible

1.6.0 boolean object:visible
Return a boolean, indicating whether or not the object is visible.
* true if the object is visible.
* false if the object is NOT visible.
Notes:
* The 1.6.0 object:setvisible method can be used to turn on/off the object visibility.
* Objects within the Solar System are only shown when Celestia's planets renderflag option is turned on, by using the celestia:setrenderflags method. The actual setting of the planets renderflag option does NOT influence the result of this object:visible method.
* A star will always stay visible, regardless the usage of this method. The rendering of all stars can only be turned on/off, by using the celestia:setrenderflags method.
Example: If Earth is visible, make it invisible for 5 seconds and vice versa.
Return to the object method index.

### setvisible

1.6.0 object:setvisible(boolean:visible)
Set the object visibility flag.
Arguments:

#### visible

    Boolean, indicating whether or not the object is set to visible.
   * true: The object will become visible.
   * false: The object will become invisible.
Notes:
* The 1.6.0 object:visible method can be used to determine whether or not an object is visible.
* Objects within the Solar System are only shown when Celestia's planets renderflag option is turned on, by using the celestia:setrenderflags method.
* A star will always stay visible, regardless the usage of this method. The rendering of all stars can only be turned on/off, by using the celestia:setrenderflags method.
Example: Toggle object visibility for specified object by using the [Shift + T] keys on the keyboard. Press the [Esc] key on the keyboard to terminate the example.
Return to the object method index.

### setorbitcolor

1.6.0 object:setorbitcolor(number:red, number:green, number:blue)
Set a specific orbit color for this object.
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:
* Orbits are only shown when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags method.
* Specific orbits are only shown when Celestia's orbitflags are turned on, using the celestia:setorbitflags method.
* The visibility of the orbit of this object can also be set by using the 1.6.0 object:setorbitvisibility method.
* The specified orbit color for this object will only be shown if the default orbit color for this object may be overridden, as set by using the 1.6.0 object:setorbitcoloroverridden method.
* As long as the object is also the current selected object, the orbit will be displayed in the red color!
Example: Set the orbit color of Earth to yellow.
Return to the object method index.

### orbitcoloroverridden

1.6.0 boolean object:orbitcoloroverridden
Return a boolean, indicating whether or not the object orbit color may be overridden.
* true if the object orbit color is overridden.
* false if the object orbit color is NOT overridden.
Notes:
* To set whether or not the default orbit color of an object may be overridden, the 1.6.0 object:setorbitcoloroverridden method can be used.
Example: If orbit color of Earth may be overridden, set orbit color of Earth tot aqua. Else print a message.
Return to the object method index.

### setorbitcoloroverridden

1.6.0 object:setorbitcoloroverridden(boolean:overridden)
Determine whether or not the default orbit color of the object will be replaced with the color set in the 1.6.0 object:setorbitcolor method.
Arguments:

#### overridden

    Boolean, indicating whether or not the default orbit color of the object will be replaced:
   * true: The default orbit color of the object will be replaced.
   * false: The default orbit color of the object will NOT be replaced.
Notes:
* Orbits are only shown when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags method.
* Specific orbits are only shown when Celestia's orbitflags are turned on, using the celestia:setorbitflags method.
* The visibility of the orbit of this object can also be set by using the 1.6.0 object:setorbitvisibility method.
* As long as the object is also the current selected object, the orbit will be displayed in the red color!
Example: Set the orbit color of Earth to yellow and default alternately.
Return to the object method index.

### orbitvisibility

1.6.0 string object:orbitvisibility
Return a string with the object's orbit visibility setting. The string will be one of:
* "normal": Visibility is based on the orbit flags settings (see celestia:setorbitflags method).
* "always": Visible whenever any orbits are turned on (see celestia:setrenderflags method).
* "never": The object's orbit is never shown, regardless the settings of the celestia:setrenderflags and celestia:setorbitflags methods.
Notes:
* The object:setorbitvisibility method can be used to set the orbit visibility policy for this object.
* Orbits are only shown when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags method. The actual setting of the orbits renderflag option does NOT influence the result of this object:orbitvisibility method.
Example:
Return to the object method index.

### setorbitvisibility

1.6.0 object:setorbitvisibility(string:visibility)
Set the orbit visibility policy for this object.
Arguments:

#### visibility

    A string describing the orbit visibility policy for this object. Must be one of:
   * "normal" Visibility is based on the orbit flags settings (see celestia:setorbitflags method).
   * "always" Visible whenever any orbits are turned on (see celestia:setrenderflags method).
   * "never" The object's orbit is never shown, regardless the settings of the celestia:setrenderflags and (celestia:setorbitflags methods.
Notes:
* The object:orbitvisibility method can be used to obtain the current orbit visibility policy for this object.
* Orbits are only shown when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags method.
Example:
Return to the object method index.

### addreferencemark

1.6.0 object:addreferencemark(table:refmark)
Display a variety of informational graphics for the object, similar to the online Reference Vectors options in the pop-up menu, when pointing with your mouse on a celestial object and pressing the right mouse button.
Arguments:

#### refmark

    A table which contains the referencemark elements as keys. Valid referencemark keys are:
   * type: A string that specifies the type of the informational graphic. Strings which can be specified as values for the table element "type" are:
   ** "body axes"
   ** "frame axes"
   ** "sun direction"
   ** "velocity vector"
   ** "spin vector"
   ** "body to body direction"
   ** "visible region"
   ** "planetographic grid"
   * size: A number that specifies the size in points of the informational graphic (optional). Be aware of the size of the object as displayed on the screen, to use the appropriate size value here, or simply skip this parameter to let the system determine the default size of the graphic. This number does not affect the graphics of type "visible region" and "planetographic grid".
   * opacity: Number between 0.0 and 1.0 that specifies the opacity of the informational graphic (optional, default is 1.0).
   ** 0.0 means the graphic is invisible.
   ** 1.0 means the graphic is shown with 100% opacity.
   * color: String that specifies the color of the informational graphic (optional).
   ** Either use HTML-style hex color strings such as "#ff0000" (red),
   ** Or use some predefined color names like "lime", "red", "green", "yellow", "blue", "orange", "white", "black", "brown", "cyan", "gold", "silver" etc.. If the predefined color name does not exist, the result will be the default "lime" marker. A list of supported color names can be found on the HTML Color Names page.
   * tag: String that specifies the identifying name of the informational graphic (optional). When used, this tag must also be used in the 1.6.0 object:removereferencemark method, to identify the correct graphic to be removed.
   * target: Object that specifies the second object involved in the informational graphic, when using the "body to body direction" or "visible region" graphic type.
Notes:
* The refmark.type strings are NOT case sensitive: "Body Axes" is considered to be the same as "body axes".
* Be aware that not all referencemark types can be turned on/off online with your mouse. When such referencemark types are not removed from within the CELX script, the enduser stays looking at the referencemark. Without the knowledge of CELX scripting such endusers are not able to remove the referencemark other than restarting Celestia !!!
Example: Goto the Moon and show which region on the Moon is visible from Earth.
Or shorter:
Return to the object method index.

### removereferencemark

1.6.0 object:removereferencemark(string:tag) or 1.6.0 object:removereferencemark(string:type)
Remove the informational graphics for the specified object, that are previously displayed using the object:addreferencemark method.
Arguments:

#### tag

    A string specifying the identifying name of the reference mark to be removed. When the tag parameter is used in the object:addreferencemark method, this removereferencemark method only works by using the same string:tag here as an argument to this method.

#### type

    A string specifying the type of the reference mark to be removed. When the tag parameter is not used in the object:addreferencemark method, this removereferencemark method also works by using the corresponding string:type here as an argument to this method.
Notes:
* Multiple reference marks can be removed at once by giving multiple string arguments to this method.
Example: Show Moon visible region from Earth and Earth direction during about 1 month simulation time.
Return to the object method index.

### catalognumber

1.6.0 number object:catalognumber(string:catalog)
Return the catalog number for a star in the specified catalog, as a number.
Arguments:

#### catalog

    String that specifies the catalog from which the number must be returned. Must be one of the currently supported catalogs:
   * "HD": Henry Draper Catalog.
   * "SAO": Smithsonian Astrophysical Observatory Catalog.
   * "HIP": Hipparcos Catalog.
Notes:
* If the object is NOT a star, or the catalog string is NOT valid, or the star is NOT present in the catalog, nil will be returned.
Example: Print the HIP, HD and SAO catalog numbers of Polaris.
Return to the object method index.

### locations

1.6.0 iterator object:locations
Return an iterator over all the locations associated with the object.
The object methods can be used on this itarator.
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:
* Only Solar System bodies have locations. For all other object types, this method will return an empty iterator.
Example: Print all location names of the current selection to the Celestia log file. You can turn the display of the log layer on and off using the tilde [~] key on the keyboard. Up to ten lines are displayed on the screen, and you can scroll back and forward using the up/down arrow and page up/down keys. Mind that the size of the log is limited by the celestia.cfg file.
Return to the object method index.

### bodyfixedframe

1.6.0 frame object:bodyfixedframe
Return the body-fixed frame for this object as a "frame" object.
Notes:
* 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: Get the body-fixed frame of the Earth
Return to the object method index.

### equatorialframe

1.6.0 frame object:equatorialframe
Return the equatorial frame for this object as a "frame" object.
Notes:
* 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: Get the equatorial frame of the Earth
Return to the object method index.

### orbitframe

1.6.0 frame object:orbitframe([number:time])
Return the frame in which the orbit for an object is defined at a particular time as a "frame" object.
Arguments:

#### time

    The time used to return the frame, as a TDB (Barycentric Dynamical Time) Julian date number. If time isn't specified, the current simulation time is assumed.
Notes:
* 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 positions of stars and deep sky objects are always defined in the universal frame.
* 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: Get the orbit frame of the Earth
Return to the object method index.

### bodyframe

1.6.0 frame object:bodyframe([number:time])
Return the frame in which the orientation for an object is defined at a particular time as a "frame" object.
Arguments:

#### time

    The time used to return the frame, as a TDB (Barycentric Dynamical Time) Julian date number. If time isn't specified, the current simulation time is assumed.
Notes:
* 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 positions of stars and deep sky objects are always defined in the universal frame.
* 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: Get the current body frame for the International Space Station.
Return to the object method index.

### getphase

1.6.0 phase object:getphase([number:time])
Get the active timeline phase for this object at the specified time, as a "phase" object.
Arguments:

#### time [optional]

    Number, giving the time as a TDB Julian date, at which the active timeline phase must be obtained. If no time is specified, the current simulation time is used.
Notes:
* This method returns nil if the object is not a solar system body, or if the time lies outside the range covered by the object's timeline.
* 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.
* The phase methods can be used on a "phase" object.
Example: Get the timeline phase for Cassini at midnight January 1, 2000 UTC
Return to the object method index.

### phases

1.6.0 iterator object:phases
Return an iterator over all the phases in an object's timeline.
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:
* Only solar system bodies have a timeline; for all other object types, this method will return an empty iterator.
* The phases in a timeline are always sorted from earliest to latest, and always cover a continuous span of time.
* The phase methods can be used on this itarator.
Example: Copy all of the current selected object phases into the array timeline.
Return to the object method index.