Webots Reference Manual

previous page go up next page

Thanks

1.Introduction

2.Controller API

3.Webots File Format

     

2.11 Supervisor

supervisor_export_image
supervisor_import_node
supervisor_node_get_from_def, supervisor_node_was_found
supervisor_set_label
supervisor_simulation_quit
supervisor_field_get, supervisor_field_set

The supervisor controller is a particular case of a robot controller, hence the robot_live, robot_step, robot_get_device, etc. functions also apply to supervisor controllers. Moreover, as long as the supervisor contains sensors and actuators in its list of children, the corresponding sensor and actuator functions can be used (except for the differential_wheels_* functions that are specific to differential wheels robots).

This section covers the supervisor specific functions, allowing the supervisor controller to track the position and orientation of Solid nodes in the scene, to move them, to take a snapshot of the scene, etc.

supervisor_export_image

NAME

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

SYNOPSIS

  #include <device/supervisor.h>

   void supervisor_export_image (gchar *filename, guint8 quality);

DESCRIPTION

The supervisor_export_image function saves the current 3D image of the simulator window into a jpeg file as specified in the filename parameter. The quality parameter defines the jpeg quality (in the range 0 - 100). The filename parameter should specify a jpeg file (as an absolute or relative path), i.e., "my_image.jpeg" or "/var/www/html/images/shot.jpg". Indeed, 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

A simple example of using the supervisor_export_image is provided in the photographer directory of the controllers directory. An example of a webcam system using supervisor_export_image is provided in the webcam directory of the controllers directory.

supervisor_import_node

NAME

   supervisor_import_node -- import a node into the scene

SYNOPSIS

  #include <device/supervisor.h>

   void supervisor_import_node (gchar *filename, gint position);

DESCRIPTION

The supervisor_import_node function imports a Webots node into the scene. This node should be defined in a Webots file referenced to 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 Object button.

The position parameter defines the position in the scene tree where the new node is going to be inserted. It can be positive or negative. Here are a few examples for the position parameter:

  • 0: insert at the beginning of the scene tree.

  • 1: insert at the second position.

  • 2: insert at the third position.

  • etc.

  • -1: insert at the last position.

  • -2: insert at the second position from the end of the scene tree.

  • -3: insert at the third position from the end.

  • etc.

As in supervisor_export_image, the filename parameter can be speficied with an absolute or a relative path.

supervisor_node_get_from_def

NAME

   supervisor_node_get_from_def, supervisor_node_was_found -- get a pointer to a node of the scene from its DEF name and check if that node exists.

SYNOPSIS

  #include <device/supervisor.h>

   NodeRef supervisor_node_get_from_def (gchar *defname);
   gboolean supervisor_node_was_found (NodeRef node);

DESCRIPTION

The supervisor_node_get_from_def function retrieves a pointer to a node of the scene from its DEF name. The return value can be used for subsequent calls to functions refering to a node of the scene. Note that this function always return a non NULL value, even if the node does not exist in the scene.

The supervisor_node_was_found checks whether the node refered to by node really exists in the scene. It returns TRUE if the node exists and FALSE otherwise. Please, note that these functions have to be called after calling the robot_step function, so that they are able to return correct values.

supervisor_set_label

NAME

   supervisor_set_label -- display a text label over the 3D scene

SYNOPSIS

  #include <device/supervisor.h>

   NodeRef supervisor_set_label (guint16 id, gchar *text, gfloat x, gfloat y, gfloat size, guint32 color);

DESCRIPTION

The supervisor_set_label function displays a text label over the 3D scene in Webots' main window. The id parameter is a an identifier for the label, you can choose any value in the range 0-65535. It will be used later on when you want to change that label, like updating 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 with the same unit as the y parameter. Finally, the color parameter defines the color for the label. It is expressed as 32 bits RGB integer value, when 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.

EXAMPLE


  • supervisor_set_label(0,"hello world",0,0,0.1,0xff0000);
          

    will display the label "hello world" in red at the upper left corner of the 3D window.


  • supervisor_set_label(1,"hello dad",0,0.1,0.1,0x00ff00);
          

    will display the label "hello dad" in green, just below.


  • supervisor_set_label(0,"hello universe",0,0,0.1,0xffff00);
          

    will change the label "hello world" defined earlier into "hello universe", setting a yellow color to the new text.

supervisor_simulation_quit

NAME

   supervisor_simulation_quit -- terminate the simulator and controller processes

SYNOPSIS

  #include <device/supervisor.h>

   void supervisor_simulation_quit ();

DESCRIPTION

The supervisor_simulator_quit function sends a request to the simulator process, asking to terminate and quit immediately. As a result of terminating the simulator process, all the controller processes, including the calling supervisor controller process will terminate.

supervisor_set_label

NAME

   supervisor_field_get, supervisor_field_set -- get and set the contents of the field of a node in the scene

SYNOPSIS

  #include <device/supervisor.h>

   void supervisor_field_get (NodeRef node, field_type type, gpointer data, guint16 ms);
   void supervisor_field_set (NodeRef node, field_type type, gpointer data);

DESCRIPTION

The supervisor_field_get function allows the supervisor controller to track the evolution of some fields of a node. Currently only a few fields are trackable, as described in the following list of field types. Each ms milliseconds, the new value of the field (if any) is stored at data with a specific data type (usually an array of gfloat). The type parameter should be a combination of the following primitive constants, as defined in the supervisor.h header file:


SUPERVISOR_FIELD_TRANSLATION_X
SUPERVISOR_FIELD_TRANSLATION_Y
SUPERVISOR_FIELD_TRANSLATION_Z
SUPERVISOR_FIELD_ROTATION_X
SUPERVISOR_FIELD_ROTATION_Y
SUPERVISOR_FIELD_ROTATION_Z
SUPERVISOR_FIELD_ROTATION_ANGLE
SUPERVISOR_FIELD_BATTERY_CURRENT
    

Some predefined combinations include:


SUPERVISOR_FIELD_TRANSLATION = SUPERVISOR_FIELD_TRANSLATION_X+
SUPERVISOR_FIELD_TRANSLATION_Y+SUPERVISOR_FIELD_TRANSLATION_Z

SUPERVISOR_FIELD_ROTATION = SUPERVISOR_FIELD_ROTATION_X+
SUPERVISOR_FIELD_ROTATION_Y+SUPERVISOR_FIELD_ROTATION_Z+
SUPERVISOR_FIELD_ROTATION_ANGLE

SUPERVISOR_FIELD_TRANSLATION_AND_ROTATION =
SUPERVISOR_FIELD_TRANSLATION+SUPERVISOR_FIELD_ROTATION
    

It is necessary that the data parameter be a pointer towards a large enough array of gfloat, able to contain all the requested values. One gfloat is necessary for each primitive value. Please note that this data pointer should point to a valid memory chunk at the time of the robot_step function. Hence, it should not be stored on the heap of a local function that won't exist any more when calling robot_step. Instead, it has to be dynamically allocated, or declared as a local or global static variable, or declared in the same function that (or a parent function of) the function calling robot_step.

In order to disable the tracking of a field, call the supervisor_field_get function with a ms parameter set to 0.

The supervisor_field_set function works the same way as supervisor_field_get, except that it changes the value of the requested field instead of reading it.

EXAMPLE

An simple example of using field tracking is given in the supervisor controller.

previous page go up next page
^ page top ^

  E-mail to webmaster Last updated: Copyright © 2002 Cyberbotics Ltd.