LatLon

Description

struct Tinman.Terrain.Georef.LatLon

A set of longitude/latitude coordinates, measured in degrees, with 64-bit floating-point precision.

A set of longitude/latitude values represent a location on a planetary body, for example on earth:

+---------------------------------------------------------------------------------+  90°N
|                     @@ @@@@@@@@     @@@           @                             | +90°
|             @           @@@@@@              @     @@@@                          |
|    @@@@  @  @@@ @   @    @@@@@        @      @ @@@@@@@@@@@@@@@@@  @             |
|  @@@@@@@@@@@@@@@   @@@  @@           @ @@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@         |
| @@@@@@@@@@@@@@@   @     @          @  @@@@@@@@@@@@@@@@@@@@@@@@@@@@  @@          |
|      @@@@@@@@@   @@@                @  @@@@@@@@@@@@@@@@@@@@@@@@@                |
|      @@@@@@@@@@@@@@@             @  @@ @@@@@@@@@@@ @@@@@@@@@@@@@    @           |
|      @@@@@@@@@@@@@@@              @@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@              |
|      @@@@@@@  @@@@@              @@@ @@@@@ @@ @@@@@@@@@@@@@@@ @@@@              |
|     @@@@@@@@@@@@@              @@   @  @   @@ @@@@@@@@@@@@@@@@@@@  @            |
|     @@@@@@@@@@@                @@    @@ @@@@@  @@@@@@@@@@@@@@@                  |
|     @@@@@@@@@@@                  @@@      @@@@@@@@@@ @@@@@@@@@@  @ @            |
|     @@@@@@@@@                  @@@@@@     @@@@@@@@@@@@@@@@@@@@@@                |
|      @@@@                      @@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@                |
|       @@@                     @@@@@@@@@@@@ @@@@   @@@@@@ @ @@@@@                |    L
|       @@     @               @@@@@@@@@ @@@@ @@@@@  @@@@@ @@@@@                  |    a
|        @@@@  @               @@@@@@@@ @@@@@ @@@@    @@@   @ @                   |    t
|          @@@                 @@@@@@@@@@@@@@  @       @     @ @                  |    i
|               @@              @@@@@@@@@@@@@@  @      @      @@                  + 0° t
|              @@@@@            @@  @@ @@@@@@@@@        @    @      @ @         @ |    u
|              @@@@@@@                @@@@@@@@@@                 @                |    d
|             @@@@@@@@                @@@@@@@@@              @  @@                |    e
|             @@@@@@@@@@@             @@@@@@@@                @  @   @@@@         |
|             @@@@@@@@@@@@             @@@@@@@                 @        @@        |
|              @@@@@@@@@@@             @@@@@@@                            @       |
|               @@@@@@@@@              @@@@@@@                       @@ @         |
|                @@@@@@@@               @  @@  @                   @@@@@@         |
|                @@@ @@@@              @@@@@   @                  @@@@@@@@        |
|                @@@ @@                @ @@@                     @@@@@@@@@        |
|                @@@@@@                  @@@                    @@@@@@@@@@        |
|                 @@@@                  @@@                      @@@ @@@@@        |
|                 @@@                                                 @@@     @   |
|                 @@                                                          @   |
|                 @@                                                  @           |
|                 @@                                                       @      |
|                  @                                                              |
|                   @                                                             |  90°S
+-----------------------------------------+---------------------------------------+ -90°
180°W                                    0°                                  180°E
-180°                                 Longitude                              +180°

The mapping from longitude/latitude coordinates to cubemap coordinates (see Cubemap class) is defined as follows:

Cubemap | Face center lies at:
 face   | Longitude | Latitude
--------+-----------+---------
   X-   |     90°W  |   0°N
        |    -90°   |   0°
--------+-----------+---------
   X+   |     90°E  |   0°N
        |    +90°   |   0°
--------+-----------+---------
   Y-   |      0°E  |  90°N
        |      0°   | +90°
--------+-----------+---------
   Y+   |      0°E  |  90°S
        |      0°   | -90°
