Celestia/Celx Scripting/CELX Lua Methods/Celx observer

Celx Scripting: Observer

observer

Observer objects are used to access properties specific to a view, such as viewer position, viewer orientation, frame of reference, and tracking status. The viewer position and orientation can be manipulated with goto commands or by setting properties directly.

Within a CELX script, the observer methods can be used on an observer object, by separating the observer object from the observer method with a semicolon.

The following methods can be used to obtain an observer object:

• Using the celestia:getobserver() method regarding the active view.
• Using the celestia:getobservers() method in case of a Multiview, which results in a list of observer objects for each view.

Notes:

1. As views (and thus observers) can be created and destroyed by the user, observer-objects in Lua can become invalid. Accessing an invalid observer object will result in an error.
2. To ease handling of observer-objects, you can compare them with other observer-objects using "==", which is not reliably possible with other celx objects.

Methods

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

goto

observer:goto(object/position:target [, number:duration, number:start_interpolation, number:end_interpolation])

Goto an object or position, similar to pressing the [G] key on the keyboard.

Arguments:

target

An "object" object or a "position" object to goto.

duration [optional]

Number of seconds the goto should take. Default is 5 seconds.

start_interpolation [optional]

The point in time during the goto (expressed as a percent number between 0 and 1), at which the observer should begin turning from the initial orientation to the final orientation. Default is 0.25.

• If start_interpolation is smaller than 0 or greater than 1, it will be adjusted to the default value.

end_interpolation [optional]

The point in time during the goto (expressed as a percent number between 0 and 1) at which the observer should finish turning from the initial orientation to the final orientation. Default is 0.75.

• If end_interpolation is smaller than 0 or greater than 1, it will be adjusted to the default value.

Notes:

1. This command returns immediately, so you probably want to wait(number:duration) seconds, before continuing the script.
2. When an "object" object is specified to goto, the final orientation will be towards the "object" object.
3. When a position object is specified to goto, the final orientation will be the same as the initial orientation.
4. Going to the position returned by object:getposition() method is not the same as going to the object. This because the returned position refers to the center of the object, so you will goto the center of that object.
5. The given position is expected to be relative to the universal frame-of-reference. So depending on the used frame of reference, you have to convert the position first to "Universal" before using it in the goto.
6. Position components (X,Y,Z) in Celestia are stored in millionths of a light year. So when you have your own 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 km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
   • From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
7. Next you can convert km or miles to millionths of a light year as follows:
   • millionths_of_a_light_year = number:km / uly_to_km
   • millionths_of_a_light_year = number:miles / uly_to_mls

Example-1:
Goto the specified object.

mars = celestia:find("Sol/Mars")
celestia:select(mars)
obs = celestia:getobserver()
obs:goto(mars, 5.0)
celestia:print("We're on our way to Mars." , 5.0, -1, -1, 2, 4)
wait(5.0)

Example-2:
Goto the specified position, halfway the Earth and the Moon. Press the [Shift + *] keys after running this example, to verify the position of the Moon in the rear mirror of the observer.

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.
newpos = earthpos + 0.5 * (moonpos - earthpos)
obs:goto(newpos, 3.0)
celestia:print("We're are going halfway Earth - Moon." , 5.0, -1, -1, 2, 4)
wait(3.0)
-- Follow and center Earth
obs:follow(earth)
obs:center(earth)
wait(2.0)

Return to the observer method index.

goto (table)

1.3.2 observer:goto(table:parameters)

Go from an initial position with an initial orientation to a final position with a final orientatien.

Using this method, many different types of gotos can be performed.

Arguments:

parameters

The parameters for the goto must be given in a table. Valid table keys are:

• duration
  Number of seconds the goto should take. Default is 5 seconds.
• from
  Initial source position from where the goto starts. Must be a "position" object.
• to
  Final target position where the goto ends. Must be a "position" object.
• initialOrientation
  Initial source orientation of the observer. Must be a "rotation" object.
• finalOrientation
  Final target orientation of the observer. Must be a "rotation" object.
• startInterpolation
  The point in time during the goto (expressed as a percent number between 0 and 1), at which the observer should begin turning from the initial orientation to the final orientation. Default is 0.25.
• endInterpolation
  The point in time during the goto (expressed as a percent number between 0 and 1) at which the observer should finish turning from the initial orienation to the final orientation. Default is 0.75.
• accelTime
  Indicates (as a percentage number between 0 and 1) how much of the time during the goto should be spent accelerating away from the initial position. It also represents the amount of time that will be spent decelerating towards the final position. The remainder of the time during the goto is spend cruising. Default is 0.25, minimum is 0.01 and maximum is 0.5.

Note: Watch for typos and the case sensitivity of Celestia regarding the keys. Unrecognized keys or values with wrong type will simply be ignored.

Notes:

1. This command returns immediately, so you probably want to wait(number:duration) seconds, before continuing the script.
2. If you want the goto to start from the current position with the current observer orientation, you can use the observer:getposition() and observer:getorientation() methods respectively.
3. The given position is expected to be relative to the universal frame-of-reference. So depending on the used frame of reference, you have to convert the position first to "Universal" before using it in the goto.
4. Position components (X,Y,Z) in Celestia are stored in millionths of a light year. So when you have your own 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 km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
   • From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
5. Next you can convert km or miles to millionths of a light year as follows:
   • millionths_of_a_light_year = number:km / uly_to_km
   • millionths_of_a_light_year = number:miles / uly_to_mls

Example:
Goto a position 20,000 km away in the X-direction of the "Universal" coordinate system, from the center of Mars.

uly_to_km = 9460730.4725808
-- Set frame of reference to "universal"
obs = celestia:getobserver()
obs:setframe(celestia:newframe("universal"))
-- Find and select Mars
mars = celestia:find("Sol/Mars")
celestia:select(mars)
-- Obtain the actual position of Mars
now = celestia:gettime()
posmars = mars:getposition(now)
-- Define table and initialize table
parameters = { }
-- Number of seconds the goto should take
parameters.duration = 5.0
-- Obtain current observer position
parameters.from = obs:getposition()
-- Determine position to goto
parameters.to = celestia:newposition((posmars.x + (20000/uly_to_km)), posmars.y, posmars.z )
-- obtain current observer orientation
parameters.initialOrientation = obs:getorientation()
-- Determine observer orientation from position to goto, towards the position of Mars
parameters.finalOrientation = parameters.to:orientationto(posmars,celestia:newvector(0,1,0))
-- Start adjusting the observer orientation from the beginning of the goto
parameters.startInterpolation = 0.0
-- End adjusting the observer orientation at the end of the goto
parameters.endInterpolation = 1.0
-- Use 10% of the time to accelerate and 10% of the time to decelarate 
parameters.accelTime = 0.1
-- Perform the goto
obs:goto(parameters)
-- Finally follow Mars and wait until the goto has finished
obs:follow(mars)
wait(parameters.duration )

