Celx 指令碼：物件

物件

CELX 中的“物件”物件並不指代一般的物件（如 Java 中的 Object），而是指天體，例如行星、恆星、航天器、位置等。

在 CELX 指令碼中，可以使用“物件”物件和物件方法之間的分號來使用物件方法。

可以使用以下方法獲取“物件”物件

使用 celestia:find() 方法。
使用 celestia:getselection() 方法。
使用 celestia:getstar() 方法。
使用 1.5.0 celestia:getdso() 方法。
使用 1.5.0 observer:gettrackedobject() 方法。
使用 frame:getrefobject 方法。
使用 frame:gettargetobject() 方法。

方法

本章包含所有可用的物件方法列表，這些方法可用於“物件”物件。

半徑

數字 object:radius()

返回物件的半徑，單位為公里，以數字形式表示。

註釋

對於橢球體，半徑為長半軸。
對於不規則物體，半徑為對齊邊界框的最長軸。
可以使用 1.5.0 object:setradius() 方法設定物件的半徑。

示例
確定並列印我們月球的半徑。

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)

返回物件方法索引。

型別

字串 object:type()

以字串形式返回物件的型別。型別可以是以下之一

行星
衛星
小行星
彗星
航天器
恆星
位置
空（指代宇宙座標系的原點）
不可見（指代參考點）
漫射
深空
- 1.5.0 星系
- 1.5.0 星雲
- 1.5.0 開放星團
1.6.0 表面特徵
1.6.0 成分
1.6.0 矮行星
1.6.0 小衛星

示例
確定並列印 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)

返回物件方法索引。

光譜型

字串 object:spectraltype()

返回恆星的光譜型，以字串形式表示。

如果物件不是恆星，則返回 nil。

註釋

光譜型告訴我們恆星的光譜類別、子類別和光度類別。
Celestia 瞭解恆星的以下光譜類別
- 摩根-肯南光譜類別：O、B、A、F、G、K、M。
- 以下罕見/不尋常類別：L、T、R、S、N、C、WC、WN、D（白矮星）、Q（中子星）、X（黑洞）。
透過在字母后面新增 0 到 9 之間的數字，光譜類別進一步細分為子類別。
Celestia 瞭解以下光度類別：I-a0、I-a、I-b、II、III、IV、V、VI、sd 和 D。
Celestia 的 STC 指令碼指南包含關於恆星光譜型的許多其他資訊。

示例

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)

返回物件方法索引。

絕對星等

數字 object:absmag()

返回恆星的絕對星等，以數字形式表示。

如果物件不是恆星，則返回 nil。

註釋

恆星的絕對星等是在 10 秒差距（~32.616 光年）的標準距離處測量的亮度，因此恆星的絕對星等不會隨著距離而改變。

示例

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)

返回物件方法索引。

名稱

字串 object:name()

返回物件的名稱，以字串形式表示。

示例

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)

返回物件方法索引。

獲取資訊

表格 object:getinfo()

返回一個包含有關此物件的可用資訊的表格。

表格的具體內容取決於物件的型別。返回的資訊包括透過其他物件方法可用的資訊。

對於恆星，表格可能包含以下鍵
- 型別
- 名稱
- catalogNumber
- stellarClass
- absoluteMagnitude
- luminosity
- 半徑
- temperature
- rotationPeriod
- bolometricMagnitude
- orbitPeriod
  - orbitPeriod 僅在恆星屬於雙星或多星系統時可用。
對於天體（例如行星），表格可能包含以下鍵
- 型別
- 名稱
- oblateness
- albedo
- 半徑
- lifespanStart
- lifespanEnd
- rotationPeriod
- orbitPeriod
- atmosphereHeight
  - 僅在該天體有大氣層時有效。
- atmosphereCloudHeight
  - 僅在該天體有大氣層時有效。
- atmosphereCloudSpeed
  - 僅在該天體有大氣層時有效。
