Webots Reference Manual - chapter 3 - section 47

Webots Reference Manual


3.47 Supervisor

Derived from Robot.

Supervisor {
  # no additional fields
}

3.47.1 Description

A Supervisor is a special kind of Robot which is specially designed to control the simulation. A Supervisor has access to extra functions that are not available to a regular Robot. If a Supervisor contains devices then the Supervisor controller can use them. Webots PRO is required to use the Supervisor node.

Note that in some special cases the Supervisor functions might return wrong values and it might not be possible to retrieve fields and nodes. This occurs when closing a world and quitting its controllers, i.e. reverting the current world, opening a new world, or closing Webots. In this case the output will be a NULL pointer or a default value. For functions returning a string, an empty string is returned instead of a NULL pointer.
language: C++, Java, Python
It is a good practice to check for a NULL pointer after calling a Supervisor function.

3.47.2 Supervisor Functions

As for a regular Robot controller, the wb_robot_init(), wb_robot_step(), etc. functions must be used in a Supervisor controller.



NAME

   wb_supervisor_export_image - save the current 3D image of the simulator into a JPEG file, suitable for building a webcam system

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

  #include <webots/supervisor.h>

  void wb_supervisor_export_image(const char *filename, int quality);

DESCRIPTION

The wb_supervisor_export_image() function saves the current image of Webots main window into a JPEG file as specified by the filename parameter. The quality parameter defines the JPEG quality (in the range 1 - 100). The filename parameter should specify a valid (absolute or relative) file name, e.g., snapshot.jpg or /var/www/html/images/snapshot.jpg. In fact, a temporary file is first saved, and then renamed to the requested filename. This avoids having a temporary unfinished (and hence corrupted) file for webcam applications.

EXAMPLE

The projects/samples/howto/worlds/supervisor.wbt world provides an example on how to use the wb_supervisor_export_image() function. In this example, the Supervisor controller takes a snapshot image each time a goal is scored.



NAME

   wb_supervisor_node_get_from_def, wb_supervisor_node_get_root - get a handle to a node in the world

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

  #include <webots/supervisor.h>

  WbNodeRef wb_supervisor_node_get_from_def(const char *def);
  WbNodeRef wb_supervisor_node_get_root();

DESCRIPTION

The wb_supervisor_node_get_from_def() function retrieves a handle to a node in the world from its DEF name. The return value can be used for subsequent calls to functions which require a WbNodeRef parameter. If the requested node does not exist in the current world file, the function returns NULL, otherwise, it returns a non-NULL handle.

