de.ipcon.tools

Class GeographyTools

java.lang.Object

de.ipcon.tools.GeographyTools

public final class GeographyTools
extends java.lang.Object

Utility class for performing operations related to geography, such as distance calculation. This class cannot be instantiated and all methods are static.

Method Summary

Modifier and Type	Method and Description
static java.math.BigDecimal	atan2(java.math.BigDecimal y, java.math.BigDecimal x) Calculates the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r, theta).
static java.math.BigDecimal	cos(java.math.BigDecimal angleRad) Calculates the trigonometric cosine of an angle.
static java.math.BigDecimal	distanceKilometers(java.math.BigDecimal lat1, java.math.BigDecimal lon1, java.math.BigDecimal lat2, java.math.BigDecimal lon2) Calculates the distance between two geographical coordinates using the Haversine formula.
static java.math.BigDecimal	distanceNauticalMiles(java.math.BigDecimal lat1, java.math.BigDecimal lon1, java.math.BigDecimal lat2, java.math.BigDecimal lon2) Calculates the distance between two geographical coordinates using the Haversine formula.
static java.math.BigDecimal	haversine(java.math.BigDecimal lat1Rad, java.math.BigDecimal lon1Rad, java.math.BigDecimal lat2Rad, java.math.BigDecimal lon2Rad, java.math.BigDecimal earthRadius) Implements the Haversine formula to calculate the great-circle distance between two points on a sphere given their latitudes and longitudes in radians.
static java.math.BigDecimal	sin(java.math.BigDecimal angleRad) Calculates the trigonometric sine of an angle.
static java.math.BigDecimal	sqrt(java.math.BigDecimal val) Calculates the square root of a BigDecimal.
static java.math.BigDecimal	toRadians(java.math.BigDecimal degrees) Converts an angle from decimal degrees to radians.
static void	validateCoordinate(java.math.BigDecimal lat, java.math.BigDecimal lon) Validates a single geographical coordinate.
static void	validateCoordinates(java.math.BigDecimal lat1, java.math.BigDecimal lon1, java.math.BigDecimal lat2, java.math.BigDecimal lon2) Validates two geographical coordinate pairs by checking each pair individually.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

distanceKilometers

public static java.math.BigDecimal distanceKilometers(java.math.BigDecimal lat1,
                                                      java.math.BigDecimal lon1,
                                                      java.math.BigDecimal lat2,
                                                      java.math.BigDecimal lon2)

Calculates the distance between two geographical coordinates using the Haversine formula. This method employs BigDecimal for all calculations to maintain precision. The result is returned in kilometers.

Parameters:

lat1 - The latitude of the first coordinate, in decimal degrees. Must be between -90 and 90.

lon1 - The longitude of the first coordinate, in decimal degrees. Must be between -180 and 180.

lat2 - The latitude of the second coordinate, in decimal degrees. Must be between -90 and 90.

lon2 - The longitude of the second coordinate, in decimal degrees. Must be between -180 and 180.

Returns:

The distance between the two specified coordinates in kilometers, as a BigDecimal.

Throws:

java.lang.IllegalArgumentException - if any of the latitude or longitude values are outside their valid range (Latitude: -90 to +90, Longitude: -180 to +180).

distanceNauticalMiles

public static java.math.BigDecimal distanceNauticalMiles(java.math.BigDecimal lat1,
                                                         java.math.BigDecimal lon1,
                                                         java.math.BigDecimal lat2,
                                                         java.math.BigDecimal lon2)

Calculates the distance between two geographical coordinates using the Haversine formula. This method employs BigDecimal for all calculations to maintain precision. The result is returned in nautical miles.

Parameters:

lat1 - The latitude of the first coordinate, in decimal degrees. Must be between -90 and 90.

lon1 - The longitude of the first coordinate, in decimal degrees. Must be between -180 and 180.

lat2 - The latitude of the second coordinate, in decimal degrees. Must be between -90 and 90.

lon2 - The longitude of the second coordinate, in decimal degrees. Must be between -180 and 180.

Returns:

The distance between the two specified coordinates in nautical miles, as a BigDecimal.

Throws:

java.lang.IllegalArgumentException - if any of the latitude or longitude values are outside their valid range (Latitude: -90 to +90, Longitude: -180 to +180).

validateCoordinate

public static void validateCoordinate(java.math.BigDecimal lat,
                                      java.math.BigDecimal lon)

Validates a single geographical coordinate. Latitude must be between -90 and +90 (inclusive). Longitude must be between -180 and +180 (inclusive). Logs an error and throws an IllegalArgumentException if validation fails.

Parameters:

lat - The latitude of the coordinate, in decimal degrees.

lon - The longitude of the coordinate, in decimal degrees.

Throws:

java.lang.IllegalArgumentException - if the latitude or longitude is outside its valid range.

validateCoordinates