--------+-----------+---------
   Z-   |      0°E  |   0°N
        |      0°   |   0°
--------+-----------+---------
   Z+   |    180°W  |   0°N
        |   -180°   |   0°

Public / Constants

East


public static readonly attribute East → (LatLon)

0°N 180°E

North


public static readonly attribute North → (LatLon)

90°N 0°E

NorthEast


public static readonly attribute NorthEast → (LatLon)

90°N 180°E

NorthWest


public static readonly attribute NorthWest → (LatLon)

90°N 180°W

OneDegree


public constant OneDegree → (1:float64)

One degree longitude/latitude.

OneMillisecond


public constant OneMillisecond → (1 / 3600000:float64)

One thousandth of a second longitude/latitude.

OneMinute


public constant OneMinute → (1 / 60:float64)

One minute longitude/latitude.

OneSecond


public constant OneSecond → (1 / 3600:float64)

One second longitude/latitude.

South


public static readonly attribute South → (LatLon)

90°S 0°E

SouthEast


public static readonly attribute SouthEast → (LatLon)

90°S 180°E

SouthWest


public static readonly attribute SouthWest → (LatLon)

90°S 180°W

Undefined


public static readonly attribute Undefined → (LatLon)

Undefined location.

West


public static readonly attribute West → (LatLon)

0°N 180°W

Zero


public static readonly attribute Zero → (LatLon)

0°N 0°E

Public / Constructors

ForCubemapFace


[Pure]
public static method ForCubemapFace → (1)

face in : CubemapFace

The cubemap face (see Cubemap).

returns → LatLon

The resulting value.

Returns the LatLon value that represents the center of the given cubemap face.

FromCube

4 overloads


[Pure]
public static method FromCube1 → (2)

cube in : Vec3I

The cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

[pow2]
Size of cubemap.

returns → LatLon

The longitude/latitude coordinates.

Converts the given cubemap coordinates to longitude/latitude coordinates.


[Pure]
public static method FromCube2 → (4)

in : int32

The cubemap X-coordinate.

in : int32

The cubemap X-coordinate.

in : int32

The cubemap X-coordinate.

opt : int32 = HeightmapsUtil.MaxCoord

[pow2]
Size of cubemap.

returns → LatLon

The longitude/latitude coordinates.

Converts the given cubemap coordinates to longitude/latitude coordinates.


[Pure]
public static method FromCube3 → (2)

cube in : Vec3D

The cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

[pow2]
Size of cubemap.

returns → LatLon

The longitude/latitude coordinates.

Converts the given cubemap coordinates to longitude/latitude coordinates.


[Pure]
public static method FromCube4 → (4)

in : float64

The cubemap X-coordinate.

in : float64

The cubemap Y-coordinate.

in : float64

The cubemap Z-coordinate.

opt : int32 = HeightmapsUtil.MaxCoord

[pow2]
Size of cubemap.

returns → LatLon

The longitude/latitude coordinates.

Converts the given cubemap coordinates to longitude/latitude coordinates.

FromDegrees


[Pure]
public static method FromDegrees → (1)

in : Vec2D

The longitude (see Vec2D.X) and latitude (see Vec2D.Y) angles, in degrees.

returns → LatLon

The LatLon value.

Creates a new instance of LatLon from the given angles.

See also

LatLon.ToDegrees

FromProjection


[Pure]
public static method FromProjection → (2)

projectRectToCube in : IMapProjection

[not-null]
The map projection to use. Must project from MapType.Rect ( IMapProjection.Source) to MapType.Cube ( IMapProjection.Target).

in : Vec2D

The map coordinates in the source raster (see IMapProjection.Source) of projectRectToCube in.

returns → LatLon

The LatLon value.

Computes a LatLon value by projecting the given rectangular map coordinates to cubemap coordinates.

FromRadians

2 overloads


[Pure]
public static method FromRadians1 → (1)

in : Vec2D

The longitude (see Vec2D.X) and latitude (see Vec2D.Y) angles, in radians.

returns → LatLon

The LatLon value.

Creates a new instance of LatLon from the given angles.

See also

LatLon.ToRadians


