/** * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees * Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, * feet. * * @param distance in real units * @param units can be degrees, radians, miles, or kilometers inches, yards, metres, meters, * kilometres, kilometers. * @return a double value representing the distance in degrees * @since 3.0.0 */ public static double lengthToDegrees(double distance, @TurfUnitCriteria String units) { return radiansToDegrees(lengthToRadians(distance, units)); }
/** * Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly * unit. The units used here equals the default. * * @param radians a double using unit radian * @return converted radian to distance value * @since 1.2.0 */ public static double radiansToLength(double radians) { return radiansToLength(radians, TurfConstants.UNIT_DEFAULT); }
/** * Converts a distance to a different unit specified. * * @param distance the distance to be converted * @param originalUnit of the distance, must be one of the units defined in * {@link TurfUnitCriteria} * @param finalUnit returned unit, {@link TurfConstants#UNIT_DEFAULT} if not specified * @return the converted distance * @since 2.2.0 */ public static double convertLength(@FloatRange(from = 0) double distance, @NonNull @TurfUnitCriteria String originalUnit, @Nullable @TurfUnitCriteria String finalUnit) { if (finalUnit == null) { finalUnit = TurfConstants.UNIT_DEFAULT; } return radiansToLength(lengthToRadians(distance, originalUnit), finalUnit); } }
/** * Takes a Point and calculates the location of a destination point given a distance in * degrees, radians, miles, or kilometers; and bearing in degrees. This uses the Haversine * formula to account for global curvature. * * @param point starting point used for calculating the destination * @param distance distance from the starting point * @param bearing ranging from -180 to 180 in decimal degrees * @param units one of the units found inside {@link TurfConstants.TurfUnitCriteria} * @return destination {@link Point} result where you specified * @see <a href="http://turfjs.org/docs/#destination">Turf Destination documetation</a> * @since 1.2.0 */ @NonNull public static Point destination(@NonNull Point point, @FloatRange(from = 0) double distance, @FloatRange(from = -180, to = 180) double bearing, @NonNull @TurfConstants.TurfUnitCriteria String units) { double longitude1 = degreesToRadians(point.longitude()); double latitude1 = degreesToRadians(point.latitude()); double bearingRad = degreesToRadians(bearing); double radians = TurfConversion.lengthToRadians(distance, units); double latitude2 = Math.asin(Math.sin(latitude1) * Math.cos(radians) + Math.cos(latitude1) * Math.sin(radians) * Math.cos(bearingRad)); double longitude2 = longitude1 + Math.atan2(Math.sin(bearingRad) * Math.sin(radians) * Math.cos(latitude1), Math.cos(radians) - Math.sin(latitude1) * Math.sin(latitude2)); return Point.fromLngLat( radiansToDegrees(longitude2), radiansToDegrees(latitude2)); }
/** * Calculates the distance between two points in degress, radians, miles, or kilometers. This * uses the Haversine formula to account for global curvature. * * @param point1 first point used for calculating the bearing * @param point2 second point used for calculating the bearing * @param units one of the units found inside {@link TurfConstants.TurfUnitCriteria} * @return distance between the two points in kilometers * @see <a href="http://turfjs.org/docs/#distance">Turf distance documentation</a> * @since 1.2.0 */ public static double distance(@NonNull Point point1, @NonNull Point point2, @NonNull @TurfConstants.TurfUnitCriteria String units) { double difLat = degreesToRadians((point2.latitude() - point1.latitude())); double difLon = degreesToRadians((point2.longitude() - point1.longitude())); double lat1 = degreesToRadians(point1.latitude()); double lat2 = degreesToRadians(point2.latitude()); double value = Math.pow(Math.sin(difLat / 2), 2) + Math.pow(Math.sin(difLon / 2), 2) * Math.cos(lat1) * Math.cos(lat2); return TurfConversion.radiansToLength( 2 * Math.atan2(Math.sqrt(value), Math.sqrt(1 - value)), units); }
/** * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into * radians. * * @param distance double representing a distance value assuming the distance units is in * kilometers * @return converted distance to radians value * @since 1.2.0 */ public static double lengthToRadians(double distance) { return lengthToRadians(distance, TurfConstants.UNIT_DEFAULT); }
/** * Converts a distance to the default units. Use * {@link TurfConversion#convertLength(double, String, String)} to specify a unit to convert to. * * @param distance double representing a distance value * @param originalUnit of the distance, must be one of the units defined in * {@link TurfUnitCriteria} * @return converted distance in the default unit * @since 2.2.0 */ public static double convertLength(@FloatRange(from = 0) double distance, @NonNull @TurfUnitCriteria String originalUnit) { return convertLength(distance, originalUnit, TurfConstants.UNIT_DEFAULT); }
/** * Takes two {@link Point}s and finds the geographic bearing between them. * * @param point1 first point used for calculating the bearing * @param point2 second point used for calculating the bearing * @return bearing in decimal degrees * @see <a href="http://turfjs.org/docs/#bearing">Turf Bearing documentation</a> * @since 1.3.0 */ public static double bearing(@NonNull Point point1, @NonNull Point point2) { double lon1 = degreesToRadians(point1.longitude()); double lon2 = degreesToRadians(point2.longitude()); double lat1 = degreesToRadians(point1.latitude()); double lat2 = degreesToRadians(point2.latitude()); double value1 = Math.sin(lon2 - lon1) * Math.cos(lat2); double value2 = Math.cos(lat1) * Math.sin(lat2) - Math.sin(lat1) * Math.cos(lat2) * Math.cos(lon2 - lon1); return radiansToDegrees(Math.atan2(value1, value2)); }
@Test public void distanceToDegrees() throws Exception { assertEquals( 57.29577951308232, TurfConversion.lengthToDegrees(1, TurfConstants.UNIT_RADIANS), DELTA); assertEquals( 0.8990393772647469, TurfConversion.lengthToDegrees(100, TurfConstants.UNIT_KILOMETERS), DELTA); assertEquals( 0.14468631190172304, TurfConversion.lengthToDegrees(10, TurfConstants.UNIT_MILES), DELTA); }
@Test public void distanceToRadians() throws Exception { assertEquals( 1, TurfConversion.lengthToRadians(1, TurfConstants.UNIT_RADIANS), DELTA); assertEquals( 1, TurfConversion.lengthToRadians(6373, TurfConstants.UNIT_KILOMETERS), DELTA); assertEquals( 1, TurfConversion.lengthToRadians(3960, TurfConstants.UNIT_MILES), DELTA); }
@Test public void convertDistance() throws TurfException { assertEquals(1, TurfConversion.convertLength(1000, TurfConstants.UNIT_METERS), DELTA); assertEquals(0.6213714106386318, TurfConversion.convertLength(1, TurfConstants.UNIT_KILOMETERS, TurfConstants.UNIT_MILES), DELTA); assertEquals(1.6093434343434343, TurfConversion.convertLength(1, TurfConstants.UNIT_MILES, TurfConstants.UNIT_KILOMETERS), DELTA); assertEquals(1.851999843075488, TurfConversion.convertLength(1, TurfConstants.UNIT_NAUTICAL_MILES), DELTA); assertEquals(100, TurfConversion.convertLength(1, TurfConstants.UNIT_METERS, TurfConstants.UNIT_CENTIMETERS), DELTA); } }
@Test public void radiansToDistance() throws Exception { assertEquals( 1, TurfConversion.radiansToLength(1, TurfConstants.UNIT_RADIANS), DELTA); assertEquals( 6373, TurfConversion.radiansToLength(1, TurfConstants.UNIT_KILOMETERS), DELTA); assertEquals( 3960, TurfConversion.radiansToLength(1, TurfConstants.UNIT_MILES), DELTA); }