- parent
  - parent 是一個 "object" 物件，可能是一個天體或恆星（不可列印）！
- hasRings
  - hasRings 是一個布林值（不可列印）！
- 以下鍵最初被認為是天體的有效鍵，但它們在 1.6.0 中返回無效/空值或導致致命錯誤，或者在早期版本中崩潰。
  修復後，這些鍵的文件將相應調整。在此之前，請跳過使用以下鍵
  - mass
  - infoURL
  - rotationOffset
  - rotationEpoch
  - rotationObliquity
  - rotationAscendingNode
  - rotationPrecessionRate
對於 深空天體，表格可能包含以下鍵
- 型別
- 名稱
- 半徑
- 1.5.0 catalogNumber
- 1.5.0 hubbleType
- 1.5.0 absoluteMagnitude
對於 位置物件，表格可能包含以下鍵
- 型別
- 名稱
- size
- importance
- infoURL
- featureType
- parent
  - parent 是一個 "object" 物件，可能是一個天體（不可列印）！

註釋

注意 Celestia 的大小寫敏感性，關於此物件方法的鍵 !!!
某些鍵可能不可用，因為它們不適用於所討論的天體（例如，它沒有大氣等），或者不包含任何有用的資料。這些鍵包含空值，例如不能列印。

示例

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)

返回物件方法索引。

mark

object:mark([string:color] [, string:symbolname] [, number:size] [, number:opacity] [, string:label] [, boolean occludable])

在物體上放置標記。

引數

color [可選]

用於標記的顏色。預設值為 "#00ff00"（青綠色）。

可以使用 HTML 樣式的十六進位制顏色字串，例如 "#ff0000"（紅色），
或者使用一些預定義的顏色名稱，例如 "lime"、"red"、"green"、"yellow"、"blue"、"orange"、"white"、"black"、"brown"、"cyan"、"gold"、"silver" 等。
如果預定義的顏色名稱不存在，則結果將是預設的 "lime" 標記。
支援的顏色名稱列表可以在 HTML 顏色名稱頁面找到。

symbolname [可選]

用於標記的符號名稱。預設值為 "diamond"。
可用的標記符號是

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 [可選]: 標記的大小（以畫素為單位）。預設值為 10。; 如果 size 小於 1，則 size 將調整為 1。; 如果 size 大於 10000，則 size 將調整為 10000。
opacity [可選]: 一個 0 到 1 之間的值，表示標記的不透明度。預設值為 1.0，完全不透明。; 負值或大於 1 的值將調整為最接近的有效值（0 或 1）。
1.5.0 label [可選]: 標記的文字標籤。預設值為空字串，表示沒有標籤。
1.6.0 occludable [可選]: 一個布林標誌，表示標記是否會被前面的物體隱藏。預設值為 true，標記會被前面的物體隱藏。

註釋

你也可以使用 celestia:mark() 方法，但該方法的可能性要少得多。
只有在 Celestia 的 markers 渲染標誌選項開啟時才會顯示標記，可以使用 celestia:setrenderflags() 方法。
如果你想更改物體上的標記，你需要先取消標記，使用 celestia:unmark() 或 object:unmark() 方法，然後用更改後的標記重新標記。
儘管該方法的所有引數都是可選的，但如果你使用的是引數列表中更後面的引數，則需要將該方法的前面引數也傳遞給它。

示例-1
在 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}

示例-2
在地球上放置一個大的紅色 "你在哪裡" 箭頭

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}

返回物件方法索引。

unmark

object:unmark()

從物體上移除標記。

註釋

如果你不取消標記物體並關閉 markers 渲染標誌，使用 celestia:setrenderflags() 方法，Celestia 仍然會記住已標記的物體。下次開啟 markers 渲染標誌時，所有物體都會被再次標記。
你可能想使用 celestia:unmark() 方法。

