Maritime Instruments — Common Features
The maritime instruments show the navigation and propulsion state of a vessel: heading, rudder angle, thrust, speed, motion, wind and so on. They are found in the Maritime - OpenBridge section of the Perspective Component Palette. Each instrument has its own page; this page describes what they have in common.

| Kind | Components |
|---|---|
| Heading and course | Compass, Compass Flat, Compass Sector, Heading, Rate Of Turn, Rot Linear, Rot Sector |
| Steering and propulsion | Rudder, Azimuth Thruster, Main Engine, Thruster, Wind Propulsion, Azimuth Thruster Labeled (deprecated) |
| Motion | Pitch, Roll, Pitch Roll, Pitch Roll Heave, Pitch Roll Yaw, Heave, Surge Sway Yaw |
| Speed and depth | Speed Gauge, Speed Arrows, Depth Actual |
| Wind | Wind, Velocity Projection Plot |
| Gauges | Gauge Vertical, Gauge Horizontal, Gauge Radial, Gauge Trend |
| Readouts | Readout, Readout List Item, Instrument Field (deprecated) |
| Indicators | Rudder Indicator, Compass Indicator, Heading Indicator, Bearing Indicator, Rot Indicator, Main Engine Indicator, Propulsion Azimuth Indicator, Tunnel Thruster, Pitch Indicator, Roll Indicator, Heave Indicator, Speed Indicator, Depth Indicator, Wind Indicator, Gauge Radial Indicator, Gauge Bar Indicator, Gauge Trend Indicator |
The images on this page show a Rudder. The features look and work the same on the other instruments, though not every instrument has all of them.
An instrument shows the values it is given. It does not read tags itself, and it takes no input from the operator: bind its properties to the tags of the sensor or the control system. The colours follow the OpenBridge palette of the session:

Instruments and Indicators
Section titled “Instruments and Indicators”Most instruments come in two forms:
- The instrument (Rudder, Compass, Gauge Vertical, …) is the full
presentation, with a scale, labels, setpoint and advice zones. What is on
this page applies to the instruments — but not every instrument has every
feature: the motion instruments, for instance, have no
state. The page of each instrument lists what it has. - The indicator (Rudder Indicator, Heading Indicator, …) is a small,
simplified symbol of the same quantity, for overviews and for places where
the exact value is shown elsewhere. It has only a few properties. Many
indicators use
type(enhancedorregular) instead ofpriority, take a value scaled from −1 to 1, and have their ownstatevalues: see the page of each indicator.
state tells whether the value shown can be trusted:
| state | ||
|---|---|---|
active (default) |
The instrument shows a live value. | ![]() |
loading |
The value is not available yet. The instrument is dimmed. | ![]() |
off |
The equipment is off or has no signal. The instrument is dimmed and the face is empty. | ![]() |
Bind state to the quality of the signal, so the operator is never shown an old
value as if it were live.
Properties
Section titled “Properties”| Name | Description | Property Type |
|---|---|---|
| state | active, loading or off. Default active. |
value |
Priority
Section titled “Priority”priority selects the colours of the value and the setpoint. Use enhanced for
the instruments the operator is steering by at the moment, and regular for the
rest, so that the important instruments stand out.
regular (default) |
enhanced |
|---|---|
![]() |
![]() |
Properties
Section titled “Properties”| Name | Description | Property Type |
|---|---|---|
| priority | regular or enhanced. Default regular. |
value |
Setpoint
Section titled “Setpoint”An instrument for something that is controlled — a rudder, a thruster, a heading — can show the setpoint: the value that has been ordered, next to the value that has been reached.
Set hasSetpoint to true and bind setpoint to the ordered value. A marker
is drawn on the scale:
| Without setpoint | With setpoint |
|---|---|
![]() |
![]() |
On instruments with more than one controlled value, each has its own set of
these properties with the name of the value in it: headingSetpoint on a
Compass, angleSetpoint and thrustSetpoint on an Azimuth Thruster. They work
in the same way.
At Setpoint
Section titled “At Setpoint”When the value has reached the setpoint, the marker is drawn in its “at setpoint” form, docked to the value:
| Not at setpoint | At setpoint |
|---|---|
![]() |
![]() |
There are two ways to decide when the setpoint is reached:
- Automatically — set
autoAtSetpointtotrue. The instrument compares the value with the setpoint itself, and treats them as equal when they differ by no more thanautoAtSetpointDeadband. - From the control system — leave
autoAtSetpointatfalseand bindatSetpointto the signal that says the setpoint is reached.
Changing the Setpoint
Section titled “Changing the Setpoint”Two properties support a control the operator uses to change the setpoint:
touching— set it totruewhile the operator has a hand on the lever or is dragging the control. The marker is drawn in its focus form, and “at setpoint” is not shown while it lasts.newSetpoint— for a control where the new value must be confirmed. SethasNewSetpointtotrueandnewSetpointto the value being chosen: the current setpoint is dimmed and a second marker shows the new one. When the operator confirms, write the value tosetpointand sethasNewSetpointtofalse. WithanimateSetpointthe marker slides to its new place.
touching |
newSetpoint |
|---|---|
![]() |
![]() |
Setpoint in the Loading and Off States
Section titled “Setpoint in the Loading and Off States”The setpoint is dimmed together with the rest of the instrument when state is
loading or off. Set setpointOverride to true to keep the setpoint in its
normal colour — for a control whose order is still valid although the feedback
is missing.
setpointOverride = false |
setpointOverride = true |
|---|---|
![]() |
![]() |
Properties
Section titled “Properties”| Name | Description | Property Type |
|---|---|---|
| hasSetpoint | Show the setpoint. Default false. |
value |
| setpoint | The ordered value. Only shown when hasSetpoint is true. |
value |
| autoAtSetpoint | Let the instrument decide when the setpoint is reached. Default false. |
value |
| autoAtSetpointDeadband | How far the value may be from the setpoint and still count as reached, with autoAtSetpoint. |
value |
| atSetpoint | Whether the setpoint is reached. Used when autoAtSetpoint is false. Default false. |
value |
| touching | The operator is operating the control. Default false. |
value |
| hasNewSetpoint | Show a second marker for a setpoint that is being chosen. Default false. |
value |
| newSetpoint | The setpoint being chosen. Only shown when hasNewSetpoint is true. |
value |
| animateSetpoint | Animate the marker when a new setpoint is confirmed. Default false. |
value |
| setpointAtZeroDeadband | How close to zero the setpoint must be to be drawn in its “zero” form. | value |
| setpointOverride | Keep the setpoint in its normal colour in the loading and off states. Default false. |
value |
Advice Zones
Section titled “Advice Zones”An advice marks a part of the scale: a range, or a single point, that is
recommended or that calls for care. advices is a list of advices, each an
object:
| Name | Description | Property Type |
|---|---|---|
| category | What the advice is for: optimal, running or eco for a range to keep to, ai for a suggestion from a simulation or an analysis, caution, warning or alarm, and exclusion. |
value |
| min | Start of a range, in the unit of the scale. | value |
| max | End of a range. | value |
| value | A point advice: one value instead of min and max. |
value |
| state | The appearance at rest: enabled (the default), hinted (dimmed, less prominent), active or triggered. |
value |
A new advice added in the Property Editor starts with category, min, max
and state filled in.
Views made with earlier versions use older names, which still work: type for
category (advice is read as optimal), hinted: true for state
hinted, and minAngle/maxAngle, minValue/maxValue or
minSpeed/maxSpeed for min/max. Some instruments also had their own name
for the whole list, such as headingAdvices on the Compass; it still works,
but use advices.
| category | state = enabled |
state = hinted |
|---|---|---|
optimal (older name: advice) |
![]() |
![]() |
caution |
![]() |
![]() |
An advice is triggered, and drawn in its alert colour, when the value or the
setpoint is inside it. adviceTrigger narrows that to value or setpoint
alone. Earlier versions of the module triggered most instruments by the setpoint
only, and the Gauge Radial and the Speed Gauge by the value only; set
adviceTrigger to keep that behaviour.
| Value inside the advice | Setpoint inside the advice |
|---|---|
![]() |
![]() |
With adviceEmphasis on, the design’s emphasis rules apply: at rest the go-to
bands are active and the no-go bands enabled, and a hit on one group turns the
other hinted. Off, every advice keeps its state until its own range is hit.
The Gauge Trend keeps its own list, advice, switched on with hasAdvice.
Properties
Section titled “Properties”| Name | Description | Property Type |
|---|---|---|
| advices | The list of advices described above. Empty by default. | array |
| adviceTrigger | Which reading triggers an advice: both (the default), value or setpoint. |
value |
| adviceEmphasis | Apply the design’s emphasis rules described above. Default false. |
value |
| Name | Description | |
|---|---|---|
| showLabels | Show the numbers of the scale. | ![]() |
| tickmarksInside | Draw the tickmarks and labels inside the ring instead of outside it, which makes the ring larger in the same box. | ![]() |
| tickmarkStyle | regular, or enhanced for darker, more prominent tickmarks. |
![]() |
Instruments with a free scale also have primaryTickmarkInterval,
secondaryTickmarkInterval and tertiaryTickmarkInterval: the distance between
the long, labelled tickmarks, the medium ones and the short ones. Each is turned
on with its has… property.
Custom Vessel Image
Section titled “Custom Vessel Image”The instruments that draw a vessel can show your own drawing instead of a
built-in one. Each vessel image property has a matching object property ending
in Src — vesselImageSrc, vesselImageSideSrc or vesselImageForeSrc —
which works like the source of Perspective’s Image component:
| Name | Description |
|---|---|
| source | The image, used in every palette that has no image of its own: a gateway image (/system/images/…, uploaded in the Image Management tool), an http(s) URL or a data URL. SVG or PNG. |
| bright | Image for the bright palette. Empty uses source. |
| day | Image for the day palette. Empty uses source. |
| dusk | Image for the dusk palette. Empty uses source. |
| night | Image for the night palette. Empty uses source. |
With every URL empty, the instrument draws the built-in vessel chosen by the vessel image property. With any URL set, the custom image replaces it, is drawn in the same place and size (a square box, as a 160 × 160 drawing with the vessel centred), and turns with the instrument in the same way.
An image loaded by URL keeps its own colours and cannot follow the palette, so a drawing made for the day palette stays light on a night screen. Give the palettes their own drawings: the instrument switches image when the palette changes. A palette without an image uses the nearest one that has one.
For example, a tug seen from the side on a Pitch:
"vesselImageSideSrc": { "source": "/system/images/vessels/tug-side-day.svg", "night": "/system/images/vessels/tug-side-night.svg"}The Compass, Heading, Wind, Velocity Projection Plot and Pitch Roll Yaw take
vesselImageSrc (a top view); the Pitch takes vesselImageSideSrc; the Roll
takes vesselImageForeSrc; the Pitch Roll and Pitch Roll Heave take both. The
Heave and Depth Actual take vesselImageSrc too, but draw it as a view from
ahead.
Most instruments — the round ones — fill the component’s box and are centred in it: make the component larger and the instrument grows. The blue frame in the images is the component’s box:
| Small box | Large box |
|---|---|
![]() |
![]() |
The labels need room inside the box, so two instruments in boxes of the same
size can end up with rings of different size if their labels differ. To make the
rings of several instruments exactly equal, set hasFaceDiameter to true and
give them the same faceDiameter, the diameter of the ring in pixels. The
instrument then has that size whatever the box, and is placed at the top left of
it:

Some instruments do not fill their box, and keep a size of their own at the top left of it: the linear gauges (Gauge Vertical, Gauge Horizontal), the Gauge Trend, and many of the indicators, which are a fixed 48 px. Others keep their proportions (Main Engine, Thruster). Each page says how the instrument sizes itself; give such a component a box at least that large, or it is cut off.
Properties
Section titled “Properties”| Name | Description | Property Type |
|---|---|---|
| hasFaceDiameter | Give the ring a fixed diameter instead of filling the box. Default false. |
value |
| faceDiameter | Diameter of the ring in pixels. Only shown when hasFaceDiameter is true. |
value |
Style and Events
Section titled “Style and Events”| Name | Description | Property Type |
|---|---|---|
| style | Standard Perspective style object. | object |
The instruments have no component events of their own. The standard Perspective
events, such as onClick, are available in the component’s event configuration.
Examples
Section titled “Examples”Example 1 — Setpoint from the Control System
Section titled “Example 1 — Setpoint from the Control System”On a Rudder:
- Bind
angleto the rudder feedback, for example[default]Steering/RudderAngle. - Set
hasSetpointtotrueand bindsetpointto[default]Steering/RudderOrder. - Set
autoAtSetpointtotrueandautoAtSetpointDeadbandto1, so the marker shows “at setpoint” when the rudder is within 1° of the order. - Bind
stateto an expression that givesoffwhen the feedback has bad quality, for exampleif(isGood({[default]Steering/RudderAngle}), 'active', 'off').
Found an error or something unclear?
Tell us what is wrong, confusing or missing on this page.
Built on the OpenBridge Design System



















