Creating and accessing Frames

In the Robotics API, Frames can be created in three different ways:

Automatically by devices that manage them (like robots),
by specifying them in a configuration file,
or by explicitely creating them in a robot program (explained in this section).

When creating Frames in a robot program, they can either be created persistent or temporary. Persistent Frames are registered in the FrameRegistry, from which they can be retrieved again by their unique name (see next section). Temporary Frames are intended to be used e.g. when some auxiliary point for a robot motion is needed. Temporary Frames also have a unique name. However, they cannot be retrieved by this name from the FrameRegistry. A temporary Frame is only available in the program if a reference to it is stored, e.g. by assigning the Frame to a variable.

Temporary Frames can be created by just creating a new instance of the Frame class. To place a Frame at a certain point in space, a Relation to another Frame has to be defined. Alternatively, temporary Frames can be created and at the same time related to existing Frames by using one of the plus(...) methods provided by the Frame class.

The following code creates a new temporary Frame that is located at a distance of 1m in direction of the x axis of the World origin Frame:

Frame temp = World.getOrigin().plus(1, 0, 0);

Persistent Frames can be created by the FrameRegistry. It provides (among others) the following static methods:

createAndRegisterFrame(String name) creates a Frame with the given name, if no such Frame exists. Otherwise, an exception is thrown.
getOrCreateFrame(String name) creates a persistent Frame with the given name, if no such Frame exists. Otherwise, the existing Frame is returned.
hasFrame(String name) checks whether a Frame with the given name already exists.
getFrame(String name) returns a Frame with the given name that has been registered in the RoboticsRegistry previously. If no such Frame exists, an exception is thrown.

Note

Calling FrameRegistry.getOrCreateFrame(String) will create a Frame with the given name, if it does not exist already. So be sure to use (getFrame(String name) if the Frame should not be created automatically, or use hasFrame(String name) to check if the Frame exists.

The following code creates a new persistent Frame:

Frame myFrame = FrameRegistry.createAndRegisterFrame("MyFrame");

Note

You should use persistent Frames only if they should be globally available in your robotics application. In all other cases, you should use temporary Frames.

≫≪∧