SIMbox Coordinates Systems Overview

From SIMboxWiki
Jump to navigation Jump to search

Introduction

The coordinate system is a fundamental concept when developing SIMbox SDK content. Some of the coordinate systems are used to describe object position in the simulation (used in SIMbox SDK); others are used to describe graphic object position in the simulation (used in Graphic Engine). In this article we will focus on coordinate systems used in the SIMbox SDK. The coordinates systems that are used by the SIMbox SDK are:

  • World Global
  • World Local
  • Object Body

SIMbox SDK provides efficient conversions between the systems above. SIMbox SDK also provides efficient conversions between World Local, World Global and UTM coordinate systems. SIMbox SDK does not support conversions to Geocentric coordinate system. SIMbox SDK does not take earth curvature into consideration.

World Global Coordinate System

In World Global coordinate system object position is described in Longitude and Latitude in WGS-84 datum. For more information see Geographic coordinate system.


World Local Coordinate System

In the World Local coordinate system the position of each object in the simulation is characterized by three values (X, Y and Z). Each one of the values describes the distance (in meters) of the coordinate along the appropriate axis.

World Local coordinate system axes directions are as shown in the diagram below:

WorldLocal.PNG

The origin of this coordinate system is usually called Global Offset or Pivot Point in simulations; we will refer to it as Global Offset from now on. The Global Offset of the World Local coordinate system is set when the session is initialized. The origin that is set in session initialization is the position of the controlled entity (of the session), or the average position of all entities if there is no controlled entity.

When running in DMT, each user (creator or joiner) has a different controlled entity. Therefore each session (running on each user's machine) might have different Global Offset and local coordinates for the same world position might be different.

To overcome this problem we use the World Global coordinates to update the object position on a remote computer and then, if required, convert to World Local coordinates.

Object Body Coordinate System

This coordinate system is attached to the object body. There is different Object Body coordinate system for each object in the simulation. Axis directions are as shown in the diagram below:

Body.PNG

Orientation

Object orientation in the simulation is defined by three Euler angles. Rotation is done in a YPR order:

  1. Yaw rotation, first, around body Z axis
  2. Pitch rotation, second, around new (after the first rotation) body X axis
  3. Roll rotation, third, around new (after the second rotation )body Y axis


  • Yaw (Ψ) – counter clockwise rotation around the Z-axis, -π to π.
  • Pitch (Θ) – clockwise rotation around the horizontal axis (X), -π/2 to π/2.
  • Roll (Φ) – clockwise rotation around the vertical axis (Y) , -π to π.


Data Structures Used

The following data structures are used to store object world local or object body position and orientation:

LinearVec

LinearVec class is used to store object position. The following example shows simple use of this data structure.

// construction
LinearVec linVec1; 
LinearVec linVec2(LinearVec::zero());
LinearVec linVec3(1.0f, 2.0f, 3.0f);

// assignment
linVec1[X] = 1.0f;
linVec1[Y] = 2.0f;
linVec1[Z] = 3.0f;

// reading
float lvX = linVec1(X);
float lvY = linVec1(Y);
float lvZ = linVec1(Z);


AngularVec

AngularVec class is used to store object orientation. The following example shows simple use of this data structure.

// construction
AngularVec angVec1;
AngularVec angVec2(AngularVec::zero());
AngularVec angVec3(Ang(Rad(0.0f)),Ang(Deg(0.0f)),Ang(Deg(180.0f)));

// assignment
angVec1[ROLL] = Ang::zero(); 
angVec1[PITCH] = Ang(Deg(10.0f));
angVec1[YAW] = Ang(Rad(PI));

// reading
float roll = angVec1(ROLL).deg();
float pitchRad = angVec1(PITCH).rad();
Ang yaw = angVec1(YAW);


Location

Location class is used to store both of the object position and orientation. The following example shows simple use of this data structure.

// construction
Location loc1;
Location loc2(LinearVec::zero(), angVec1);

// reading
LinearVec position = loc1.linVec();
float locX = loc1.linVec()(X);

// assignment
loc1.linVecRef() = position;
loc1.linVecRef()[X] = 10.0f;

// reading
AngularVec orientation = loc1.angVec();
float rollDeg = loc1.angVec()(ROLL).deg();
Ang pitch = loc1.angVec()(PITCH);

// assignment
loc1.angVecRef() = angVec1;<br>
loc1.angVecRef()[PITCH] = Ang(Deg(90.0f));

For more information on these data structures see LinearVec, AngularVec and Location.

Graphic Engine Coordinate System

For historical reasons there is also Graphic Engine coordinate system that is used for setting graphic 3D objects position. This coordinate system is similar to World Local coordinate system, the only difference is that the X and Y axes are switched. As in World Local coordinate system, each object’s position is characterized by three values(X, Y and Z). Each one of the values is describing the distance in meters of the coordinate along the appropriate axis. The origin of this coordinate system is the same as in World Local coordinate system.

Graphic Engine coordinate system axes directions are as shown in the diagram bellow:

GraphicEngine.PNG


Data Structures Used

The following data structures are used to store object position and orientation:

zsVec3

Float array of size three. The array is used to store both object position and orientation. Use the following conversion functions to convert zsVec to LinearVec (or AngularVec) and vice versa.

SimApi::Convertor::linearVec2zsVec
SimApi::Convertor::angularVec2zsVec
SimApi::Convertor::zsVec2LinearVec
SimApi::Convertor::zsVec2AngularVec

Conversion Between the Systems

World Global to Local conversion:

double lon, lat;
float localX, localY;
SimApi::Convertor::globalToLocal(lon, lat, localX, localY);

World Local to Global conversion:

double lon, lat;
float LocalX, LocalY;
SimApi::Convertor::localToGlobal(LocalX, LocalY, lon, lat);<br><br>

Object Body to World Local, World Local to Object Body conversions:

float orientation[3];
LinearVec world, body;
SimApi::Entities::world2body(orientation,world,body);
SimApi::Entities::body2world(orientation,body,world);

For more information about conversions see SimApi::Convertor, and Entities class reference (World2body, Body2World).