Turf Module
The Turf module (mapbox-sdk-turf) of the Mapbox Java SDK allows you to do spatial processing operations, such as length and area calculations, spatial joins, and unit nearest-neighbor queries in a Java or Kotlin environment.
Turf.js is a modular geospatial engine written in JavaScript. This module ports many of the operations available in turf.js to Java. These operations run 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 Maps, Search, and Navigation SDKs for Android. This means that if you are using one these SDKs, you already have access to this library and do not need to install it separately.
See the installation guide for detailed installation instructions using Gradle or Maven.
Import each method you want to use. Below are some examples of import statements for various turf methods:
import com.mapbox.turf.TurfMeasurement.length
import com.mapbox.turf.TurfConversion.radiansToDegrees
import com.mapbox.turf.TurfMisc.lineSlice
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.
Learn more about GeoJSON, a file format for geolocation data.
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);
companion object {
// Create a GeoJSON point representation of the locations.
private val TOWER_BRIDGE = Point.fromLngLat(-0.07515, 51.50551)
private val 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 class | Description | Available methods |
|---|---|---|
TurfAssertions | Contains 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 |
TurfClassification | Methods found in this class consume a set of information and classify it according to a shared quality or characteristic. | nearestPoint |
TurfConstants | This is a Java-specific class that contains Java constants such as units. | |
TurfConversion | A class of methods that take in an object, convert it, and then return the object in the desired units or object. | convertLength explode lengthToDegrees lengthToRadians degreesToRadians radiansToDegrees radiansToLength |
TurfException | This is a runtime exception when parameters of a method aren't adequate, the GeoJSON object is missing information, or an arithmetic issue occurs. | |
TurfJoins | Contains methods that can determine if points lie within a polygon or not. | inside pointsWithinPolygon |
TurfMeasurement | Contains an assortment of methods used to calculate measurements such as bearing, destination, midpoint, etc. | along bbox bbox-polygon bearing destination distance envelope length midpoint square |
TurfMeta | Contains methods that are useful for getting all the coordinates from a specific GeoJSON geometry. | coordAll getCoord |
TurfMisc | Contains all the miscellaneous methods that Turf can do. | lineSlicelineSliceAlong nearestPointOnLine |
TurfTransformation | Methods in this class consume one GeoJSON object and output a new object with the defined parameters provided. | circle |