Return to the observer method index.

gotolonglat

1.3.2 observer:gotolonglat(object:target [, number:longitude, number:latitude, number:distance, number:duration, vector:up-axis])

Goto a position above the longitude/latitude surface coordinates in duration seconds, with given distance of the object and up-axis pointing up.

Arguments:

target

Object to goto. Must be an "object" object.

longitude [optional]

Longitude object surface coordinate in radians. Default is 0.
Longitude is specified as a negative number for the Western hemisphere and as a positive number for the Eastern hemisphere ("+" sign is not necessary).

latitude [optional]

Latitude object surface coordinate in radians. Default is 0.
Latitude is specified as a negative number for the Southern hemisphere, and as a positive number for the Northern hemisphere ("+" sign is not necessary).

distance [optional]

Distance from the center of the object in km. Default is 5 times the radius of the object.
Special distance values are:

• 0 (zero): goto the center of the object.
• Radius of the object in km: goto the surface of the object.

duration [optional]

Number of seconds the goto should take. Default is 5 seconds.

up-axis [optional]

Defines which axis points up. Must be a vector object.

• celestia:newvector(1,0,0) --> X-axis
• celestia:newvector(0,1,0) --> Y-axis is the default
• celestia:newvector(0,0,1) --> Z-axis

Notes:

1. Longitude and latitude are in radians (0 to 2*π), NOT degrees (0 to 360). 180 degrees (half a circle) is the same as π radians = 3.14159265 radians = math.pi radians (Lua). You can convert degrees to radians and vice versa as follows:
   • radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
   • degrees = math.deg( number:radians ) = ( number:radians * 180 / math.pi) = ( number:radians * 180 / 3.14159265).
2. The radius of the object in km can be obtained, using the object:radius() method. If the distance in km is smaller than the radius of the object in km, the goto will end inside the object.
3. This command returns immediately, so you probably want to wait(number:duration) seconds before continuing in your script.

Example:
This example selects the Earth and positions the camera over Seattle, Washington, USA, at a distance of 12,000 km above the surface.

earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs = celestia:getobserver()
obs:synchronous(earth)
earthdistance = 12000 + earth:radius()
longitude = math.rad(-122.0)
latitude = math.rad(47.0)
obs:gotolonglat(earth, longitude, latitude, earthdistance, 5.0)
celestia:print("Traveling to Seattle, Washington, USA.", 5.0, -1, -1, 2, 4)
wait(5.0)
celestia:print("Hovering over Seattle, Washington, USA.", 5.0, -1, -1, 2, 4)
wait(5.0)

Return to the observer method index.

gotolocation

observer:gotolocation(position:target [, number:duration])

Goto position target in duration seconds.

Arguments:

target

Position to goto, in the observer's current frame of reference. Must be a "position" object.

duration [optional]

Number of seconds the goto should take. Default is 5 seconds.

Notes:

1. This command returns immediately, so you probably want to wait(number:duration) seconds before continuing in your script.
2. The position in this observer:gotolocation() method is relative to the current frame of reference for this observer, while the observer:goto() and observer:goto(table) methods use the universal frame of reference!
3. Position components (X,Y,Z) in Celestia are stored in millionths of a light year. So when you have your own 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 km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
   • From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
4. Next you can convert km or miles to millionths of a light year as follows:
   • millionths_of_a_light_year = number:km / uly_to_km
   • millionths_of_a_light_year = number:miles / uly_to_mls

Example:
Goto location: X = +7000km, Y = +9000km, Z = +11000km from the center of Earth.

obs = celestia:getobserver()
-- Select and follow Earth (so the coordinate system
-- of the frame of reference is set to "ecliptic").
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs:follow(earth)
-- Convert km to millionths of a light year, using "uly_to_km".
uly_to_km = 9460730.4725808
newpos = celestia:newposition(7000/uly_to_km, 9000/uly_to_km, 11000/uly_to_km)
-- Goto target position.
obs:gotolocation(newpos, 5.0 )
wait(5.0)
-- You are at the right position now, but probably Earth is 
-- not visible yet. Center Earth to be sure to see our planet. 
obs:center(earth, 1.0)
wait(1.0)

Return to the observer method index.

gotodistance

1.3.2 observer:gotodistance(object:target [, number:distance, number:duration, vector:up-axis])

Goto given distance of target object in duration seconds, with up-axis pointing up.

Arguments:

target

Object to goto. Must be an "object" object.

distance [optional]

The distance from the center of the target object, where to stop in km. Default is 20000 km.

duration [optional]

Number of seconds the goto should take. Default is 5 seconds.

up-axis [optional]

Defines which axis points up. Must be a vector object.

• celestia:newvector(1,0,0) --> X-axis
• celestia:newvector(0,1,0) --> Y-axis is the default
• celestia:newvector(0,0,1) --> Z-axis

Notes:

1. The radius of the object in km can be obtained, using the object:radius() method. If the distance in km is smaller than the radius of the object in km, the goto will end inside the object.
2. This command returns immediately, so you probably want to wait(number:duration) seconds before continuing in your script.

Example:
Select the Sun, travel to it, then select Earth and travel to it. Then spend 3.0 seconds, changing your display distance to be further away to 90.000 km from the surface of Earth.

sun = celestia:find("Sol")
celestia:select(sun)
obs = celestia:getobserver()
obs:goto(sun, 3.0)
wait(4.0)
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs:goto(earth, 3.0)
wait(4.0)
obs:gotodistance(earth, 90000+earth:radius(), 3.0)
wait(3.0)

Return to the observer method index.

gotosurface

1.3.2 observer:gotosurface(object:target [, number:duration])

Goto the surface of the given object and look at the horizon. Like pressing the [Ctrl+G] keys on the keyboard.

Arguments:

target

Object on which to land. Must be an "object" object.

duration [optional]

Number of seconds the goto should take. Default is 5 seconds.

Notes:

1. The landing position will correspond with the longitude and latitude surface coordinates of the object you are hovering above, before the goto starts.
2. The horizon you are looking at after the goto, corresponds with the direction of the object that is pointing up on your screen, before the goto starts.
3. This command returns immediately, so you probably want to wait(number:duration) seconds before continuing in your script.

Example:
Goto the surface of Mars.

obs = celestia:getobserver()
planet = celestia:find("Sol/Mars")
celestia:select(planet)
obs:goto(planet, 3.0)
wait(4.0)
obs:gotosurface(planet, 3.0)
wait(3.0)

Return to the observer method index.

center

observer:center(object:target [, number:duration])

Rotate the observer view so, that the target object is centered on the screen. Like pressing the [c] key on the keyboard.

Arguments:

target

Object to be centered on the screen. Must be an "object" object.

duration [optional]

Number of seconds the centering should take. Default is 5 seconds.

