Repository files navigation

This project allows encoding and decoding of MapBox Vector Tiles (MVT).
It is originally based onmapbox-vector-tile-java, which is unfortunatelydiscontinued and I want to thank its authors for their work.

• protoc generated model for Mapbox Vector Tiles v2.1.
• Provides MVT encoding through use of the Java Topology Suite (JTS).
• All dependencies were upgraded to their latest version (including JTS)
• Pull requests from the original source were integrated (52 and53)
• Clean up of the code and optimizations (use null annotations and streamline flow)
• Support for current JDKs
  • JDK 21 (main branch)
  • deprecated branches
    • JDK 17
    • JDK 11
• The license is stillApache-2.0

• https://www.mapbox.com/vector-tiles/specification/ for overview of the MVT spec.
• https://github.com/mapbox/vector-tile-spec/tree/master/2.1 for details on the MVT spec.
• https://developers.google.com/protocol-buffers/ for details on protoc.
• https://projects.eclipse.org/projects/locationtech.jts for details on JTS.

There is a Maven artifact in the official Maven repository, so just add this to your Maven POM:

<dependency><groupId>io.github.sebasbaumh</groupId><artifactId>mapbox-vector-tile-java</artifactId><version>25.1.0</version></dependency>

compile 'io.github.sebasbaumh:mapbox-vector-tile-java:25.1.0'

The version reflects the year of the release, e.g.25.1.0 is a version released in 2025.

The API differs a bit frommapbox-vector-tile-java with the main point being a different namespace (io.github.sebasbaumh.mapbox.vectortile) as publishing a project to Maven Central requires to own that namespace.

EspeciallyJtsAdapter has been reworked and optimized. Usually you will have to move fromaddAllFeatures/toFeatures toaddFeatures instead.

There are also some changes in the class structure, so make sure check your existing code for errors or deprecation warnings. For converters and filters it is now possible to usenull values to use none/ignore them.

Example for encoding a JTS geometry to a vector tile asbyte[]:

// prepare helper classesGeometryFactorygeomFactory =newGeometryFactory();MvtLayerPropsmvtLayerProps =newMvtLayerProps();MvtLayerParamsmvtLayerParams =MvtLayerParams.DEFAULT;VectorTile.Tile.Layer.BuildermvtLayerBuilder =MvtUtil.newLayerBuilder("test",mvtLayerParams);// build tile envelope - 1 quadrant of the worldEnvelopetileEnvelope =newEnvelope(0d,WORLD_SIZE *.5d,0d,WORLD_SIZE *.5d);// this is the geometryorg.locationtech.jts.geom.Pointpoint =geomFactory.createPoint(newCoordinate(12,45));// encode the geometryorg.locationtech.jts.geom.GeometrytileGeom =JtsAdapter.createTileGeom(point,tileEnvelope,geomFactory,mvtLayerParams,null);// add it to the layer buildermvtLayerBuilder.addAllFeatures(JtsAdapter.addFeatures(tileGeom,mvtLayerProps,null));// finish writing of featuresMvtUtil.writeProps(mvtLayerBuilder,mvtLayerProps);VectorTile.Tile.BuildermvtBuilder =VectorTile.Tile.newBuilder();mvtBuilder.addLayers(mvtLayerBuilder.build());// build the vector tile (here as byte array)byte[]mvtData =mvtBuilder.build().toByteArray();

Per-tile geometry conversion overview:

Use MvtReader.loadMvt() to load MVT data from a path or input streaminto JTS geometry. The TagKeyValueMapConverter instance will convertMVT feature tags to a Map with primitive values. The map will bestored as a JTS geometry user data object within the Geometry.

The JtsMvt object wraps the JTS Geometry with MVT layer informationand structure.

GeometryFactorygeomFactory =newGeometryFactory();JtsMvtjtsMvt =MvtReader.loadMvt(Paths.get("path/to/your.mvt"),geomFactory,newTagKeyValueMapConverter());// Allow negative-area exterior rings with classifier// (recommended for Mapbox compatibility)JtsMvtjtsMvt =MvtReader.loadMvt(Paths.get("path/to/your.mvt"),geomFactory,newTagKeyValueMapConverter(),MvtReader.RING_CLASSIFIER_V1);

Per-layer geometry conversion overview:

