Skip to content

Compass

The Compass shows the heading and the course over ground of the vessel on a full compass rose. It can also show the heading setpoint, the rate of turn, the wind and the current. It is found in the Maritime - OpenBridge section of the Perspective Component Palette as Compass.

Compass with heading, course, setpoint and wind

The parts of the instrument:

  1. Compass rose — the ring with north marked. See Orientation.
  2. Heading and course arrows — the filled arrow is the heading (HDG), the outlined arrow the course over ground (COG). See Heading and Course.
  3. Vessel — a symbol of the vessel in the centre, turned to the heading, or readouts in its place. See Centre.
  4. Setpoint — the ordered heading, on the outer ring. See Heading Setpoint.
  5. Rate of turn — moving dots or a bar. See Rate of Turn.
  6. Wind and current — arrows outside the ring. See Wind and Current.

The Compass is one of the maritime instruments. State, priority, how a setpoint works, advice zones and sizing are shared by all of them and are described in Maritime Instruments — Common Features. This page covers what is specific to the Compass.

A Compass dropped from the palette shows heading and course 0° and has no labels:

Compass with default properties

Bind heading to the heading of the vessel and courseOverGround to its course over ground, both in degrees.

hdgArrowStyle and cogArrowStyle select how each is drawn:

hdgArrowStyle
arrowHead (default) Heading as an arrow head
needle Heading as a needle
vector Heading as a vector
beamLine Heading with a beam line
cogArrowStyle
arrowHead (default) Course as an arrow head
needle Course as a needle
vector Course as a vector
velocityVector Course as a velocity vector
Name Description Property Type
heading Heading of the vessel in degrees. Default 0. value
courseOverGround Course over ground in degrees. Default 0. value
hdgArrowStyle arrowHead, needle, vector or beamLine. Default arrowHead. value
cogArrowStyle arrowHead, needle, vector or velocityVector. Default arrowHead. value

direction selects what is up on the instrument:

direction
northUp (default) North is up; the vessel and the arrows turn. North up
headingUp The heading is up; the compass rose turns under the vessel. Heading up
courseUp The course over ground is up. Course up

showLabels shows the letters N, E, S and W; the north arrow is always shown. tickmarksInside moves the letters and the north arrow inside the outer ring, which makes the ring larger in the same box.

showLabels = false tickmarksInside = true
Compass without labels Compass with labels inside
Name Description Property Type
direction northUp, headingUp or courseUp. Default northUp. value
showLabels Show the letters N, E, S and W. Default false. value
tickmarksInside Place the letters and the north arrow inside the ring. Default false. value

Set headingSetpoint to the ordered heading to show a setpoint marker on the outer ring. Leave it empty (null) for no setpoint. The setpoint works as described in Setpoint, with heading in the property names.

Setpoint at 60° Reached A new setpoint being chosen
Compass with a setpoint Compass at its setpoint Compass with a new setpoint

Unlike most instruments, the Compass decides by itself when the setpoint is reached: autoAtHeadingSetpoint is true by default, with a deadband of 2°.

advices is a list of advice zones on the compass rose, with min and max as headings in degrees. Here, a caution zone from 70° to 100°:

Compass with a caution zone

A zone is triggered when the heading or the heading setpoint is inside it; adviceTrigger narrows that to the heading (value) or the setpoint alone. headingAdvices is the older name of the list. It still works, and when it is not empty it replaces advices, but use advices.

Name Description Property Type
headingSetpoint Ordered heading in degrees. Empty by default: no setpoint. value
autoAtHeadingSetpoint Let the compass decide when the setpoint is reached. Default true. value
autoAtHeadingSetpointDeadband Degrees the heading may differ from the setpoint and still count as reached. Default 2. Only shown when autoAtHeadingSetpoint is true. value
atHeadingSetpoint Whether the setpoint is reached. Only shown when autoAtHeadingSetpoint is false. value
touching The operator is operating the heading control. Default false. value
hasNewHeadingSetpoint Show a second marker for a setpoint that is being chosen. Default false. value
newHeadingSetpoint The setpoint being chosen. Only shown when hasNewHeadingSetpoint is true. value
animateSetpoint Animate the marker when a new setpoint is confirmed. Default false. value
headingSetpointAtZeroDeadband How close to zero the setpoint must be to be drawn in its “zero” form. Default 0.5. value
headingSetpointOverride Keep the setpoint in its normal colour in the loading and off states. Default false. value
advices Advice zones on the compass rose, with min and max in degrees. Empty by default. array
adviceTrigger Which reading triggers a zone: both (the heading or the setpoint), value (the heading) or setpoint. Default both. value
adviceEmphasis Apply the design’s emphasis rules between go-to and no-go zones. Default false. value
headingAdvices Deprecated, use advices. Still works: when not empty, it replaces advices. array

The Compass shows the rate of turn (ROT) in one of two ways, selected with rotType, and in one of two places, selected with rotPosition:

rotType rotPosition = innerCircle (default) rotPosition = scale
dots (default) Dots on the inner circle Dots on the scale
bar Bar on the inner circle Bar on the scale
  • dots — dots that travel around the ring, faster the faster the vessel turns, in the direction of the turn.
  • bar — an arc that starts at the heading and grows in the direction of the turn. It reaches rotArcExtent degrees of the ring when the rate of turn is rotMaxValue.