示例
找到北極星，將它居中並標記，用閃爍的標記標記 10 秒

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}

返回物件方法索引。

getposition

position object:getposition([number:time])

以 "position" 物件的形式返回物體在指定時間的宇宙座標位置。

引數

time [可選]: 用於確定此物體位置的時間。預設值為當前模擬時間，如果未指定。

註釋

Celestia 的本機座標系基於 J2000 黃道，但與傳統定義相比旋轉了 90 度。
Celestia 中的位置分量（X、Y、Z）以光年的百萬分之一為單位儲存。因此，當你想用公里或英里定義你的位置時，你需要轉換這些位置。因此，你可以使用一個常量，它必須在你的指令碼中先初始化
- 從光年的百萬分之一轉換為公里，使用常量 uly_to_km = 9460730.4725808。
- 從光年的百萬分之一轉換為英里，使用常量 uly_to_mls = 5912956.5453630。
接下來，你可以將光年的百萬分之一轉換為公里或英里，如下所示
- km = number:millionths_of_a_light_year * uly_to_km
- miles = number:millionths_of_a_light_year * uly_to_mls
CELX "position" 物件包含空間中一個點的精確座標。位置相對於座標系，可能需要在進一步使用之前轉換為或從宇宙座標系轉換。
可以在 CELX "position" 物件上使用 position 方法。 "Position" 物件也可以用在其他方法中，這些方法需要 "position" 物件作為引數。

示例
該函式獲取物體 'obj' 相對於另一個物體 'center' 在時間 t 的位置。位置以公里為單位，並且使用標準 J2000 黃道座標系（其中 z 軸是 J2000 黃道平面的指向北方的法線，x 軸是沿黃道平面和地球赤道的升交點指向外）。

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

返回物件方法索引。

getchildren

table object:getchildren()

返回一個包含此物體所有子物體的表格，作為 "object" 物件。

註釋

可以在 CELX "object" 物件上使用 object 方法。 "Object" 物件也可以用在其他方法中，這些方法需要 "object" 物件作為引數。

示例
轉到太陽系的概覽位置，將所有行星的大小放大約 20 秒。然後重置為正常的行星大小。

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

返回物件方法索引。

preloadtexture

object:preloadtexture()

從磁碟載入物體的所有紋理到圖形卡的記憶體中。

註釋

使用此方法可以幫助產生執行更流暢的指令碼，因為預載入紋理會減少接近物體時的延遲。

示例
在前往土星的衛星 Titan 之前，先預載入 Titan 的紋理。

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

返回物件方法索引。

setradius

1.5.0 object:setradius(number:radius)

設定物體的新的半徑。

引數

半徑: 物體的新半徑，以公里為單位。

註釋

可以使用 object:radius() 方法獲取物件的實際半徑。

示例 1
移動到地球-月球系統中的某個位置，並將月球和地球的實際大小放大十倍，持續約 10 秒。然後將月球和地球重置回其原始大小。

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)

示例 2
放大行星的大小，以教育的方式展示我們的太陽系。

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

返回物件方法索引。

localname

1.5.0 string object:localname()

返回物件的本地化名稱，以字串形式表示。

如果無法獲取本地化物件名稱，則返回“?”。

註釋

從 1.5.0 版本開始，Celestia 完全支援國際化。對於每種語言，程式中使用過的所有字串都可以進行翻譯，其中一個就是物件的名稱。
“Sol”，以及所有其他恆星和許多 DSO 的名稱，都沒有本地化。

示例
顯示當前選定物件的本地化名稱。

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

返回物件方法索引。

visible

1.6.0 boolean object:visible()

返回一個布林值，指示物件是否可見。

如果物件可見，則返回 true。
如果物件不可見，則返回 false。

註釋

