Compass2D

The Compass2D node allows the user to visualize the yaw, pitch and roll of a given input matrix and output a requested rotation and orientation based on this matrix.

Platform support

This element is fully supported on XR-Windows, XR-Portable Windows, XR-Portable iOS, XR-Portable Android, and XR-P WASM platforms.

Note: On touch screen, the buttons require a double-tap with finger instead of a single-click with mouse.

Yaw

The yaw represents the rotation around the vertical axis (usually the y axis). This displays the direction of the cardinal points relative to the input, and divides the space between the cardinal points in medium ticks, with associated buttons, and small ticks.

Ticks

The direction ticks are related to the cardinal direction buttons, while the small and medium ticks divide the space between the cardinal direction—based on the values of smallTicks and mediumTicks. For example, mediumTicks set to 3 will add three ticks between each cardinal direction, dividing the space into four equal spaces.

Customization

The ticks can be customized in various ways:

• color (directionTickColor, mediumTickColor, smallTickColor)

• size (directionTickSize, mediumTickSize, smallTickSize)

• alignment (directionTickAlignment, mediumTickAlignment, smallTickAlignment)

  Alignment options	Image
  down
  middle
  up

• style (directionTickStyle, directionTickStyle, directionTickStyle)

  Style options	Image
  rectangular
  roundedrectangle
  triangle

Buttons

Direction and medium ticks are related to a corresponding button, which indicates a direction. They can be pressed to output a rotation and orientation, based on the input matrix and the values of two fields: if directionButtonOverridePitchEnabled or mediumButtonOverridePitchEnabled is set to true (is enabled), when pressed the buttons will overwrite the pitch value of the input matrix with the directionButtonOverridePitch or mediumButtonOverridePitch for the output.

Customization

The ticks can be customized in various ways:

• color (directionTickColor, mediumTickColor, smallTickColor)

• size (directionButtonSize, mediumButtonSize)

• borderThickness (directionButtonBorderThickness, mediumButtonBorderThickness)

• style (directionButtonStyle, mediumButtonStyle)

  Style options	Image
  rectangle
  circle
  roundedrectangle

• offset (directionButtonVerticalOffset, mediumButtonVerticalOffset)

Button states

The buttons can be in one of four states.

Each state can be customized with:

• Color of the button background (directionButtonColor/mediumButtonColor)

• Color of the border of the button (directionBorderColor/mediumBorderColor)

Cardinal directions

The direction buttons also contain a text that represents the direction, each text can be modified (directionNames) to assign a value to each of the 4 cardinal directions and the value of the field must be four strings separated by a comma ',' (such as "N,E,S,W"): in order the first value will be given to the Z positive direction, the second to the X positive direction, the third to the Z negative direction and the fourth to the X negative direction.

The font can customized (directionFont) and the color can be changed for each button state (directionFontColor).

Pitch

The pitch represents the rotation around the horizontal, right-to-left axis. This displays the current pitch relative to the input.

• The pitch interaction (pitchInteractionMode) can be enabled to interact with it, disabled to just display but not interact with it, or invisible to not display at all.

• To interact with the pitch, keep the relative button pressed and slide it up and down to output a rotation and orientation.

• The pitch can also be inverted (pitchInvertion). When enabled, the pitch button will go in the bar, instead of going down, up when looking up.

Customization

The pitch can be customized in various ways:

• color (pitchLineColor, pitchButtonColor)

• size (pitchButtonSize, pitchLineSize)

Roll

The roll represents the rotation around the horizontal, front-to-back axis. This displays the current roll relative to the input. For now, the roll is only used as a display, without possible interactions.

Customization

The roll can be customized in various different ways:

• size (rollLineSize)

• color (rollLineColor)

• style (rollLineStyle)

  Style options	Image
  solid
  dash
  dot
  dash-dot
  dash-dot-dot
  custom	Use rollLineCustomPattern to set the custom pattern.

Interactions and output

The compass is used both to display the input matrix rotation and to output a requested rotation. This will be reflected in the outputRotation (squat) and outputOrientation (svec3) fields.

• Yaw — You can press on the medium and direction buttons. This will result on a single output base on the button.

  The user can also press outside these buttons and drag, this will output continuously with the yawset based on the position of the drag.

