Positioner (Class)
Namespace: Wrld.Space.Positioners
A Positioner represents a point at a geographic location on an indoor or outdoor map, and provides a convenient means of positioning an object when its absolute altitude may be unknown. A Positioner’s latitude and longitude are explicitly specified. However, its vertical position is defined implicitly, by specifying an elevation relative to one of:
Mean Sea Level.
The ground at the specified latitude and longitude.
An indoor map floor.
A resultant position is calculated for the specified relative elevation. This calculation may depend on streamed map resources being loaded - for example, terrain or indoor maps. As dependent map resources become available, the resultant position is re-calculated with an updated vertical component.
This resultant position is also transformed by any current map animation - for example, when viewing an indoor map in ‘expanded’ view, or when viewing an outdoor map in ‘map collapse’ view. Change to this resultant transformed point is notified via OnTransformedPointChanged.
In addition, a screen-space projection of the resultant position is provided, which is convenient for positioning a screen-space UI element so that it appears anchored relative to a geographic location.
Fields
| Name | Type | Description |
|---|---|---|
| OnTransformedPointChanged | Action | Notification that the resultant transformed point of this Positioner instance has changed. An app may hook to this event in order to respond to a change to a Positioner by accessing the updated resultant transformed point via Positioner.TryGetECEFLocation or Positioner.TryGetLatLongAltitude. |
| OnScreenPointChanged | Action | Notification that the screen projection of the resultant transformed point of this Positioner instance has changed. An app may hook to this event in order to respond to a change to a Positioner by accessing the updated projected screen-space point via Positioner.TryGetScreenPoint. |
| OnPositionerPositionChangedDelegate | Action | Deprecated - synonymous with OnScreenPointChanged. Alternatively, consider using OnTransformedPointChanged if responding to changes to the resultant world-space position of this Positioner. |
Methods
bool TryGetECEFLocation (out DoubleVector3 out_positionerECEFLocation)
Try to get the resultant transformed position of this Positioner as an ECEF coordinate. The method returns false if the resultant transformed position is not currently defined - in which case IsTransformedPointDefined would also return false.
Returns: True if the Positioner’s ECEF location could be determined, false otherwise.
| Argument | Type | Description |
|---|---|---|
| out_positionerECEFLocation | DoubleVector3 | If the return value is true, the resultant transformed position of this Positioner, represented as an ECEF coordinate; else a zero value. |
bool TryGetLatLongAltitude (out LatLongAltitude out_latLongAlt)
Try to get the resultant transformed position of this Positioner as a LatLongAltitude. The method returns false if the resultant transformed position is not currently defined - in which case IsTransformedPointDefined would also return false. To transform out_latLongAlt into a world-space translation, see SpacesApi.GeographicToWorldPoint.
Returns: True if out_latLongAlt was successfully set; else false.
| Argument | Type | Description |
|---|---|---|
| out_latLongAlt | LatLongAltitude | If the return value is true, the resultant transformed position of this Positioner, represented as a LatLongAltitude; else a zero value |
bool TryGetScreenPoint (out Vector3 out_screenPoint)
Try to get the projected screen-space position of the resultant transformed position. Try to get the on-screen position of this Positioner. Note that the screen point value obtained via this method may change every frame.
Returns: True if the Positioner’s screen point could be determined, false otherwise.
| Argument | Type | Description |
|---|---|---|
| out_screenPoint | Vector3 | The screen point of this Positioner. The value is only valid if the returned result is true. |
void SetLocation (double latitudeDegrees, double longitudeDegrees)
Set the explicit latitude and longitude coordinates of this Positioner.
| Argument | Type | Description |
|---|---|---|
| latitudeDegrees | double | The latitude, in degrees. |
| longitudeDegrees | double | The longitude, in degrees. |
void SetPosition (LatLong position)
Set the explicit latitude and longitude coordinates of this Positioner.
| Argument | Type | Description |
|---|---|---|
| position | LatLong | The position as a LatLong. |
LatLong GetPosition ()
Get the explicitly-set latitude and longitude coordinates of this Positioner.
Returns: The position as a LatLong.
void SetElevation (double elevation)
Set the elevation of this Positioner, in meters. The behaviour of this depends on the ElevationMode.
| Argument | Type | Description |
|---|---|---|
| elevation | double | The elevation, in meters. |
double GetElevation ()
Get the elevation of this Positioner, in meters.
Returns: The elevation of this Positioner, in meters.
void SetElevationMode (ElevationMode elevationMode)
Set the ElevationMode of this Positioner. See the ElevationMode documentation for more details.
| Argument | Type | Description |
|---|---|---|
| elevationMode | ElevationMode | The ElevationMode of this positioner. |
ElevationMode GetElevationMode ()
Get the ElevationMode of this Positioner.
Returns: The ElevationMode of this Positioner.
void SetIndoorMap (String indoorMapId, int indoorMapFloorId)
Sets the Indoor Map of this Positioner. If this is unset, the Positioner will be outside instead.
| Argument | Type | Description |
|---|---|---|
| indoorMapId | String | The identifier of the indoor map on which the positioner should be displayed. See the IndoorMapApi documentation for more details. |
| indoorMapFloorId | int | The identifier of the indoor map floor on which the Positioner should be displayed. |
String GetIndoorMapId ()
Get the Indoor Map Id string of this Positioner.
Returns: The Indoor Map Id, as a string.
int GetIndoorMapFloorId ()
Get the Indoor Map Floor Id of this Positioner.
Returns: The Indoor Map Floor Id of this Positioner.
bool IsTransformedPointDefined ()
Query whether the resultant transformed point of this positioner is currently defined. May return false if, for example, this Positioner is on an indoor map, and the indoor map is not currently being displayed. If true, then getting the transformed point via TryGetECEFLocation or TryGetLatLongAltitude will succeed; else they will fail.
Returns: True if the resultant transformed point of this positioner is currently defined; else false.
bool IsBehindGlobeHorizon ()
Returns true if the screen projection of this Positioner would appear beyond the horizon for the current viewpoint. For example, when viewing the map zoomed out so that the entire globe is visible, calling this method on a Positioner that is located on the opposite side of the Earth from the camera would return true.
Returns: Whether or not this Positioner is beyond the horizon.
void Discard ()
Destroys the Positioner.
Properties
int Id
Uniquely identifies this object instance.
int Id { get; private set; }