[Pure]
public static method FromRadians2 → (2)

latitude in : float64

The latitude angle, in radians.

longitude in : float64

The longitude angle, in radians.

returns → LatLon

The LatLon value.

Creates a new instance of LatLon from the given angles.

See also

LatLon.ToRadians

FromString

2 overloads


[Pure]
public static method FromString1 → (1)

str in : string

The string representation.

returns → LatLon

The LatLon value.

Creates a LatLon value from the given string representation.

ValidatingException

If the given input string is invalid.


[Pure]
public static method FromString2 → (2)

str in : string

The string representation.

defaultValue in : LatLon

The value to return if str in is invalid.

returns → LatLon

The LatLon value.

Creates a LatLon value from the given string representation.

FromStringTry


[Pure]
public static method FromStringTry → (2)

str in : string

The string representation.

latLon out : LatLon

The output LatLon value.

returns → bool

true if a LatLon value has been parsed and stored into latLon out, false if the input string is invalid ( latLon out will be set to Undefined in this case).

Creates a LatLon value from the given string representation.

LatLon

2 overloads


public constructor LatLon1 → (2)

latitude in : float64

The latitude in the range [-90..90].

longitude in : float64

The longitude in the range [-180..180].

Creates a new instance of LatLon.


public constructor LatLon2 → (6)

latDeg in : float64

The latitude degrees.

latMin in : float64

The latitude minutes.

latSec in : float64

The latitude seconds.

lonDeg in : float64

The longitude degrees.

lonMin in : float64

The longitude minutes.

lonSec in : float64

The longitude seconds.

Creates a new instance of LatLon.

Public / Methods

Add

2 overloads


[Pure]
public method Add1 → (2)

latitude in : float64

The value to add to the latitude of this value.

longitude in : float64

The value to add to the longitude of this value.

returns → LatLon

The resulting LatLon value (Normalize) should be called on the returned value in order to avoid range overflows).

Adds the given longitude/latitude values to this LatLon value.


[Pure]
public method Add2 → (1)

value in : LatLon

The longitude/latitude values to add to this value.

returns → LatLon

The resulting LatLon value (Normalize) should be called on the returned value in order to avoid range overflows).

Adds the given longitude/latitude values to this LatLon value.

ClampLatitude

2 overloads


[Pure]
public method ClampLatitude1 → (1)

maximum in : float64

The latitude range: [-max..max].

returns → LatLon

The clamped value.

Clamps the latitude to the given range.


[Pure]
public method ClampLatitude2 → (2)

in : float64

First range bound.

in : float64

Second range bound.

returns → LatLon

The clamped value.

Clamps the latitude to the given range: [a..b] resp. [b..a].

Div


[Pure]
public method Div → (1)

value in : float64

The scalar value to divide by.

returns → LatLon

The resulting LatLon value (Normalize) should be called on the returned value in order to avoid range overflows).

Divides the longitude and latitude values of this LatLon value by the given scalar.

FromDegreeMinuteSecond


[Pure]
public static method FromDegreeMinuteSecond → (3)

degrees in : float64

The degrees part.

minutes opt : float64 = 0

The minutes part (1/60th degree).

seconds opt : float64 = 0

The seconds part (1/60th minute).

returns → float64

The angle in degrees.

Computes an angle in degrees from the given DMS tuple.

FromSexagesimal


[Pure]
public static method FromSexagesimal → (1)

value in : float64

The sexagesimal DMS value.

returns → float64

The value in decimal degrees.

Converts the given angle in sexagesimal DMS (degree-minute-second) notation into a value in decimal degrees.

Sexagesimal DMS is a pseudo unit (EPSG 9110) and is specified as a decimal pseudo number, where the decimal digits must be interpreted in a special way:

123.456789...
      \_____/  seconds (1/60th minute)
    \/         minutes (1/60th degree)
\_/            degrees

IsUndefinedCoordinate


[Pure]
public static method IsUndefinedCoordinate → (1)

coordinate in : float64

The coordinate value.

returns → bool

true if coordinate in is undefined, false if it is valid.

