# Celx Scripting: Position
## position

A "position" object contains the exact coordinates of a point in space. A "position" object is relative to a coordinate system (i.e. a frame of reference, see Celx Scripting: Frame) and may need to be converted to or from universal coordinates before further use.
Within a CELX script, the position methods need to be prefixed with the obtained "position" object, separated with a colon.
The following methods can be used to obtain a "position" object:
* Using the celestia:newposition method.
* Using the celestia:newposition(base64) method.
* Using the observer:getposition method.
* Using the object:getposition method.
* Using the position:addvector method.
* Using the frame:to method.
* Using the frame:from method.
* Using the 1.6.0 phase:getposition method.
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
* Internally "position" objects use 128 bit per component and therefore have higher precision than available directly in Lua (which typically uses 64-bit IEEE754 double precision floating point numbers). The calculations that you can perform however on a "position" object are limited, so you'll often want to convert "position" objects to normal Lua numbers. In order to avoid precision problems, the usual practice is to convert a "position" object to a "vector" object, relative to the origin (such as the Sun or Solar System Barycenter). You can do this by subtracting the origin's position from the object- or observer position to get a "vector" object like this:

## Operators

"Position" objects can be added and subtracted from each other. It is also possible to add a "position" object with a "vector" object, or subtract a "vector" object from a "position" object.
* position + vector → position
* position + position → position
* position - position → vector
* position - vector → position
Note:Subtracting two "position" objects produces a "vector" object and NOT a "position" object.

## Members

You can access and assign the x, y, and z components of a "position" object directly, e.g.
Note: Accessing components this way returns normal Lua numbers, which have less precision than the 128-bit values stored in a "position" object.

## Methods

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

### addvector

position position:addvector(vector:vec)
Add a vector to the position and return the result as a "position" object.
Arguments:

#### vec

    The vector to be added to the position. Must be a "vector" object.
Notes:
* You can also use position = position + vector instead of this position:addvector method. Both have the same result.
* Like position components, the vector components (X,Y,Z) in Celestia are also stored in millionths of a light year.
* 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: Goto a position in space just beside the path where Earth will be over 1 day. Look from that position at Earth and see how Earth comes towards you and just misses you (time is sped up 3600x).
Return to the position method index.

### vectorto

vector position:vectorto(position:target)
Return the "vector" object, pointing from this position to the target position.
Arguments:

#### target

    The target position the vector should be pointing to. Must be a "position" object.
Notes:
* You can also use vector = position target - position source instead of this position:vectorto method. Both have the same result.
* The precision of a vector (IEEE754 double precision floating point) may be insufficient to express this distance exactly.
* A CELX "vector" object is a geometric object that has both a length and direction [X, Y, Z] in a 3 dimensional coordinate system.
* The vector methods can be used on a CELX "vector" object. "Vector" objects can also be used in other methods, requiring a "vector" object as an argument.
Example: Get a vector, giving the heliocentric position of the Earth
Return to the position method index.

### distanceto

number position:distanceto(position:target)
Return the distance in kilometers from this position to the target position, as a number.
Arguments:

#### target

    The target position the distance must be calculated to. Must be a "position" object.
Example: Determine and display the actual distance from the obserber to Neptune.
Return to the position method index.

### orientationto

rotation position:orientationto(position:target, vector:up)
Return a "rotation" object which can be used to orient a viewer to point from this position toward the target position.
Arguments:

#### target

    The target position at which the viewer should focus on. Must be a "position" object.

#### up

    The up vector, defining which axis should be pointing up. Must be a "vector" object. Must not be parallel to the target direction, otherwise the rotation is undefined.
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: Goto a position just beside Mars and orient the observer towards the planet.
Return to the position method index.

### getx

number position:getx
Return the X coordinate of the position as a number.
Notes:
* The precision is returned as a double-precision floating point value and may not have sufficient precision to express the exact position.
Example: Get the actual position of Earth and display the X-, Y- and Z-components of that position in the lower left corner of the screen.
Return to the position method index.

### gety

number position:gety
Return the Y coordinate of the position as a number.
Notes:
* The precision is returned as a double-precision floating point value and may not have sufficient precision to express the exact position.
Example: Get the actual position of Earth and display the X-, Y- and Z-components of that position in the lower left corner of the screen.
Return to the position method index.

### getz

number position:getz
Return the Z coordinate of the position as a number.
Notes:
* The precision is returned as a double-precision floating point value and may not have sufficient precision to express the exact position.
Example: Get the actual position of Earth and display the X-, Y- and Z-components of that position in the lower left corner of the screen.
Return to the position method index.