Skip to content

Pitch Roll

The Pitch Roll shows the pitch and the roll of the vessel in one instrument: the pitch on the arcs to the left and right, the roll on the arcs at the top and bottom, and the vessel seen from the side and from the fore in the centre. It is found in the Maritime - OpenBridge section of the Perspective Component Palette as Pitch Roll.

Pitch Roll with a pitch of 3° and a roll of 8°

The parts of the instrument:

  1. Pitch arcs — left and right, with the needle and the average band of the pitch.
  2. Roll arcs — top and bottom, with the needle and the average band of the roll.
  3. Vessels — seen from the side and from the fore, or readouts in their place. See Centre.

It combines a Pitch and a Roll. The average bands, the advice, the arcs, the vessel images and the readouts work as described on the Pitch page, with the name of the axis in the property names.

A Pitch Roll dropped from the palette shows pitch and roll 0° (shown here at 300 × 300 px; a new Pitch Roll is 509 × 509 px):

Pitch Roll with default properties

Bind pitch and roll to the pitch and roll of the vessel in degrees. Positive values turn the needles clockwise. minAvgPitch, maxAvgPitch, minAvgRoll and maxAvgRoll draw the average bands.

type selects the layout. Unlike the Pitch and the Roll, the default is the dual scale:

dual-scale (default) single-scale
Four arcs Pitch on the right, roll at the bottom
  • dual-scale — the pitch on the left and right arcs, the roll on the top and bottom arcs.
  • single-scale — one pitch arc on the right and one roll arc at the bottom, with a thin ring completing the circle and needle lines from the centre.
Name Description Property Type
pitch Pitch in degrees. Default 0. value
roll Roll in degrees. Default 0. value
type dual-scale or single-scale. Default dual-scale. value
minAvgPitch Lower end of the pitch average band. Default 0. value
maxAvgPitch Upper end of the pitch average band. Default 0. value
minAvgRoll Lower end of the roll average band. Default 0. value
maxAvgRoll Upper end of the roll average band. Default 0. value

The pitch and the roll each have caution zones, as described in Pitch Advice. The zones turn to the caution colour only when their trigger… property is true; here triggerRollAdvice:

Pitch advice 10°, roll advice 15° triggerRollAdvice = true
Caution zones on all arcs Triggered roll caution zones
Name Description Property Type
hasMaxPitchAdvice Show the pitch caution zones. Default false. value
maxPitchAdvice Largest recommended pitch. Only shown when hasMaxPitchAdvice is true. value
triggerPitchAdvice Draw the pitch zones in the caution colour. Only shown when hasMaxPitchAdvice is true. value
hasMaxRollAdvice Show the roll caution zones. Default false. value
maxRollAdvice Largest recommended roll. Only shown when hasMaxRollAdvice is true. value
triggerRollAdvice Draw the roll zones in the caution colour. Only shown when hasMaxRollAdvice is true. value

arcAngle is how far each of the arcs reaches to each side of its centre; the default 30 gives four arcs of 60°. zoomToFitArc enlarges the arcs to fill the box, as described in Arc and Zoom.

To give the pitch and the roll different reaches, set hasPitchArcAngle and pitchArcAngle (the left and right arcs), or hasRollArcAngle and rollArcAngle (the top and bottom arcs). An axis without its own angle uses arcAngle.

arcAngle = 30 (default) 15, zoomToFitArc = true pitchArcAngle = 15
Arcs of ±30° Arcs of ±15° enlarged Shorter pitch arcs
Name Description Property Type
arcAngle Reach of each arc to each side, in degrees. Default 30. value
zoomToFitArc Enlarge the arcs to fill the box. Default false. value
hasPitchArcAngle Give the pitch arcs their own reach. Default false. value
pitchArcAngle Reach of the pitch arcs. Default 30. Only shown when hasPitchArcAngle is true. value
hasRollArcAngle Give the roll arcs their own reach. Default false. value
rollArcAngle Reach of the roll arcs. Default 30. Only shown when hasRollArcAngle is true. value

The centre shows the vessel from the side (vesselImageSide, turned with the pitch) and from the fore (vesselImageFore, turned with the roll). Choose them as described in Vessel Image and on the Roll. scaleForeImage enlarges the fore view:

Cargo vessel scaleForeImage = 2
Cargo vessel from side and fore Larger fore view

Set hasReadout to true to show the pitch (above) and the roll (below) as numbers instead of the vessels. A new Pitch Roll has pitchLabel Pitch, rollLabel Roll and the shared unit DEG; clear them to show the numbers only:

hasReadout = true Labels and unit cleared
Readouts with labels Readouts, numbers only

Note: With labels, the readouts need more room than the space between the arcs: at 200 px the labels overlap the arcs, as in the left image. Make the instrument larger, or clear the labels.

Name Description Property Type
vesselImageSide Vessel seen from the side. Default psv-side. value
vesselImageSideSrc Your own side view instead of vesselImageSide. See Custom Vessel Image. object
vesselImageFore Vessel seen from the fore. Default psv-fore. value
vesselImageForeSrc Your own fore view instead of vesselImageFore. See Custom Vessel Image. object
scaleForeImage Size factor for the fore view. Default 1. value
hasReadout Show the pitch and roll as numbers instead of the vessels. Default false. value
pitchLabel Label of the pitch readout. Default Pitch. Only shown when hasReadout is true. value
rollLabel Label of the roll readout. Default Roll. Only shown when hasReadout is true. value
unit Unit of both readouts. Default DEG. Only shown when hasReadout is true. value
fractionDigits Number of decimals in both readouts. Default 0. Only shown when hasReadout is true. value

priority works as described in Priority. With enhanced, priorityElements limits the enhanced colour to some of the axes: a list of pitch and roll.

priority = enhanced priorityElements = ["roll"]
Enhanced Pitch Roll Only the roll enhanced

A new Pitch Roll lists both axes, so enhanced colours the whole instrument, as in the left image. With an empty priorityElements nothing is drawn in the enhanced colour.

Name Description Property Type
priorityElements Axes drawn in the enhanced colour: pitch, roll. Default ["pitch", "roll"]. array

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

  • Priority — priority.
  • Size — the Pitch Roll fills the smaller side of its box as a circle; it has no faceDiameter.
  • Style and Events — style.

The Pitch Roll has no component events of its own.

  1. Drop a Pitch Roll into the view and make it about 300 × 300 px.
  2. Bind pitch to [default]Motion/Pitch and roll to [default]Motion/Roll.
  3. Set hasMaxRollAdvice to true and maxRollAdvice to 15, and bind triggerRollAdvice to abs({[default]Motion/Roll}) > 15.
  4. Set vesselImageSide to cargo-side and vesselImageFore to cargo-fore.

Built on the OpenBridge Design System