Derived from Robot.

Supervisor {   # no additional fields }

3.42.1 Description

A supervisor is a program which controls a world and its robots. For convenience it is represented as a robot without any wheels, driven by a controller with extended capabilities which supervises the whole world.

3.42.2 Supervisor Functions

The supervisor controller is a particular case of a robot controller, hence the wb_robot_init(), wb_robot_step(), 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 wb_differential_wheels_*() functions that are specific to DifferentialWheels 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.

NAME

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

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

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

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 return 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

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

DESCRIPTION

The wb_supervisor_node_get_type() function returns a symbolic value corresponding the type of the node specified as an argument. 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_name() function returns a text string corresponding to the name of the node, like "DifferentialWheels", "Appearance", "LightSensor", etc.

C++, Java, Python Note: 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

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

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

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

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 for 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

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

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

• wb_supervisor_set_label(1,"hello Webots",0,0.1,0.1,0x00ff00,0.5);

  will display the label "hello Webots" in semi-transparent green, just below.

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

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

Matlab Note: 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

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

DESCRIPTION

The wb_supervisor_simulator_quit() function sends a request to the simulator process, asking it to terminate immediately. As a result of terminating the simulator process, all the controller processes, including the calling supervisor controller process, will terminate.

NAME

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

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 you supervisor program in order to reload it when the supervisor controller restarts.

NAME

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

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

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

DESCRIPTION

The wb_supervisor_start_animation() function starts saving the current simulation to a Webview animation file. Saving the animation will halt after the wb_supervisor_stop_animation() function is called. The filename parameter should refer to a file with a .WVA extension.

Webview is the Webots animation viewer. It is freely available as a stand-alone application or as a plugin for Mozilla, Netscape and Internet Explorer. It allows the user to replay your simulations as 3D animations in which the user can navigate to observe the behavior of the robots. Webview is available free of charge from Cyberbotics' web site.

NAME

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

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 installed 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

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

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. 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.

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) 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).

C++, Java, Python Note: 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

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

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 with the name of the function used, otherwise the return value is undefined (and a warning message is displayed).

The wb_supervisor_field_get_mf_*() functions work the same way as the wb_supervisor_field_get_mf_*() 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 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 return value is undefined (and a warning message is displayed).

NAME

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

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_mf_*() 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 shows how to change a texture from the supervisor while the simulation is running. The soccer.wbt world provides a simple example for getting and setting fields with the above described functions.

NAME

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

DESCRIPTION

The wb_supervisor_field_import_mf_node() function imports a Webots node into an MF_NODE. This node should be defined in a .wbt 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:

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

• 1: insert at the second position.

• 2: insert at the third position.

• -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.

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: Note that this function is still limited in the actual Webots version. For exemple, 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.

^ page top ^