Module Core.Vector
CORE - Vector algebra.
Main Features:
- Easy vector algebra function
- Redefinition of
+,-,*,/,%operators to be compatible with vectors - Interface to DCS API functions
- Reduced confusion of DCS coordinate system
- Better performance than related classes (COORDINATE, POINT_VEC)
Example Missions:
Demo missions can be found on github.
Author: funkyfranky
Global(s)
Global VECTOR |
Mathematics knows no races or geographic boundaries; for mathematics, the cultural world is one country. --David Hilbert The VECTOR ConceptThe VECTOR class has a great concept! https://github.com/automattf/vector.lua/blob/master/vector.lua The DCS Coordinate SystemDCS has a rather unconventional way to define the coordinate system. |
Mathematics knows no races or geographic boundaries; for mathematics, the cultural world is one country. --David Hilbert
The VECTOR Concept
The VECTOR class has a great concept!
https://github.com/automattf/vector.lua/blob/master/vector.lua
The DCS Coordinate System
DCS has a rather unconventional way to define the coordinate system.
The definition even depends whether you work with a 2D vector or a 3D vector. The good think is, that you usually do not need to worry about this unless you directly call the DCS API functions. Plus, this class tries to hide the differences between 2D and 3D conventions as good as possible with internal if-cases.
Still, it is important to unterstand the differences. So let us explain:
Usually, we draw a coordinate system in 2D and label the horizonal axis (pointing right) as the x-axis. The vertical axis (poining up on a piece of paper)
3D
The x-axis points North. The z-axis points East. The y-axis points upwards and defines the altitue with respect to the mean sea level.
2D
The x-axis points North (just like in the 3D) case. The y-axis points East.
Constructors
There are different ways to create a new instance of a VECTOR. All methods start with New.
From Components
From 2D or 3D Vectors
From Polar Coordinates
From Spherical Coordinates
Operators
Addition [MATH] +
Subtraction [MATH] -
Multiplication [MATH] *
Devision [MATH] /
Modulo [MATH] %
DCS API Interface
This class offers easy and convenient ways to access all vector related DCS API functions.
Land and Surface
Atmosphere
Effects and Actions
Map Markings
Coordinates
Inferface to other MOOSE Classes
Of course, this class is interfaced with other MOOSE classes in the sense that you can obtain and work with VECTOR instances from MOOSE objects, from which a position or direction vector can be derived.
GROUP
UNIT
STATIC
SCENERY
ZONE
Examples
A new VECTOR object can be created with the VECTOR.New function.
Here we create two vectors, a and b, and add them to create a new vector c.
local a=VECTOR:New(1, 0)
local b=VECTOR:New(0, 1)
local c=a+b
This is how it works.
Global _VECTORID |
VECTOR unique ID |
VECTOR unique ID
Type(s)
| Fields and Methods inherited from VECTOR | Description |
|---|---|
|
Add a vector to this. |
|
VECTOR:ArrowTo(Vector, Coalition, Color, FillColor, LineType) |
Creates a arrow from this VECTOR to another vector on the F10 map. |
|
Name of the class. |
|
|
Get a clone (deep copy) of this vector. |
|
|
Calculate the dot product of this VECTOR with another vector. |
|
|
Creates an explosion at a given point at the specified power. |
|
|
Creates a signal flare at the given point in the specified color. |
|
|
Get a vector on the closest railroad. |
|
|
Get a vector on the closest road. |
|
|
Get a COORDINATE object. |
|
|
Get the directional vector that points from another VECTOR |
|
|
Get the directional vector that points from this VECTOR to another VECTOR |
|
|
Get the distance from this vector to another vector. |
|
|
Get heading of vector. |
|
|
Get the difference of the heading of this vector w. |
|
|
Get the heading from a given vector to this vector. |
|
|
Get the heading from this vector to another given vector. |
|
|
Returns an intercept point at which a ray drawn from the this vector in the passed normalized direction for a specified distance. |
|
|
Return an intermediate VECTOR between this and another given vector. |
|
|
Get latitude and longitude of this vector. |
|
|
Get length/norm/magnitude of this vector. |
|
|
Get MGRS information of this vector. |
|
|
Get the path on road from this vector to a given other vector. |
|
|
Get profile of the land between the two passed points. |
|
|
Returns the distance from sea level at this vector. |
|
|
Returns the distance from sea level at this vector. |
|
|
Get the surface type at the vector. |
|
|
Get the name of surface type at the vector. |
|
|
Returns a temperature and pressure at this vector. |
|
|
Get 2D vector as simple table. |
|
|
Get 3D vector as simple table. |
|
|
Returns a velocity vector of the wind at this vector. |
|
|
Creates an illumination bomb at the specified point. |
|
|
Check if a given vector has line of sight with this vector. |
|
|
Create mark on F10 map. |
|
|
Create a new VECTOR class instance from given cartesian coordinates |
|
|
Get the directional vector that points from a given vector |
|
|
Creates a new VECTOR instance from given the latitude and longitude in decimal degrees (DD). |
|
|
Creates a new VECTOR instance from given latitude and longitude in degrees, minutes and seconds (DMS). |
|
|
Create a new VECTOR class instance from polar coordinates (r, phi). |
|
|
Create a new VECTOR class instance from spherical coordinates (r, theta, phi). |
|
|
Create a new VECTOR class instance from given 2D or 3D vector object. |
|
|
Normalize this vector, so that has a length of 1. |
|
|
Replace this vector with another one. |
|
|
Calculate the rotation or cross product of this VECTOR with another vector. |
|
|
Rotate the VECTOR clockwise in the 2D (x,z) plane. |
|
|
Set length/norm/magnitude of this vector. |
|
|
Set x-component of vector. |
|
|
Set y-component of vector. |
|
|
Set z-component of vector. |
|
|
Creates a smoke at this vector. |
|
|
Creates a large smoke and fire effect of a specified type and density at this vector. |
|
|
Stop smoke or fire effect. |
|
|
Subtract a vector from this one. |
|
|
Provides an MGRS string. |
|
|
Translate the vector by a given distance and angle. |
|
|
Check if passed object is a Vector. |
|
|
Meta function to add vectors together. |
|
|
Meta function for dividing a vector by a scalar or by another vector. |
|
|
Meta function to check if two vectors are equal. |
|
|
VECTOR private index. |
|
|
Meta function to multiplicate vector by another vector or a scalar. |
|
|
Meta function to subtract vectors. |
|
|
Meta function to change how vectors appear as string. |
|
|
Meta function to make vectors negative. |
|
|
Verbosity of output. |
|
|
VECTOR class version. |
|
|
Component pointing North if > 0 and South if < 0. |
|
|
Component pointing up if >0 and down if < 0. This describes the altitude above main sea level. |
|
|
Component pointing East if > 0 and West if < 0. |
VECTOR class.
Field(s)
Name of the class.
Verbosity of output.
VECTOR class version.
Component pointing North if > 0 and South if < 0.
Component pointing up if >0 and down if < 0. This describes the altitude above main sea level.
Component pointing East if > 0 and West if < 0.
Function(s)
Add a vector to this.
This function works for DCS#Vec2, DCS#Vec3, VECTOR, COORDINATE objects.
Note that if you want to add a VECTOR, you can also simply use the + operator.
Creates a arrow from this VECTOR to another vector on the F10 map.
Defined in:
VECTOR
Parameters:
#VECTOR Vector
The vector defining the endpoint.
#number Coalition
Coalition Id: -1=All, 0=Neutral, 1=Red, 2=Blue. Default -1.
#table Color
RGB color with alpha {r, g, b, alpha}. Default {1, 0, 0, 0.7}.
#table FillColor
RGB color with alpha {r, g, b, alpha}. Default {1, 0, 0, 0.5}.
#number LineType
Line type: 0=No line, 1=Solid, 2=Dashed, 3=Dotted, 4=Dot Dash, 5=Long Dash, 6=Two Dash. Default 1.
Return value:
#number:
Marker ID. Can be used to remove the drawing.
Get a clone (deep copy) of this vector.
Calculate the dot product of this VECTOR with another vector.
This function works for DCS#Vec2, DCS#Vec3, VECTOR, COORDINATE objects.
Defined in:
VECTOR
Parameter:
DCS#Vec3 Vec
The other vector. Can also be a DCS#Vec2, DCS#Vec3, COORDINATE or VECTOR object.
Return value:
#number:
Dot product Sum_i(a[i]*b[i]). Note that this is a scalar and not a vector any more!
Creates an explosion at a given point at the specified power.
Defined in:
VECTOR
Parameter:
#number Power
The power in kg TNT. Default 100 kg.
Return value:
self
Creates a signal flare at the given point in the specified color.
The flare will be launched in the direction of the azimuth angle.
Defined in:
VECTOR
Parameters:
#number Color
Color of flare. Default Green.
#number Azimuth
Azimuth angle in degrees. Default 0.
Return value:
self
Get a vector on the closest railroad.
Get a vector on the closest road.
Get a COORDINATE object.
Defined in:
VECTOR
Parameter:
#boolean OnSurface
If true, the y component is set the land height [m] of the 2D position.
Return value:
The COORDINATE object.
Get the directional vector that points from another VECTOR a to this VECTOR.
Get the directional vector that points from this VECTOR to another VECTOR a.
Get the distance from this vector to another vector.
Defined in:
VECTOR
Parameters:
#VECTOR Vector
Vector to which the distance is requested.
#boolean Only2D
If true, calculate only the projected 2D distance.
Return value:
#number:
Distance in meters.
Get heading of vector.
Note that a heading of
- 000° = North
- 090° = East
- 180° = South
- 270° = West.
Defined in:
VECTOR
Parameter:
#boolean To360
If true or nil, adjust heading to [0,360) range. If false, headings not in this range can occur.
Return value:
#number:
Heading in degrees.
Get the difference of the heading of this vector w.
Example 1: This vector has a heading of 90° (pointing East) and the other vector has a heading of 225° (pointing South-West), we would optain a delta of 225°-90°=135°.
Example 2: This vector has a heading of 180 (pointing South) and the other vector has a heading of 90° (pointing East), we would optain a delta of 90°-180°=-90°.
Defined in:
VECTOR
Parameter:
#VECTOR Vector
Vector to which the heading is requested.
Return value:
#number:
Heading from this vector to the other vector in degrees.
Get the heading from a given vector to this vector.
Defined in:
VECTOR
Parameter:
#VECTOR Vector
Vector from which the heading is requested.
Return value:
#number:
Heading from the other vector to this vector in degrees.
Get the heading from this vector to another given vector.
Defined in:
VECTOR
Parameter:
#VECTOR Vector
Vector to which the heading is requested.
Return value:
#number:
Heading from this vector to the other vector in degrees.
Returns an intercept point at which a ray drawn from the this vector in the passed normalized direction for a specified distance.
Return an intermediate VECTOR between this and another given vector.
Get latitude and longitude of this vector.
Defined in:
VECTOR
Return values:
#number:
Latitude in decimal degrees (DD).
#number:
Longitude in decimal degrees (DD).
Get length/norm/magnitude of this vector.
Defined in:
VECTOR
Return value:
#number:
Length of vector.
Get MGRS information of this vector.
MGRS = {UTMZone = string, MGRSDigraph = string, Easting = number, Northing = number}
Defined in:
VECTOR
Return value:
#table:
MGRS table with UTMZone, MGRSDiGraph, Easting and Northing keys.
Get the path on road from this vector to a given other vector.
Defined in:
VECTOR
Parameter:
#VECTOR Vec
The destination vector.
Return value:
Pathline with points on road.
Get profile of the land between the two passed points.
Defined in:
VECTOR
Parameter:
#VECTOR Vec3
The 3D destination vector. If a 2D vector is passed, y is set to the land height.
Return value:
Pathline with points of the profile.
Returns the distance from sea level at this vector.
Defined in:
VECTOR
Return value:
#number:
Distance above sea leavel in meters.
Returns the distance from sea level at this vector.
Defined in:
VECTOR
Return values:
#number:
Heigh above sea leavel in meters.
#number:
Depth (positive) at this point in meters.
Get the surface type at the vector.
- LAND = 1
- SHALLOW_WATER = 2
- WATER = 3
- ROAD = 4
- RUNWAY = 5
Defined in:
VECTOR
Return value:
#number:
Surface type
Get the name of surface type at the vector.
- LAND = 1
- SHALLOW_WATER = 2
- WATER = 3
- ROAD = 4
- RUNWAY = 5
Defined in:
VECTOR
Return value:
#string:
Surface type name
Returns a temperature and pressure at this vector.
Defined in:
VECTOR
Return values:
#number:
Temperatur in Kelvin.
#number:
Pressure in Pascals.
Get 2D vector as simple table.
Get 3D vector as simple table.
Defined in:
VECTOR
Parameter:
#boolean OnSurface
If true, the y component is set the land height [m] of the 2D position.
Return value:
3D array {x=x, y=y, z=z}.
Returns a velocity vector of the wind at this vector.
Turbolences can be optionally be included.
Defined in:
VECTOR
Parameter:
#boolean WithTurbulence
If true, return wind including turbulence.
Return value:
Velocity 3D vector [m/s] the wind is blowing to.
Creates an illumination bomb at the specified point.
Defined in:
VECTOR
Parameters:
#number Power
The power in Candela (cd). Should be between 1 and 1000000. Default 1000 cd.
#number Altitude
(Optional) Altitude [m] at which the illumination bomb is created.
Return value:
self
Check if a given vector has line of sight with this vector.
Create mark on F10 map.
Defined in:
VECTOR
Parameters:
#string MarkText
Free format text that shows the marking clarification.
#number Recipient
Recipient of the mark: -1=All (default), 0=Neutral, 1=Red, 2=Blue. Can also be a GROUP object.
#boolean ReadOnly
(Optional) Mark is readonly and cannot be removed by users. Default false.
Return value:
#number:
Mark ID.
Create a new VECTOR class instance from given cartesian coordinates x, y and z, where z is optional.
Note that whether the z component is passed or nil has great impact on the interpretation of the y component.
If z is not given (nil), then y is used as z (the coordinate pointing East) because we always constuct a 3D vector.
If z is given (not nil), then y is used as coordinate pointing up (out of plane) as for all 3D DCS vectors.
Defined in:
VECTOR
Parameters:
#number x
Component of vector along x-axis (pointing North in both 2D and 3D).
#number y
Component of vector along y-axis (pointing East in 2D and Up in 3D).
#number z
(Optional) Component of the z-axis (pointing East in 3D).
Return value:
self
Get the directional vector that points from a given vector a to another given vector b.
The vector is c=-a+b=b-a.
Creates a new VECTOR instance from given the latitude and longitude in decimal degrees (DD).
Defined in:
VECTOR
Parameters:
#number Latitude
Latitude in decimal degrees.
#number Longitude
Longitude in decimal degrees.
#number Altitude
(Optional) Altitude in meters. Default is the land height at the 2D position.
Return value:
self
Creates a new VECTOR instance from given latitude and longitude in degrees, minutes and seconds (DMS).
Note that latitude and longitude are passed as strings and the characters °, ' and " are important.
Defined in:
VECTOR
Parameters:
#string Latitude
Latitude in DMS as string, e.g. "42° 24' 14.3"".
#string Longitude
Longitude in DMS as string, e.g. "42° 24' 14.3"".
#number Altitude
(Optional) Altitude in meters. Default is the land height at the coordinate.
Return value:
Create a new VECTOR class instance from polar coordinates (r, phi).
Defined in:
VECTOR
Parameters:
#number r
Distance.
#number phi
Angle in Degrees. Note that 0° corresponds to North, 90° East etc.
Return value:
self
Create a new VECTOR class instance from spherical coordinates (r, theta, phi).
Defined in:
VECTOR
Parameters:
#number r
Distance in meters with r>=0.
#number theta
Polar angle in Degrees measured from a fixed polar axis or zenith direction. This angle is in [0°, 180°].
#number phi
Azimuthal angle in Degrees. This angle is in [0°, 360°).
Return value:
self
Create a new VECTOR class instance from given 2D or 3D vector object.
Normalize this vector, so that has a length of 1.
Replace this vector with another one.
If the given vector is 2D, we
Calculate the rotation or cross product of this VECTOR with another vector.
This function works for DCS#Vec2, DCS#Vec3, VECTOR, COORDINATE objects.
Rotate the VECTOR clockwise in the 2D (x,z) plane.
Defined in:
VECTOR
Parameters:
#number Angle
Rotation angle in degrees). Default 0.
#boolean Copy
Create a copy of the VECTOR so the original stays unchanged.
Return value:
The translated vector or a copy of it.
Set length/norm/magnitude of this vector.
Defined in:
VECTOR
Parameter:
#number Length
Desired length of vector.
Set x-component of vector.
The x-axis points to the North.
Set y-component of vector.
The y-axis points to the upwards and describes the altitude above mean sea level.
Defined in:
VECTOR
Parameter:
#number y
Value of y. Default land/surface height at this point.
Return value:
self
Set z-component of vector.
The z-axis points to the East.
Creates a smoke at this vector.
Defined in:
VECTOR
Parameters:
#number Color
Color of the smoke: 0=Green, 1=Red, 2=White, 3=Orange, 4=Blue. Default 0.
#number Duration
(Optional) Duration of the smoke in seconds. Default nil.
Return value:
#string:
Name of the smoke object. Can be used to stop it.
Creates a large smoke and fire effect of a specified type and density at this vector.
- 1 = small smoke and fire
- 2 = medium smoke and fire
- 3 = large smoke and fire
- 4 = huge smoke and fire
- 5 = small smoke
- 6 = medium smoke
- 7 = large smoke
- 8 = huge smoke
Defined in:
VECTOR
Parameters:
#number Preset
Preset of smoke. Default BIGSMOKEPRESET.LargeSmokeAndFire.
#number Density
Density between [0,1]. Default 0.5.
#number Duration
(Optional) Duration of the smoke and fire in seconds.
Return value:
#string:
Name of the smoke. Can be used to stop it.
Stop smoke or fire effect.
Defined in:
VECTOR
Parameters:
#string Name
Name of the smoke object.
#number Delay
Delay in seconds before the smoke is stopped.
Return value:
self
Subtract a vector from this one.
This function works for DCS#Vec2, DCS#Vec3, VECTOR, COORDINATE objects.
Note that if you want to add a VECTOR, you can also simply use the - operator.
Provides an MGRS string.
Defined in:
VECTOR
Parameter:
Core.Settings#SETTINGS Settings
(Optional) The settings. Can be nil, and in this case the default settings are used. If you want to specify your own settings, use the _SETTINGS object.
Return value:
#string:
The MGRS text.
Translate the vector by a given distance and angle.
Defined in:
VECTOR
Parameters:
#number Distance
Distance in meters. Default 1000 meters.
#number Heading
Heading angle in degrees. Default 0° = North.
#boolean Copy
Create a copy of the VECTOR so the original stays unchanged.
Return value:
The translated vector or a copy of it.
Check if passed object is a Vector.
Defined in:
VECTOR
Parameter:
#table t
The object to be tested.
Return value:
#boolean:
Returns true if t is a #VECTOR and false otherwise.
Meta function to add vectors together.
Meta function for dividing a vector by a scalar or by another vector.
Meta function to check if two vectors are equal.
Meta function to multiplicate vector by another vector or a scalar.
Meta function to subtract vectors.
Meta function to change how vectors appear as string.
Defined in:
VECTOR
Return value:
#string:
String representation of vector.
Meta function to make vectors negative.