Is the given geographic coordinate undefined?

Mul


[Pure]
public method Mul → (1)

value in : float64

The scalar multiplication factor.

returns → LatLon

The resulting LatLon value (Normalize) should be called on the returned value in order to avoid range overflows).

Multiplies the longitude/latitude values of this LatLon value by the given scalar factor.

Neg


[Pure]
public method Neg → ()

returns → LatLon

The resulting LatLon value.

Negates the longitude and latitude values of this LatLon value.

NiceStepFind


[Pure]
public static method NiceStepFind → (2)

angle in : float64

The angle value, in degrees.

divisible opt : bool = false

Return nice-looking values that are also nicely divisible (see remarks)?

returns → int32

Index of nice-looking value that is nearest to angle in.

Returns a nice-looking angle value that is similar to the given angle in value.

A nice-looking angle value sums up without creating big fractions, i.e. degrees are always a divisor of 360, minutes and seconds are always a divisor of 60 and milliseconds are always a divisor of 1000:

  • Milliseconds:
    [0..3] : 0°00'00.001'', 0°00'00.002'', 0°00'00.004'', 0°00'00.005'',
    [4..7] : 0°00'00.008'', 0°00'00.010'', 0°00'00.020'', 0°00'00.025'',
    [8..11] : 0°00'00.040'', 0°00'00.050'', 0°00'00.100'', 0°00'00.125'',
    [12..14] : 0°00'00.200'', 0°00'00.250'', 0°00'00.500''

  • Seconds:
    [15..18] : 0°00'01'', 0°00'02'', 0°00'03'', 0°00'04'',
    [19..22] : 0°00'05'', 0°00'06'', 0°00'10'', 0°00'12'',
    [23..25] : 0°00'15'', 0°00'20'', 0°00'30''

  • Minutes:
    [26..29] : 0°01', 0°02', 0°03', 0°04',
    [30..33] : 0°05', 0°06', 0°10', 0°12',
    [34..36] : 0°15', 0°20', 0°30'

  • Degrees:
    [37..44] : 1°, 2°, 3°, 4°, 5°, 6°, 8°, 9°,
    [45..51] : 10°, 12°, 15°, 18°, 20°, 24°, 30°,
    [52..57] : 36°, 40°, 45°, 60°, 72°, 90°,
    [58..60] : 120°, 180°, 360°

By setting the divisible opt parameter to true, the list of nice-looking angle values is reduced to this:

  • Milliseconds:
    0°00'00.001'', 0°00'00.005'', 0°00'00.025'', 0°00'00.050'', 0°00'00.250'', 0°00'00.500''

  • Seconds:
    0°00'01'', 0°00'05'', 0°00'15'', 0°00'30''

  • Minutes:
    0°01', 0°05', 0°15', 0°30'

  • Degrees:
    1°, 5°, 15°, 30°, 60°, 120°, 360°

NiceStepGet


[Pure]
public static method NiceStepGet → (1)

index in : int32

[0..60]
Index of nice-looking value to get (see remarks).

returns → float64

The nice-looking angle value, in degrees.

Returns a nice-looking angle step value.

A nice-looking angle value sums up without creating big fractions, i.e. degrees are always a divisor of 360, minutes and seconds are always a divisor of 60 and milliseconds are always a divisor of 1000:

  • Milliseconds:
    0°00'00.001'', 0°00'00.002'', 0°00'00.004'', 0°00'00.005'',
    0°00'00.008'', 0°00'00.010'', 0°00'00.020'', 0°00'00.025'',
    0°00'00.040'', 0°00'00.050'', 0°00'00.100'', 0°00'00.125'',
    0°00'00.200'', 0°00'00.250'', 0°00'00.500''

  • Seconds:
    0°00'01'', 0°00'02'', 0°00'03'', 0°00'04'',
    0°00'05'', 0°00'06'', 0°00'10'', 0°00'12'',
    0°00'15'', 0°00'20'', 0°00'30''

  • Minutes:
    0°01', 0°02', 0°03', 0°04',
    0°05', 0°06', 0°10', 0°12',
    0°15', 0°20', 0°30'

  • Degrees:
    1°, 2°, 3°, 4°, 5°, 6°, 8°, 9°,
    10°, 12°, 15°, 18°, 20°, 24°, 30°,
    36°, 40°, 45°, 60°, 72°, 90°,
    120°, 180°, 360°

