agi.foundation.coordinates

(agi.foundation.core-2024r3.jar)

Class MilitaryGridReferenceSystem

java.lang.Object

agi.foundation.coordinates.MilitaryGridReferenceSystem

All Implemented Interfaces:

IEquatable<MilitaryGridReferenceSystem>, ImmutableValueType, ValueType, IEquatableEpsilon<MilitaryGridReferenceSystem>

public final class MilitaryGridReferenceSystem
extends Object
implements IEquatable<MilitaryGridReferenceSystem>, IEquatableEpsilon<MilitaryGridReferenceSystem>, ImmutableValueType

A set of coordinates for specifying locations on the Earth based on a grid of longitude and latitude zones as outlined in Defense Mapping Agency Technical Manual (DMA TM) 8358.1, "Datums, Ellipsoids, Grids, and Grid Reference Systems", Edition 1, 20 September 1990.

See Also:

UniversalPolarStereographic, UniversalTransverseMercator

Constructor Summary

Constructors

Constructor and Description
MilitaryGridReferenceSystem(String grid, String square, double easting, double northing) Initializes a set of Military Grid Reference System (MGRS) coordinates from the provided values.
MilitaryGridReferenceSystem(UniversalPolarStereographic coordinates) Initializes a set of Military Grid Reference System (MGRS) coordinates from the provided Universal Polar Stereographic (UPS) coordinates.
MilitaryGridReferenceSystem(UniversalTransverseMercator coordinates, Ellipsoid ellipsoid) Initializes a set of Military Grid Reference System (MGRS) coordinates from the provided Universal Transverse Mercator (UTM) coordinates and ellipsoid.

Method Summary

Modifier and Type	Method and Description
static boolean	equals(MilitaryGridReferenceSystem left, MilitaryGridReferenceSystem right) Returns true if the two instances are exactly equal.
boolean	equals(Object obj) Indicates whether another object is exactly equal to this instance.
boolean	equalsEpsilon(MilitaryGridReferenceSystem other, double epsilon) Indicates whether each coordinate value of another instance of this type is within the required tolerance of the corresponding coordinate value of this instance.
boolean	equalsType(MilitaryGridReferenceSystem other) Indicates whether another instance of this type is exactly equal to this instance.
double	getEasting() Gets the eastward distance of the location into the square.
String	getGrid() Gets the 1 or 3 character grid zone designator.
double	getNorthing() Gets the northward distance of the location into the grid.
String	getSquare() Gets the 2 character 100,000 meter square designator.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
static boolean	notEquals(MilitaryGridReferenceSystem left, MilitaryGridReferenceSystem right) Returns true if the two instances are not exactly equal.
String	toString() Returns the string representation of the value of this instance.
boolean	tryConvertToUniversalPolarStereographic(UniversalPolarStereographic[] ups) Attempts to convert this instance to a set of UniversalPolarStereographic coordinates.
boolean	tryConvertToUniversalTransverseMercator(Ellipsoid ellipsoid, UniversalTransverseMercator[] utm) Attempts to convert this instance to a set of UniversalTransverseMercator coordinates.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MilitaryGridReferenceSystem

public MilitaryGridReferenceSystem(@Nonnull
                                   String grid,
                                   @Nonnull
                                   String square,
                                   double easting,
                                   double northing)

Initializes a set of Military Grid Reference System (MGRS) coordinates from the provided values.

Parameters:

grid - The 1 or 3 character grid zone designator.

square - The 2 character 100,000 meter square designator.

easting - The eastward distance of the location into the square.

northing - The northward distance of the location into the square.

Throws:

ArgumentNullException - Thrown when grid or square is null.

MilitaryGridReferenceSystem

public MilitaryGridReferenceSystem(@Nonnull
                                   UniversalPolarStereographic coordinates)

Initializes a set of Military Grid Reference System (MGRS) coordinates from the provided Universal Polar Stereographic (UPS) coordinates.

Parameters:

coordinates - The UPS coordinates.

MilitaryGridReferenceSystem

