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

返回对象方法索引。