public static void validateCoordinates(java.math.BigDecimal lat1,
                                       java.math.BigDecimal lon1,
                                       java.math.BigDecimal lat2,
                                       java.math.BigDecimal lon2)

Validates two geographical coordinate pairs by checking each pair individually. Latitudes must be between -90 and +90 (inclusive). Longitudes must be between -180 and +180 (inclusive). Logs an error and throws an IllegalArgumentException if any validation fails.

Parameters:

lat1 - The latitude of the first coordinate.

lon1 - The longitude of the first coordinate.

lat2 - The latitude of the second coordinate.

lon2 - The longitude of the second coordinate.

Throws:

java.lang.IllegalArgumentException - if any coordinate is outside its valid range.

toRadians

public static java.math.BigDecimal toRadians(java.math.BigDecimal degrees)

Converts an angle from decimal degrees to radians. The conversion formula used is: radians = degrees * (PI / 180). Calculations are performed using BigDecimal with the predefined MathContext.

Parameters:

degrees - The angle in decimal degrees to be converted.

Returns:

The angle in radians, as a BigDecimal.

sin

public static java.math.BigDecimal sin(java.math.BigDecimal angleRad)

Calculates the trigonometric sine of an angle. The input angle is expected to be in radians. This method uses Math.sin(double) internally after converting the BigDecimal to a double, and then constructs a new BigDecimal with the result, using the class's predefined MathContext. Note: Conversion to double may result in a loss of precision for extremely large or precise BigDecimal values.

Parameters:

angleRad - The angle in radians, as a BigDecimal.

Returns:

The sine of the angle, as a BigDecimal with the defined MathContext.

cos

public static java.math.BigDecimal cos(java.math.BigDecimal angleRad)

Calculates the trigonometric cosine of an angle. The input angle is expected to be in radians. This method uses Math.cos(double) internally after converting the BigDecimal to a double, and then constructs a new BigDecimal with the result, using the class's predefined MathContext. Note: Conversion to double may result in a loss of precision for extremely large or precise BigDecimal values.

Parameters:

angleRad - The angle in radians, as a BigDecimal.

Returns:

The cosine of the angle, as a BigDecimal with the defined MathContext.

atan2

public static java.math.BigDecimal atan2(java.math.BigDecimal y,
                                         java.math.BigDecimal x)

Calculates the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r, theta). This method computes the arc tangent of y/x in the range of -PI to PI. It uses Math.atan2(double, double) internally after converting the BigDecimal inputs to doubles, and then constructs a new BigDecimal with the result, using the class's predefined MathContext. Note: Conversion to double may result in a loss of precision.

Parameters:

y - The ordinate coordinate as a BigDecimal.

x - The abscissa coordinate as a BigDecimal.

Returns:

The theta component of the point (r, theta) in polar coordinates that corresponds to the point (x, y) in Cartesian coordinates, as a BigDecimal with the defined MathContext.

sqrt

public static java.math.BigDecimal sqrt(java.math.BigDecimal val)

Calculates the square root of a BigDecimal. This method uses Math.sqrt(double) internally after converting the BigDecimal to a double, and then constructs a new BigDecimal with the result, using the class's predefined MathContext. Throws an ArithmeticException if the input value is negative. Note: Conversion to double may result in a loss of precision. For high-precision square roots of BigDecimal, a dedicated algorithm (e.g., Newton-Raphson) would be required.

Parameters:

val - The non-negative BigDecimal value for which to calculate the square root.

Returns:

The square root of val, as a BigDecimal with the defined MathContext.

Throws:

java.lang.ArithmeticException - if val is negative.

haversine

public static java.math.BigDecimal haversine(java.math.BigDecimal lat1Rad,
                                             java.math.BigDecimal lon1Rad,
                                             java.math.BigDecimal lat2Rad,
                                             java.math.BigDecimal lon2Rad,
                                             java.math.BigDecimal earthRadius)

Implements the Haversine formula to calculate the great-circle distance between two points on a sphere given their latitudes and longitudes in radians.

The Haversine formula is: a = sin²(Δφ/2) + cos φ1 ⋅ cos φ2 ⋅ sin²(Δλ/2) c = 2 ⋅ atan2(√a, √(1−a)) d = R ⋅ c where φ is latitude, λ is longitude, R is earth's radius. All trigonometric calculations use helper methods that convert to double and back to BigDecimal.

Parameters:

lat1Rad - The latitude of the first point in radians, as a BigDecimal.

lon1Rad - The longitude of the first point in radians, as a BigDecimal.

lat2Rad - The latitude of the second point in radians, as a BigDecimal.

lon2Rad - The longitude of the second point in radians, as a BigDecimal.

earthRadius - The radius of the sphere (e.g., Earth's radius in km or NM), as a BigDecimal.

Returns:

The great-circle distance between the two points, in the same units as earthRadius, as a BigDecimal.

See Also:

Haversine Formula on Wikipedia