Vec3 for (a) dummy, still confused

[ACS_Dev]

Hi,

I have read the documentation regarding vec3 coordinates many times, made a spreadsheet of vec3 readouts resulting from various aircraft orientations and searched both the forums and discords for a better understanding of the system but it still is not clicking for me.

I understand that vec3 has 4 components, each with a table of 3 values. The P value makes perfect sense to me, it is the others that are confusing. I don't understand why each of the other 3 values is a table, also of 3 values. Why not only 1? I can't really comprehend how they interact either.

Can anyone explain this better? I have been trying to wrap my head around this for days but so far have failed and it is extremely frustrating.

[Exorcet]

My understanding is the orientation for the object rotates with the object. The x, y, z after the p are telling you where the x axis, y axis, and z axis of the object are pointing.

 

This is 2D and not 3D, but the p would refer to the blue lines while the x would refer to the black x orientation line and y would refer to the black y orientation line (though I think that's actually z in DCS). The x and y are vec3 because you need the three components along the global x, y, z coordinate system to define them.

[Grimes]

https://www.khanacademy.org/math/linear-algebra/vectors-and-spaces might help. Its been 20 years since I've done any math related to this stuff. I just find code that seems to work and constantly re-use it. 

[cfrag]

21 hours ago, ACS_Dev said:

I have read the documentation regarding vec3 coordinates many times, made a spreadsheet of vec3 readouts resulting from various aircraft orientations and searched both the forums and discords for a better understanding of the system but it still is not clicking for me.

For better or worse, a good deal of this probably has to do with the fact that documentation around all things DCS mission API has room to grow.

Now, what may be confusing you are two related functions that return things that look very similar, sound very similar, and used radically different. This is further made difficult by the way that they are implemented in Lua, as Lua is a very clever programming language that can lead people like me to believe that they themselves are clever.

Let us start with the vec3 that you mention. Now, if you have done any vector algebra, the common use case for a vec3 is that of a 3D vector. If your eyes just glazed, here is a more detailed explanation. 

A "vector" in math is a construct that has a size (called "magnitude") and a direction. One very common representation of a vector we use is one that has 'coordinate offsets'. If you, for example, play Chess, you will notice that there are numbers from 1 through 8 and letters a through h along the side, allowing you to identify each and every field on the board uniquely by their position (offset from the origin). So the field in the bottom left corner would be identified as "a1", and the one in the upper right corner as "h8". Math takes this concept and makes it a bit more general, and uses number for every 'axis', so position "a1" becomes co-ordinates [1,1] and "h8" becomes [8,8].

When used with maps, we use the same principle, and can identify each position on the map as an offset to the 'origin' of the map - the point who has the co-ordinates [0,0]. Since we are talking about math, they love abstraction, and we can apply this principle not only to 2D maps, but also to more "dimensions", for example by adding height to a map, and suddenly every position is identified by the point on the map and the height it has - by three coordinates. And what points to this point from the origin of this system is the vector. One form of presentation is the vector that contains the offset for East/West, one for North/South, and one for Height. Which part of these co-ordinates is used for what is up to you (or the one who defines it, here ED and DCS)

DCS can be a bit difficult here because it uses a non-standard description for points in the world, and to make matters worse, it uses two different ways to represent this. One for points on a 2D map, where we use 2 coordinates, one called "x" (used in DCS for North/South) and one called "y" used only for maps to indicate East/West. That is often represented in the "vec2" data type. So we often have a vec2 implemented in Lua as {x = 123, y = 456}. (See Lua notes, below)

When we talk about points in the game (not just map), we need 3 coordinates, and DCS often uses the representation {x = 123, y = 456, z = 789}. Now, be aware that the context for y and z has changed: y now is height above ground, and z is the offset east/west

So, for most intents and purposes, when you deal with a variable "myVec" that is of type vec3 in DCS Lua, you are dealing with a table that has at least three attributes: myVec.x, myVec.y, myVec.z. 

Now, since this is Lua there are a number of important caveats:

• a table if type vec3 can have more attributes than just x, y, and z
• the type of the attributes x, y, and z should be a number, but it can be many different things, for example another table (as we see later) or string.

So, when we look at a standard Lua method to get a unit's 3D position while the mission is running, we invoke myPoint = myUnit:getPoint() and that returns a vec3 into myPoint with myPoint.x, myPoint.y and myPoint.z containing Northing,  Height, and Easting, respectively. This is mostly standard, except for the Lua caveats, and the somewhat funky assignments for x, y and z.

Now, you are surprised that sometimes you get something different. I know of one place where you may get thrown by this, and that is if you invoke the confusingly named "Unit:getPosition()" method. Although the name implies that you would be receiving the position of a unit in the game, a very close inspection of the description of the method shows you that you do not receive a vec3 as return value, but a construct called "position3". Now, to be absolutely frank: there are few worse ways imaginable to name both, because:

• getPosition() does not return a position
• position3 does not have 3 but 4 attributes
• three of the components confusingly are named "x", "y" and "z" but they are not numbers but vectors themselves.

The thing to take home here is that getPosition() DOES NOT RETURN A vec3. It returns a position3 type: a vector comprised of 4 (not 3) NON-NUMBER elements.

The position3 "vector" us used to describe a very important element in physics, it describes a state: where something is (a vec 3 describing a point), and how it is oriented there (the directions of its "up", "left" and "forward" in the "world"). Few people ever use the orientation values. You can use part of it to derive a unit's heading and velocity vector. The 'where' part is what you are looking for - it is the same vec3 that you would get if you invoked Unit:getPoint()

So, your confusion is probably caused by some very unfortunate naming from ED/DCS, and a severe lack of good documentation.

In a nutshell: a vec3 is a Lua table that usually contains the 3D offset of something from the local origin (the location [0, 0, 0] in its "x", "y" and "z" attributes.

The getPosition() method DOES NOT RETURN A POSITION and does not return a vec3. Don't use this method unless you absolutely know what you are doing, and are aware of the fact that it does not return a vec3.

Hope this helps a bit clearing this up. You have been misled  

Edited April 18, 2024 by cfrag

[ACS_Dev]

Alright firstly, thank you to all who replied, this is very helpful.

On 4/17/2024 at 8:57 AM, Exorcet said:

My understanding is the orientation for the object rotates with the object. The x, y, z after the p are telling you where the x axis, y axis, and z axis of the object are pointing.

 

This is 2D and not 3D, but the p would refer to the blue lines while the x would refer to the black x orientation line and y would refer to the black y orientation line (though I think that's actually z in DCS). The x and y are vec3 because you need the three components along the global x, y, z coordinate system to define them.

I understand the simply positional aspect of the coordinates system and am trying to move on to the orientation side of it. Unfortunately I do not yet know what I am doing but will need to learn in order to build the things I plan on building. As detective Calvin @cfrag says it can be used to determine things like heading and velocity vectors. That's exactly the kind of stuff I need to learn, and to learn it I need to understand this system and what it outputs. Fortunately the wiki has the functions I need for now but I may need more in the future.

[cfrag]

2 hours ago, ACS_Dev said:

detective Calvin

Bullet. Tracer Bullet.