Skip to content

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.

A rudder instrument with a setpoint

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:

A rudder instrument in the night palette

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 (enhanced or regular) instead of priority, take a value scaled from −1 to 1, and have their own state values: see the page of each indicator.

state tells whether the value shown can be trusted:

state
active (default) The instrument shows a live value. Active instrument
loading The value is not available yet. The instrument is dimmed. Loading instrument
off The equipment is off or has no signal. The instrument is dimmed and the face is empty. Instrument that is off

Bind state to the quality of the signal, so the operator is never shown an old value as if it were live.

Name Description Property Type
state active, loading or off. Default active. value

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
Regular priority Enhanced priority
Name Description Property Type
priority regular or enhanced. Default regular. value

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
Instrument without a setpoint Instrument with a 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.

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
Setpoint not reached Setpoint reached

There are two ways to decide when the setpoint is reached:

  • Automatically — set autoAtSetpoint to true. The instrument compares the value with the setpoint itself, and treats them as equal when they differ by no more than autoAtSetpointDeadband.
  • From the control system — leave autoAtSetpoint at false and bind atSetpoint to the signal that says the setpoint is reached.

Two properties support a control the operator uses to change the setpoint:

  • touching — set it to true while 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. Set hasNewSetpoint to true and newSetpoint to the value being chosen: the current setpoint is dimmed and a second marker shows the new one. When the operator confirms, write the value to setpoint and set hasNewSetpoint to false. With animateSetpoint the marker slides to its new place.
touching newSetpoint
Setpoint while touching A new setpoint being chosen

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
Dimmed setpoint Setpoint kept in colour
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

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) Optimal advice Hinted optimal advice
caution Caution advice Hinted caution advice

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
Value inside a caution advice Setpoint inside a caution 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.

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. Scale with labels
tickmarksInside Draw the tickmarks and labels inside the ring instead of outside it, which makes the ring larger in the same box. Tickmarks inside the ring
tickmarkStyle regular, or enhanced for darker, more prominent tickmarks. Enhanced 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.


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
Instrument in a small box Instrument in a 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:

Instrument with a fixed face diameter

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.

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

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.

Example 1 — Setpoint from the Control System

Section titled “Example 1 — Setpoint from the Control System”

On a Rudder:

  1. Bind angle to the rudder feedback, for example [default]Steering/RudderAngle.
  2. Set hasSetpoint to true and bind setpoint to [default]Steering/RudderOrder.
  3. Set autoAtSetpoint to true and autoAtSetpointDeadband to 1, so the marker shows “at setpoint” when the rudder is within 1° of the order.
  4. Bind state to an expression that gives off when the feedback has bad quality, for example if(isGood({[default]Steering/RudderAngle}), 'active', 'off').

Built on the OpenBridge Design System