The Robot Frame System
Any robot configured in Viam comes with the Frame System service: an internally managed and mostly static system for storing the “reference frame” of each component of a robot within a coordinate system configured by the user.
The Frame System is the basis for many of Viam’s other services, like Motion and Vision. It stores the required contextual information to use the position and orientation readings returned by some components.
Configuration
To enable the default frame for a given component on a robot, navigate to the Config tab of the robot’s page in the Viam app and click Components. With mode as Builder, click Add Frame on the component’s card and Save Config.
To adjust the frame from its default configuration, change the parameters as needed for your robot before saving.
Navigate to the Config tab on your robot’s page in the Viam app, select the Builder mode, scroll to a component’s panel, and click Add Frame:
Select a parent
frame and fill in the coordinates for translation
(mm) and orientation
(deg, rad, or q), according to the position and orientation of your component in relation to the parent
frame.
{
"components": [
{
"name": "<your_component_name_1>",
"type": "<your_component_type_1>",
"model": "<your_component_model_1>",
"attributes": { ... },
"depends_on": [],
"frame": {
"parent": "<world>",
"translation": {
"y": <int>,
"z": <int>,
"x": <int>
},
"orientation": {
"type": "<ov_degrees>",
"value": {
"x": <int>,
"y": <int>,
"z": <int>,
"th": <int>
}
}
}
}
]
}
Configure the reference frame as follows:
Parameter | Inclusion | Required |
---|---|---|
Parent | Required | Default: world . The name of the reference frame you want to act as the parent of this frame. |
Translation | Required | Default: (0, 0, 0) . The coordinates that the origin of this component’s reference frame has within its parent reference frame.Units: mm. |
Orientation | Required | Default: (0, 0, 1), 0 . The orientation vector that yields the axes of the component’s reference frame when applied as a rotation to the axes of the parent reference frame.Types: Orientation Vector Degrees , Orientation Vector Radians , and Quaternion . |
Geometry | Optional | Default: none . Collision geometries for defining bounds in the environment of the robot.Types: Sphere , Box , and Capsule . |
Note
The Orientation
parameter offers Types
for ease of configuration, but the Frame System always stores and returns orientation vectors in Orientation Vector Radians
.
Degrees
and Quaternion
will be converted to Radians
.
Tip
Viam’s coordinate system considers +X
to be forward, +Y
to be left, and +Z
to be up.
You can use the right-hand rule to determine the orientation of these axes.
For more information about determining the appropriate values for these parameters, see these two examples:
- A Reference Frame: A component attached to a static surface
- Nested Reference Frames: A component attached to another, dynamic, component
Visualize the Frame System
You can visualize how your robot is oriented in the Frame System in the Viam app. Navigate to the Config tab on your robot’s page, select mode as Builder, and click on Frame System.
The Viam app shows you a 3D visualization of the spatial configuration of the reference frames of components configured on your robot:
This tab provides a simple interface for simultaneously viewing and editing the position, orientation, and geometries of a robot’s components in the Frame System.
For example:
Consider a robot configured with a jetson
board, wired to a webcam
camera and a wheeled
base with two motors driving its wheels.
No reference frame configuration has been specified, so on the Frame System subtab of the Config tab, the components are shown to all be located on the default world
origin point as follows:
The distance on the floor from the wheeled base to the board and camera setup is 200 millimeters.
Add this value to "X"
in the base’s reference frame Translation
attribute, and the Frame System readjusts to show the base’s translation:
The distance from the board to the camera mounted overhead is 50 millimeters.
Add this value to "Z"
in the camera’s reference frame Translation
attribute, and the Frame System readjusts to show the camera’s translation:
Now the distance between these components is accurately reflected in the visualization. However, the camera doesn’t yet display as oriented towards the base.
Adjust the orientation vector to 0.5 degrees in "OX"
in the camera’s reference frame Orientation
attribute, and the Frame System readjusts to show the camera’s orientation:
Now that the Frame System is accurately configured with the robot’s spatial orientation, Motion Service methods that take in reference frame information can be utilized.
Display Options
Click and drag on the Frame System visualization to view the display from different angles, and pinch to zoom in and out:
Click the video camera icon below and to the right of the Frame System button to switch beween the default Perspective Camera and the Orthographic Camera view:
Bounding Geometries
To visualize a component’s spatial constraints, add Geometry
properties by selecting a component and selecting a Geometry type in the Frame System subtab of the Config tab of a robot’s page on the Viam app.
By default, a Geometry is shown surrounding the origin point of a component:
You can adjust the Size and Translation of a Geometry to change these bounds. For example:
How the Frame System Works
viam-server
builds a tree of reference frames for your robot with the world
as the root node and regenerates this tree following reconfiguration.
Access a topologically-sorted list of the generated reference frames in the robot’s logs at --debug
level:
Consider the example of nested reference frame configuration where two dynamic components are attached: a robotic arm, A
, attaches to a gantry, G
, which in turn is fixed in place at a point on the World
of a table.
The resulting tree of reference frames looks like:
viam-server
builds the connections in this tree by looking at the "frame"
portion of each component in the robot’s configuration and defining two reference frames for each component:
- One with the name of the component, representing the actuator or final link in the component’s kinematic chain: like
"A"
as the end of an arm. - Another representing the origin of the component, defined with the component’s name and the suffix "_origin".
Access the Frame System
The Robot API supplies the following method to interact with the Frame System:
Method Name | Description |
---|---|
TransformPose | Transform a pose measured in one reference frame to the same pose as it would have been measured in another. |
TransformPose
Transform a given source pose from the reference frame to a new specified destination reference frame. For example, if a 3D camera observes a point in space you can use this method to calculate where that point is relative to another object.
Parameters:
query
(PoseInFrame
): The pose that should be transformed.destination
(str): The name of the reference frame to transform the given pose to.additional_transforms
(Optional[List[Transform]]): A list of additional transforms.
Returns:
PoseInFrame
(PoseInFrame): Transformed pose in destination reference frame.
For more information, see the Python SDK Docs.
# Transform a pose into the frame of myArm
first_pose = Pose(x=0.0, y=0.0, z=0.0, o_x=0.0, o_y=0.0, o_z=1.0, theta=0.0)
first_pif = PoseInFrame(reference_frame="world", pose=first_pose)
transformed_pif = await robot.transform_pose(first_pif, "myArm")
print("Position: (x:", transformed_pif.pose.x, ", y:", transformed_pif.pose.y, ", z:", transformed_pif.pose.z, ")")
print("Orientation: (o_x:", transformed_pif.pose.o_x,
", o_y:", transformed_pif.pose.o_y,
", o_z:",transformed_pif.pose.o_z,
", theta:", transformed_pif.pose.theta, ")")
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.pose
([PoseInFrame]): The pose that should be transformed.dst
(string): The name of the reference frame to transform the given pose to.additionalTransforms
(Optional[LinkInFrame]): A list of additional transforms.
Returns:
- (error): An error, if one occurred.
PoseInFrame
(referenceframe.PoseInFrame): Transformed pose in destination reference frame.
For more information, see the Go SDK Docs.
// Define a Pose coincident with the world reference frame
firstPose := spatialmath.NewPoseFromPoint(r3.Vector{X: 0.0, Y: 0.0, Z: 0.0})
// Establish the world as the reference for firstPose
firstPoseInFrame := referenceframe.NewPoseInFrame(referenceframe.World, firstPose)
// Calculate firstPoseInFrame from the perspective of the origin frame of myArm
transformedPoseInFrame, err := robot.TransformPose(ctx, firstPoseInFrame, "myArm", nil)
fmt.Println("Transformed Position:", transformedPoseInFrame.Pose().Point())
fmt.Println("Transformed Orientation:", transformedPoseInFrame.Pose().Orientation())
Additional Transforms
Additional Transforms exist to help the Frame System determine the location of and relationships between objects not initially known to the robot.
For example:
In our example of nested dynamic attachment, the arm can be managed by the Frame System without additional transforms because the base of the arm is fixed with respect to the gantry’s platform, and the gantry’s origin is fixed with respect to the
world
reference frame (centered at(0, 0, 0)
in the robot’s coordinate system).However, an arm with an attached camera might generate additional information about the poses of other objects with respect to references frames on the robot.
With the Vision Service, the camera might detect objects that do not have a relationship to a
world
reference frame.If a camera is looking for an apple or an orange, the arm can be commanded to move to the detected fruit’s location by providing an additional transform that contains the detected pose with respect to the camera that performed the detection.
The detecting component (camera) would be fixed with respect to the
world
reference frame, and would supply the position and orientation of the detected object.With this information, the Frame System could perform the right calculations to express the pose of the object in the
world
reference frame.
Usage:
- You can pass a detected object’s frame information to the
supplemental_transforms
parameter in your calls to Viam’s Motion Service’sGetPose
method. - Functions of some services and components also take in a
WorldState
parameter, which includes atransforms
property. TransformPose
has the option to take in these additional transforms.
Was this page helpful?
Glad to hear it! If there is anything we could be doing better, please create an issue.
We're sorry about that. If you'd like to talk to us for help, please join the Community Discord. To ensure we know what's wrong with this page, you can also open an issue.