可以使用 1.6.0 object:setvisible() 方法開啟或關閉物件的可見性。
只有當 Celestia 的 planets 渲染標誌選項開啟時，才會顯示太陽系內的物體，可以使用 celestia:setrenderflags() 方法實現。planets 渲染標誌選項的實際設定不會影響 object:visible() 方法的結果。
恆星始終可見，無論是否使用此方法。所有恆星的渲染只能透過 celestia:setrenderflags() 方法開啟或關閉。

示例
如果地球可見，則將其設為不可見 5 秒，反之亦然。

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

返回物件方法索引。

setvisible

1.6.0 object:setvisible(boolean:visible)

設定物件的可見性標誌。

引數

visible

布林值，指示物件是否被設定為可見。

true：物件將變為可見。
false：物件將變為不可見。

註釋

可以使用 1.6.0 object:visible() 方法確定物件是否可見。
只有當 Celestia 的 planets 渲染標誌選項開啟時，才會顯示太陽系內的物體，可以使用 celestia:setrenderflags() 方法實現。
恆星始終可見，無論是否使用此方法。所有恆星的渲染只能透過 celestia:setrenderflags() 方法開啟或關閉。

示例
使用鍵盤上的 [Shift + T] 鍵切換指定物件的可見性。按下鍵盤上的 [Esc] 鍵以終止示例。

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

返回物件方法索引。

setorbitcolor

1.6.0 object:setorbitcolor(number:red, number:green, number:blue)

為該物件設定特定的軌道顏色。

引數

red: 顏色的 RGB 值的紅色部分，必須在 0 到 1 之間。
green: 顏色的 RGB 值的綠色部分，必須在 0 到 1 之間。
blue: 顏色的 RGB 值的藍色部分，必須在 0 到 1 之間。

註釋

只有當 Celestia 的 orbits 渲染標誌選項開啟時，才會顯示軌道，可以使用 celestia:setrenderflags() 方法實現。
只有當 Celestia 的 orbitflags 開啟時，才會顯示特定的軌道，可以使用 celestia:setorbitflags() 方法實現。
還可以使用 1.6.0 object:setorbitvisibility() 方法設定該物件的軌道可見性。
只有當該物件的預設軌道顏色可以被覆蓋時，才會顯示該物件指定的軌道顏色，可以使用 1.6.0 object:setorbitcoloroverridden() 方法設定。
只要該物件也是當前選定的物件，軌道就會以紅色顯示！

示例
將地球的軌道顏色設定為黃色。

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

返回物件方法索引。

orbitcoloroverridden

1.6.0 boolean object:orbitcoloroverridden()

返回一個布林值，指示該物件的軌道顏色是否可以被覆蓋。

如果物件的軌道顏色被覆蓋，則返回 true。
如果物件的軌道顏色沒有被覆蓋，則返回 false。

註釋

要設定物件的預設軌道顏色是否可以被覆蓋，可以使用 1.6.0 object:setorbitcoloroverridden() 方法。

示例
如果地球的軌道顏色可以被覆蓋，則將地球的軌道顏色設定為青色。否則，列印一條訊息。

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

返回物件方法索引。

setorbitcoloroverridden

1.6.0 object:setorbitcoloroverridden(boolean:overridden)

確定該物件的預設軌道顏色是否將被 1.6.0 object:setorbitcolor() 方法中設定的顏色替換。

引數

overridden

布林值，指示該物件的預設軌道顏色是否將被替換。

true：該物件的預設軌道顏色將被替換。
false：該物件的預設軌道顏色將不被替換。

註釋

只有當 Celestia 的 orbits 渲染標誌選項開啟時，才會顯示軌道，可以使用 celestia:setrenderflags() 方法實現。
只有當 Celestia 的 orbitflags 開啟時，才會顯示特定的軌道，可以使用 celestia:setorbitflags() 方法實現。
還可以使用 1.6.0 object:setorbitvisibility() 方法設定該物件的軌道可見性。
只要該物件也是當前選定的物件，軌道就會以紅色顯示！

