Celestia/Celx Scripting/CELX Lua Methods/Celx object

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:

1. For ellipsoidal objects, the radius is the long semi-axes.
2. For irregular objects, the radius is the longest axis of an aligned bounding box.
3. 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.

moon = celestia:find("Sol/Earth/Moon")
rmoon = moon:radius()
celestia:print("The radius of our Moon is: " .. rmoon .. " km.", 5.0, -1, -1, 2, 4)
wait(5.0)

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

m33 = celestia:find("M 33")
type = m33:type()
celestia:print("The type of M33 is: " .. type, 5.0, -1, -1, 2, 4)
wait(5.0)

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:

1. The spectral type tells something about the spectral class, subcategory and luminosity class of stars.
2. 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).
3. The spectral classes are further divided into subclasses by adding a numerical value between 0 and 9 to the letter.
4. Celestia knows the following luminosity classes: I-a0, I-a, I-b, II, III, IV, V, VI, sd and D.
5. The STC-Scripting Guide for Celestia contains a lot of additional information about spectral types of stars.

Example:

sun = celestia:find("Sol")
spectraltype = sun:spectraltype()
celestia:print("Our own Sun is of spectraltype: " .. spectraltype, 5.0, -1, -1, 2, 4)
wait(5.0)

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:

1. 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:

redgiant = celestia:find("Betelgeuse")
celestia:select(redgiant)
obs = celestia:getobserver()
obs:goto(redgiant)
magnitude = redgiant:absmag()
celestia:print("The absolute magnitude of Redgiant Betelgeuse is: " .. magnitude, 5.0, -1, -1, 2, 4)
wait(5.0)

Return to the object method index.

name

string object:name()

Return the name of the object as a string.

Example:

polestar = celestia:find("Polaris")
celestia:select(polestar)
obs = celestia:getobserver()
obs:goto(polestar)
starname = polestar:name()
celestia:print("The name of our current Northpole star is: " .. starname, 5.0, -1, -1, 2, 4)
wait(5.0)

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.

1. 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.
2. 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
3. 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
4. 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:

1. Mind the case sensitivity of celestia, regarding the keys for this object method !!!
2. 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:

planet = celestia:find("Sol/Venus")
celestia:select(planet)
obs = celestia:getobserver()
obs:goto(planet)
name = planet:name()
table = planet:getinfo()
celestia:print("The available information on " .. name .. ":\n" ..
               "Type: " .. table.type .. "\n" ..
               "Name: " .. table.name .. "\n" ..
               "Oblateness: " .. table.oblateness .. "\n" ..
               "Albedo: " .. table.albedo .. "\n" ..
               "Radius: " .. table.radius .. "\n" ..
               "Lifespan Start: " .. table.lifespanStart .. "\n" ..
               "Lifespan End: " .. table.lifespanEnd .. "\n" ..
               "Rotation Period: " .. table.rotationPeriod .. "\n" ..
               "orbit Period: " .. table.orbitPeriod .. "\n" ..
               "atmosphere Height: " .. table.atmosphereHeight .. "\n" ..
               "atmosphere Cloud Height: " .. table.atmosphereCloudHeight .. "\n" ..
               "atmosphere Cloud Speed: " .. table.atmosphereCloudSpeed, 30.0, -1, -1, 2, 25)
wait(30.0)

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:

