Overview

Turf for Java

Turf is a modular geospatial engine written in JavaScript. The Turf for Java library allows Android-based projects to use Turf algorithms as well. You can do Turf algorithms completely on device and don't require any type of call/response to any API or internet database.

This page walks you through the powerful ways you can use Turf, setting up Turf inside of your project, and the appropriate times to use Turf.

Read the official Turf.js library documentation for a full list of Turf methods created across platforms. It takes time to port over JavaScript Turf methods into Java, test them, and make sure proper usage. This is why, when using this Java library, you might find a Turf method that has not been ported yet.

Installation

Mapbox uses Turf heavily inside of our SDKs for Android, which means that if you are, for example, using one of our map plugins or our Navigation SDK, you already have access to this library. So, this dependency would be available to you transitively in your app.

To start developing an application using Turf for Java, you'll need to add the appropriate dependencies inside of your app by either placing it inside of your Maven's POM file or inside of Gradle's build.gradle file. You can find the dependency on MavenCentral.

Add the dependency

Gradle

  1. Start IntelliJ or Android Studio.
  2. Open up your application's build.gradle.
  3. Under dependencies, add a new build rule for the latest mapbox-sdk-turf.
  4. Click on Sync Project with Gradle Files near the toolbar in the IDE.
repositories {
  mavenCentral()
}

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-sdk-turf:4.8.0'
}

Maven

If your project's using Maven instead of Gradle, you can add the dependency inside your projects POM.xml file.

<dependency>
    <groupId>com.mapbox.mapboxsdk</groupId>
    <artifactId>mapbox-sdk-turf</artifactId>
    <version>4.8.0</version>
</dependency>

Porting to Java

While the Java port follows the same algorithms, naming schemes, and testing, there are a few things specific to Java when using Turf inside your Java project. If you are looking for documentation on a specific Turf method, see the official Turf.js documentation.

Working with GeoJSON

All Turf methods deal with spatial data that follows the GeoJSON spec. If you are not familiar with GeoJSON, it is a powerful format for encoding a variety of geographic data structures. The Turf Java library makes use of this and includes GeoJSON as a dependency inside this library. This means if you want to, for example, take the distance between two Lat/Lng points, you'd first need to have a representation of those coordinates as a GeoJSON Point object.

For example, you could use the following code to measure the straight distance (in feet) between the London Tower Bridge and the London Eye:

// Create a GeoJSON point representation of the locations.
private static final Point TOWER_BRIDGE = Point.fromLngLat(-0.07515, 51.50551);
private static final Point LONDON_EYE = Point.fromLngLat(-0.12043, 51.50348);
// Run the points through the Turf Measurement method and receive the distance.
TurfMeasurement.distance(TOWER_BRIDGE, LONDON_EYE, TurfConstants.UNIT_FEET);

Class and method naming scheme

The Java port of Turf uses categories that represent the class name. For example, the "Measurement" category in the Turf.js API documentation will be the TurfMeasurement class in the Java port. This will include all the methods that fall underneath the category.

Available methods

The project has an ongoing list of methods being ported. GitHub issues are always welcome when your project is in need of a method which has not yet been ported. The chart below displays the available methods:

Turf Java classDescriptionAvailable methods
TurfAssertionsContains a set of methods used to enforce expectations of a certain type. It can also offer methods to calculate various shapes from given points.geojsonType
featureOf
collectionOf
TurfClassificationMethods found in this class are meant to consume a set of information and classify it according to a shared quality or characteristic.nearestPoint
TurfConstantsThis is a Java-specific class that contains Java constants such as units.
TurfConversionThis class is made up of methods that take in an object, convert it, and then return the object in the desired units or object.lengthToDegrees
degreesToRadians
radiansToDegrees
radiansToLength
lengthToRadians
convertLength
TurfExceptionThis is a runtime exception that is thrown when the parameters of a method aren't adequate, the GeoJSON object is missing information, or an arithmetic issue occurs.
TurfJoinsContains methods that can determine if points lie within a polygon or not.inside
pointsWithinPolygon
TurfMeasurementContains an assortment of methods used to calculate measurements such as bearing, destination, midpoint, etc.bearing
destination
distance
length
midpoint
along
bbox
TurfMetaContains methods that are useful for getting all the coordinates from a specific GeoJSON geometry.coordAll
getCoord
TurfMiscContains all the miscellaneous methods that Turf can perform.lineSlice
lineSliceAlong
nearestPointOnLine
TurfTransformationMethods in this class consume one GeoJSON object and output a new object with the defined parameters provided.circle
Was this page helpful?