• Pitch — You can press on the pitch button and drag it up and down. This will result in a continuous output with the pitch modified and set based on the current position of the pitch button.

  If pitchTapEnabled is set to true the user can also directly tap outside the pitch button and inside the pitch area, the output will be based on the tap position.

  Fields	Type	Use	Default	Description
  yawFov	sfloat		360	The FOV visualized for the yaw.
  inputMatrix	sfloat	Read only		The input matrix read to display the rotation on the compass.
  inputEnabled	sbool		true	Enables or disables the reading of the inputMatrix
  interactionEnabled	sbool		true	Specifies whether the node is interactable or not, both with the buttons and the drag.
  outputRotation	squat	Read only		Given an interaction, button or drag, outputs the requested rotation.
  outputOrientation	svec3	Read only		Given an interaction, button or drag, outputs the requested orientation.
  dynamicFontScaling	sbool		true	Scales the font dynamically.
  pitchTapEnabled	sbool		true	Enables the interaction of tap on the pitch area.
  pitchInvertion	sbool		false	Inverts the movement of the pitch button, when looking up the pitch also goes up.
  pitchInteractionMode	senum		enabled	Values are: enable (can interact with the pitch area), disable (the pitch is displayed, but can't be interacted), invisible (not displayed).
  pitchIsDragging	sbool	Read only		Returns true while dragging on the pitch.
  yawOffset	sfloat		0	Adds an offset to the yaw of the input matrix.
  yawIsDragging	sbool	Read only		Returns true while dragging on the yaw.
  directionFont	sstring		Arial, antialias, 25	The font of the direction button text.
  directionNames	mstring		Z,X,-Z,-X	The names displayed on the direction button. Must be a length of 4, in order the Z or North, the X or East, the -Z or South and -X or West.
  directionTickAlignment	senum		down	Values are: up, middle, down. The position of the direction ticks on the yaw.
  directionTickSize	svec2		30 30	The size of the direction ticks on the yaw.
  directionTickStyle	senum		triangle	The style and shape of the direction ticks on the yaw. Values are: rectangle, roundedrectangle, triangle.
  directionButtonStyle	senum		roundedrectangle	The style and shape of the direction buttons. Values are: rectangle, roundedrectangle, circle.
  directionButtonSize	svec2		120 75	The size of the direction buttons on the yaw.
  directionButtonVerticalOffset	sfloat		0	Can be [-0.5, 0.5]. The vertical offset of the direction buttons on the yaw.
  directionButtonBorderThickness	sfloat		3	The thickness of the border of the direction buttons.
  directionButtonOverridePitch	sfloat		0	When directionButtonOverridePitchEnabled is enabled, overrides the output pitch with this value when pressing on a direction button.
  directionButtonOverridePitchEnabled	sbool		false	Enables the override of the pitch output when pressing a direction button.
  directionTickColor	svec4		1 1 1 0.9	The color of the direction ticks on the yaw.
  directionFontColor, directionOverFontColor, directionDownFontColor, directionDisabledFontColor	svec4		1 1 1 0.9	The color of the font, 4 different colors, one for each state: normal, over, pressed, and disabled.
  directionButtonColor, directionOverButtonColor, directionDownButtonColor, directionDisabledButtonColor	svec4		1 1 1 0	The color of the direction button, 4 different colors, one for each state: normal, over, pressed, and disabled.
  directionBorderColor, directionOverBorderColor, directionDownBorderColor, directionDisabledBorderColor	svec4		1 1 1 0	The color of the direction button border, 4 different colours, one for each state: normal, over, pressed, and disabled.
  mediumTicks	sint		1	The number of medium ticks and buttons between each direction button.
  mediumTickAligment	senum		down	The position of the medium ticks on the yaw. Values are: up, middle, down.
  mediumTickSize	svec2		6 25	The size of the medium ticks on the yaw.
  mediumTickStyle	senum		rectangle	The style and shape of the medium ticks on the yaw. Values are: rectangle, roundedrectangle, triangle.
  mediumButtonStyle	senum		circle	The style and shape of the medium buttons. Values are: rectangle, roundedrectangle, circle.
  mediumButtonSize	svec2		45 45	The size of the direction medium on the yaw.
  mediumButtonVerticalOffset	sfloat		0	Can be [-0.5, 0.5]. The vertical offset of the medium buttons on the yaw.
  mediumButtonOverridePitch	sfloat		0	When mediumButtonOverridePitchEnabled is enabled, this overrides the output pitch with this value when pressing a medium button.
  mediumButtonOverridePitchEnabled	sbool		false	Enable the override of the pitch output when pressing a medium button.
  mediumButtonBorderThickness	sfloat		1	The thickness of the border of the medium buttons.
  mediumTickColor	svec4		1 1 1 0.9	The color of the direction ticks on the yaw.
  mediumButtonColor, mediumOverButtonColor, mediumDownButtonColor, mediumDisabledButtonColor	svec4		0.55 0.70 0.89 1	The color of the medium buttons—four different colors, one for each state: normal, over, pressed and disabled.
  mediumBorderColor, mediumOverBorderColor, mediumDownBorderColor, mediumDisabledBorderColor	svec4		1 1 1 0	The color of the medium buttons borders—four different colors, one for each state: normal, over, pressed and disabled.
  smallTicks	sint		3
  smallTickAlignment	senum		down	The position of the small ticks on the yaw. Values are: up, middle, down.
  smallTickSize	svec2		4 12	The size of the direction ticks on the yaw.
  smallTickStyle	senum		rectangle	The style and shape of the small ticks on the yaw. Values are: rectangle, roundedrectangle, triangle.
  smallTickColor	svec4		1 1 1 0.9	The color of the small ticks on the yaw.
  rollLineShow	sbool		true	If enabled, show the roll line on the compass.
  rollLineSize	sfloat		10	The size of the roll line on the compass.
  rollLineStyle	senum		solid	Values are: solid, dash, dot, dashDot, dashDotDot, custom.
  rollLineCustomPattern	mfloat		2 1 1 2	A custom pattern applied when rollLineStyle is set to custom.
  rollLineColor	svec4		1 1 1 0.9	The color of the roll line in the compass.
  backgroundColor	svec4		0.2 0.2 0.2 0.1	The color of the background of the compass.
  pitchButtonSize	sfloat		30	The size of the pitch button on the pitch area.
  pitchLineSize	sfloat		10	The size of the pitch line that shows the pitch area.
  pitchLineColor	svec4		1 1 1 0.5	The color of the pitch line.
  pitchButtonColor	svec4		1 1 1 0.9	The color of the pitch button used to interact with the pitch area.