示例
將地球的軌道顏色設定為黃色和預設顏色交替顯示。

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

返回物件方法索引。

orbitvisibility

1.6.0 string object:orbitvisibility()

返回一個字串，其中包含該物件的軌道可見性設定。該字串將是以下之一：

"normal"：可見性基於軌道標誌設定（請參見 celestia:setorbitflags() 方法）。
"always"：只要任何軌道開啟，就會可見（請參見 celestia:setrenderflags() 方法）。
"never"：無論 celestia:setrenderflags() 和 celestia:setorbitflags() 方法的設定如何，該物件的軌道都不會顯示。

註釋

可以使用 object:setorbitvisibility() 方法設定該物件的軌道可見性策略。
只有當 Celestia 的 orbits 渲染標誌選項開啟時，才會顯示軌道，可以使用 celestia:setrenderflags() 方法實現。orbits 渲染標誌選項的實際設定不會影響 object:orbitvisibility() 方法的結果。

示例

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)

返回物件方法索引。

setorbitvisibility

1.6.0 object:setorbitvisibility(string:visibility)

設定該物件的軌道可見性策略。

引數

visibility

描述該物件的軌道可見性策略的字串。必須是以下之一：

"normal"
可見性基於軌道標誌設定（請參見 celestia:setorbitflags() 方法）。
"always"
只要任何軌道開啟，就會可見（請參見 celestia:setrenderflags() 方法）。
"never"
無論 celestia:setrenderflags() 和 (celestia:setorbitflags() 方法的設定如何，該物件的軌道都不會顯示。

註釋

可以使用 object:orbitvisibility() 方法獲取該物件的當前軌道可見性策略。
只有當 Celestia 的 orbits 渲染標誌選項開啟時，才會顯示軌道，可以使用 celestia:setrenderflags() 方法實現。

示例

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

返回物件方法索引。

addreferencemark

1.6.0 object:addreferencemark(table:refmark)

顯示該物件各種資訊圖形，類似於將滑鼠懸停在某個天體上並按下滑鼠右鍵時彈出選單中的“線上參考向量”選項。

引數

refmark

一個包含參考標記元素作為鍵的表格。有效的參考標記鍵是

type：指定資訊圖形型別的字串。
可以指定為表格元素 "type" 值的字串是
- "body axes"
- "frame axes"
- "sun direction"
- "velocity vector"
- "spin vector"
- "body to body direction"
- "visible region"
- "planetographic grid"
size：指定資訊圖形大小（單位為點）的數字（可選）。請注意螢幕上顯示的物件大小，以在此處使用適當的大小值，或者直接跳過此引數，讓系統確定圖形的預設大小。此數字不會影響型別為 "visible region" 和 "planetographic grid" 的圖形。
opacity：指定資訊圖形不透明度的 0.0 到 1.0 之間的數字（可選，預設值為 1.0）。
- 0.0 表示圖形不可見。
- 1.0 表示圖形以 100% 的不透明度顯示。
color：指定資訊圖形顏色的字串（可選）。
- 可以使用 HTML 樣式的十六進位制顏色字串，例如 "#ff0000"（紅色），
- 或者使用一些預定義的顏色名稱，例如 "lime"、"red"、"green"、"yellow"、"blue"、"orange"、"white"、"black"、"brown"、"cyan"、"gold"、"silver" 等。
  如果預定義的顏色名稱不存在，則結果將是預設的 "lime" 標記。
  支援的顏色名稱列表可以在 HTML 顏色名稱頁面找到。
tag：指定資訊圖形標識名稱的字串（可選）。如果使用，此標籤也必須在 1.6.0 object:removereferencemark() 方法中使用，以識別要刪除的正確圖形。
target：指定使用 "body to body direction" 或 "visible region" 圖形型別時，參與資訊圖形的第二個物件的物體。

註釋

refmark.type 字串不區分大小寫："Body Axes" 等同於 "body axes"。
請注意，並非所有參考標記型別都可以透過滑鼠線上開啟/關閉。當此類參考標記型別未從 CELX 指令碼中刪除時，終端使用者會一直看到該參考標記。在不知道 CELX 指令碼的情況下，終端使用者無法刪除參考標記，除非重新啟動 Celestia !!!

示例
轉到月球並顯示從地球上可見的月球哪個區域。

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

或更簡潔

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

返回物件方法索引。

removereferencemark

1.6.0 object:removereferencemark(string:tag) 或 1.6.0 object:removereferencemark(string:type)

刪除指定物件的先前使用 object:addreferencemark() 方法顯示的資訊圖形。

引數

tag: 一個指定要刪除的參考標記的標識名稱的字串。
當標籤引數在 object:addreferencemark() 方法中使用時，此removereferencemark() 方法僅透過在此處使用相同的string:tag 作為此方法的引數才能工作。
型別: 一個指定要刪除的參考標記型別的字串。
當標籤引數未在 object:addreferencemark() 方法中使用時，此removereferencemark() 方法也透過在此處使用相應的string:type 作為此方法的引數才能工作。

註釋

可以透過向此方法傳遞多個字串引數來一次刪除多個參考標記。

示例
顯示約 1 個月模擬時間內的地球可見月球區域和地球方向。

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)