Example: First center Saturn on your screen and then goto the planet straight ahead.

obs = celestia:getobserver()
planet = celestia:find("Sol/Saturn")
obs:center(planet, 3.0)
wait(3.0)
obs:goto(planet, 3.0)
wait(3.0)

Return to the observer method index.

centerorbit

1.3.2 observer:centerorbit(object:target [, number:duration])

Orbit the object used as the reference in the current frame such that the target becomes centered within duration seconds. This is like pressing [Shift+C] keys on the keyboard.

Arguments:

target

Object to be centered. Must be an "object" object.

duration [optional]

Number of seconds the centering should take. Default is 5 seconds.

Notes:

1. If you have an original object somewhere on your screen and then you center a new object, using the observer:center() method, you might or might not lose sight of your original object, as the observer rotates to center the new object. With this observer:centerorbit() method it is possible to swing the observer to center the target object, without losing sight of the original object, which is used as the reference in the current frame.
2. When the object used as the reference in the current frame is still centered on the screen, using this method may cause the target object to (fully or partially) disappear behind the reference object.
3. If the object used as the reference in the current frame is the same as the target object, but NOT centered on the screen, the result of this method will just be an orbit around the object for duration seconds, where the observer orientation stays the same with respect to the object.
4. If the target object is already centered on the screen, nothing will happen when using this method.
5. If the current frame of reference is “universal”, nothing will happen when using this method.

Example:

-- Goto and follow the Moon at specified distance
moon = celestia:find("Sol/Earth/Moon")
moonradius = moon:radius()
obs = celestia:getobserver()
obs:gotodistance(moon, 17500+moonradius, 3.0)
obs:follow(moon)
wait(3.0)
-- Rotate the observer a bit, so the Moon is not centered anymore
duration = 1.0
rotsteps = 25 * duration
rot = celestia:newrotation(celestia:newvector(0,1,0), math.rad(10)/rotsteps)
rotsteptime = duration/rotsteps
for i = 1, rotsteps do
   obs:rotate(rot)
   wait(rotsteptime)
end
-- Find and select Earth and center Earth on the screen, with the Moon still visible
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs:centerorbit(earth, 4.0)
wait(4.0)

Return to the observer method index.

travelling

boolean observer:travelling()

Return a boolean, indicating whether or not a goto or center is currently in progress.

• true means a goto or center is currently in progress
• false means there is currently NO goto or center in progress

Notes:

1. This method can be useful in combination with the observer:cancelgoto() method, which stops any goto or center currently in progress.
2. This method can be used in a Lua "while" loop, to prevent continuing with other methods, while there is still a goto or center in progress.

Example:
Goto the Moon in 10 seconds and flash message when arrived.

moon = celestia:find("Sol/Earth/Moon")
obs = celestia:getobserver()
obs:goto(moon, 10.0)
actual_travel = obs:travelling()
while actual_travel do
   actual_travel = obs:travelling()
   wait(0.0)
end
celestia:flash("Arrived at the Moon", 5.0)
wait(5.0)

Return to the observer method index.

cancelgoto

1.3.2 observer:cancelgoto()

Stop any goto or center command currently in progress.

Notes:

1. Unlike the CEL: CANCEL { } command, which also cancels any goto, this method does NOT take effect on the current frame of reference and object tracking. To fully simulate the CEL: CANCEL { } command, you also have to use the observer:track(nil) method and the celestia:newframe("universal") with the observer:setframe() methods.

Example:
Goto the Moon in 20 seconds, but cancel that goto after 5 seconds.

moon = celestia:find("Sol/Earth/Moon")
obs = celestia:getobserver()
obs:goto(moon, 20.0)
wait(5.0)
actual_travel = obs:travelling()
if actual_travel then
   obs:cancelgoto()
   celestia:flash("GOTO aborted.",5.0)
   wait(5.0)
end

Return to the observer method index.

follow

observer:follow(object:target)

Activate follow-mode on target object.

Follow is the same as setting the frame of reference to "ecliptical" with target as reference object.

Arguments:

target

The object to be followed. Must be an "object" object.

Notes:

1. As the object moves through space, the observer moves with it. The object can rotate on its axis, which means the longitude will constantly change. The observer will remain the same distance and latitude above the object.
2. The X axis points away from the Sun in the direction of the Julian 2000.0 vernal equinox. The Y axis is normal to the ecliptic with positive Y north. The Z axis completes the right-handed coordinate system.

Example:
Select Mars, activate follow mode and then travel to Mars.

mars = celestia:find("Sol/Mars")
celestia:select(mars)
obs = celestia:getobserver()
obs:follow(mars)
obs:goto(mars, 2.0)
wait(2.0)

Return to the observer method index.

synchronous

observer:synchronous(object:target)

Activate synchronous-mode on target object.

Synchronous-mode is the same as setting the frame of reference to "planetographic" (a.k.a. "geographic"), with target as reference object.

Arguments:

target

The object to be synchronize with. Must be an "object" object.

Notes:

1. The observer remains in a stationary, or geosynchronous orbit above the reference object. As the object rotates on its axis, the observer will remain the same distance, longitude and latitude above the object, as if it were attached to the object.
2. The origin of the Celestia Coordinate System is the center of the reference object.
3. In the Geographic Coordinate System, the axes rotate with the selected object. The Y axis is the axis of rotation, counter-clockwise, so it points north for prograde rotators (like Earth), and south for retrograde rotators (like Venus). The X axis points from the center of the object to the intersection of its zero longitude meridian and equator. The Z axis (at a right angle to the XY plane) completes the right-handed coordinate system.

Example:
Select Earth and activate synchronous-mode.

earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs = celestia:getobserver()
obs:synchronous(earth)

Return to the observer method index.

chase

observer:chase(object:target)

Activate chase-mode on target object.

Chase-mode is the same as setting the frame of reference to "chase" with target as reference object.

Arguments:

target

The object to chase. Must be an "object" object.

Notes:

1. In Chase mode, the position of the observer remains fixed relative to the target's direction of motion and the observers orientation keeps constant with respect to the direction in which an object is moving.
2. The origin of the Celestia Coordinate System is the center of the reference object.
3. This Coordinate System is similar to "lock", except that the Z axis points in the direction of motion relative to the target object's parent body (the Sun for planets, a planet for moons).

Example:
Select the Moon, activate chase-mode and then go to the Moon.

moon = celestia:find("Sol/Earth/Moon")
celestia:select(moon)
obs = celestia:getobserver()
obs:chase(moon)
obs:goto(moon, 2.0)
wait(2.0)

Return to the observer method index.

lock

observer:lock(object:target)

Activate lock-mode on the axis from the current reference object to the target object.

Lock-mode is the same as setting the frame of reference to "lock" with target as target-object and the current reference object.

Arguments:

target

The object to be locked with the current reference object. Must be an "object" object.

