{"id":37020546,"url":"https://github.com/sebasbaumh/mapbox-vector-tile-java","last_synced_at":"2026-01-14T02:23:48.203Z","repository":{"id":37957496,"uuid":"493672241","full_name":"sebasbaumh/mapbox-vector-tile-java","owner":"sebasbaumh","description":"Java Mapbox Vector Tile Library for Encoding/Decoding","archived":false,"fork":false,"pushed_at":"2025-12-01T16:19:31.000Z","size":682,"stargazers_count":13,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-03T22:24:16.053Z","etag":null,"topics":["java","jdk21","jts","mapbox","mapbox-vector-tile","vector-tiles"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sebasbaumh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-05-18T13:20:57.000Z","updated_at":"2025-12-01T11:31:17.000Z","dependencies_parsed_at":"2023-02-02T05:02:00.951Z","dependency_job_id":"cbdb5c67-6447-4378-ac23-54c450777c98","html_url":"https://github.com/sebasbaumh/mapbox-vector-tile-java","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/sebasbaumh/mapbox-vector-tile-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebasbaumh%2Fmapbox-vector-tile-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebasbaumh%2Fmapbox-vector-tile-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebasbaumh%2Fmapbox-vector-tile-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebasbaumh%2Fmapbox-vector-tile-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sebasbaumh","download_url":"https://codeload.github.com/sebasbaumh/mapbox-vector-tile-java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebasbaumh%2Fmapbox-vector-tile-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","jdk21","jts","mapbox","mapbox-vector-tile","vector-tiles"],"created_at":"2026-01-14T02:23:47.534Z","updated_at":"2026-01-14T02:23:48.197Z","avatar_url":"https://github.com/sebasbaumh.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MapBox Vector Tile - Java\n\n[![CodeQL](https://github.com/sebasbaumh/mapbox-vector-tile-java/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/sebasbaumh/mapbox-vector-tile-java/actions/workflows/codeql-analysis.yml)\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.sebasbaumh/mapbox-vector-tile-java)](https://search.maven.org/artifact/io.github.sebasbaumh/mapbox-vector-tile-java)\n[![javadoc](https://javadoc.io/badge2/io.github.sebasbaumh/mapbox-vector-tile-java/javadoc.svg)](https://javadoc.io/doc/io.github.sebasbaumh/mapbox-vector-tile-java/latest/index.html)\n[![License](https://img.shields.io/github/license/sebasbaumh/mapbox-vector-tile-java.svg)](https://github.com/sebasbaumh/mapbox-vector-tile-java/blob/master/LICENSE)\n\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=sebasbaumh_mapbox-vector-tile-java\u0026metric=ncloc)](https://sonarcloud.io/dashboard?id=sebasbaumh_mapbox-vector-tile-java)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=sebasbaumh_mapbox-vector-tile-java\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=sebasbaumh_mapbox-vector-tile-java)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=sebasbaumh_mapbox-vector-tile-java\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=sebasbaumh_mapbox-vector-tile-java)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=sebasbaumh_mapbox-vector-tile-java\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=sebasbaumh_mapbox-vector-tile-java)\n\nThis project allows encoding and decoding of MapBox Vector Tiles (MVT).  \n*It is originally based on [mapbox-vector-tile-java](https://github.com/wdtinc/mapbox-vector-tile-java), which is unfortunately [discontinued](https://github.com/wdtinc/mapbox-vector-tile-java/issues/45#issuecomment-1126996294) and I want to thank its authors for their work.*\n\n## Project goals and improvements:\n* protoc generated model for Mapbox Vector Tiles v2.1.\n* Provides MVT encoding through use of the Java Topology Suite (JTS).\n* All dependencies were upgraded to their latest version (including JTS)\n* Pull requests from the original source were integrated ([52](https://github.com/wdtinc/mapbox-vector-tile-java/pull/52) and [53](https://github.com/wdtinc/mapbox-vector-tile-java/pull/53))\n* Clean up of the code and optimizations (use null annotations and streamline flow)\n* Support for current JDKs\n  * JDK 21 ([main branch](https://github.com/sebasbaumh/mapbox-vector-tile-java/tree/main))\n  * deprecated branches\n    * [JDK 17](https://github.com/sebasbaumh/mapbox-vector-tile-java/tree/jdk17)\n    * [JDK 11](https://github.com/sebasbaumh/mapbox-vector-tile-java/tree/jdk11)\n* The license is still [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0.html)\n\n### See also:\n\n * https://www.mapbox.com/vector-tiles/specification/ for overview of the MVT spec.\n * https://github.com/mapbox/vector-tile-spec/tree/master/2.1 for details on the MVT spec.\n * https://developers.google.com/protocol-buffers/ for details on protoc.\n * https://projects.eclipse.org/projects/locationtech.jts for details on JTS.\n\n\n## How to use it ##\n### Maven\nThere is a Maven artifact in the official Maven repository, so just add this to your Maven POM:\n\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003eio.github.sebasbaumh\u003c/groupId\u003e\n\t\u003cartifactId\u003emapbox-vector-tile-java\u003c/artifactId\u003e\n\t\u003cversion\u003e25.1.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Gradle\n\n```\ncompile 'io.github.sebasbaumh:mapbox-vector-tile-java:25.1.0'\n```\n\n## Overview\n\nThe version reflects the year of the release, e.g. `25.1.0` is a version released in 2025.\n\n### Changes from to the original [mapbox-vector-tile-java](https://github.com/wdtinc/mapbox-vector-tile-java)\n\nThe API differs a bit from [mapbox-vector-tile-java](https://github.com/wdtinc/mapbox-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.\n\nEspecially [`JtsAdapter`](https://github.com/sebasbaumh/mapbox-vector-tile-java/blob/main/src/main/java/io/github/sebasbaumh/mapbox/vectortile/adapt/jts/JtsAdapter.java) has been reworked and optimized. Usually you will have to move from `addAllFeatures`/`toFeatures` to `addFeatures` instead.\n\nThere 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 use `null` values to use none/ignore them.\n\n## Usage\n\n### Encoding vector tiles\n\nExample for encoding a JTS geometry to a vector tile as `byte[]`:\n```java\n// prepare helper classes\nGeometryFactory geomFactory = new GeometryFactory();\nMvtLayerProps mvtLayerProps = new MvtLayerProps();\nMvtLayerParams mvtLayerParams = MvtLayerParams.DEFAULT;\nVectorTile.Tile.Layer.Builder mvtLayerBuilder = MvtUtil.newLayerBuilder(\"test\", mvtLayerParams);\n\n// build tile envelope - 1 quadrant of the world\nEnvelope tileEnvelope = new Envelope(0d, WORLD_SIZE * .5d, 0d, WORLD_SIZE * .5d);\n\n// this is the geometry\norg.locationtech.jts.geom.Point point = geomFactory.createPoint(new Coordinate(12,45));\n// encode the geometry\norg.locationtech.jts.geom.Geometry tileGeom = JtsAdapter.createTileGeom(\n        point, tileEnvelope, geomFactory, mvtLayerParams, null);\n// add it to the layer builder\nmvtLayerBuilder.addAllFeatures(JtsAdapter.addFeatures(tileGeom, mvtLayerProps, null));\n\n// finish writing of features\nMvtUtil.writeProps(mvtLayerBuilder, mvtLayerProps);\nVectorTile.Tile.Builder mvtBuilder = VectorTile.Tile.newBuilder();\nmvtBuilder.addLayers(mvtLayerBuilder.build());\n// build the vector tile (here as byte array)\nbyte[] mvtData = mvtBuilder.build().toByteArray();\n```\n\n## Overview\n\n### Reading MVTs\n\nPer-tile geometry conversion overview:\n\n![Image of Geometry Conversion Overview](docs/mvt_read_flow.png)\n\nUse MvtReader.loadMvt() to load MVT data from a path or input stream\ninto JTS geometry. The TagKeyValueMapConverter instance will convert\nMVT feature tags to a Map with primitive values. The map will be\nstored as a JTS geometry user data object within the Geometry.\n\nThe JtsMvt object wraps the JTS Geometry with MVT layer information\nand structure.\n\n```java\nGeometryFactory geomFactory = new GeometryFactory();\n\nJtsMvt jtsMvt = MvtReader.loadMvt(\n        Paths.get(\"path/to/your.mvt\"),\n        geomFactory,\n        new TagKeyValueMapConverter());\n\n\n// Allow negative-area exterior rings with classifier\n// (recommended for Mapbox compatibility)\nJtsMvt jtsMvt = MvtReader.loadMvt(\n        Paths.get(\"path/to/your.mvt\"),\n        geomFactory,\n        new TagKeyValueMapConverter(),\n        MvtReader.RING_CLASSIFIER_V1);\n```\n\n### Building and Writing MVTs\n\nPer-layer geometry conversion overview:\n\n![Image of Geometry Conversion Overview](docs/mvt_build_flow.png)\n\n#### 1) Create or Load JTS Geometry\n\nCreate or load any JTS Geometry that will be included in the MVT. The Geometries are assumed\nto be in the global/world units for your target projection. Example: meters for EPSG:3857.\n\n#### 2) Create Tiled JTS Geometry in MVT Coordinates\n\nCreate tiled JTS geometry with JtsAdapter#createTileGeom(). MVTs currently\ndo not support feature collections so any JTS geometry collections will be flattened\nto a single level.\nKeep in mind that MVTs use local 'screen coordinates' with inverted y-axis compared with cartesian.\n\n```java\nIGeometryFilter acceptAllGeomFilter = geometry -\u003e true;\nEnvelope tileEnvelope = new Envelope(0d, 100d, 0d, 100d); // TODO: Your tile extent here\nMvtLayerParams layerParams = new MvtLayerParams(); // Default extent\n\nGeometry tileGeom = JtsAdapter.createTileGeom(\n        jtsGeom, // Your geometry\n        tileEnvelope,\n        geomFactory,\n        layerParams,\n        acceptAllGeomFilter);\n```\n\n#### 3) Create MVT Builder, Layers, and Features\n\nAfter creating a tile's geometry in step 2, it is ready to be encoded in a MVT protobuf.\n\nNote: Applications can perform step 2 multiple times to place geometry in separate MVT layers.\n\nCreate the VectorTile.Tile.Builder responsible for the MVT protobuf\nbyte array. This is the top-level object for writing the MVT:\n\n```java\nVectorTile.Tile.Builder tileBuilder = VectorTile.Tile.newBuilder();\n```\n\nCreate an empty layer for the MVT using the MvtUtil#newLayerBuilder() utility function:\n\n```java\nVectorTile.Tile.Layer.Builder layerBuilder = MvtUtil.newLayerBuilder(\"myLayerName\", layerParams);\n```\n\nMVT JTS Geometry from step 2 need to be converted to MVT features.\n\nMvtLayerProps is a supporting class for building MVT layer\nkey/value dictionaries. A user data converter will take JTS Geometry\nuser data (preserved during MVT tile geometry conversion) and convert it to MVT tags:\n\n```java\nMvtLayerProps layerProps = new MvtLayerProps();\nIUserDataConverter userDataConverter = new UserDataKeyValueMapConverter();\nList\u003cVectorTile.Tile.Feature\u003e features = JtsAdapter.addFeatures(layerBuilder, tileGeom, layerProps, userDataConverter);\n```\n\nUse MvtUtil#writeProps() utility function after JtsAdapter#addFeatures() to add the key/value dictionary to the\nMVT layer:\n\n```java\nMvtUtil.writeProps(layerBuilder, layerProps);\n```\n\n#### 4) Write MVT\n\nThis example writes the MVT protobuf byte array to an output file.\n\n```java\nVectorTile.Tile mvt = tileBuilder.build();\ntry {\n    Files.write(path, mvt.toByteArray());\n} catch (IOException e) {\n    logger.error(e.getMessage(), e);\n}\n```\n\n### Buffering Polygons Beyond MVT Extent\n\nFor polygon geometry that will be styled with outlines, it is recommended that\nthe clipping area be larger than the tile extent area. This can be handled like\nthe example in MvtBuildTest#testBufferedPolygon(). Code example:\n\n```java\n// Create input geometry\nfinal GeometryFactory geomFactory = new GeometryFactory();\nfinal Geometry inputGeom = buildPolygon(RANDOM, 200, geomFactory);\n\n// Build tile envelope - 1 quadrant of the world\nfinal double tileWidth = WORLD_SIZE * .5d;\nfinal double tileHeight = WORLD_SIZE * .5d;\nfinal Envelope tileEnvelope = new Envelope(0d, tileWidth, 0d, tileHeight);\n\n// Build clip envelope - (10 * 2)% buffered area of the tile envelope\nfinal Envelope clipEnvelope = new Envelope(tileEnvelope);\nfinal double bufferWidth = tileWidth * .1f;\nfinal double bufferHeight = tileHeight * .1f;\nclipEnvelope.expandBy(bufferWidth, bufferHeight);\n\n// Build buffered MVT tile geometry\nfinal TileGeomResult bufferedTileGeom = JtsAdapter.createTileGeom(\n        inputGeom, tileEnvelope, clipEnvelope, geomFactory,\n        DEFAULT_MVT_PARAMS, null);\n\n// Create MVT layer\nfinal VectorTile.Tile mvt = encodeMvt(DEFAULT_MVT_PARAMS, bufferedTileGeom);\n```\n\n## Examples\n\nSee [tests](https://github.com/sebasbaumh/mapbox-vector-tile-java/tree/main/src/test/java/io/github/sebasbaumh/mapbox/vectortile).\n\n## How to generate VectorTile class using vector_tile.proto\n\nIf vector_tile.proto is changed in the specification, VectorTile may need to be regenerated.\n\nCommand `protoc` version should be the same version as the POM.xml dependency.\n\n`protoc --java_out=src/main/java src/main/resources/vector_tile.proto`\n\n#### Extra .proto config\n\nThese options were added to the .proto file:\n\n * syntax = \"proto2\";\n * option java_package = \"io.github.sebasbaumh.mapbox.vectortile\";\n * option java_outer_classname = \"VectorTile\";\n\n## Known Issues\n\n * 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.\n * Invalid or non-simple geometry may not work correctly with JTS operations when creating tile geometry.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebasbaumh%2Fmapbox-vector-tile-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebasbaumh%2Fmapbox-vector-tile-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebasbaumh%2Fmapbox-vector-tile-java/lists"}