Celx Scripting: Vector

vector

A "vector" object in Celestia is a 3-tuple of double precision floating point values, which represent a geometric object that has both a length and direction [X, Y, Z] in a 3 dimensional coordinate system.

Within a CELX script, the vector methods need to be prefixed with the obtained "vector" object, separated with a semicolon.

The following methods can be used to obtain a "vector" object:

Using the celestia:newvector() method.
Using the position:vectorto() method.
Using the vector:normalize() method.
Using the rotation:imag() method.
Using the rotation:transform() method.
By subtracting two "position" objects.

Notes:

Vector components (X,Y,Z) in Celestia are stored in millionths of a light year. So when you have your own vectors defined in km or miles, you have to convert these vectors. 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

Operators

"Vector" 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 - vector → position
vector + vector → vector
vector - vector → vector

Scalar multiplication with "Vector" objects:

number * vector → vector
vector * number → vector

The * operator gives the dot product of two vectors v and w:

v * w = v.x*w.x + v.y*w.y + v.z*w.z → number

The ^ operator gives the cross product of two vectors v and w:

v ^ w = [(v.y*w.z - v.z*w.y), (v.z*w.x - v.x*w.z), (v.x*w.y - v.y*w.x)] → vector

The new vector is perpendicular (according the right-hand rule) to the plane containing the two input vectors

v ^ w = - w ^ v

Be careful when using this: ^ is normally the exponentiation operator in Lua, and thus has higher precedence than almost any other operator, including unary minus.

Members

You can access and assign the x, y, and z components of a "vector" object directly, e.g.

vec = celestia:newvector(0, 0, 0)
vec.x = vec.x + 1

Methods

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

getx

number vector:getx()

Return the X coordinate of the vector as a number.

Example:
Get a vector giving the heliocentric position of the Earth and display the X-, Y- and Z-components of that vector in the lower left corner of your screen.

now = celestia:gettime()
sunpos = celestia:find("Sol"):getposition(now)
earthpos = celestia:find("Sol/Earth"):getposition(now)
heliovector = sunpos:vectorto(earthpos)
heliovector_x = heliovector:getx()
heliovector_y = heliovector:gety()
heliovector_z = heliovector:getz()
celestia:print("Heliocentric position of Earth:\nX = " .. heliovector_x .. 
               "\nY = " .. heliovector_y .. "\nZ = " .. heliovector_z, 10, -1, -1, 1, 6)
wait(10.0)

Return to the vector method index.

gety

number vector:gety()

Return the Y coordinate of the vector as a number.

Example:
Get a vector giving the heliocentric position of the Earth and display the X-, Y- and Z-components of that vector in the lower left corner of your screen.

now = celestia:gettime()
sunpos = celestia:find("Sol"):getposition(now)
earthpos = celestia:find("Sol/Earth"):getposition(now)
heliovector = sunpos:vectorto(earthpos)
heliovector_x = heliovector:getx()
heliovector_y = heliovector:gety()
heliovector_z = heliovector:getz()
celestia:print("Heliocentric position of Earth:\nX = " .. heliovector_x .. 
               "\nY = " .. heliovector_y .. "\nZ = " .. heliovector_z, 10, -1, -1, 1, 6)
wait(10.0)

Return to the vector method index.

getz

number vector:getz()

Return the Z coordinate of the vector as a number.

Example:
Get a vector giving the heliocentric position of the Earth and display the X-, Y- and Z-components of that vector in the lower left corner of your screen.

now = celestia:gettime()
sunpos = celestia:find("Sol"):getposition(now)
earthpos = celestia:find("Sol/Earth"):getposition(now)
heliovector = sunpos:vectorto(earthpos)
heliovector_x = heliovector:getx()
heliovector_y = heliovector:gety()
heliovector_z = heliovector:getz()
celestia:print("Heliocentric position of Earth:\nX = " .. heliovector_x .. 
               "\nY = " .. heliovector_y .. "\nZ = " .. heliovector_z, 10, -1, -1, 1, 6)
wait(10.0)

Return to the vector method index.

normalize

vector vector:normalize()

Return a normalized "vector" object.
A normalized vector is a vector that points in the same direction as the original vector, but with length = 1.

Notes:

This method does not modify the original vector.
Normalizing a zero-length vector causes division by zero. The result will be a vector of NaNs.
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:
create a vector that points from the actual position of Earth to the actual position of the Moon, with length = 1.

earth = celestia:find("Sol/Earth")
moon = celestia:find("Sol/Earth/moon")
now = celestia:gettime()
earthpos = earth:getposition(now)
moonpos = moon:getposition(now)
vector = earthpos:vectorto(moonpos)
n_vector = vector:normalize()

Return to the vector method index.

length

number vector:length()

Return the length of this vector in in millionths of a light year, as a number.

Example:
Display the actual distance from the center of Earth to the center of the Moon in km.

uly_to_km = 9460730.4725808
earth = celestia:find("Sol/Earth")
moon = celestia:find("Sol/Earth/moon")
now = celestia:gettime()
earthpos = earth:getposition(now)
moonpos = moon:getposition(now)
vector = earthpos:vectorto(moonpos)
distance = vector:length() * uly_to_km
celestia:print("Actual distance center Earth - center Moon: " .. distance .. " km.", 10.0, -1, -1, 2, 4)
wait(10.0)

Return to the vector method index.