返回物件方法索引。

catalognumber

1.6.0 number object:catalognumber(string:catalog)

引數

catalog

指定必須返回目錄號的目錄的字串。必須是當前支援的目錄之一

註釋

如果物件不是恆星，或者目錄字串無效，或者恆星不在目錄中，則將返回 nil。

示例
列印北極星的 HIP、HD 和 SAO 目錄號。

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)

返回物件方法索引。

locations

1.6.0 iterator object:locations()

返回與物件關聯的所有位置的迭代器。

這些 object 方法可以在此迭代器上使用。

迭代器是一個物件，可以被認為是某種型別的指標，它具有兩個主要操作

引用物件集合中的一個特定元素（稱為元素訪問），
修改自身以指向下一個元素（稱為元素遍歷）。

還必須有一種方法可以建立迭代器，使其指向某個第一個元素，以及某種方法可以確定迭代器是否已遍歷物件集合中的所有元素。

註釋

只有太陽系天體有位置。對於所有其他物件型別，此方法將返回一個空迭代器。

示例
將當前選擇的名稱輸出到 Celestia 日誌檔案。您可以使用鍵盤上的波浪號 [~] 鍵開啟和關閉日誌層的顯示。螢幕上最多顯示十行，您可以使用向上/向下箭頭和頁面向上/向下鍵來滾動回滾和前進。請注意日誌的大小受 celestia.cfg 檔案的限制。

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

返回物件方法索引。

bodyfixedframe

1.6.0 frame object:bodyfixedframe()

返回此物件的本體固定框架，作為 "frame" 物件。

註釋

CELX 參考 "frame" 是一個原點和一組軸，它們定義了用於天體的軌跡和方向的座標系。原點是目錄檔案中定義的另一個天體。有幾種方法可以設定座標系軸。
這些 frame 方法可以在 CELX "frame" 物件上使用。本節還提供了有關使用參考框架的更多資訊。"Frame" 物件也可以在需要 "frame" 物件作為引數的其他方法中使用。

示例
獲取地球的本體固定框架

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

返回物件方法索引。

equatorialframe

1.6.0 frame object:equatorialframe()

返回此物件的赤道框架，作為 "frame" 物件。

註釋

CELX 參考 "frame" 是一個原點和一組軸，它們定義了用於天體的軌跡和方向的座標系。原點是目錄檔案中定義的另一個天體。有幾種方法可以設定座標系軸。
這些 frame 方法可以在 CELX "frame" 物件上使用。本節還提供了有關使用參考框架的更多資訊。"Frame" 物件也可以在需要 "frame" 物件作為引數的其他方法中使用。