1. You can also use the celestia:mark() method instead, but that method has much less possibilities.
2. Markers are only shown when Celestia's markers renderflag option is turned on, using the celestia:setrenderflags() method.
3. 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.`
4. 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

celestia:setrenderflags{markers = true}
obs = celestia:getobserver()
sirius = celestia:find("Sirius")
sirius:mark("blue", "circle", 15)
obs:center(sirius)
wait(10.0)
celestia:unmarkall()
celestia:setrenderflags{markers = false}

Example-2:
Place a large red 'you are here' arrow on the Earth

celestia:setrenderflags{markers = true}
obs = celestia:getobserver()
home = celestia:find("Sol/Earth")
home:mark("#ff0000", "leftarrow", 20, 1, "You are here")
obs:center(home)
wait(10.0)
celestia:unmarkall()
celestia:setrenderflags{markers = false}

Return to the object method index.

unmark

object:unmark()

Remove marker from the object.

Notes:

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

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

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

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:

1. Celestia's native coordinate system is based on the J2000 ecliptic, but it's rotated by 90 degrees from the conventional definition.
2. 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.
3. 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
4. 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.
5. 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.)

function position_ecl_j2000(obj, center, t)
   local uly_to_km = 9460730.4725808
   local p0 = center:getposition(t)
   local p = obj:getposition(t)
   -- Convert to kilometers
   local v = (p - p0) * uly_to_km
   -- Convert from Celestia's internal coordinate system
   return celestia:newvector(v.x, -v.z, v.y)
end

-- Retrieve the heliocentric ecliptic coordinates of Earth at the current simulation time
sun = celestia:find("Sun")
earth = celestia:find("Sun/Earth")
vec = position_ecl_j2000(earth, sun, celestia:gettime())

Return to the object method index.

getchildren

table object:getchildren()

Return a table containing all children of this object, as "object" objects.

Notes:

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

-- Render planets and planet orbits and show planet labels
celestia:setorbitflags{ Planet = true }
celestia:setrenderflags{ planets = true, orbits = true, smoothlines = true }
celestia:setlabelflags{ planets = true }
celestia:setminorbitsize(3)
-- Find and select our Sun and goto position to have a good overview on our Solar System 
sol = celestia:find("Sol")
celestia:select(sol)
obs = celestia:getobserver()
obs:gotolonglat(sol, 0, math.rad(70), 1.3e10, 1.0)
wait(1.0)
-- Return all children of our Sun in table sol_children
sol_children = sol:getchildren()
-- Create table to save original size of all planets 
iRadius = {}
for k, child in pairs(sol_children) do
   if child:type() == "planet" then
      -- Save original size of planet
      iRadius[k] = child:radius()
      -- Increase planet size
      child:setradius(iRadius[k] * 4e3)
   end
end
-- Have this overview for the specified wait time
wait(20.0)
-- Reset original size of all planets
sol_children = sol:getchildren()
for k, child in pairs(sol_children) do
   if child:type() == "planet" then
      child:setradius(iRadius[k])
   end
end
-- Clear rendering of orbits and hide planet labels
celestia:setrenderflags{ orbits = false }
celestia:setlabelflags{ planets = false }

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:

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

titan = celestia:find("Sol/Saturn/Titan")
titan:preloadtexture()
celestia:select(titan)
obs = celestia:getobserver()
obs:gotodistance(titan, 20000, 5.0)
wait(5.0)

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:

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

obs = celestia:getobserver()
-- Set frame of reference to "universal".
obs:setframe(celestia:newframe( "universal"))
-- Find the actual position of the Earth.
earth = celestia:find("Sol/Earth")
earthpos = earth:getposition()
-- Find the actual position of the Moon.
moon = celestia:find("Sol/Earth/Moon")
moonpos = moon:getposition()
-- Calculate new position halfway Earth - Moon to look at.
newpos1 = earthpos + 0.5 * (moonpos - earthpos)
-- Calculate new position to goto
newpos2 = newpos1 + celestia:newvector(0, 0.2, 0)
obs:goto(newpos2, 1.0)
wait(1.0)
obs:lookat(newpos1, celestia:newvector(0, 0, 1))
-- save, set and reset the radius of the Moon and Earth
earthradius = earth:radius()
moonradius = moon:radius()
earth:setradius(10*earthradius)
moon:setradius(10*moonradius)
wait(10.0)
moon:setradius(moonradius)
earth:setradius(earthradius)

Example2:
Increase the size of Planets for an educational view of our solar system.

-- Callback to restore original size of Planets.
function celestia_cleanup_callback()
   sol_children = sol:getchildren()
   for k, child in pairs(sol_children) do
      if child:type() == "planet" then
         child:setradius(iRadius[k])
      end
   end
end
-- Render planets, orbits and planet labels
celestia:setorbitflags{ Planet = true }
celestia:setrenderflags{ planets = true, orbits = true, smoothlines = true }
celestia:setlabelflags{ planets = true }
celestia:setminorbitsize(3)
-- Goto position above the Solar System
sol = celestia:find("Sol")
celestia:select(sol)
obs = celestia:getobserver()
obs:gotolonglat(sol, 0, 70, 1e10, 5)
wait(5)
-- Enlarge the planets
sol_children = {}
iRadius = {}
sol_children = sol:getchildren()
for k, child in pairs(sol_children) do
   if child:type() == "planet" then
      iRadius[k] = child:radius()
      child:setradius(iRadius[k] * 4000)
   end
end
while true do
   wait(0)
end

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:

1. 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.
2. "Sol", along with the name of all other stars and many DSOs are not localized.

Example:
Display the localized name of the current selection.

while true do
   sel = celestia:getselection()
   name = sel:name()
   lname = sel:localname()
   celestia:print("The localized name of " .. name .. " is: " .. lname, 1.0, -1, -1, 2, 4)
   wait(0)
end

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:

1. The 1.6.0 object:setvisible() method can be used to turn on/off the object visibility.
2. 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.
3. 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.

obj = celestia:find("Sol/Earth")
obj_rad = obj:radius()
obs = celestia:getobserver()
obs:gotodistance(obj, 4*obj_rad, 1.0)
wait(1.0)
obj_visible = obj:visible()
if obj_visible then
   celestia:print(obj:localname().." set to invisible for 5 seconds", 5.0, -1, -1, 2, 4)
   obj:setvisible(false)
   wait(5.0)
   obj:setvisible(true)
else
   celestia:print(obj:localname().." set to visible for 5 seconds", 5.0, -1, -1, 2, 4)
   obj:setvisible(true)
   wait(5.0)
   obj:setvisible(false)
end

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:

1. The 1.6.0 object:visible() method can be used to determine whether or not an object is visible.
2. Objects within the Solar System are only shown when Celestia's planets renderflag option is turned on, by using the celestia:setrenderflags() method.
3. 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.

-- Edit the next line to define another object
obj = celestia:find("Sol/Earth")
--
obj_rad = obj:radius()
obs = celestia:getobserver()
obs:gotodistance(obj, 4*obj_rad, 1.0)
wait(1.0)

function toggleObjVisibility()
   obj:setvisible(not obj:visible())
   if obj:visible() then
      celestia:print(obj:localname().." visible")
   else
      celestia:print(obj:localname().." invisible")
   end
end

-- Edit the next line to define another key than the [T] key
keyhandlers = { T = toggleObjVisibility }

function handlekey(k) 
   handler = keyhandlers[k.char] 
   if handler ~= nil then 
      handler()
      return true
   else
      return false
   end 
end 

celestia:registereventhandler("key", handlekey)

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:

1. Orbits are only shown when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags() method.
2. Specific orbits are only shown when Celestia's orbitflags are turned on, using the celestia:setorbitflags() method.
3. The visibility of the orbit of this object can also be set by using the 1.6.0 object:setorbitvisibility() method.
4. 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.
5. 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.

-- Render planets and planet orbits and show planet labels
celestia:setorbitflags{ Planet = true }
celestia:setrenderflags{ planets = true, orbits = true, smoothlines = true }
celestia:setlabelflags{ planets = true }
celestia:setminorbitsize(3)
-- Find and select our Sun and goto position to have a good overview on our Solar System 
sol = celestia:find("Sol")
celestia:select(sol)
obs = celestia:getobserver()
obs:gotolonglat(sol, 0, math.rad(70), 7e9, 1.0)
wait(1.0)
earth = celestia:find("Sol/Earth")
earth:setorbitcolor(1, 1, 0)
earth:setorbitcoloroverridden(true)

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:

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

earth = celestia:find("Sol/Earth")
obs = celestia:getobserver()
-- Uncomment the next line if you want colors to be overridden
-- earth:setorbitcoloroverridden(true)
obs:gotolonglat(earth, 0, math.rad(20), 5e8, 1.0)
wait(1.0)
celestia:select(nil)
celestia:setorbitflags{ Planet = true }
celestia:setrenderflags{ planets = true, orbits = true, smoothlines = true }
earth_orbitcolor_yn = earth:orbitcoloroverridden()
if earth_orbitcolor_yn then
   earth:setorbitcolor(0, 1, 1)
else
   celestia:print("The orbit color of Earth may NOT be overridden", 5.0, -1, -1, 2, 4)
   wait(5.0)
end

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:

1. Orbits are only shown when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags() method.
2. Specific orbits are only shown when Celestia's orbitflags are turned on, using the celestia:setorbitflags() method.
3. The visibility of the orbit of this object can also be set by using the 1.6.0 object:setorbitvisibility() method.
4. 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.

-- Render planets and planet orbits and show planet labels
celestia:setorbitflags{ Planet = true }
celestia:setrenderflags{ planets = true, orbits = true, smoothlines = true }
celestia:setlabelflags{ planets = true }
celestia:setminorbitsize(3)
-- Find and select our Sun and goto position to have a good overview on our Solar System 
sol = celestia:find("Sol")
celestia:select(sol)
obs = celestia:getobserver()
obs:gotolonglat(sol, 0, math.rad(70), 5e9, 1.0)
wait(1.0)
earth = celestia:find("Sol/Earth")
earth:setorbitcolor(1, 1, 0)
for i = 1, 10 do
   earth:setorbitcoloroverridden(true)
   wait(0.5)
   earth:setorbitcoloroverridden(false)
   wait(0.5)
end

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:

1. The object:setorbitvisibility() method can be used to set the orbit visibility policy for this object.
2. 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:

obj = celestia:find("Sol/Earth")
obj_orbitvisible = obj:orbitvisibility()
celestia:print("The orbit visibility of " .. obj:name() .. " is: " .. obj_orbitvisible, 5.0, -1, -1, 2, 4)
wait(5.0)

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:

1. The object:orbitvisibility() method can be used to obtain the current orbit visibility policy for this object.
2. Orbits are only shown when Celestia's orbits renderflag option is turned on, using the celestia:setrenderflags() method.

Example:

-- Find and select our Sun and goto position to have a good overview on our Solar System 
sol = celestia:find("Sol")
celestia:select(sol)
obs = celestia:getobserver()
obs:gotolonglat(sol, 0, math.rad(70), 8e8, 1.0)
wait(1.0)
-- Render planets and show planet labels
celestia:setrenderflags{ planets = true, smoothlines = true }
celestia:setlabelflags{ planets = true }
celestia:setminorbitsize(3)
earth = celestia:find("Sol/Earth")
-- Never render Earth's orbit
earth:setorbitvisibility("never")
celestia:setrenderflags{ orbits = true }
celestia:setorbitflags{ Planet = true }
celestia:print("Orbit of Earth is never rendered", 7.5, -1, -1, 2, 4)
wait(7.5)
-- Always render Earth's orbit
earth:setorbitvisibility("always")
celestia:setorbitflags{ Planet = false }
celestia:print("Orbit of Earth is always rendered, ALTHOUGH planet orbits are NOT rendered.", 7.5, -1, -1, 2, 4)
wait(7.5)
-- Do not render orbits, also not Earth's orbit.
celestia:setrenderflags{ orbits = false }
celestia:print("No orbits are rendered at all.", 7.5, -1, -1, 2, 4)
wait(7.5)
-- Normal render Earth's orbit
earth:setorbitvisibility("normal")
celestia:setrenderflags{ orbits = true }
celestia:setorbitflags{ Planet = false }
celestia:print("Orbit of Earth is not rendered, BECAUSE planet orbits are NOT rendered.", 7.5, -1, -1, 2, 4)
wait(7.5)
celestia:setorbitflags{ Planet = true }
celestia:print("Orbit of Earth is normally rendered, BECAUSE planet orbits are rendered.", 7.5, -1, -1, 2, 4)
wait(7.5)
-- Reset rendering of orbits and labeling of planets
celestia:setrenderflags{ orbits = false }
celestia:setlabelflags{ planets = false }

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:

1. The refmark.type strings are NOT case sensitive: "Body Axes" is considered to be the same as "body axes".
2. 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.

moon=celestia:find("Sol/Earth/Moon")
earth=celestia:find("Sol/Earth")
obs = celestia:getobserver()
obs:gotodistance(moon, 15000, 1.0)
wait(1.0)
--
refmarktable={}
refmarktable.type = "visible region"
refmarktable.size = 1000
refmarktable.color = "green"
refmarktable.opacity = 1.0
refmarktable.tag = "Earthvisible"
refmarktable.target = earth
--
moon:addreferencemark(refmarktable)
wait(10.0)
moon:removereferencemark("Earthvisible")

Or shorter:

moon=celestia:find("Sol/Earth/Moon")
earth=celestia:find("Sol/Earth")
obs = celestia:getobserver()
obs:gotodistance(moon, 15000, 1.0)
wait(1.0)
-- note the curly braces
moon:addreferencemark{type = "visible region", size = 1000, color = "green",
                      opacity = 1.0, tag = "Earthvisible", target = earth}
wait(10.0)
moon:removereferencemark("Earthvisible")

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:

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

moon=celestia:find("Sol/Earth/Moon")
earth=celestia:find("Sol/Earth")
obs = celestia:getobserver()
obs:gotolonglat(moon, 0 , math.rad(90), 12000, 1.0)
wait(1.0)
-- Show visible region from Earth
refmarktable1={}
refmarktable1.type = "visible region"
refmarktable1.color = "green"
refmarktable1.opacity = 1.0
refmarktable1.tag = "Earthvisible"
refmarktable1.target = earth
moon:addreferencemark(refmarktable1)
-- Shof direction to Earth
refmarktable2={}
refmarktable2.type="body to body direction"
refmarktable2.size = 1200
refmarktable2.color = "green"
refmarktable2.opacity = 1.0
refmarktable2.tag = "Earthdirection"
refmarktable2.target=earth
moon:addreferencemark(refmarktable2)
-- Accelerate time to simulate a month
celestia:settimescale(180000)
celestia:print( "During a Moon orbit the portion of the\n" .. 
                "illuminated Hemisphere that is visible to Earth\n" .. 
                "vary from 100% (Full Moon) to 0% (New Moon).", 10.0, -1, -1, 2, 6)
wait(14.0)
-- Remove the reference marks
moon:removereferencemark(refmarktable1.tag, refmarktable2.tag)
-- Reset timescale
celestia:settimescale(1)

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:

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

npstar = celestia:find("Polaris")
celestia:getobserver():center(npstar)
celestia:select(npstar)
nHD = npstar:catalognumber("HD")
nSAO = npstar:catalognumber("SAO")
nHIP = npstar:catalognumber("HIP")
celestia:print("Our current North Polestar " .. npstar:name() .. 
               " has the following catalog numbers:\n" ..
               "HIP " .. nHIP .. "\n" ..
               "HD " .. nHD .. "\n" ..
               "SAO " .. nSAO, 10.0, -1, -1, 2, 7)
wait(10.0)

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:

1. referencing one particular element in an object collection (called element access),
2. modifying itself so it points to the next element (called element traversal).

There must also be a way to create an iterator so it points to some first element as well as some way to determine when the iterator has exhausted all of the elements in an object collection.

Notes:

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

for loc in celestia:getselection():locations() do
   celestia:log(loc:name())
end

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:

1. 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.
2. 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

earth = celestia:find("Sol/Earth")
e_bff = earth:bodyfixedframe()

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:

1. 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.
2. 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

earth = celestia:find("Sol/Earth")
e_eqf = earth:equatorialframe()

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:

1. 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.
2. The positions of stars and deep sky objects are always defined in the universal frame.
3. The frame methods can be used on a CELX "frame" object. This section also gives more information about using reference frames. "Frame" objects can also be used in other methods, requiring a "frame" object as an argument.

Example:
Get the orbit frame of the Earth

earth = celestia:find("Sol/Earth")
e_orbf = earth:orbitframe()

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:

1. 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.
2. The positions of stars and deep sky objects are always defined in the universal frame.
3. The frame methods can be used on a CELX "frame" object. This section also gives more information about using reference frames. "Frame" objects can also be used in other methods, requiring a "frame" object as an argument.

Example:
Get the current body frame for the International Space Station.

iss = celestia:find("Sol/Earth/ISS")
issf = iss:bodyframe()

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:

1. 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.
2. The TDB time scale is a bit different from the more familiar UTC. By using TDB, Celestia places objects much more accurately. As of January 1, 2008, the difference between the two is about 65 seconds. For more information, see Celestia/Time_Scales.
3. To convert between UTC and TDB times, you can use the 1.5.0 celestia:utctotdb() and 1.5.0 celestia:tdbtoutc() methods.
4. To convert between normal calender dates and julian days, you can use the celestia:tojulianday() and celestia:fromjulianday() methods.
5. The phase methods can be used on a "phase" object.

Example:
Get the timeline phase for Cassini at midnight January 1, 2000 UTC

cassini = celestia:find("Sol/Cassini")
tdb = celestia:utctotdb(2000, 1, 1)
phase = cassini:getphase(tdb)

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:

1. referencing one particular element in an object collection (called element access),
2. modifying itself so it points to the next element (called element traversal).

There must also be a way to create an iterator so it points to some first element as well as some way to determine when the iterator has exhausted all of the elements in an object collection.

Notes:

1. Only solar system bodies have a timeline; for all other object types, this method will return an empty iterator.
2. The phases in a timeline are always sorted from earliest to latest, and always cover a continuous span of time.
3. The phase methods can be used on this itarator.

Example:
Copy all of the current selected object phases into the array timeline.

timeline = { }
count = 0
for phase in celestia:getselection():phases() do
   count = count + 1
   timeline[count] = phase
end

Return to the object method index.