NiceStepRound


[Pure]
public static method NiceStepRound → (2)

step in : int32

[0..60]
Index of nice-looking step value.

degrees in : float64

The latitude resp. longitude angle, in degrees.

returns → float64

The rounded latitude/longitude tuple.

Rounds the given latitude resp. longitude angle to the given nice-looking step value.


[Pure]
public method NiceStepRound → (1)

step in : int32

[0..60]
Index of nice-looking step value.

returns → LatLon

The rounded latitude/longitude tuple.

Rounds this latitude/longitude tuple to the given nice-looking step value.

Normalize


[Pure]
public method Normalize → ()

returns → LatLon

The normalized value pair.

Normalizes this pair of latitude/longitude values so that the longitude value lies in the range [-180..180] and the latitude lies within [-90..90].

Longitude values are wrapped at the normalization range boundaries; latitude values are clamped to the range boundaries.

NormalizeLatitude


[Pure]
public static method NormalizeLatitude → (1)

latitude in : float64

The input latitude angle, in degrees.

returns → float64

The normalized latitude angle.

Normalizes the given latitude angle.

See also

LatLon.Normalize

NormalizeLongitude180


[Pure]
public static method NormalizeLongitude180 → (2)

longitude in : float64

The input longitude angle, in degrees.

unique opt : bool = true

Return -180 instead of 180?

returns → float64

The normalized longitude angle.

Normalizes the given longitude angle.

See also

LatLon.Normalize

NormalizeLongitude360


[Pure]
public static method NormalizeLongitude360 → (2)

longitude in : float64

The input longitude angle, in degrees.

unique opt : bool = true

Return 0 instead of 360?

returns → float64

The normalized longitude angle.

Normalizes the given longitude angle.

See also

LatLon.Normalize

NormalizeLongitudePi


[Pure]
public static method NormalizeLongitudePi → (2)

longitude in : float64

The input longitude angle, in radians.

unique opt : bool = true

Return -pi instead of pi?

returns → float64

The normalized longitude angle.

Normalizes the given longitude angle.

See also

LatLon.Normalize

NormalizeLongitudePiTwo


[Pure]
public static method NormalizeLongitudePiTwo → (2)

longitude in : float64

The input longitude angle, in radians.

unique opt : bool = true

Return 0 instead of pi*2?

returns → float64

The normalized longitude angle.

Normalizes the given longitude angle.

See also

LatLon.Normalize

Sub

2 overloads


[Pure]
public method Sub1 → (2)

latitude in : float64

The value to subtract from the latitude of this value, in degrees.

longitude in : float64

The value to subtract from the longitude of this value, in degrees.

returns → LatLon

The resulting LatLon value (Normalize) should be called on the returned value in order to avoid range overflows).

Subtracts the given longitude/latitude values from this LatLon value.


[Pure]
public method Sub2 → (1)

value in : LatLon

The longitude/latitude values to subtract from this value.

returns → LatLon

The resulting LatLon value (Normalize) should be called on the returned value in order to avoid range overflows).

Subtracts the given longitude/latitude values from this LatLon value.

ToCubeD


[Pure]
public method ToCubeD → (1)

opt : int32 = HeightmapsUtil.MaxCoord

[pow2]
Size of cubemap.

returns → Vec3D

The cubemap coordinates.

Converts this set of longitude/latitude coordinates to cubemap coordinates.

ToCubeI


[Pure]
public method ToCubeI → (1)

opt : int32 = HeightmapsUtil.MaxCoord

[pow2]
Size of cubemap.

returns → Vec3I

The cubemap coordinates.

Converts this set of longitude/latitude coordinates to cubemap coordinates.

ToDegrees


[Pure]
public method ToDegrees → ()

returns → Vec2D