示例
獲取地球的赤道框架

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

返回物件方法索引。

orbitframe

1.6.0 frame object:orbitframe([number:time])

返回在特定時間定義物件軌道的框架，作為 "frame" 物件。

引數

time: 用於返回框架的時間，以 TDB（質心動力時間）儒略日數表示。
如果未指定時間，則假定為當前模擬時間。

註釋

CELX 參考 "frame" 是一個原點和一組軸，它們定義了用於天體的軌跡和方向的座標系。原點是目錄檔案中定義的另一個天體。有幾種方法可以設定座標系軸。
恆星和深空天體的位置始終在宇宙框架中定義。
這些 frame 方法可以在 CELX "frame" 物件上使用。本節還提供了有關使用參考框架的更多資訊。"Frame" 物件也可以在需要 "frame" 物件作為引數的其他方法中使用。

示例
獲取地球的軌道框架

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

返回物件方法索引。

bodyframe

1.6.0 frame object:bodyframe([number:time])

返回在特定時間定義物件方向的框架，作為 "frame" 物件。

引數

time: 用於返回框架的時間，以 TDB（質心動力時間）儒略日數表示。
如果未指定時間，則假定為當前模擬時間。

註釋

CELX 參考 "frame" 是一個原點和一組軸，它們定義了用於天體的軌跡和方向的座標系。原點是目錄檔案中定義的另一個天體。有幾種方法可以設定座標系軸。
恆星和深空天體的位置始終在宇宙框架中定義。
這些 frame 方法可以在 CELX "frame" 物件上使用。本節還提供了有關使用參考框架的更多資訊。"Frame" 物件也可以在需要 "frame" 物件作為引數的其他方法中使用。

示例
獲取國際空間站的當前本體框架。

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

返回物件方法索引。

getphase

1.6.0 phase object:getphase([number:time])

獲取指定時間此物件的活動時間線階段，作為 "phase" 物件。

引數

time [可選]: 數字，給出以 TDB 儒略日數表示的時間，在該時間必須獲取活動時間線階段。如果未指定時間，則使用當前模擬時間。

註釋

如果物件不是太陽系天體，或者時間超出物件時間線覆蓋的範圍，則此方法將返回 nil。
TDB 時間尺度與更常見的 UTC 略有不同。透過使用 TDB，Celestia 可以更準確地放置天體。截至 2008 年 1 月 1 日，兩者之間的差異約為 65 秒。有關更多資訊，請參閱 Celestia/Time_Scales.
要將 UTC 時間和 TDB 時間相互轉換，可以使用 1.5.0 celestia:utctotdb() 和 1.5.0 celestia:tdbtoutc() 方法。
要將普通日曆日期和儒略日相互轉換，可以使用 celestia:tojulianday() 和 celestia:fromjulianday() 方法。
這些 phase 方法可以在 "phase" 物件上使用。

示例
獲取 2000 年 1 月 1 日午夜 UTC 的卡西尼號時間線階段

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

返回物件方法索引。

phases

1.6.0 iterator object:phases()

返回物件時間線中所有階段的迭代器。

迭代器是一個物件，可以被認為是某種型別的指標，它具有兩個主要操作

引用物件集合中的一個特定元素（稱為元素訪問），
修改自身以指向下一個元素（稱為元素遍歷）。

還必須有一種方法可以建立迭代器，使其指向某個第一個元素，以及某種方法可以確定迭代器是否已遍歷物件集合中的所有元素。

註釋

只有太陽系天體有時間線；對於所有其他物件型別，此方法將返回一個空迭代器。
時間線中的階段始終按從早到晚的順序排序，並且始終覆蓋連續的時間跨度。
這些 phase 方法可以在此迭代器上使用。

示例
將當前選定物件的所有階段複製到陣列時間軸中。

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

返回物件方法索引。