Custom Gauge Ball - HeliosVirtualCockpit/Helios GitHub Wiki

Abstract

The Custom Gauge Ball control is a 3D Sphere which was primarily introduced to provide a more realistic component for an Attitude Indicator gauge. This control can be found in the Customer Controls section of the Profile Editor Toolbox.

The Texture

The texture is the rectangular image which gets wrapped around a sphere mesh.

The top side of the rectangular image will become the North Pole.
The bottom side of the rectangular image will become the South Pole.
Vertical lines on the image will become lines of Longitude.
Horizontal lines on the image will become lines of Latitude.
Ideally the image's Width should be twice the Height.
The image is wrapped starting at the rear of the sphere, with the central point of the rectangle sitting on the intersection of the equator and the Greenwich Meridian (ie in line with the Z-Axis), and completes the wrap at the rear of the image once again.

The Camera

This is the viewing position for the sphere, and is aligned at the front of the sphere along the Z-Axis. The camera cannot be moved.

Lighting

The sphere can be lit from a single point, with one color of light.

Axes Orientation

Without any initial rotations applied to the sphere, (from the perspective of the camera) the Axes are as follows:

The X-Axis runs from left to right through the centre of the sphere.
The Y-Axis runs through the poles * [^1] and the centre of the sphere.
The Z-Axis runs from the camera position straight through the centre of the sphere.

Note

The green circle represents the very centre of the sphere

Hopefully this is what you would expect.

Note

Once "initial rotations" are made to get the sphere to appear in the correct position when there are no "normal" rotations, it is very likely that one or more of the axes will have also been rotated. This can be a little confusing [^1]. In certain circumstances[^2] Helios will swap the X and Y axis in an attempt to make the rotations a little more intuitive.

Tip

If your initial rotations are not in multiples of 90°, then it is likely that your texture image is "wonky" and you should correct the texture image in preference to correcting the problem with initial rotations.

Rotations

All values used to rotate the Custom Gauge Ball are degrees.

Calibrations

Calibrations are used map the input values coming from DCS to the number of degrees needed to rotate an axis by the expected amount. Two point Calibrations can be applied to the values arriving from an interface for each of the axes. For example, an argument that exports a value in the range -1 to 1 from DCS (known as the input) might get mapped to values from 180 to -180 degrees to match the expected axes rotation (and direction) needed by the gauge (the output).

Note

Calibrations are not applied to the "Set All Rotations" input binding because setting calibrations are already available on the DCS.Common.DCSBallRotation interface function.

Field of View

This value can be set for the Custom Gauge Ball control, and effectively sets the size at which the sphere is rendered.

Performance

The 3D Sphere is a relatively expensive in performance terms, and therefore a new binding has been introduced in order to reduce the number of times the Custom Gauge Ball needs to be rendered. Using individual X, Y & Z bindings will result in 3 renders per value change, however using the "Set All Rotations" input binding will result in a single render per value change.

Tip

information about how to add a "Set All Rotations" function to an interface can be found here

If performance remains an issue, there is additional guidance / suggestions on this page

Additional Information

The built-in texture images used by Helios for 3D spheres are vector images which improves clarity when scaling. These images can be used with the Custom Gauge Ball.

Resource Name	Image
`{Helios}/Gauges/A-10/ADI/ADI-Ball.xaml`
`{M2000C}/Gauges/ADI/ADI_Ball.xaml`
`{FA-18C}/Gauges/ADI/ADI-Ball.xaml`
`{F-16C}/Gauges/ADI/Viper-ADI-Ball.xaml`
`{AH-64D}/Images/SAI/adi_ball1.xaml`
`{Helios}/Gauges/Common/ChequerBoard.xaml`