Celestia/Celx Scripting/CELX Lua Methods/Celx vector

= 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:
 * 1) 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:
 * 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

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: The new vector is perpendicular (according the right-hand rule) to the plane containing the two input vectors 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.
 * 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
 * v ^ w = - w ^ v

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

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

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

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

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:
 * 1) This method does not modify the original vector.
 * 2) Normalizing a zero-length vector causes division by zero. The result will be a vector of NaNs.
 * 3) A CELX "vector" object is a geometric object that has both a length and direction [X, Y, Z] in a 3 dimensional coordinate system.
 * 4) 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

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.