Webots Reference Manual - chapter 3 - section 10

Webots Reference Manual


3.10 Compass

Derived from Device.

Compass {
  MFVec3f    lookupTable    []    # interpolation
  SFBool     xAxis          TRUE  # compute x-axis
  SFBool     yAxis          TRUE  # compute y-axis
  SFBool     zAxis          TRUE  # compute z-axis
}

3.10.1 Description

A Compass node can be used to model a 1, 2 or 3-axis digital compass (magnetic sensor). The Compass node returns a vector that indicates the direction of the virtual north. The virtual north is specified by the northDirection field in the WorldInfo node.

3.10.2 Field Summary

3.10.3 Compass Functions



NAME

   wb_compass_enable, wb_compass_disable, wb_compass_get_sampling_period, wb_compass_get_values - enable, disable and read the output values of the compass device

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/compass.h>

  void wb_compass_enable(WbDeviceTag tag, int ms);
  void wb_compass_disable(WbDeviceTag tag);
  const double *wb_compass_get_values(WbDeviceTag tag);
  int wb_compass_get_sampling_period(WbDeviceTag tag);

DESCRIPTION

The wb_compass_enable() function turns on the Compass measurement each ms milliseconds.

The wb_compass_disable() function turns off the Compass device.

The wb_compass_get_sampling_period() function returns the period given into the wb_compass_enable() function, or 0 if the device is disabled.

The wb_compass_get_values() function returns the current Compass measurement. The returned vector indicates the direction of the virtual north in the coordinate system of the Compass device. Here is the internal algorithm of wb_compass_get_values() in pseudo-code:

float[3] wb_compass_get_values() {
  float[3] n = getGlobalNorthDirection();
  n = rotateToCompassOrientation3D(n);
  n = normalizeVector3D(n);
  n[0] = applyLookupTable(n[0]);
  n[1] = applyLookupTable(n[1]);
  n[2] = applyLookupTable(n[2]);
  if (xAxis == FALSE) n[0] = 0.0;
  if (yAxis == FALSE) n[1] = 0.0;
  if (zAxis == FALSE) n[2] = 0.0;
  return n;
}

If the lookupTable is empty and all three xAxis, yAxis and zAxis fields are TRUE then the length of the returned vector is 1.0.

The values are returned as a 3D-vector, therefore only the indices 0, 1, and 2 are valid for accessing the vector. Let's look at one example. In Webots global coordinates system, the xz-plane represents the horizontal floor and the y-axis indicates the elevation. The default value of the northDirection field is [ 1 0 0 ] and therefore the north direction is horizontal and aligned with the x-axis. Now if the Compass node is in upright position, meaning that its y-axis is aligned with the global y-axis, then the bearing angle in degrees can be computed as follows:

language: C

double get_bearing_in_degrees() {
const double *north = wb_compass_get_values(tag);
double rad = atan2(north[0], north[2]);
double bearing = (rad - 1.5708) / M_PI * 180.0;
if (bearing < 0.0)
  bearing = bearing + 360.0;
return bearing;
}

language: C, C++
The returned vector is a pointer to the internal values managed by the Compass node, therefore it is illegal to free this pointer. Furthermore, note that the pointed values are only valid until the next call to wb_robot_step() or Robot::step(). If these values are needed for a longer period they must be copied.
language: Python
getValues() returns the vector as a list containing three floats.
release 7.0.2
Copyright © 2012 Cyberbotics Ltd. All right reserved.