This guide will teach you how to create and configure a 3D Scene module.

Prerequisite: Create a view

Before you can set up a 3D Scene module, you need to create a view for your device. For more information, see Create a view and add modules.

Step 1: Create a 3D Scene module

Navigate to the view to which you want to add a 3D Scene module.
Click the dropdown next to the view name >> Edit...
Click the Add (+) Module button >> 3D Scene.

Step 2: Configure your 3D Scene module

The following sections will guide you through each configuration option for the 3D Scene module.

Maps

A map is a rendering of the space your robot inhabits. You can choose between two types of map as the base layer of your 3D Scene rendering: GPS map and occupancy map.

GPS

A GPS map layer is powered by either a GPS telemetry stream, or a default latitude and longitude.

Property	Usage
World map type	Set your GPS map to satellite image mode or street mode.
Map edge length	Select the size of your map. Larger map boundaries take longer to render and update.
Default latitude	Manual entry of the default latitude of your GPS map. N and E are positive values, S and W are negative values. If you specify a default latitude and default longitude, that location will become the origin of your scene and override the telemetry stream.
Default longitude	Manual entry of the default longitude of your GPS map. N and E are positive values, S and W are negative values. If you specify a default latitude and default longitude, that location will become the origin of your scene and override the telemetry stream.
Telemetry stream	Provide a GPS telemetry stream. The latitude and longitude of this GPS stream will set the origin of your map. If you specify a default latitude and default longitude, that location will become the origin of your scene and override the telemetry stream.
X offset	Set an x-axis offset of the center of your scene from the origin of the map.
Y offset	Set a y-axis offset of the center of your scene from the origin of the map.
Z offset	Set a z-axis offset of the center of your scene from the origin of the map.

Occupancy map

An occupancy map shows localization data in the vicinity of your robot.

Property	Usage
Telemetry stream	Provide a localization stream to feed the occupancy map visualization. For more information, see Add a ROS localization stream and Configure localization for teleoperation.
Use historical data	Enable if a live data stream is not available. Formant will use the most recent historical data available.
X offset (m)	Set an x-axis offset of the center of your scene from the origin of the map.
Y offset (m)	Set a y-axis offset of the center of your scene from the origin of the map.
Z offset (m)	Set a z-axis offset of the center of your scene from the origin of the map.

Device layers

This section describes the various layers you can add on top of your map.

Position indicator

You can add either a glowing dot or a URDF of your robot as the indicator of your device's position on the map.

📘
Position your device on the map
To position your device on the map, use the Cartesian, Odometry, or Transform tree transforms. This will place your device relative to the origin of the map.

Property	Usage
Use URDF	If ON, the robot's URDF file will be used to render a visualization of your robot. You must have a URDF file specified for your device. For more information, see Add a URDF file. If OFF, your robot's position will be represented by a glowing dot on the map.
Telemetry joint state stream	Telemetry stream containing joint state data. If realtime stream is also provided, it will override the telemetry stream and disconnect joint state data from the timeline.
Realtime joint state stream	Realtime stream containing joint state data. If specified, joint state will always reflect realtime position and will disconnect from the timeline.
Name	Name of this position indicator layer.
Enable trail	If ON, a trail will be left behind as your robot moves on the map.
Transform type	See the Transforms section below.

Marker array

Property	Usage
Name	Name of this marker array layer.
Allow transparency	If ON, Formant will read transparency values from marker array stream. If OFF, markers will render as opaque. Transparency requires additional computation time.
Telemetry stream	Provide a Marker Array stream to feed the geometry layer visualization
Transform	See the Transforms section below.

Point cloud

Property	Usage
Name	Name of this point cloud layer.
Decay time (s)	Set how long data points will stay in the point cloud visualization before disappearing.
Use color data	If enabled, Formant will display the color provided by the sensor. If disabled, Formant will auto-fill with a default color.
Telemetry stream	Telemetry stream containing point cloud data. If realtime stream is also provided, it will override the telemetry stream and disconnect point cloud data from the timeline.
Realtime stream	Realtime stream containing point cloud data. If specified, point cloud will always reflect realtime state and will disconnect from the timeline.
Transform	See the Transforms section below.

Path

Property	Usage
Name	Name of this path layer.
Path opacity %	Path opacity percentage between 0 - 100.
Path type	Static path stays the same size regardless of zoom. Dynamic path resizes with zoom for consistent display size.
Path width	Set path width between 0 - 10.
Telemetry stream	Localization stream from which to populate path.
Transform	See the Transforms section below.

Transforms

Use transforms to set the position of a layer relative to the origin of your 3D scene.

Cartesian

Sets the origin of a layer to the (x,y,z) coordinates relative to the origin of the map.

Property Name	Input	Usage
X offset	Layer's offset along the x-axis from the origin (meters)	Set the layer's x-axis offset from the scene's origin.
Y offset	Layer's offset along the y-axis from the origin (meters)	Set the layer's y-axis offset from the scene's origin.
Z offset	Layer's offset along the z-axis from the origin (meters)	Set the layer's z-axis offset from the scene's origin.

GPS

Sets the origin for a layer to (relative latitude, relative longitude). Layered object is placed according to the GPS stream. Distances in meters are then calculated between the GPS stream and the origin of the layer.

Property Name	Input	Usage
Relative latitude	Layer's origin latitude	Set layer's origin latitude. N and E are positive values, S and W are negative values.
Relative longitude	Layer's origin longitude	Set layer's origin longitude. N and E are positive values, S and W are negative values.
GPS stream	Name of GPS stream for layer	Provide a GPS stream to perform a GPS transformation on your layer. Position and distances for this layer will be calculated relative to the the Relative latitude and Relative longitude. For example, if the layer is a waypoint placed at `(45, 105)`, and the GPS stream reports a robot location of `(46,104)`, a distance measurement between the GPS stream and the layer's origin would report the distance in meters that is subtended by a `(lat, long)` difference of `(1,-1)`.

Odometry

Move an object in your scene based on odometry data, via either telemetry stream or realtime stream. When both streams are present, telemetry is prioritized. For more information on telemetry vs. realtime streams, see Telemetry vs realtime data streams.

Property Name	Input	Usage
Localization stream	Name of localization telemetry stream	Provide a localization stream to perform an odometry transformation on your layer.
Localization world to local	Boolean	Enable to perform a world-to-local transformation on your odometry data.
Localization realtime stream	Name of localization realtime stream	Provide a localization realtime stream to perform an odometry transformation on your layer.

Transform tree

Move an object in your scene based on transform tree data.

Property Name	Input	Usage
Transform tree stream	Name of transform tree stream	Provide a transform tree stream to perform a transform tree transformation on your layer.
Transform tree end point	Name of end point	Provide the name of the end point of interest in your transform tree.

Advanced options

Property	Usage
Sync with timeline	Set this to OFF if using during teleoperation. If ON, data will be shown at timeline point. If OFF, the 3D scene will ignore the timeline and always show live data.
Display ground	Toggle the ground plane.
Enable debug mode	Puts a bounding box around each layer to show their boundaries within the 3D Scene.

Add and configure a 3D Scene module

Prerequisite: Create a view

Step 1: Create a 3D Scene module

Step 2: Configure your 3D Scene module

Maps