Skip to content

Heading

The Heading instrument shows the heading and the course over ground of the vessel on a compass ring. It is the reduced form of the Compass: the same arrows, setpoint, orientation and centre, without rate of turn, wind and current. It is found in the Maritime - OpenBridge section of the Perspective Component Palette as Heading.

Heading with a setpoint and a vessel

The parts of the instrument:

  1. Compass ring — with north marked, and the letters N, E, S and W. See Orientation.
  2. Heading and course arrows — the heading (HDG) and the course over ground (COG). See Heading and Course.
  3. Setpoint — the ordered heading. See Heading Setpoint.
  4. Centre — a vessel symbol or readouts. See Centre.

The Heading is one of the maritime instruments. Priority, setpoints, advice zones and sizing are described in Maritime Instruments — Common Features. Use the Compass when the rate of turn, wind or current must be shown as well. The Heading has no state.

A Heading with default properties shows heading and course 0° as needles, a small car-ferry-aft vessel, and no labels. A Heading dropped from the palette starts with the generic-top vessel instead (see Centre):

Heading 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, as on the Compass (see Compass — Heading and Course), but on the Heading both are needle by default:

hdgArrowStyle
needle (default) Heading as a needle
arrowHead Heading as an arrow head
vector Heading as a vector
beamLine Heading with a beam line
cogArrowStyle
needle (default) Course as a needle
arrowHead Course as an arrow head
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 needle, arrowHead, vector or beamLine. Default needle. value
cogArrowStyle needle, arrowHead, vector or velocityVector. Default needle. value

direction selects what is up on the instrument, as on the Compass (see Compass — Orientation):

northUp (default) headingUp courseUp
North up Heading up Course up

showLabels shows the letters N, E, S and W, and tickmarksInside moves them inside the ring:

showLabels = false showLabels = true tickmarksInside = true
Without labels With labels Labels inside the ring

Note: The letters are only drawn when the component’s box is at least about 200 px; in a smaller box showLabels has no visible effect.

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

The heading setpoint works as on the Compass; see Compass — Heading Setpoint and Setpoint. Set headingSetpoint to the ordered heading and leave it empty for no setpoint. The Heading decides by itself when the setpoint is reached (autoAtHeadingSetpoint is true, with a deadband of 2°).

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

advices is a list of advice zones on the ring, with min and max as headings in degrees:

Heading with a caution zone from 70° to 100°

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 instrument 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
advices Advice zones on the ring, 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

vesselImage selects the vessel symbol in the centre, which turns with the heading. Use a symbol seen from the top; the list of top views is on the Compass page.

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

Note: A Heading dropped from the palette starts with generic-top. The default for a view that never set vesselImage, car-ferry-aft, is a view from astern, which shows as a tiny symbol in the centre. Set vesselImage to a top view such as generic-top. A Heading without any vessel symbol is not possible.

Instead of the vessel, the centre can show numbers. centerReadouts is a list of readouts, each an object with a source: hdg for the heading or cog for the course over ground. The first is drawn large at the top and the rest below it. Each entry can also have a label, a unit and fractionDigits. The source rot is accepted but has no value on the Heading and shows a dash.

[{source: hdg}, {source: cog}] [{source: hdg}, {source: rot}]
Heading and course readouts A rot readout shows a dash
Name Description Property Type
vesselImage Vessel symbol in the centre. Default car-ferry-aft; auto draws none. 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 or cog. Empty by default. array

priority works as described in Priority. With priority enhanced, priorityElements selects which arrows get the enhanced colour: a list of hdg and cog. A new Heading lists hdg. The setpoint is drawn in the enhanced colour whatever the list holds. The property is only shown when priority is enhanced.

regular (default) enhanced, priorityElements empty enhanced, priorityElements = ["hdg"] (the default)
Regular priority Enhanced priority, nothing listed Heading needle in the enhanced colour
Name Description Property Type
priorityElements Arrows drawn in the enhanced colour: hdg, cog. Default ["hdg"]. Only shown when priority is enhanced. array

The Heading fills the component’s box and is centred in it. With hasFaceDiameter the ring has a fixed size whatever the box; see Size. The blue frame is the component’s box:

Filling the box faceDiameter = 140
Heading filling its box Heading with a fixed face diameter

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

The Heading has no component events of its own.

Example 1 — Heading Display with a Heading Order

Section titled “Example 1 — Heading Display with a Heading Order”
  1. Drop a Heading into the view and make it square, about 300 px.
  2. Set showLabels to true and vesselImage to generic-top.
  3. Bind heading to [default]Nav/Heading and courseOverGround to [default]Nav/COG.
  4. Bind headingSetpoint to [default]Autopilot/HeadingOrder.

Built on the OpenBridge Design System