Position and Orientation

A location is often used to describe a place or area where an object is located (e.g. your location is in a certain room). A position is a more precise indicator of where an object is located (e.g. your position is at X=3 and Y=4). Similar to other positioning systems, OpenHPS uses the concepts of relative and absolute positions.

The aforementioned position descriptions such as a place, area or XY position are called absolute positions, they describe a physical point inside a known space such as the Earth or a building.

When describing a position that uses a certain landmark to describe the position, the position is relative to this landmark. Relative positions can be expressed in distance, angle or velocity and could potentially be used to determine a more precise absolute position. In general, a relative position can not be used if the position is contained by the landmark - in that particular case you are talking about an absolute position relative to the landmark (e.g. you are in the center of a building).

Creating a cartesian position

A cartesian position can be created using an Absolute2DPosition or Absolute3DPosition.

ts
import { Absolute2DPosition } from '@openhps/core';
 
const pos = new Absolute2DPosition(1, 2);

Creating a geographical position

By default, geographical positions use the WGS-84 coordinate system with a latitude, longitude and elevation in meters.

ts
import { GeographicalPosition } from '@openhps/core';
 
const pos = new GeographicalPosition(50.820466, 4.392189, 9);

Geographical Coordinate System

Geographical positions can be constructed from other coordinate systems than WGS-84, but will always be stored using this coordinate system. You can find more information on available coordinate systems here.

Name Function Note
EPSG4326 GCS.EPSG4326
WGS-84 GCS.WGS84 (alias for EPSG4326)
ECEF GCS.ECEF
EPSG3857 GCS.EPSG3857 
ts
import { GeographicalPosition, Vector3, GCS } from '@openhps/core';
 
const pos = new GeographicalPosition();
pos.fromVector(new Vector3(50.820466, 4.392189, 9), GCS.WGS84);

Likewise, the toVector3() function on an AbsolutePosition accepts an optional argument for the coordinate system.

ts
import { GeographicalPosition, GCS } from '@openhps/core';
 
const pos = new GeographicalPosition(50.820466, 4.392189, 9);
pos.toVector3(GCS.ECEF);

Creating a relative position

  • RelativeDistance: Distance to another data object.
  • RelativeRSSI: Received signal strength to another (transmitting) data object.
  • RelativeAngle: Angle to another data object.
  • RelativeVelocity: Relative velocity towards another object.
ts
import { RelativeDistance } from '@openhps/core';
 
object.addRelativePosition(new RelativeDistance("WAP_1", 10));
object.addRelativePosition(new RelativeDistance("WAP_2", 5));
object.addRelativePosition(new RelativeDistance("WAP_3", 8));

Creating an orientation

Every absolute position can contain an orientation. The orientation is stored as a quaternion but can be initialized through euler angles or axis angles.

ts
import { Orientation, AngleUnit } from '@openhps/core';
 
const orientation = Orientation.fromEuler({
    pitch: 0,
    roll: 0,
    yaw: 90,
    unit: AngleUnit.DEGREE
});
position.orientation = orientation;

An orientation offers the same quaternion methods as Three.js. You can find more information about available methods here.

Examples

You can find an ObservableHQ notebook with examples for creating an orientation here.

Creating a Pose

A Pose is a position and orientation combined. It is represented as a 4x4 matrix.

The pose is composed of a translation (position) denoted as MM and a rotation matrix.

M=(100tx010ty001tz0001)M=\begin{pmatrix} 1 & 0 & 0 & t_x\\ 0 & 1 & 0 & t_y\\ 0 & 0 & 1 & t_z\\ 0 & 0 & 0 & 1 \end{pmatrix}RX(θ)=(10000cos(θ)sin(θ)00−sin(θ)cos(θ)00001)R_X(\theta)=\begin{pmatrix} 1 & 0 & 0 & 0\\ 0 & cos(\theta) & sin(\theta) & 0\\ 0 & -sin(\theta) & cos(\theta) & 0\\ 0 & 0 & 0 & 1 \end{pmatrix}RY(θ)=(cos(θ)0−sin(θ)00100sin(θ)0cos(θ)00001)R_Y(\theta)=\begin{pmatrix} cos(\theta) & 0 & -sin(\theta) & 0\\ 0 & 1 & 0 & 0\\ sin(\theta) & 0 & cos(\theta) & 0\\ 0 & 0 & 0 & 1 \end{pmatrix}RZ(θ)=(cos(θ)−sin(θ)00sin(θ)cos(θ)0000100001)R_Z(\theta)=\begin{pmatrix} cos(\theta) & -sin(\theta) & 0 & 0\\ sin(\theta) & cos(\theta) & 0 & 0\\ 0 & 0 & 1 & 0\\ 0 & 0 & 0 & 1\\ \end{pmatrix}

Position accuracy and probability

Accuracy defines how accurate the position is from the given or calculated coordinates. An accuracy can be defined in 1D, 2D or a 3D spheroid but should always support being expressed as a one dimensional value.

Accuracy is always present in an absolute position and can be directly updated with ```setAccuracy``.

ts
position.setAccuracy(20, LengthUnit.CENTIMETER);

Alternatively you can specify a 2D, 3D or custom accuracy.

ts
import { Accuracy1D, Accuracy2D, Accuracy3D, LengthUnit } from '@openhps/core';
position.accuracy = new Accuracy1D(5, LengthUnit.METER);
// or
position.accuracy = new Accuracy2D(5, 3, LengthUnit.METER);
// or
position.accuracy = new Accuracy3D(5, 3, 1, LengthUnit.METER);