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


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

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


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.

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:
 * 5) * From km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
 * 6) * 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:
 * 8) * millionths_of_a_light_year = number:km / uly_to_km
 * 9) * 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


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

Notes:
 * 1) Longitude and latitude are in radians (0 to 2*&pi;), 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:
 * 2) * radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
 * 3) * degrees = math.deg( number:radians ) = ( number:radians  * 180 / math.pi) = ( number:radians  * 180 / 3.14159265).
 * 4) 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.
 * 5) 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


Goto position target in duration seconds.

Notes: Example: Goto location: X = +7000km, Y = +9000km, Z = +11000km from the center of Earth.
 * 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:
 * 4) * From km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
 * 5) * From miles to millionths of a light year, use a constant uly_to_mls = 5912956.5453630.
 * 6) Next you can convert km or miles to millionths of a light year as follows:
 * 7) * millionths_of_a_light_year = number:km / uly_to_km
 * 8) * millionths_of_a_light_year = number:miles / uly_to_mls

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


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

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


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

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


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

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


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.

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

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


Activate follow-mode on target object.

Follow is the same as setting the frame of reference to "ecliptical" with target as reference 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


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.

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


Activate chase-mode on target object.

Chase-mode is the same as setting the frame of reference to "chase" with target as reference 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


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.

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


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

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

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:
 * 2) * From km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
 * 3) * 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:
 * 5) * millionths_of_a_light_year = number:km / uly_to_km
 * 6) * millionths_of_a_light_year = number:miles / uly_to_mls
 * 7) 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.
 * 8) 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


Set the new position of this observer.

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:
 * 2) * From km to millionths of a light year, use a constant uly_to_km = 9460730.4725808.
 * 3) * 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:
 * 5) * millionths_of_a_light_year = number:km / uly_to_km
 * 6) * 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

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


Set the new orientation of this observer.

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


Rotate the observer, according the given rotation.

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


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

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

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

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
number

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


Set the speed of this observer.

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

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


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

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
table

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


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

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

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&deg;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:
 * 4) * radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
 * 5) * degrees = math.deg( number:radians ) = ( number:radians  * 180 / math.pi) = ( number:radians  * 180 / 3.14159265).
 * 6) 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&deg;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&deg;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


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

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&deg;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:
 * 4) * radians = math.rad( number:degrees ) = ( number:degrees / 180 * math.pi) = ( number:degrees / 180 * 3.14159265).
 * 5) * degrees = math.deg( number:radians ) = ( number:radians  * 180 / math.pi) = ( number:radians  * 180 / 3.14159265).
 * 6) 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&deg;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&deg;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

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


Set the new frame of reference for this observer.

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


Split the view for this observer.

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

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
object

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


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

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.