public MilitaryGridReferenceSystem(@Nonnull
                                   UniversalTransverseMercator coordinates,
                                   @Nonnull
                                   Ellipsoid ellipsoid)

Initializes a set of Military Grid Reference System (MGRS) coordinates from the provided Universal Transverse Mercator (UTM) coordinates and ellipsoid.

Parameters:

coordinates - The UTM coordinates.

ellipsoid - The reference ellipsoid.

Throws:

ArgumentNullException - Thrown when ellipsoid is null.

Method Detail

tryConvertToUniversalPolarStereographic

public final boolean tryConvertToUniversalPolarStereographic(@Nonnull
                                                             UniversalPolarStereographic[] ups)

Attempts to convert this instance to a set of UniversalPolarStereographic coordinates.

Parameters:

ups - The converted coordinates.

Returns:

true if this instance could be converted to the desired coordinate type; otherwise false.

tryConvertToUniversalTransverseMercator

public final boolean tryConvertToUniversalTransverseMercator(@Nonnull
                                                             Ellipsoid ellipsoid,
                                                             @Nonnull
                                                             UniversalTransverseMercator[] utm)

Attempts to convert this instance to a set of UniversalTransverseMercator coordinates.

Parameters:

ellipsoid - The reference ellipsoid.

utm - The converted coordinates.

Returns:

true if this instance could be converted to the desired coordinate type; otherwise false.

Throws:

ArgumentNullException - Thrown when ellipsoid is null.

getGrid

@Nonnull
public final String getGrid()

Gets the 1 or 3 character grid zone designator.

getSquare

@Nonnull
public final String getSquare()

Gets the 2 character 100,000 meter square designator.

getEasting

public final double getEasting()

Gets the eastward distance of the location into the square.

getNorthing

public final double getNorthing()

Gets the northward distance of the location into the grid.

equals

public boolean equals(Object obj)

Indicates whether another object is exactly equal to this instance.

Overrides:

equals in class Object

Parameters:

obj - The object to compare to this instance.

Returns:

true if obj is an instance of this type and represents the same value as this instance; otherwise false.

See Also:

Object.hashCode(), HashMap

equalsType

public final boolean equalsType(@Nonnull
                                MilitaryGridReferenceSystem other)

Indicates whether another instance of this type is exactly equal to this instance.

Specified by:

equalsType in interface IEquatable<MilitaryGridReferenceSystem>

Parameters:

other - The instance to compare to this instance.

Returns:

true if other represents the same value as this instance; otherwise false.

equalsEpsilon

public final boolean equalsEpsilon(@Nonnull
                                   MilitaryGridReferenceSystem other,
                                   double epsilon)

Indicates whether each coordinate value of another instance of this type is within the required tolerance of the corresponding coordinate value of this instance.

Specified by:

equalsEpsilon in interface IEquatableEpsilon<MilitaryGridReferenceSystem>

Parameters:

other - The set of MilitaryGridReferenceSystem coordinates to compare to this instance.

epsilon - The limit at which the absolute differences between the coordinate values will not be considered equal.

Returns:

true if the absolute differences are less than or equal to epsilon; otherwise false.

hashCode

public int hashCode()

Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.

Overrides:

hashCode in class Object

Returns:

A hash code for the current object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

toString

public String toString()

Returns the string representation of the value of this instance.

Overrides:

toString in class Object

Returns:

A string that represents the value of this instance in the form "Grid, Square, Easting, Northing".

equals

public static boolean equals(@Nonnull
                             MilitaryGridReferenceSystem left,
                             @Nonnull
                             MilitaryGridReferenceSystem right)

Returns true if the two instances are exactly equal.

Parameters:

left - The instance to compare to right.

right - The instance to compare to left.

Returns:

true if left represents the same value as right; otherwise false.

notEquals

public static boolean notEquals(@Nonnull
                                MilitaryGridReferenceSystem left,
                                @Nonnull
                                MilitaryGridReferenceSystem right)

Returns true if the two instances are not exactly equal.

Parameters:

left - The instance to compare to right.

right - The instance to compare to left.

Returns:

true if left does not represent the same value as right; otherwise false.