Drawing Protocol

One of the primary functions of RoboViz is allowing other processes or clients to perform drawing of simple shapes inside of RoboViz. This process may be referred to as remote drawing. To accomplish this, RoboViz has a simple network protocol for allowing clients to control custom drawing. The primary intention for this is to allow robots running on the SimSpark server to send information useful in debugging their internal state or behavior.

Clients interact with RoboViz by issuing commands. For drawing purposes, an example of a command is draw line, or draw sphere. Each command is formatted in a specific way that is suitable for it to be sent using UDP packets over a network. The details of how to format each command will be described below, but first it is necessary to understand how drawing works at a high level.

Shapes and Sets

To make remote drawing flexible and simple, all drawing is accomplished by working with a small set of shapes. More complex shapes must be constructed by using combinations of these shapes. A shape's description has properties such as position, color, and scale. Clients send commands to RoboViz that request it to add such shapes to its rendering; these commands are called draw shape commands.

Each shape is also part of a group of shapes called a shape set; these sets can contain one or more shapes. Every shape set is identified by a unique name (a string). When RoboViz receives draw shape commands from the client, it parses the individual shapes and adds them to their respective set. During rendering in RoboViz, each set is visited and its shapes are drawn.

Shapes are grouped into sets mainly so they can be filtered inside RoboViz. For example, each robot may have its own set of shapes so that the user of RoboViz can view only that agent's shapes and hide everything else. A robot may also have many sets for each type of behavior. How the sets are organized is entirely up to the client. However, the recommended to use a hierarchical naming pattern. For instance, a shape set name such as "RoboCanes.1.Behaviors.PathPlanning" might be used to indicate all shapes belonging to the first agent on a team called RoboCanes that pertain to path planning behavior. With this naming pattern, all of this particular agent's sets can be referenced as "RoboCanes.1".

Draw Option Commands

While draw shape commands request that RoboViz add shapes, they are not enough to sufficiently control the remote drawing process. Commands that influence the rendering process of shapes are called draw option commands. These commands are used for achieving animation and resolving concurrency issues.

Problems arise if a shape set is rendered at the same time RoboViz is receiving new draw shape commands for that set. To resolve this problem, each shape set has two buffers: a front and back buffer. When a client sends a draw shape command, RoboViz parses the shape and add it to the back buffer. These shapes will not be visible until the client sends a swap buffer command, at which point the back and front buffers swap roles. In other words, the front buffer always contains a set's shapes which may be rendered in RoboViz. It is important to note that as soon as RoboViz executes a buffer swap, the shape set's new back buffer is cleared of all shapes.

Static and Animated Shapes

The type of shapes a client can add to RoboViz may be categorized into two types: static and animated. Static shapes are those that persist after being added and do not need to be refreshed or updated. For example, a grid on top of the field or 3D coordinate axes do not require the shapes to change over time. Animated shapes are those that need to have their properties updated; a vector representing a robot's forward direction is an example.

Inside draw shape commands, there is absolutely no distinction between static and animated shapes. These types merely refer to how a client program treats the draw commands for a shape set. Static shapes have the advantage of only needing to be transmitted a single time and only require a single swap buffer command. Animated shapes must have their values sent repeatedly;  each time values are updated the shape set must also have its buffers swapped to display the changes.

Coordinate Systems

When issuing commands to RoboViz, it is assumed that you will use the coordinate system of the SimSpark simulation server. For SimSpark, the field is on the XY plane and the up direction is Z; RoboViz uses a more standard computer graphics coordinate system where the field is on the XZ plane and the up direction is Y.

The following figure shows the field in SimSpark coordinates. The center of the field is the origin. The current field dimensions are 18 meters in width and 12 meters in height; these values are subject to change!

Note: these dimensions have been changed to 21x14 instead of 18x12.