Set hasRateOfTurnDegreesPerMinute to true and bind rateOfTurnDegreesPerMinute to the rate of turn in degrees per minute; positive is a turn to starboard.

With rotPortStarboard set to true, the bar is drawn in the starboard colour (green) for a turn to starboard and in the port colour (red) for a turn to port:

Rate-of-turn bar in the starboard colour

Note: Until hasRateOfTurnDegreesPerMinute is set, the Compass uses the deprecated rotationsPerMinute property, which is 0 by default, so the dots of a new Compass stand still. Set hasRateOfTurnDegreesPerMinute to true and bind the value to show the rate of turn.

Name Description Property Type
hasRateOfTurnDegreesPerMinute Use rateOfTurnDegreesPerMinute. Default false. value
rateOfTurnDegreesPerMinute Rate of turn in degrees per minute; positive is starboard. Only shown when hasRateOfTurnDegreesPerMinute is true. value
rotType dots or bar. Default dots. value
rotPosition innerCircle or scale (the outer ring). Default innerCircle. value
rotDotAnimationFactor How much faster than the real rate the dots move. Default 18. Only shown when rotType is dots. value
rotMaxValue Rate of turn, in degrees per minute, at which the bar is full. Default 60. Only shown when rotType is bar. value
rotArcExtent Length of the full bar, in degrees of the ring. Default 60. Only shown when rotType is bar. value
rotAtZeroDeadband Rate of turn below which the bar is shown as zero. Default 0.05. Only shown when rotType is bar. value
rotPortStarboard Colour the bar by the direction of the turn. Default false. value
rotationsPerMinute Deprecated. Used when hasRateOfTurnDegreesPerMinute is false. Default 0. value

The Compass can show where the wind and the current come from, as arrows outside the ring that point towards the centre.

Wind Current
Compass with a wind arrow Compass with a current arrow
  • Wind — set windFromDirection to the direction the wind comes from, in degrees, and currentWindSpeedKnots to its speed in knots. The barbs on the arrow show the speed.
  • Current — set currentFromDirection to the direction the current comes from, and currentSpeed to the number of arrow heads to draw, as a measure of its strength.

Each arrow is shown only when both of its properties are set.

Name Description Property Type
windFromDirection Direction the wind comes from, in degrees. Empty by default. value
currentWindSpeedKnots Wind speed in knots. Empty by default. value
currentFromDirection Direction the current comes from, in degrees. Empty by default. value
currentSpeed Strength of the current, as a number of arrow heads. Empty by default. value

vesselImage selects the vessel symbol in the centre. There are symbols for several vessel types, each seen from the top, side, fore or aft; for the Compass use one seen from the top:

generic-top (default) cargo-top car-ferry-top
Generic vessel Cargo vessel Car ferry

The other top views are cargo-wind-top, fishing-vessel-top, psv-top, sov-top, tanker-top, drone-small-top, drone-medium-top, drone-generic-top and rov-top.

Instead of the vessel, the centre can show the numbers. centerReadouts is a list of readouts, each an object with a source: hdg for the heading, cog for the course over ground or rot for the rate of turn. The first is drawn large at the top and the rest side by side below it:

Compass with readouts in the centre

Note: The readouts keep their size while the compass scales. On a compass smaller than about 380 px they reach past the inner circle, so the dots on the inner circle pass over them; at about 250 px and below they also cover the N marker and the arrows. Give a compass with centre readouts at least 380 px, or use rotPosition scale or rotType bar to keep the dots off the readouts.

Name Description Property Type
vesselImage Vessel symbol in the centre. Default generic-top. Not drawn when centerReadouts has entries. value
vesselImageSrc Your own vessel image instead of vesselImage. See Custom Vessel Image. object
centerReadouts Readouts shown instead of the vessel, each with a source of hdg, cog or rot. Empty by default. array

state and priority work as described in State and Priority.

active loading off
Active compass Loading compass Compass that is off

With priority enhanced, priorityElements selects which parts get the enhanced colour: a list of hdg, cog, rot, wind and current. A new Compass lists hdg. The setpoint is drawn in the enhanced colour whatever the list holds. The property is only shown when priority is enhanced.

priority = enhanced, priorityElements empty priorityElements = ["hdg"] (the default)
Enhanced compass, nothing listed Compass with the heading enhanced
Name Description Property Type
priorityElements Parts drawn in the enhanced colour: hdg, cog, rot, wind, current. Default ["hdg"]. Only shown when priority is enhanced. array

These work in the same way on every maritime instrument, and are described in Maritime Instruments — Common Features:

The Compass has no component events of its own.

  1. Drop a Compass into the view and make it square, about 400 px.
  2. Set showLabels to true.
  3. Bind heading to [default]Nav/Heading and courseOverGround to [default]Nav/COG.
  4. Bind headingSetpoint to [default]Autopilot/HeadingOrder.
  5. Set hasRateOfTurnDegreesPerMinute to true, bind rateOfTurnDegreesPerMinute to [default]Nav/ROT, and set rotType to bar.
  6. Set priority to enhanced while the autopilot is engaged, with an expression such as if({[default]Autopilot/Engaged}, 'enhanced', 'regular').

Built on the OpenBridge Design System