Create or load any JTS Geometry that will be included in the MVT. The Geometries are assumedto be in the global/world units for your target projection. Example: meters for EPSG:3857.

Create tiled JTS geometry with JtsAdapter#createTileGeom(). MVTs currentlydo not support feature collections so any JTS geometry collections will be flattenedto a single level.Keep in mind that MVTs use local 'screen coordinates' with inverted y-axis compared with cartesian.

IGeometryFilteracceptAllGeomFilter =geometry ->true;EnvelopetileEnvelope =newEnvelope(0d,100d,0d,100d);// TODO: Your tile extent hereMvtLayerParamslayerParams =newMvtLayerParams();// Default extentGeometrytileGeom =JtsAdapter.createTileGeom(jtsGeom,// Your geometrytileEnvelope,geomFactory,layerParams,acceptAllGeomFilter);

After creating a tile's geometry in step 2, it is ready to be encoded in a MVT protobuf.

Note: Applications can perform step 2 multiple times to place geometry in separate MVT layers.

Create the VectorTile.Tile.Builder responsible for the MVT protobufbyte array. This is the top-level object for writing the MVT:

VectorTile.Tile.BuildertileBuilder =VectorTile.Tile.newBuilder();

Create an empty layer for the MVT using the MvtUtil#newLayerBuilder() utility function:

VectorTile.Tile.Layer.BuilderlayerBuilder =MvtUtil.newLayerBuilder("myLayerName",layerParams);

MVT JTS Geometry from step 2 need to be converted to MVT features.

MvtLayerProps is a supporting class for building MVT layerkey/value dictionaries. A user data converter will take JTS Geometryuser data (preserved during MVT tile geometry conversion) and convert it to MVT tags:

MvtLayerPropslayerProps =newMvtLayerProps();IUserDataConverteruserDataConverter =newUserDataKeyValueMapConverter();List<VectorTile.Tile.Feature>features =JtsAdapter.addFeatures(layerBuilder,tileGeom,layerProps,userDataConverter);

Use MvtUtil#writeProps() utility function after JtsAdapter#addFeatures() to add the key/value dictionary to theMVT layer:

MvtUtil.writeProps(layerBuilder,layerProps);

This example writes the MVT protobuf byte array to an output file.

VectorTile.Tilemvt =tileBuilder.build();try {Files.write(path,mvt.toByteArray());}catch (IOExceptione) {logger.error(e.getMessage(),e);}

For polygon geometry that will be styled with outlines, it is recommended thatthe clipping area be larger than the tile extent area. This can be handled likethe example in MvtBuildTest#testBufferedPolygon(). Code example:

// Create input geometryfinalGeometryFactorygeomFactory =newGeometryFactory();finalGeometryinputGeom =buildPolygon(RANDOM,200,geomFactory);// Build tile envelope - 1 quadrant of the worldfinaldoubletileWidth =WORLD_SIZE *.5d;finaldoubletileHeight =WORLD_SIZE *.5d;finalEnvelopetileEnvelope =newEnvelope(0d,tileWidth,0d,tileHeight);// Build clip envelope - (10 * 2)% buffered area of the tile envelopefinalEnvelopeclipEnvelope =newEnvelope(tileEnvelope);finaldoublebufferWidth =tileWidth *.1f;finaldoublebufferHeight =tileHeight *.1f;clipEnvelope.expandBy(bufferWidth,bufferHeight);// Build buffered MVT tile geometryfinalTileGeomResultbufferedTileGeom =JtsAdapter.createTileGeom(inputGeom,tileEnvelope,clipEnvelope,geomFactory,DEFAULT_MVT_PARAMS,null);// Create MVT layerfinalVectorTile.Tilemvt =encodeMvt(DEFAULT_MVT_PARAMS,bufferedTileGeom);

Seetests.

If vector_tile.proto is changed in the specification, VectorTile may need to be regenerated.

Commandprotoc version should be the same version as the POM.xml dependency.

protoc --java_out=src/main/java src/main/resources/vector_tile.proto

These options were added to the .proto file:

• syntax = "proto2";
• option java_package = "io.github.sebasbaumh.mapbox.vectortile";
• option java_outer_classname = "VectorTile";

• Creating tile geometry with non-simple line strings that self-cross in many places will be 'noded' by JTS during an intersection operation. This results in ugly output.
• Invalid or non-simple geometry may not work correctly with JTS operations when creating tile geometry.