AltitudeConverter


public final class AltitudeConverter
extends Object

java.lang.Object
   ↳ android.location.altitude.AltitudeConverter


Converts altitudes reported above the World Geodetic System 1984 (WGS84) reference ellipsoid into ones above Mean Sea Level.

Reference:

 Brian Julian and Michael Angermann.
 "Resource efficient and accurate altitude conversion to Mean Sea Level."
 2023 IEEE/ION Position, Location and Navigation Symposium (PLANS).
 

Summary

Public constructors

AltitudeConverter()

Creates an instance that manages an independent cache to optimized conversions of locations in proximity to one another.

Public methods

void addMslAltitudeToLocation(Context context, Location location)

Adds a Mean Sea Level altitude to the location.

boolean tryAddMslAltitudeToLocation(Location location)

Same as addMslAltitudeToLocation(android.content.Context, android.location.Location) except that this method can be called on the main thread as data will not be loaded from raw assets.

Inherited methods

Public constructors

AltitudeConverter

Added in API level 34
public AltitudeConverter ()

Creates an instance that manages an independent cache to optimized conversions of locations in proximity to one another.

Public methods

addMslAltitudeToLocation

Added in API level 34
public void addMslAltitudeToLocation (Context context, 
                Location location)

Adds a Mean Sea Level altitude to the location. In addition, adds a Mean Sea Level altitude accuracy if the location has a finite and non-negative vertical accuracy; otherwise, does not add a corresponding accuracy.

Must be called off the main thread as data may be loaded from raw assets.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
context Context: This value cannot be null.

location Location: This value cannot be null.

Throws
IOException if an I/O error occurs when loading data from raw assets.
IllegalArgumentException if the location has an invalid latitude, longitude, or altitude above WGS84. Specifically, the latitude must be between -90 and 90 (both inclusive), the longitude must be between -180 and 180 (both inclusive), and the altitude above WGS84 must be finite.

tryAddMslAltitudeToLocation

Added in API level 35
public boolean tryAddMslAltitudeToLocation (Location location)

Same as addMslAltitudeToLocation(android.content.Context, android.location.Location) except that this method can be called on the main thread as data will not be loaded from raw assets. Returns true if a Mean Sea Level altitude is added to the location; otherwise, returns false and leaves the location unchanged.

Prior calls to addMslAltitudeToLocation(android.content.Context, android.location.Location) off the main thread are necessary to load data from raw assets. Example code on the main thread is as follows:

if (!mAltitudeConverter.tryAddMslAltitudeToLocation(location)) {
       // Queue up only one call off the main thread.
       if (mIsAltitudeConverterIdle) {
           mIsAltitudeConverterIdle = false;
           executeOffMainThread(() -> {
               try {
                   // Load raw assets for next call attempt on main thread.
                   mAltitudeConverter.addMslAltitudeToLocation(mContext, location);
               } catch (IOException e) {
                   Log.e(TAG, "Not loading raw assets: " + e);
               }
               mIsAltitudeConverterIdle = true;
           });
       }
   }
 

Parameters
location Location: This value cannot be null.

Returns
boolean