The resulting vector holding the longitude (see Vec2D.X) and latitude (see Vec2D.Y) angles, in degrees.

Converts this LatLon value to a vector of longitude/latitude in degrees.

ToProjection


[Pure]
public method ToProjection → (1)

projectCubeToRect in : IMapProjection

[not-null]
The map projection to use. Must project from MapType.Cube ( IMapProjection.Source) to MapType.Rect ( IMapProjection.Target).

returns → Vec2D

The map coordinates in the target raster (see IMapProjection.Target) of projectCubeToRect in.

Projects this LatLon value onto a rectangular map.

ToRadians


[Pure]
public method ToRadians → ()

returns → Vec2D

The resulting vector holding the longitude (see Vec2D.X) and latitude (see Vec2D.Y) angles, in radians.

Converts this LatLon value to a vector of longitude/latitude in radians.

ToSexagesimal


[Pure]
public static method ToSexagesimal → (1)

value in : float64

The value in decimal degrees.

returns → float64

The sexagesimal DMS value.

Converts the given angle in decimal degrees into a value in sexagesimal DMS (degree-minute-second) notation.

Sexagesimal DMS is a pseudo unit (EPSG 9110) and is specified as a decimal pseudo number, where the decimal digits must be interpreted in a special way:

123.456789...
      \_____/  seconds (1/60th minute)
    \/         minutes (1/60th degree)
\_/            degrees

ToString


[Pure]
public static method ToString → (3)

angle in : float64

The angle value to format, in degrees.

latOrLon in : bool

true if angle in is a latitude angle, false if it is a longitude angle.

format opt : LatLonFormat = LatLonFormat.Default

The formatting options.

returns → string

The string representation.

Returns the string representation of the given latitude/longitude angle.

The string representation has the following form:

a°b'c".dX

where…​
…​ a, b, c and d are the latitude degrees, minutes, seconds and milliseconds, X is either N (positive latitude), S (negative latitude), E (positive longitude) or W (negative longitude).


[Pure]
public method ToString2 → (1)

format in : LatLonFormat

The formatting options.

returns → string

The string representation.

Returns the string representation of this set of latitude/longitude coordinates.

The string representation has the following form:

a°b'c".dX e°f'g".hY

where…​
…​ a, b, c and d are the latitude degrees, minutes, seconds and milliseconds, X is either N (positive latitude) or S (negative latitude).
…​ e, f, g and h are the longitude degrees, minutes, seconds and milliseconds, Y is either E (positive longitude) or W (negative longitude).

The parts for minutes, seconds and milliseconds are omitted if their value is zero:

12°34'56.789"N 123°45'57.891"E
12°34'56"N 123°45'57"E
12°34'N 123°45'E
12°N 123°E

Public / Attributes

IsNormalized


public attribute IsNormalized → (get)

value : bool

true if the coordinates are normalized, false if not.

Are these geographic coordinates normalized?

Normalized latitude angles are in the range [-90..90], normalized longitude angles are in the range [-180..180].

See also

LatLon.Normalize

IsUndefined


public attribute IsUndefined → (get)

value : bool

true if the coordinates are undefined, false if not.

Is this coordinate set undefined?

Latitude


public readonly attribute Latitude → (float64)

The latitude in the range [-90..90].

LatitudeRadians


public attribute LatitudeRadians → (get)

value : float64

The latitude angle, in radians.

The latitude in the range [-pi/2..pi/2].

Longitude


public readonly attribute Longitude → (float64)

The longitude in the range [-180..180].

LongitudeRadians


public attribute LongitudeRadians → (get)

value : float64

The longitude angle, in radians.

The longitude in the range [-pi..pi].

Extensions

ToCoords


public static method ToCoords → (2)

elevation in : float64

The terrain-space elevation.

geometry in : IGeometry

[not-null]
The geometry object.

returns → Vec3D

The geocentric coordinates.

Translates these longitude/latitude coordinates into geocentric coordinates.

Serialization

Serializer


public static readonly attribute Serializer → (ITypeSerializer<LatLon>)

The serialization helper object for values of LatLon.