# 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:
* 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.
* 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:
* This command returns immediately, so you probably want to wait(number:duration) seconds, before continuing the script.
* When an "object" object is specified to goto, the final orientation will be towards the "object" object.
* When a position object is specified to goto, the final orientation will be the same as the initial orientation.
* 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.
* 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.
* 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.
* 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.
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.
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:
* This command returns immediately, so you probably want to wait(number:duration) seconds, before continuing the script.
* 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.
* 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.
* 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.
* 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.
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:
* 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).
* 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.
* 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.
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:
* This command returns immediately, so you probably want to wait(number:duration) seconds before continuing in your script.
* 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!
* 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.
* 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.
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:
* 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.
* 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.
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:
* The landing position will correspond with the longitude and latitude surface coordinates of the object you are hovering above, before the goto starts.
* 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.
* This command returns immediately, so you probably want to wait(number:duration) seconds before continuing in your script.
Example: Goto the surface of Mars.
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.
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:
* 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.
* 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.
* 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.
* If the target object is already centered on the screen, nothing will happen when using this method.
* If the current frame of reference is “universal”, nothing will happen when using this method.
Example:
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:
* This method can be useful in combination with the observer:cancelgoto method, which stops any goto or center currently in progress.
* 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.
Return to the observer method index.

### cancelgoto

1.3.2 observer:cancelgoto
Stop any goto or center command currently in progress.
Notes:
* 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.
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:
* 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.
* 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.
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:
* 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.
* The origin of the Celestia Coordinate System is the center of the reference object.
* 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.
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:
* 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.
* The origin of the Celestia Coordinate System is the center of the reference object.
* 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.
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:
* 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.
* The origin of the Celestia Coordinate System is the center of the reference object.
* 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.
* 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.
* 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.
* 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.
* 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).
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:
* 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.
* 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.
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:
* 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.
* 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
* 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.
* 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:
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:
* 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.
* 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.
Return to the observer method index.

### getorientation

rotation observer:getorientation
Return the current orientation of this observer, as a "rotation" object.
Notes:
* 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).
* 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:
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.
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:
* 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).
* 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.
* 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.
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.
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:
* 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...
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:
* 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.
* 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.
* To convert between UTC and TDB times, you can use the 1.5.0 celestia:utctotdb and 1.5.0 celestia:tdbtoutc methods.
* 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.
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:
* The speed of this observer can be set, using the observer:setspeed method.
* 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.
* 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).
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:
* The actual speed of this observer can be obtained by using the observer:getspeed method.
* 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.
* 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).
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:
* The empty string "" is returned when the 'Normal' surface is used.
Example:
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:
* 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:
Example:
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:
* 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:
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:
* The observer:getlocationflags method can be used to obtain the current settings for labeling of specific location types.
* The celestia:setminfeaturesize method can be used to set the minimum size for locations to be labeled.
* 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.
or shorter:
or even more shorter:
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:
* 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.
* 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).
* 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).
* 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.
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:
* 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.
* 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).
* 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).
* 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".
Return to the observer method index.

### getframe

frame observer:getframe
Return the frame of reference for this observer in a CELX "frame" object.
Notes:
* The observer:setframe method can be used to set the new frame of reference for this observer.
* 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.
* 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:
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:
* The observer:getframe method can be used to obtain the current frame of reference for this observer.
* 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:
Example-2: The following example selects the Moon, then sets the active Coordinate System to CHASE and goes to the Moon:
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.
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:
* 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.
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:
* 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.
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:
* 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.
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.
Return to the observer method index.

### gettrackedobject

1.5.0 object observer:gettrackedobject
Return the currently tracked object in a CELX "object" object.
Notes:
* If no object is currently tracked, an empty object is returned. An empty object is different from nil!
* 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.
* 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.
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.
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:
* 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).
* 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.
* 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.
* 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.
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.
Return to the observer method index.