Coordinate Systems

Internally, Gameware Navigation creates all of its data and does all of its internal calculations using a coordinate system with the following properties:

It is Z-up.
It is right-handed.
All distances are expressed in meters.

The axes of this system are defined using the following convention. Note that the positive direction of the Y, or Front, axis is "into" the screen (away from the reader).

This has the following consequences:

Whenever you pass coordinates, vectors or distances to a Gameware Navigation component, you must express those values in the Gameware Navigation coordinate system.
Whenever you retrieve coordinates, vectors or distances from a Gameware Navigation component, the values will be expressed in the Gameware Navigation coordinate system.

If you use a different coordinate system in your game engine, you will need to convert values back and forth. See the following section.

NOTE:There are a few exceptions, but these are clearly indicated by the presence of ClientCoordinates in the name of the function or method. For example, ClientInputConsumer::ConsumeTriangleFromPosInClientCoordinates().

The CoordSystem helper class

The CoordSystem class is an optional helper that you can use to convert coordinates, vectors, distances, and bounding boxes between the coordinate system you use in your game and the coordinate system used by Gameware Navigation.

To use this class:

Create an instance of the CoordSystem class, and initialize it with a call to CoordSystem::Setup().
Call any of its class methods to convert data back and forth.

Setting up the CoordSystem

The following code shows how to set up a CoordSystem for use in a game that uses the Y axis as the up axis, and that expresses distance in centimeters:

Kaim::CoordSystem coordSystem = Kaim::CoordSystem();
    KyFloat32 oneMeterInClientUnits = 100.f;
    Kaim::CoordSystem::ClientAxis clientRightAxis = Kaim::CLIENT_X;
    Kaim::CoordSystem::ClientAxis clientFrontAxis = Kaim::CLIENT_MINUS_Z;
    Kaim::CoordSystem::ClientAxis clientUpAxis = Kaim::CLIENT_Y;
 
    coordSystem.Setup(  oneMeterInClientUnits, 
                        clientRightAxis, 
                        clientFrontAxis, 
                        clientUpAxis );

Converting coordinates and vectors

For example, the following call transforms a specified position from the coordinate system used in the game engine to the Gameware Navigation coordinate system.

Kaim::Vec3f navPos = coordSystem.ClientToNavigation_Pos(position);

Similarly, the following call transforms a specified directional vector from the Gameware Navigation coordinate system to the coordinate system used in the game engine.

Kaim::Vec3f navDir = coordSystem.NavigationToClient_Normal(dir);

The conversion methods offered by the CoordSystem class use floating-point numbers to represent distance measurements, and arrays of floating-point numbers to represent coordinates. If you use double-precision numbers, you may have additional processing to do in order to convert your data.

You are of course free to write your own functions to encapsulate the data conversions. This minimizes code duplication, and allows you to ensure type safety by making your functions accept and return the same data types you use in your game.

Converting bounding boxes

You may occasionally find it necessary to convert a bounding box between the Gameware Navigation coordinate system and the coordinate system used in your game engine. In this case, it is particularly recommended to make use of the CoordSystem or its macros to carry out the transformation, as converting a bounding box between coordinate systems can be tricky.

Typically, axis-aligned bounding boxes are defined using the two extremas of the box:

The minima, or the corner with the smallest X, Y and Z values.
The maxima, or the corner with the largest X, Y and Z values.

If you convert the coordinates of the minima and the maxima independently from one coordinate system to another, you can end up with two different corners of the box in the target coordinate system.

For example, if your game world uses a left-handed Z-up coordinate system, mapping coordinates to the right-handed Z-up system used by Gameware Navigation may involve the following transformation: (-X, Y, Z). If the coordinates of the minima and maxima are (minX, minY, minZ) and (maxX, maxY, maxZ), transforming these coordinates independently produces (–minX, minY, minZ) and (–maxX, maxY, maxZ). Because maxX was necessarily higher than minX originally, –maxX is guaranteed to be lower than –minX after the transformation. These two sets of coordinates, while still representing diagonally opposite corners of the bounding box, no longer represent the extremas.

To take a concrete example, imagine a cubic axis-aligned bounding box with its minima at the origin point (0, 0, 0) and its maxima at the corner (100, 100, 100). Transforming these two sets of coordinates independently would produce the coordinates (–0, 0, 0) and (–100, 100, 100). These corners no longer represent the minima, or the corner with the smallest X, Y and Z values, and the maxima, or the corner with the largest X, Y and Z values. Instead, the minima of the translated bounding box ought to be (–100, 0, 0) and the maxima ought to be (–0, 100, 100).

The CoordSystem class takes this into consideration when converting bounding boxes, and ensures that the corners used to define the box will always be the minima and maxima in the target coordinate system.

For example, the following call transforms a bounding box from the coordinate system used in the game engine to the Gameware Navigation coordinate system.

Kaim::Box3f navAABB;
coordSystem.ClientToNavigation_Box(gameMinima, gameMaxima, navAABB);