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 celestia:getdso method.
 * Using the 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

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

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
 * galaxy
 * nebula
 * opencluster
 * surfacefeature
 * component
 * dwarfplanet
 * 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

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:
 * 3) * The Morgan-Keenan spectral classes: O, B, A, F, G, K, M.
 * 4) * The following rara/unusual classes: L, T, R, S, N, C, WC, WN, D (white dwarf), Q (neutron star), X (black hole).
 * 5) The spectral classes are further divided into subclasses by adding a numerical value between 0 and 9 to the letter.
 * 6) Celestia knows the following luminosity classes: I-a0, I-a, I-b, II, III, IV, V, VI, sd and D.
 * 7) 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

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

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

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:
 * 2) * type
 * 3) * name
 * 4) * catalogNumber
 * 5) * stellarClass
 * 6) * absoluteMagnitude
 * 7) * luminosity
 * 8) * radius
 * 9) * temperature
 * 10) * rotationPeriod
 * 11) * bolometricMagnitude
 * 12) * orbitPeriod
 * 13) ** orbitPeriod is only available in case of a star in a binary or multiple star system.
 * 14) For a body (e.g. a planet ) the table may include these keys:
 * 15) * type
 * 16) * name
 * 17) * oblateness
 * 18) * albedo
 * 19) * radius
 * 20) * lifespanStart
 * 21) * lifespanEnd
 * 22) * rotationPeriod
 * 23) * orbitPeriod
 * 24) * atmosphereHeight
 * 25) ** Only valid if body has an atmosphere.
 * 26) * atmosphereCloudHeight
 * 27) ** Only valid if body has an atmosphere.
 * 28) * atmosphereCloudSpeed
 * 29) ** Only valid if body has an atmosphere.
 * 30) * parent
 * 31) ** parent is an "object" object, which may be a body or a star (not printable)!
 * 32) * hasRings
 * 33) ** hasRings is a Boolean (not printable)!
 * 34) * 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 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:
 * 35) ** mass
 * 36) ** infoURL
 * 37) ** rotationOffset
 * 38) ** rotationEpoch
 * 39) ** rotationObliquity
 * 40) ** rotationAscendingNode
 * 41) ** rotationPrecessionRate
 * 42) For a deepsky object, the table may include these keys:
 * 43) * type
 * 44) * name
 * 45) * radius
 * 46) * catalogNumber
 * 47) * hubbleType
 * 48) * absoluteMagnitude
 * 49) For a location object, the table may include these keys:
 * 50) * type
 * 51) * name
 * 52) * size
 * 53) * importance
 * 54) * infoURL
 * 55) * featureType
 * 56) * parent
 * 57) ** 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


Place a marker on an object.

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

Return the position of the object at the specified time in universal coordinates, as a "position" object.

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

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


Set the new radius of the object.

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
string

Return the localized name of the object as a string.

Return "?" if there is no localized object name available.

Notes:
 * 1) From version, 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
boolean

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


Set the object visibility flag.

Notes:
 * 1) The  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


Set a specific orbit color for this object.

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

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


Determine whether or not the default orbit color of the object will be replaced with the color set in the object:setorbitcolor method.

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

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


Set the orbit visibility policy for this object.

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


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.

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
or

Remove the informational graphics for the specified object, that are previously displayed using the object:addreferencemark 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
number

Return the catalog number for a star in the specified catalog, as a number.

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
iterator

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: There must also be a way to create an iterator so it points to some first element as well as some way to determine when the iterator has exhausted all of the elements in an object collection.
 * 1) referencing one particular element in an object collection (called element access),
 * 2) modifying itself so it points to the next element (called element traversal).

Notes:
 * 1) 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
frame

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
frame

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
frame

Return the frame in which the orbit for an object is defined at a particular time 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 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
frame

Return the frame in which the orientation for an object is defined at a particular time 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 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
phase

Get the active timeline phase for this object at the specified time, as a "phase" object.

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  celestia:utctotdb and  celestia:tdbtoutc methods.
 * 4) To convert between normal calender dates and julian days, you can use the celestia:tojulianday and celestia:fromjulianday methods.
 * 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
iterator

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: There must also be a way to create an iterator so it points to some first element as well as some way to determine when the iterator has exhausted all of the elements in an object collection.
 * 1) referencing one particular element in an object collection (called element access),
 * 2) modifying itself so it points to the next element (called element traversal).

Notes:
 * 1) 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.