The wb_supervisor_node_get_root() function returns a handle to the root node which is actually a Group node containing all the nodes visible at the top level in the scene tree window of Webots. Like any Group node, the root node has a MFNode field called "children" which can be parsed to read each node in the scene tree. An example of such a usage is provided in the supervisor.wbt sample worlds (located in the projects/samples/devices/worlds directory of Webots.



NAME

   wb_supervisor_node_get_type, wb_supervisor_node_get_type_name - get information on a specified node

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

  #include <webots/supervisor.h>

  WbNodeType wb_supervisor_node_get_type(wbNodeRef node);
  const char *wb_supervisor_node_get_type_name(wbNodeRef node);

DESCRIPTION

The wb_supervisor_node_get_type() function returns a symbolic value corresponding the type of the node specified as an argument. If the argument is NULL, it returns WB_NODE_NO_NODE. A list of all node types is provided in the webots/nodes.h include file. Node types include WB_NODE_DIFFERENTIAL_WHEELS, WB_NODE_APPEARANCE, WB_NODE_LIGHT_SENSOR, etc.

The wb_supervisor_node_get_type_name() function returns a text string corresponding to the name of the node, like "DifferentialWheels", "Appearance", "LightSensor", etc. If the argument is NULL, the function returns NULL.

language: C++, Java, Python
In the oriented-object APIs, the WB_NODE_* constants are available as static integers of the Node class (for example, Node::DIFFERENTIAL_WHEELS). These integers can be directly compared with the output of the Node::getType()


NAME

   wb_supervisor_node_get_field - get a field reference from a node

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

  #include <webots/supervisor.h>

  WbFieldRef wb_supervisor_node_get_field(WbNodeRef node, const char *field_name);

DESCRIPTION

The wb_supervisor_node_get_field() function retrieves a handler to a node field. The field is specified by its name in field_name and the node it belongs to. It can be a single field (SF) or a multiple field (MF). If no such field name exist for the specified node, the return value is NULL. Otherwise, it returns a handler to a field.



NAME

   wb_supervisor_node_get_position, wb_supervisor_node_get_orientation - get the global (world) position/orientation of a node

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

  #include <webots/supervisor.h>

  const double *wb_supervisor_node_get_position(WbNodeRef node);
  const double *wb_supervisor_node_get_orientation(WbNodeRef node);

DESCRIPTION

The wb_supervisor_node_get_position() function returns the position of a node expressed in the global (world) coordinate system. The node argument must be a Transform node (or a derived node), otherwise the function will print a warning message and return NULL. This function returns a vector containing exactly 3 values.

The wb_supervisor_node_get_orientation() function returns a matrix that represents the rotation of the node in the global (world) coordinate system. The node argument must be a Transform node (or a derived node), otherwise the function will print a warning message and return NULL. This function returns a matrix containing exactly 9 values that shall be interpreted as a 3 x 3 orthogonal rotation matrix:

[ R[0] R[1] R[2] ]
[ R[3] R[4] R[5] ]
[ R[6] R[7] R[8] ]

Each column of the matrix represents where each of the three main axes (x, y and z) is pointing in the node's coordinate system. The columns (and the rows) of the matrix are pairwise orthogonal unit vectors (i.e., they form an orthonormal basis). Because the matrix is orthogonal, its transpose is also its inverse. So by transposing the matrix you can get the inverse rotation. Please find more info here.

By multiplying the rotation matrix on the right with a vector and then adding the position vector you can express the coordinates of a point in the global (world) coordinate system knowing its coordinates in a local (node) coordinate system. For example:

p' = R * p + T

where p is a point whose coordinates are given with respect to the local coordinate system of a node, R the the rotation matrix returned by wb_supervisor_node_get_orientation(node), T is the position returned by wb_supervisor_node_get_position(node) and p' represents the same point but this time with coordinates expressed in the global (world) coordinate system.

The WEBOTS_HOME/projects/robots/ipr/worlds/ipr_cube.wbt project shows how to use these functions to do this.



NAME

   wb_supervisor_node_get_center_of_mass - get the global position of a solid's center of mass

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

  #include <webots/supervisor.h>

  const double *wb_supervisor_node_get_center_of_mass(WbNodeRef node);

DESCRIPTION

The wb_supervisor_node_get_center_of_mass() function returns the position of the center of mass of a Solid node expressed in the global (world) coordinate system. The node argument must be a Solid node (or a derived node), otherwise the function will print a warning message and return NULL. This function returns a vector containing exactly 3 values. If the node argument has a NULL physics node, the return value is always the zero vector.

The WEBOTS_HOME/projects/samples/.wbt project shows how to use this function.



NAME

   wb_supervisor_node_get_contact_points - get the contact points of a solid and of all its descendants

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

  #include <webots/supervisor.h>

  const double *wb_supervisor_node_get_contact_points(WbNodeRef node, int *number_of_contact_points);

DESCRIPTION

The wb_supervisor_node_get_contact_points() function returns the list contact points belonging to a given Solid and all its descendants. The second argument allows to retrieve the length of this list. Contact points are expressed in the global (world) coordinate system. If the number of contact points is not zero, the x (resp. y, z) coordinate of the ith contact point is the element number 3*i (resp. 3*i + 1, 3*i + 2) in the returned array. The node argument must be a Solid node (or a derived node), which moreover has no Solid parent, otherwise the function will print a warning message and return NULL.

The WEBOTS_HOME/projects/samples/.wbt project shows how to use this function.



NAME

   wb_supervisor_node_get_static_balance - return the boolean value of the static balance test based on the support polygon of a solid

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

  #include <webots/supervisor.h>

  bool wb_supervisor_node_get_static_balance(WbNodeRef node);

DESCRIPTION

The wb_supervisor_node_get_static_balance() function returns the boolean value of the static balance test based on the support polygon of a solid. The node argument must be a Solid node (or a derived node), which moreover has no Solid parent. Otherwise the function will print a warning message and return false. The support polygon of a solid is the convex hull of the solid's contact points projected onto a plane that is orthognal to the gravity direction. The test consists in checking whether the projection of the center of mass onto this plane lies inside or outside the support polygon.

The WEBOTS_HOME/projects/samples/.wbt project shows how to use this function.



NAME

   wb_supervisor_set_label - overlay a text label on the 3D scene

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

  #include <webots/supervisor.h>

  void wb_supervisor_set_label(int id, const char *text, double x, double y, double size, int color, double transparency);

DESCRIPTION

The wb_supervisor_set_label() function displays a text label overlaying the 3D scene in Webots' main window. The id parameter is an identifier for the label; you can choose any value in the range 0 to 65535. The same value may be used later if you want to change that label, or update the text. The text parameter is a text string which should contain only displayable characters in the range 32-127. The x and y parameters are the coordinates of the upper left corner of the text, relative to the upper left corner of the 3D window. These floating point values are expressed in percent of the 3D window width and height, hence, they should lie in the range 0-1. The size parameter defines the size of the font to be used. It is expressed in the same unit as the y parameter. Finally, the color parameter defines the color of the label. It is expressed as a 4 bytes RGB integer, where the first byte is ignored, the second byte represents the red component, the third byte represents the green component and the last byte represents the blue component. The transparency parameter defines the transparency of the label. A transparency level of 0 means no transparency, while a transparency level of 1 means total transparency (the text will be invisible). Intermediate values correspond to semi-transparent levels.

EXAMPLE

language: Matlab
In the Matlab version of wb_supervisor_set_label() the color argument must be a vector containing the three RGB components: [RED GREEN BLUE]. Each component must be a value between 0.0 and 1.0. For example the vector [1 0 1] represents the magenta color.


NAME

   wb_supervisor_simulation_quit - terminate the simulator and controller processes

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

  #include <webots/supervisor.h>

  void wb_supervisor_simulation_quit(int status);

DESCRIPTION

The wb_supervisor_simulator_quit() function quits Webots, as if one was using the menu File > Quit Webots. This function makes it easier to invoke a Webots simulation from a script because it allows to terminate the simulation automatically, without human intervention. As a result of quitting the simulator process, all controller processes, including the calling supervisor controller, will terminate. The wb_supervisor_simulator_quit() sends a request to quit the simulator and immediately returns to the controller process, it does not wait for the effective termination of the simulator. After the call to wb_supervisor_simulator_quit(), the controller should call the wb_robot_cleanup() function and then exit. The POSIX exit status returned by Webots can be defined by the status status parameter. Some typical values for this are the EXIT_SUCCESS or EXIT_FAILURE macros defined into the stdlib.h file. Here is a C example:

language: C

#include <webots/robot.h>
#include <webots/supervisor.h>
#include <stdlib.h>

#define TIME_STEP 32

int main(int argc, char *argv[]) {
  wb_robot_init();
  ...
  while (! finished) {
    // your controller code here
    ...
    wb_robot_step(TIME_STEP);
  }
  saveExperimentsData();
  wb_supervisor_simulation_quit(EXIT_SUCCESS); // ask Webots to terminate
  wb_robot_cleanup(); // cleanup resources
  return 0;
}

In object-oriented languages, there is no wb_robot_cleanup() function, in this case the controller should call its destructor. Here is a C++ example:

language: C

#include <webots/Robot.hpp>
#include <webots/Supervisor.hpp>
#include <cstdlib>

using namespace webots;

class MySupervisor : public Supervisor { 
public:
  MySupervisor() { ... }
  virtual ~MySupervisor() { ... }
  void run() {
    ...
    while (! finished) {
      // your controller code here
      ...
      step(TIME_STEP);
    }
    simulationQuit(EXIT_SUCCESS);  // ask Webots to terminate
  }
    
int main(int argc, char *argv[]) {
  MySupervisor *controller = new MySupervisor();
  controller->run();
  delete controller; // cleanup resources
  return 0;
}



NAME

   wb_supervisor_simulation_revert - reload the current world

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

  #include <webots/supervisor.h>

  void wb_supervisor_simulation_revert();

DESCRIPTION

The wb_supervisor_simulator_revert() function sends a request to the simulator process, asking it to reload the current world immediately. As a result of reloading the current world, the supervisor process and all the robot processes are terminated and restarted. You may wish to save some data in a file from your supervisor program in order to reload it when the supervisor controller restarts.



NAME

   wb_supervisor_simulation_physics_reset - stop the inertia of all solids in the world and reset the random number generator

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

  #include <webots/supervisor.h>

  void wb_supervisor_simulation_physics_reset();

DESCRIPTION

The wb_supervisor_simulation_physics_reset() function sends a request to the simulator process, asking it to stop the movement of all physics-enabled solids in the world. It means that for any Solid node containing a Physics node, the linear and angular velocities of the corresponding body are reset to 0, hence the inertia is also zeroed. This is actually implemented by calling the ODE dBodySetLinearVel() and dBodySetAngularVel() functions for all bodies with a zero velocity parameter. This function is especially useful for resetting a robot to its initial position and inertia.

Furthermore, this function resets the seed of the random number generator used in Webots, so that noise-based simulations can be be reproduced identically after calling this function.



NAME

   wb_supervisor_start_movie, wb_supervisor_stop_movie - export the current simulation into a movie file

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

  #include <webots/supervisor.h>

  void wb_supervisor_start_movie(const char *filename, int width, int height, int type, int quality);
  void wb_supervisor_stop_movie();

DESCRIPTION

The wb_supervisor_start_movie() function starts saving the current simulation into a movie file. The movie creation process will complete after the wb_supervisor_stop_movie() function is called. The movie is saved in the file defined by the filename parameter. If the filename doesn't ends with an .avi extension, the file extension is completed automatically. Under Mac OS X and Linux, the extension can also be .mpeg according to the type parameter. The type parameter specify the type of movie to be created. It corresponds to the choice offered in the dialog box when creating a movie manually from the Webots graphical user interface: 0 means the top choice, 1 means the second choice from the top, etc. For example, under Linux and Mac OS X, 0 means MPEG-4 and 1 means MPEG-1. Under Windows, the choices depend on the encoders available on your system and may include for example DivX or Xvid if they are installed. The quality corresponds to the movie compression factor that affects the movie quality and file size. It should be a value between 1 and 100. It may be ignored under Windows depending on the chosen movie encoders (the quality of the movie is defined by the setup of the chosen encoder). Beware, that choosing a too small value for MPEG-4 encoding may cause the mencoder program to fail because of a too low bitrate.



NAME

   wb_supervisor_field_get_type, wb_supervisor_field_get_type_name, wb_supervisor_field_get_count - get a handler and more information on a field in a node

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

  #include <webots/supervisor.h>

  WbFieldType wb_supervisor_field_get_type(WbFieldRef field);
  const char *wb_supervisor_field_get_type_name(WbFieldRef field);
  int wb_supervisor_field_get_count(WbFieldRef field);

DESCRIPTION

The wb_supervisor_field_get_type() returns the data type of a field found previously from the wb_supervisor_node_get_field() function, as a symbolic value. If the argument is NULL, the function returns 0. Field types are defined in webots/supervisor.h and include for example: WB_SF_FLOAT, WB_MF_NODE, WB_SF_STRING, etc.

The wb_supervisor_field_get_type_name() returns a text string corresponding to the data type of a field found previously from the wb_supervisor_node_get_field() function. Field type names are defined in the VRML'97 specifications and include for example: "SFFloat", "MFNode", "SFString", etc. If the argument is NULL, the function returns NULL.

The wb_supervisor_field_get_count() returns the number of items of a multiple field (MF) passed as an argument to this function. If a single field (SF) or NULL is passed as an argument to this function, it returns -1. Hence, this function can also be used to test if a field is MF (like WB_MF_INT32) or SF (like WB_SF_BOOL).

language: C++, Java, Python
In the oriented-object APIs, the WB_*F_* constants are available as static integers of the Field class (for example, Field::SF_BOOL). These integers can be directly compared with the output of the Field::getType()


NAME

   wb_supervisor_field_get_sf_bool, wb_supervisor_field_get_sf_int32, wb_supervisor_field_get_sf_float, wb_supervisor_field_get_sf_vec2f, wb_supervisor_field_get_sf_vec3f, wb_supervisor_field_get_sf_rotation, wb_supervisor_field_get_sf_color, wb_supervisor_field_get_sf_string, wb_supervisor_field_get_sf_node, wb_supervisor_field_get_mf_int32, wb_supervisor_field_get_mf_float, wb_supervisor_field_get_mf_vec2f, wb_supervisor_field_get_mf_vec3f, wb_supervisor_field_get_mf_color, wb_supervisor_field_get_mf_string, wb_supervisor_field_get_mf_node - get the value of a field

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

  #include <webots/supervisor.h>

  bool wb_supervisor_field_get_sf_bool(WbFieldRef field);
  int wb_supervisor_field_get_sf_int32(WbFieldRef field);
  double wb_supervisor_field_get_sf_float(WbFieldRef field);
  const double *wb_supervisor_field_get_sf_vec2f(WbFieldRef sf_field);
  const double *wb_supervisor_field_get_sf_vec3f(WbFieldRef field);
  const double *wb_supervisor_field_get_sf_rotation(WbFieldRef field);
  const double *wb_supervisor_field_get_sf_color(WbFieldRef field);
  const char *wb_supervisor_field_get_sf_string(WbFieldRef field);
  WbNodeRef wb_supervisor_field_get_sf_node(WbFieldRef field);
  int wb_supervisor_field_get_mf_in32(WbFieldRef field, int index);
  double wb_supervisor_field_get_mf_float(WbFieldRef field, int index);
  const double *wb_supervisor_field_get_mf_vec2f(WbFieldRef field, int index);
  const double *wb_supervisor_field_get_mf_vec3f(WbFieldRef field, int index);
  const double *wb_supervisor_field_get_mf_color(WbFieldRef field, int index);
  const char *wb_supervisor_field_get_mf_string(WbFieldRef field, int index);
  WbNodeRef wb_supervisor_field_get_mf_node(WbFieldRef field, int index);

DESCRIPTION

The wb_supervisor_field_get_sf_*() functions retrieve the value of a specified single field (SF). The type of the field has to match the name of the function used, otherwise the return value is undefined (and a warning message is displayed). If the field parameter is NULL, it has the wrong type, or the index is not valid, then a default value is returned. Default values are defined as 0 and 0.0 for integer and double values, false in case of boolean values, and NULL for vectors, strings and pointers.

The wb_supervisor_field_get_mf_*() functions work the same way as the wb_supervisor_field_get_sf_*() functions but with multiple field argument. They take an additional index argument which refers to the index of the item in the multiple field (MF). The type of the field has to match the name of the function used and the index should be comprised between 0 and the total number of item minus one, otherwise the return value is undefined (and a warning message is displayed).



NAME

   wb_supervisor_field_set_sf_bool, wb_supervisor_field_set_sf_int32, wb_supervisor_field_set_sf_float, wb_supervisor_field_set_sf_vec2f, wb_supervisor_field_set_sf_vec3f, wb_supervisor_field_set_sf_rotation, wb_supervisor_field_set_sf_color, wb_supervisor_field_set_sf_string, wb_supervisor_field_set_mf_int32, wb_supervisor_field_set_mf_float, wb_supervisor_field_set_mf_vec2f, wb_supervisor_field_set_mf_vec3f, wb_supervisor_field_set_mf_color, wb_supervisor_field_set_mf_string, wb_supervisor_field_set_mf_node - set the value of a field

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

  #include <webots/supervisor.h>

  void wb_supervisor_field_set_sf_bool(WbFieldRef field, bool value);
  void wb_supervisor_field_set_sf_int32(WbFieldRef field, int value);
  void wb_supervisor_field_set_sf_float(WbFieldRef field, double value);
  void wb_supervisor_field_set_sf_vec2f(WbFieldRef sf_field, const double values[2]);
  void wb_supervisor_field_set_sf_vec3f(WbFieldRef field, const double values[3]);
  void wb_supervisor_field_set_sf_rotation(WbFieldRef field, const double values[4]);
  void wb_supervisor_field_set_sf_color(WbFieldRef field, const double values[3]);
  void wb_supervisor_field_set_sf_string(WbFieldRef field, const char *value);
  void wb_supervisor_field_set_mf_int32(WbFieldRef field, int index, int value);
  void wb_supervisor_field_set_mf_float(WbFieldRef field, int index, double value);
  void wb_supervisor_field_set_mf_vec2f(WbFieldRef field, int index, const double values[2]);
  void wb_supervisor_field_set_mf_vec3f(WbFieldRef field, int index, const double values[3]);
  void wb_supervisor_field_set_mf_color(WbFieldRef field, int index, const double values[3]);
  void wb_supervisor_field_set_mf_string(WbFieldRef field, int index, const char *value);

DESCRIPTION

The wb_supervisor_field_set_sf_*() functions assign a value to a specified single field (SF). The type of the field has to match with the name of the function used, otherwise the value of the field remains unchanged (and a warning message is displayed).

The wb_supervisor_field_set_mf_*() functions work the same way as the wb_supervisor_field_set_sf_*() functions but with a multiple field (MF) argument. They take an additional index argument which refers to the index of the item in the multiple field. The type of the field has to match with the name of the function used and the index should be comprised between 0 and the total number of item minus one, otherwise the value of the field remains unchanged (and a warning message is displayed).

EXAMPLES

The texture_change.wbt world, located in the projects/samples/howto/worlds directory, shows how to change a texture from the supervisor while the simulation is running. The soccer.wbt world, located in the projects/samples/demos/worlds directory, provides a simple example for getting and setting fields with the above described functions.



NAME

   wb_supervisor_field_import_mf_node - import a node into an MF_NODE field (typically a "children" field) from a file

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

  #include <webots/supervisor.h>

  void wb_supervisor_field_import_mf_node(WbFieldRef field, int position, const char *filename);

DESCRIPTION

The wb_supervisor_field_import_mf_node() function imports a Webots node into an MF_NODE. This node should be defined in a .wbo file referenced by the filename parameter. Such a file can be produced easily from Webots by selecting a node in the scene tree window and using the Export button.

The position parameter defines the position in the MF_NODE where the new node will be inserted. It can be positive or negative. Here are a few examples for the position parameter:

The filename parameter can be specified as an absolute or a relative path. In the later case, it is relative to the location of the supervisor controller.

This function is typically used in order to add a node into a "children" field. Note that a node can be imported into the scene tree by calling this function with the "children" field of the root node.

Note that this function is still limited in the actual Webots version. For example, a device imported into a Robot node doesn't reset the Robot, so the device cannot be get by using the wb_robot_get_device() function.
release 7.0.2
Copyright © 2012 Cyberbotics Ltd. All right reserved.