Notes:

1. In Lock mode, the position of the observer remains fixed relative to the line between the reference object and the target object. As the target object moves around the reference object (relatively speaking) so does the observer. The distance from the observer to the reference object remains the same, where the distance from the observer to the target object may vary.
2. The origin of the Celestia Coordinate System is the center of the reference object.
3. The Z axis points from the reference object to the target object. The Y axis lies in the plane defined by the Z axis and the rotation axis of the reference object, at a right angle to the Z axis. The X axis completes the right-handed coordinate system.
4. Just selecting an object previously to activating the lock-mode, doesn't make that object the reference object. To make an object the reference object, use the observer:follow() or observer:synchronous() or observer:chase() method first, before activating lock-mode.
5. If the reference object is the same as the target object, within a Solar System the central star will be set as the reference object instead.
6. If the central star in a Solar System is the reference object as well as the target object, using this observer:lock() method will not have any effect.
7. If the "universal" frame of reference is active prior to using this observer:lock() method (so no reference object is available), using this method will not have any effect.

Example:
Maintain position with respect to the Earth and keep the line between the Moon and the Earth fixed in the view. (Mind that the position with respect to the Moon will vary, because of the eccentricity of the Moon's orbit).

-- Goto and follow the Moon at specified distance
moon = celestia:find("Sol/Earth/Moon")
moonradius = moon:radius()
obs = celestia:getobserver()
obs:gotodistance(moon, 45000+moonradius, 3.0)
obs:follow(moon)
wait(3.0)
-- Rotate the observer a bit, so the Moon is not centered anymore
duration = 1.0
rotsteps = 25 * duration
rot = celestia:newrotation(celestia:newvector(0,1,0), math.rad(10)/rotsteps)
rotsteptime = duration/rotsteps
for i = 1, rotsteps do
   obs:rotate(rot)
   wait(rotsteptime)
end
-- Find and select Earth and center Earth on the screen, with the Moon still visible
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs:centerorbit(earth, 4.0)
wait(4.0)
-- Make Earth the current reference object
obs:follow(earth)
-- Both Moon and Earth are in view now.
-- Activate lock mode and accelerate time.
obs:lock(moon)
celestia:settimescale(21600)

Return to the observer method index.

track

observer:track(object:target)

Set tracking on object, i.e. always keep the target object centered on the screen as it moves through space.

Arguments:

target

The object to track. Must be an "object" object.

Notes:

1. Tracking will stay activated on an object, even if another object is selected. You must cancel tracking on the first object before you seek to view another object.
2. To stop tracking an object, use observer:track(nil).

Example:
Release hold on any currently selected object, then select and goto Earth and track it. The Earth will begin to recede from you at the speed it actually travels in space, but Celestia will track the Earth by keeping it centered in the display. Time will be sped up by 1000x.

obs = celestia:getobserver()
obs:cancelgoto()
obs:track(nil)
obs:setframe(celestia:newframe("universal"))
earth = celestia:find("Sol/Earth")
celestia:select(earth)
distance = 7 * earth:radius()
obs:gotodistance(earth, distance, 3.0 )
wait (5.0)
obs:track(earth)
celestia:settimescale(1000)

Return to the observer method index.

getposition

position observer:getposition()

Return the current position of this observer in universal coordinates, as a "position" object.

Notes:

1. Position components (X,Y,Z) in Celestia are stored in millionths of a light year. So when you have your own 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 km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
   • From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
2. Next you can convert km or miles to millionths of a light year as follows:
   • millionths_of_a_light_year = number:km / uly_to_km
   • millionths_of_a_light_year = number:miles / uly_to_mls
3. 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.
4. 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:

obs = celestia:getobserver()
actual_obspos = obs:getposition()
celestia:print("Actual observer position:\nX = " .. actual_obspos.x .. 
               "\nY = " .. actual_obspos.y .. "\nZ = " ..  actual_obspos.z, 15, -1, -1, 1, 6)
wait(15.0)

Return to the observer method index.

setposition

observer:setposition(position:pos)

Set the new position of this observer.

Arguments:

pos

The new position of this observer in universal coordinates. Must be a "position" object.

Notes:

1. Position components (X,Y,Z) in Celestia are stored in millionths of a light year. So when you have your own 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 km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
   • From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
2. Next you can convert km or miles to millionths of a light year as follows:
   • millionths_of_a_light_year = number:km / uly_to_km
   • millionths_of_a_light_year = number:miles / uly_to_mls

Example:
Set new observer position halfway the Earth and the Moon. Press the [Shift + *] keys after running this example, to verify the position of the Moon in the rear mirror of the observer.

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.
moonpos = celestia:find("Sol/Earth/Moon"):getposition()
-- Calculate new position halfway Earth - Moon.
newpos = earthpos + 0.5 * (moonpos - earthpos)
-- Set new observer position and follow/center Earth
obs:setposition(newpos)
obs:follow(earth)
obs:center(earth, 0.0)
wait(0.0)

Return to the observer method index.

getorientation

rotation observer:getorientation()

Return the current orientation of this observer, as a "rotation" object.

Notes:

1. A CELX "rotation" object is internally a Quaternion, which is one possibility to mathematically describe a rotation in 3 dimensions (i.e. it can be converted to a rotation matrix). A rotation can also be used to describe the orientation of objects or the observer (i.e. where the observer is looking to, and where "up" is).
2. The rotation methods can be used on a CELX "rotation" object. "Rotation" objects can also be used in other methods, requiring a "rotation" object as an argument.

Example:

obs = celestia:getobserver()
actual_obsrot = obs:getorientation()

Return to the observer method index.

setorientation

observer:setorientation(rotation:rot)

Set the new orientation of this observer.

Arguments:

rot

The new orientation of this observer. Must be a "rotation" object.

Example:
Set new observer position halfway the Earth and the Moon and then set the observer orientation towards the Earth and Moon alternately.

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.
moonpos = celestia:find("Sol/Earth/Moon"):getposition()
-- Calculate new position halfway Earth - Moon.
newpos = earthpos + 0.5 * (moonpos - earthpos)
obs:setposition(newpos)
-- Follow Earth
obs:follow(earth)
-- Observer orientation to look from newpos towards Earth.
rot1 = newpos:orientationto(earthpos, celestia:newvector(0,1,0))
-- Observer orientation to look from newpos towards the Moon.
rot2 = newpos:orientationto(moonpos, celestia:newvector(0,1,0))
-- Alternately switch the observer orientation.
for i = 1, 5 do
   obs:setorientation(rot1)
   wait(1.0)
   obs:setorientation(rot2)
   wait(1.0)
end

Return to the observer method index.

rotate

observer:rotate(rotation:rot)

Rotate the observer, according the given rotation.

Arguments:

rot

The rotation to be used on the current observer orientation. Must be a "rotation" object.

Notes:

1. This method sets the new observer orientation immediately. To more simulate the CEL: ROTATE command and let the observer rotate during a period of time, the rotation angle can be split up in more smaller rotation angles, which are quickly processed after each other, by using this observer:rotate() method in a Lua "for" or "while" control structure (see next notes).
2. When using this observer:rotate() method in a Lua "for" control structure (see example-1), the rotation period will take a fraction longer than number:duration seconds (depending on the speed of your computer), but the total rotation angle along the specified axis will be exactly correct. This because the commands in the generated loop also take some additional computer time to execute. In case of a slower computer, you can decrease the number of steps per second, but that can also mean the scene becomes more jerkier.
3. It is also possible to use this observer:rotate() method in a Lua "while" control structure, (see example-2). In that case the rotation period can be set exactly to the number:duration seconds, but the total rotation angle along the specified axis will NOT be exactly correct. Again depending on the speed of your computer, you'll have to make a guess about the step-angle or wait-time for each sequence in the "while" control structure, to end up as close to the total target rotation angle as possible.

Example-1:
Select, follow and center Earth, then rotate the observer during about 5 seconds over exactly 90 degrees to the right, along the Z axis of Earth.

-- Find, select, follow and center Earth first.
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs = celestia:getobserver()
obs:follow(earth)
obs:center(earth, 1.0)
wait(1.0)
-- Rotate the observer during about 5 seconds over exactly 90 degrees along the Z axis
duration = 5.0
axis_vector = celestia:newvector(0,0,1)
rotationangle = math.rad(90)
obs = celestia:getobserver()
-- Split up the rotation in 50 steps per second.
-- The factor 0.75 is an estimate and may depend on the speed of your computer.
rotsteps = 50 * duration
rotsteptime = 0.75*duration/rotsteps
-- Create new rotation object of split up rotation angle over the specified axis.
rot = celestia:newrotation(axis_vector, rotationangle/rotsteps)
-- Actually execute the rotation.
for i = 1, rotsteps do
   obs:rotate(rot)
   wait(rotsteptime)
end

Example-2:
Select, follow and center Earth, then rotate the observer during exactly 5 seconds over about 90 degrees to the right, along the Z axis of Earth.

-- Find, select, follow and center Earth first.
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs = celestia:getobserver()
obs:follow(earth)
obs:center(earth, 1.0)
wait(1.0)
-- Rotate the observer during exactly 5 seconds over about 90 degrees along the Z axis
duration = 5.0
axis_vector = celestia:newvector(0,0,1)
rotationangle = math.rad(90)
obs = celestia:getobserver()
-- Split up the rotation in 50 steps per second.
-- The factor 0.75 is an estimate and may depend on the speed of your computer.
rotsteps = 50 * duration
rotsteptime = 0.75*duration/rotsteps
-- Create new rotation object of split up rotation angle over the specified axis.
rot = celestia:newrotation(axis_vector, rotationangle / rotsteps)
-- Get the elapsed time in seconds since the script has been started and store in "t0". 
t0= celestia:getscripttime()
-- Actually execute the rotation.
while celestia:getscripttime() <= t0 + duration do
   obs:rotate(rot)
   wait(rotsteptime)
end

Return to the observer method index.

lookat

observer:lookat([position:from,] position:to, vector:up)

Set the orientation of the observer according the specification to look from position:from at position:to with vector:up pointing up.

Arguments:

from [optional]

The point from which to look at position to. Must be a "position" object.
If not given, the current position is used instead.

to

The point to look at from position from. Must be a "position" object.

up

A vector pointing to where up should be in the current view. Must be a "vector" object.
Must not be parallel to the axis from --> to.

Notes:

1. To set the observer orientation to look from position:from at position:to does NOT mean that the observer is also placed at position:from. This method only sets the observer orientation, not the position of the observer.

Example:
Goto the position in space where Earth will be over 1 day. Look from that position at Earth and see how Earth comes towards you (time is sped up 3600x). Get out of the way in time...

-- Find and select Earth
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs = celestia:getobserver()
-- Set frame of reference to "universal".
obs:setframe(celestia:newframe("universal"))
-- Determine the new observer position and the position of Earth
now = celestia:gettime()
newpos = earth:getposition(now+1)
posearth = earth:getposition(now)
obs:goto(newpos,0.0)
wait(0.0)
-- Look at Earth and see how it comes towards you
upvec = celestia:newvector(0,1,0)
obs:lookat(newpos, posearth, upvec)
celestia:settimescale(3600)

Return to the observer method index.

gettime

number observer:gettime()

Return this observers time as a TDB (Barycentric Dynamical Time) Julian date.

Older Celestia versions use UTC (Coordinated Universal Time) to calculate times and positions.
Starting with version 1.5.0, although Celestia still displays UTC on the screen,
it uses the TDB time scale internally for everything else, so for CELX scripting !!!

Notes:

1. This method differs from the celestia:gettime() method, because in case of a Multiview scene the simulation time can differ between the available observers. This method returns the time for the observer of the active view. For more information about the synchronizing time between the different views (observers), check the 1.6.1 celestia:synchronizetime() and 1.6.1 celestia:istimesynchronized() methods.
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.

Example:
Get the TDB time for the observer of the active view and convert it to a UTC calendar date/time. This can be checked by comparing the result of the print statement with the UTC date/time displayed in the upper right corner of your screen.

celestia:settimescale(0)
obs = celestia:getobserver()
actual_observer_tdbtime = obs:gettime()
ut = celestia:tdbtoutc(actual_observer_tdbtime)
celestia:print("Date/time: " .. ut.year .. " " .. ut.month .. " " .. ut.day .. " "
                .. ut.hour .. " " .. ut.minute .. " " .. ut.seconds, 10.0, -1, -1, 2, 4) 
wait(10.0)

Return to the observer method index.

getspeed

1.3.2 number observer:getspeed()

Return the current speed of this observer in millionths of a light year per second, as a number.

Notes:

1. The speed of this observer can be set, using the observer:setspeed() method.
2. When you want to convert the obtained speed in km/s or miles/s, 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/s = number:millionths_of_a_light_year/s * uly_to_km
   • miles/s = number:millionths_of_a_light_year/s * uly_to_mls

Example:
Obtain the actual speed of this observer. To check the working of this example, you can first press the [A] key on the keyboard e few times to set the observer speed to a specific value, as will be displayed in the lower left corner on your screen (if not, press the [V] key on the keyboard).

uly_to_km = 9460730.4725808
obs = celestia:getobserver()
actual_obsspeed = obs:getspeed() * uly_to_km
celestia:print("Actual observer speed: " .. actual_obsspeed .. " km/s.", 10.0, -1, -1, 2, 4)
wait(10.0)

Return to the observer method index.

setspeed

1.3.2 observer:setspeed(number:speed)

Set the speed of this observer.

Arguments:

speed

Speed of this observer in millionths of a light year per second. Must be a number.

Notes:

1. The actual speed of this observer can be obtained by using the observer:getspeed() method.
2. When you have your own speed defined in km/s or miles/s, you have to convert this speed to millionths of a light year per second. Therefor you can use a constant, which must be initialized first within your script:
   • From km/s to millionths of a light year/s, use a constant uly_to_km = 9460730.4725808.
   • From miles/s to millionths of a light year/s, use a constant uly_to_mls = 5912956.5453630.
3. Next you can convert km/s or miles/s to millionths of a light year/s as follows:
   • millionths_of_a_light_year/s = number:km/s / uly_to_km
   • millionths_of_a_light_year/s= number:miles/s / uly_to_mls

Example:
Set the speed of this observer to 150 km/s. The observer speed will be displayed in the lower left corner on your screen (if not, press the [V] key on the keyboard).

uly_to_km = 9460730.4725808
obs = celestia:getobserver()
obs:setspeed(150/uly_to_km)

Return to the observer method index.

getsurface

string observer:getsurface()

Return a string, describing the currently used surface. This can be "limit of knowledge" or possibly the name of an Alternate Surface.

Notes:

1. The empty string "" is returned when the 'Normal' surface is used.

Example:

obs = celestia:getobserver()
actual_surface = obs:getsurface()
celestia:print("Actual surface: " .. actual_surface, 10.0, -1, -1, 2, 4)
wait(10.0)

Return to the observer method index.

setsurface

observer:setsurface(string:name)

Set an alternate surface texture to be displayed by this observer, for the object(s) related to the specified surface name.

Arguments:

name

The name of the surface to be used. Must be a string.
The name must correspond with the name of the alternate surface, defined in the AltSurface entry of the solarsys.ssc file. It is NOT the name of the texture file itself.
Note: use the empty string "" when the 'Normal' surface must be set.

Notes:

1. If you for example want to create an alternate surface texture for Earth, called "Earth-2", and it's related texture filename is earth2.jpg, you would add the following entry to the solarsys.ssc file, after the closing brace for the ' "Earth" "Sol" ' entry. "Earth-2" in the code below is the surface name to be specified in the observer:setsurface() method:

AltSurface "Earth-2" "Sol/Earth"
{
  Texture "earth2.jpg"
}

Example:

-- Set surface to 'limit of knowledge'
celestia:getobserver():setsurface("limit of knowledge")

-- Set surface to 'Normal'
celestia:getobserver():setsurface("")

-- Set surface to 'Earth-2' according the code in 'Notes'.
celestia:getobserver():setsurface("Earth-2")

Return to the observer method index.

getlocationflags

1.3.2 table observer:getlocationflags()

Return a table with all known locationflags (see observer:setlocationflags() method) as keys, and a boolean as value, indicating whether a specific locationflag is enabled or disabled.

Notes:

1. This method is especially useful to save all locationflags at the beginning of a script, so these values can be reset at script end or script termination, by using the function celestia_cleanup_callback().

Example:

obs = celestia:getobserver()
actual_locationflags = obs:getlocationflags()

Return to the observer method index.

setlocationflags

1.3.2 observer:setlocationflags(table:locationflags)

Enable or disable the labeling of specific location types, when locations are turned on using the celestia:setlabelflags() or celestia:showlabel() method.

Arguments:

locationflags

A table which contains the locationflags as keys, and booleans as values for each key. Each locationflag must be one of:

• city
• observatory
• landingsite
• crater
• vallis
• mons
• planum
• chasma
• patera
• mare
• rupes
• tessera
• regio
• chaos
• terra
• volcano
• astrum
• corona
• dorsum
• fossa
• catena
• mensa
• rima
• undae
• tholus
• reticulum
• planitia
• linea
• fluctus
• farrum
• insula
• other

Notes:

1. The observer:getlocationflags() method can be used to obtain the current settings for labeling of specific location types.
2. The celestia:setminfeaturesize() method can be used to set the minimum size for locations to be labeled.
3. On the Celestia Motherlode you can find and download different tour scripts to the planets of our Solar System, by Bob Hegwood. When you install and run these scripts on your computer, you will find out a lot about the meanings of the specific location types.

Example:
Enable the labeling of ALL location types.

-- create and initialize table
table = {}
table.city = true
table.observatory = true
table.landingsite = true
table.crater = true
table.vallis = true
table.mons = true
table.planum = true
table.chasma = true
table.patera = true
table.mare = true
table.rupes = true
table.tessera = true
table.regio = true
table.chaos = true
table.terra = true
table.astrum = true
table.corona = true
table.dorsum = true
table.fossa = true
table.catena = true
table.mensa = true
table.rima = true
table.undae = true
table.reticulum = true
table.planitia = true
table.linea = true
table.fluctus = true
table.farrum = true
table.other = true
obs = celestia:getobserver()
obs:setlocationflags(table)
celestia:setlabelflags{locations = true}

or shorter:

-- note the curly braces
obs = celestia:getobserver()
obs:setlocationflags{city = true, observatory = true, landingsite = true, crater = true,
                     vallis = true, mons = true, planum = true, chasma = true, patera = true,
                     mare = true, rupes = true, tessera = true, regio = true, chaos = true,
                     terra = true, astrum = true, corona = true, dorsum = true, fossa = true,
                     catena = true, mensa = true, rima = true, undae = true, reticulum = true,
                     planitia = true, linea = true, fluctus = true, farrum = true, other = true}
celestia:setlabelflags{locations = true}

or even more shorter:

obs = celestia:getobserver()
table = obs:getlocationflags()
for key, value in pairs(table) do 
   table[key] = true 
end
obs:setlocationflags(table)
celestia:setlabelflags{locations = true}

Return to the observer method index.

getfov

number observer:getfov()

Return the current Field Of View (FOV) value for this observer as a number in radians.

Notes:

1. Celestia computes the FOV value relative to the size of the display window, in pixels, but it can also be set by using the observer:setfov() method.
2. The FOV value is displayed in the lower right corner of your screen in the format degrees°minutes'seconds". (If no value is shown, press the [V] key on the keyboard).
3. Angles in CELX are defined in radians instead of degrees. 180 degrees (half a circle) is the same as π radians = 3.14159265 radians = math.pi radians (LUA). You can convert degrees to radians and vice versa as follows:
   • radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
   • degrees = math.deg( number:radians ) = ( number:radians * 180 / math.pi) = ( number:radians * 180 / 3.14159265).
4. Be aware that the minutes part and seconds part in the display on your screen do NOT go from 0 to 100, but from 0 to 60.
   To convert from degrees°minutes'seconds" to radians, you first have to convert the minutes and seconds to a decimal degrees value and vice versa.

Example:
Obtain and print the actual FOV value in degrees°minutes'seconds". Compare it with the FOV value in the lower right corner of your screen.

obs = celestia:getobserver()
actual_fov = obs:getfov()
degrees = math.deg(actual_fov)
-- Determine whole number of degrees
degrees_d = math.floor(degrees)
-- Determine whole number of minutes
degrees = (degrees - degrees_d) * 60
degrees_m = math.floor(degrees)
-- Determine number of seconds
degrees_s = (degrees - degrees_m) * 60
celestia:print("Actual FOV value is: " .. degrees_d .. " degrees " ..
                degrees_m .. " minutes " .. degrees_s .. " seconds.", 10.0, -1, -1, 2, 4)
wait(10.0)

Return to the observer method index.

setfov

observer:setfov(number:fov)

Set the Field Of View (FOV) value for this observer in radians.

Arguments:

fov

The new FOV value in radians. Must be a number.

Notes:

1. Celestia computes the FOV value relative to the size of the display window, in pixels. The current FOV value for this observer can be obtained, using the observer:getfov() method.
2. The FOV value is displayed in the lower right corner of your screen in the format degrees°minutes'seconds". (If no value is shown, press the [V] key on the keyboard).
3. Angles in CELX are defined in radians instead of degrees. 180 degrees (half a circle) is the same as π radians = 3.14159265 radians = math.pi radians (LUA). You can convert degrees to radians and vice versa as follows:
   • radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
   • degrees = math.deg( number:radians ) = ( number:radians * 180 / math.pi) = ( number:radians * 180 / 3.14159265).
4. Be aware that the minutes part and seconds part in the display on your screen do NOT go from 0 to 100, but from 0 to 60.
   To convert from degrees°minutes'seconds" to radians, you first have to convert the minutes and seconds to a decimal degrees value and vice versa.

Example:
Set the new FOV value for this observer to 25°45'15".

degrees_d = 25
degrees_m = 45
degrees_s = 15
-- Convert number of seconds to decimal minutes
degrees = degrees_s / 60
-- Convert number of minutes to decimal degrees
degrees = (degrees_m + degrees) / 60
degrees = degrees_d + degrees
radians = math.rad(degrees)
obs = celestia:getobserver()
obs:setfov(radians)

Return to the observer method index.

getframe

frame observer:getframe()

Return the frame of reference for this observer in a CELX "frame" object.

Notes:

1. The observer:setframe() method can be used to set the new frame of reference for this observer.
2. 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.
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:

obs = celestia:getobserver()
actual_frame = obs:getframe()

Return to the observer method index.

setframe

observer:setframe(frame:f)

Set the new frame of reference for this observer.

Arguments:

f

The new frame of reference for this observer. Must be a "frame" object.

Notes:

1. The observer:getframe() method can be used to obtain the current frame of reference for this observer.
2. The celestia:newframe() method can be used to create a new reference frame as a "frame" object.

Example-1:
Tell Celestia to set the active Coordinate System to UNIVERSAL:

frame = celestia:newframe("universal")
obs = celestia:getobserver()
obs:setframe(frame)

Example-2:
The following example selects the Moon, then sets the active Coordinate System to CHASE and goes to the Moon:

moon = celestia:find("Sol/Earth/Moon")
celestia:select(moon)
frame = celestia:newframe("chase", moon)
obs = celestia:getobserver()
obs:setframe(frame)
obs:goto(moon, 2.0)
wait(2.0)

Example-3:
Tell Celestia to set the active Coordinate System to LOCK the Earth with the Sun. The example will maintain your position with respect to the center of the Earth, and keep both the Sun (Sol) and the Earth in view when time passes. Before running this example, be sure both the Earth and the Sun are already in the view of the observer.

earth = celestia:find("Sol/Earth")
celestia:select(earth)
sun = celestia:find("Sol")
frame = celestia:newframe("lock", earth, sun)
obs = celestia:getobserver()
obs:setframe(frame)
celestia:settimescale(50000)

Return to the observer method index.

splitview

1.3.2 observer:splitview(string:splitdirection [, number:splitpos])

Split the view for this observer.

Arguments:

splitdirection

String used to determine in which direction the screen must be split. Must be:

• "H" for a horizontal split.
• "V" for a vertical split.

splitpos [optional]

Where to split the active view as a percent number between 0 (left/down) and 1 (richt/up). Default is 0.5 (in the middle).

• If splitpos is smaller than 0.1, splitpos will be adjusted to 0.1.
• If splitpos is greater than 0.9, splitpos will be adjusted to 0.9.

Notes:

1. The celestia:getobservers() method can be used after using this observer:splitview() method, to obtain an "observer" object for each view.

Example:
Split the actual view in the middle vertically. Left goto Venus, right goto Mars and restore singleview after 10 seconds again.

obs = celestia:getobserver()
obs:splitview("V", 0.5)
observers = celestia:getobservers()
venus = celestia:find("Sol/Venus")
observers[1]:gotodistance(venus, 50000)
mars = celestia:find("Sol/Mars")
observers[2]:gotodistance(mars, 30000)
wait(10.0)
obs:singleview()

Return to the observer method index.

deleteview

1.3.2 observer:deleteview()

Delete the view of this observer.

After using this method, the observer becomes invalid.

Notes:

1. Using this method only makes sense if there is at least one Mulitiview left. This method has no effect on a singleview observer.

Example:
Split the actual view in the middle vertically. Left goto Venus, right goto Mars and after 10 seconds, delete the view on Venus.

obs = celestia:getobserver()
obs:splitview("V", 0.5)
observers = celestia:getobservers()
venus = celestia:find("Sol/Venus")
observers[1]:gotodistance(venus, 50000)
mars = celestia:find("Sol/Mars")
observers[2]:gotodistance(mars, 30000)
wait(10.0)
observers[1]:deleteview()

Return to the observer method index.

singleview

1.3.2 observer:singleview()

Make the view of this observer the only view.

All other observer views will be deleted and become invalid at once.

Notes:

1. This method is also useful in the function celestia_cleanup_callback(), so the single view will always be restored at script end or script termination.

Example:
Create a multiview of 4 observers and after a few seconds, make the 4^th observer the only view.

obs = celestia:getobserver()
obs:splitview("V", 0.5)
observers = celestia:getobservers()
observers[1]:splitview("H", 0.5)
observers[2]:splitview("H", 0.5)
observers = celestia:getobservers()
mercury = celestia:find("Sol/Mercury")
observers[1]:gotodistance(mercury, 20000)
venus = celestia:find("Sol/Venus")
observers[2]:gotodistance(venus, 50000)
mars = celestia:find("Sol/Mars")
observers[3]:gotodistance(mars, 30000)
io = celestia:find("Sol/Jupiter/Io")
observers[4]:gotodistance(io, 15000)
celestia:print("Which view does not belong in this scene?", 10.0, -1, -1, 2, 4)
wait(10.0)
observers[4]:singleview()
celestia:print("This view, because Io is a moon of\n" ..
               "Jupiter, instead of a planet.", 10.0, -1, -1, 2, 4)
wait(10.0)

Return to the observer method index.

isvalid

1.3.2 boolean observer:isvalid()

Return a boolean, indicating whether or not an observer is still valid:

• true if this observer is still valid.
• false if this observer is NOT valid anymore.

Example:
Create a multiview, then delete some views and determine which observer is still valid.

obs = celestia:getobserver()
obs:splitview("V", 0.5)
observers = celestia:getobservers()
observers[1]:splitview("H", 0.5)
observers[2]:splitview("H", 0.5)
observers = celestia:getobservers()
mercury = celestia:find("Sol/Mercury")
observers[3]:gotodistance(mercury, 20000)
venus = celestia:find("Sol/Venus")
observers[1]:gotodistance(venus, 50000)
earth = celestia:find("Sol/Earth")
observers[4]:gotodistance(earth, 50000)
mars = celestia:find("Sol/Mars")
observers[2]:gotodistance(mars, 30000)
celestia:print("The 4 inner planets of our Solar System.", 10.0, -1, -1, 2, 4)
wait(10.0)
observers[4]:singleview()
celestia:print("Back to our own planet", 3.0, -1, -1, 2, 4)
wait(3.0)
valid = { }
for key, value in pairs(observers) do 
   valid[key] = observers[key]:isvalid() 
   if valid[key] then
      celestia:print("Observer " .. key .. " is valid.", 3.0, -1, -1, 2, 4)
   else
      celestia:print("Observer " .. key .. " is NOT valid.", 3.0, -1, -1, 2, 4)
   end
   wait(3.5)
end

Return to the observer method index.

gettrackedobject

1.5.0 object observer:gettrackedobject()

Return the currently tracked object in a CELX "object" object.

Notes:

1. If no object is currently tracked, an empty object is returned. An empty object is different from nil!
2. A CELX "object" object does refer to a celestial object like a planet or a star, but it can also be a location or spacecraft.
3. 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:
Display the currently tracked object name in this observer. The example can be terminated by pressing the [Esc] key on the keyboard.
While running this example, you can select different objects and press the [T] key on the keyboard to track or stop tracking the object.

while true do
   obs = celestia:getobserver()
   tracked_obj = obs:gettrackedobject()
   tracked_obj_name = tracked_obj:name()
   if tracked_obj_name == "?" then
      celestia:print("No object currently tracked")
   else
      celestia:print("Tracking "..tracked_obj_name)
   end
   wait(0)
end

Return to the observer method index.

makeactiveview

1.6.0 observer:makeactiveview()

Make the view of this observer the current active view.

Example:
After creating a Multiview, determine which observer is the active view and restore sinleview for that observer.

obs = celestia:getobserver()
obs:splitview("V", 0.5)
observers = celestia:getobservers()
venus = celestia:find("Sol/Venus")
observers[1]:gotodistance(venus, 50000)
mars = celestia:find("Sol/Mars")
observers[2]:gotodistance(mars, 30000)
wait(10.0)
observers[1]:makeactiveview()
obs = celestia:getobserver()
obs:singleview()

Return to the observer method index.

orbit

1.6.1 observer:orbit(rotation:rot)

Orbit the observer around the current reference object according the given rotation.

Arguments:

rot

The rotation to be used by this observer for the orbit. Must be a "rotation" object.

Notes:

1. This method sets the new observer position and orientation immediately. To more simulate the CEL: ORBIT command and let the observer orbit during a period of time, the rotation angle can be split up in more smaller rotation angles, which are quickly processed after each other, by using this observer:orbit() method in a Lua "for" or "while" control structure (see next notes).
2. When using this observer:orbit() method in a Lua "for" control structure (see example-1), the orbit period will take a fraction longer than number:duration seconds (depending on the speed of your computer), but the total orbit angle around the specified axis will be exactly correct. This because the commands in the generated loop also take some additional computer time to execute. In case of a slower computer, you can decrease the number of steps per second, but that can also mean the scene becomes more jerkier.
3. It is also possible to use this observer:orbit() method in a Lua "while" control structure, (see example-2). In that case the orbit period can be set exactly to the number:duration seconds, but the total orbit angle around the specified axis will NOT be exactly correct. Again depending on the speed of your computer, you'll have to make a guess about the step-angle or wait-time for each sequence in the "while" control structure, to end up as close to the total target orbit angle as possible.
4. In case of the universal frame of reference, where no reference object is present, using this observer:orbit() method will not result in an observer orbit, even if an object is selected!

Example-1:
Select, follow and center Earth, then orbit the observer during about 10 seconds over exactly 360 degrees, along the Y axis of Earth.

-- Find, select, follow and center Earth first.
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs = celestia:getobserver()
obs:follow(earth)
obs:center(earth, 1.0)
wait(1.0)
-- Orbit during about 10 seconds over 360 degrees, around the Y axis
duration = 10.0
orbitangle = math.rad(360.0)
axis_vector = celestia:newvector(0,1,0)
-- Split up the orbit in 30 steps per second and determine the orbit steptime for each single step.
-- The factor 0.75 is an estimate and may depend on the speed of your computer.
orbitsteps = 30 * duration
orbitsteptime = 0.75*duration/orbitsteps
-- Create new rotation object of split up orbit angle around the specified axis.
rot = celestia:newrotation(axis_vector, orbitangle/orbitsteps)
-- Actually execute the orbit.
for i = 1, orbitsteps do
   obs:orbit(rot)
   wait(orbitsteptime)
end

Example-2:
Select, follow and center Earth, then orbit the observer during exactly 10 seconds over about 360 degrees, along the Y axis of Earth.

-- Find, select, follow and center Earth first.
earth = celestia:find("Sol/Earth")
celestia:select(earth)
obs = celestia:getobserver()
obs:follow(earth)
obs:center(earth, 1.0)
wait(1.0)
-- Orbit during 10 seconds over about 360 degrees, around the Y axis
duration = 10.0
orbitangle = math.rad(360.0)
axis_vector = celestia:newvector(0, 1, 0)
-- Split up the orbit in 30 steps per second and determine the orbit steptime for each single step.
-- The factor 0.75 is an estimate and may depend on the speed of your computer.
orbitsteps = 30 * duration
orbitsteptime = 0.75*duration/orbitsteps
-- Create new rotation object of split up orbit angle around the specified axis.
rot = celestia:newrotation(axis_vector, orbitangle/orbitsteps)
-- Get the elapsed time in seconds since the script has been started and store in "t0". 
t0 = celestia:getscripttime()
-- Actually execute the orbit
while celestia:getscripttime() <= t0 + duration do
   obs:orbit(rot)
   wait(orbitsteptime)
end

Return to the observer method index.