Specification | Vector tiles - Docs Mapbox

Vector tiles are encoded as Google Protobufs (PBF), which allow for serializing structured data. For clarity, Mapbox Vector Tiles use the .mvt file suffix. The ... Youareusinganoutdatedbrowserandwillencountersomeproblemswithourwebsite.Pleaseconsiderupgrading.UpgradeNowVectortilesSearchReferenceSpecificationAlldocsVectortilesSpecificationSpecificationOnthispageVersioningFormatHowareOpenStreetMapPBFfilesrelatedtoMapboxVectorTiles?EncodinggeometryEncodingattributesWindingorderImplementationsWhatthespecdoesn'tcoverHowtousevectortilesasadatasetHowtoencodeattributesthataren'tstringsornumbersClippingSimplificationShareyourfeedbackAspecificationisanimportantmeansofsettingstandardsaroundhowdataisstoredandencoded.Likeapplicationsmakeassumptionsaboutwhatinformationexistsinadatabase,Mapboxtoolsmakeassumptionsabouthowvectortilesstoregeographicinformation.TheMapboxVectorTileSpecificationexplicitlyprovidesinformationaboutfileformatsandextensions,projectionsandbounds,andtheinternalstructureofvectortiles.Thispageincludes:explanationsofversiondistinctionsexamplesofgeometryencodingexamplesofattributeencodinganexplanationoftheimportanceofwindingorderalistofconceptsnotincludedinthespecificationVersioningTheMapboxVectorTileSpecificationisversionedbasedonmajor.minornotation.Themajorversionwillbeincrementedwithanytechnicalchangetothespecificationformatorwayitshouldbeinterpreted.Changestotheminorversionwillbereservedforanyclarificationorcorrectionofclericalerrorsassociatedwiththespecificationlanguage.ThemajorversioninthespecificationnameissynonymouswiththeversionfieldinaMapboxVectorTilelayer.SeetheLayerssectionoftheVectorTileSpecificationformoredetails.VersionDate of releaseUpdates2.1January19,2016Correctiontothewordinginafewlocationsofthe2.0specification.2.0December4,2015Thefocusofversion2.0oftheMapboxVectorTilespecificationistheclarificationoftheintentoftheintialversionofthespecificationandthedefinitionofinteriorandexteriorringswithinpolygons.Thefieldswithintheprotobufferaremoreclearlydefinedinthisversionofthespecificationandthestepsfordecodersandencodersaremoreexplicitydeclared.1.0.1July28,2014Update.protofiletomatchProtocolBufferstyleguide,changednamespace1.0.0April13,2014FirstreleaseFormatVectortilesareencodedasGoogleProtobufs(PBF),whichallowforserializingstructureddata.Forclarity,MapboxVectorTilesusethe.mvtfilesuffix.Thespecificationdetailsarelargelystructuredaroundtherulesimplementedinthebase.protofile.HowareOpenStreetMapPBFfilesrelatedtoMapboxVectorTiles?Theyarenotrelatedatall.PBFsareaformat,muchlikeXMLandcantakemanyforms.MapboxVectorTilesandOpenStreetMapPBFsareprotobuffiles,butconformtocompletelydifferentspecificationsandareusedindifferentways.EncodinggeometryToencodegeographicinformationintoavectortileatoolmustconvertgeographiccoordinates,suchaslatitudeandlongitude,intovectortilegridcoordinates.Vectortilesholdnoconceptofgeographicinformation.Theyencodepoints,lines,andpolygonsasx/ypairsrelativetothetopleftofthegridinaright-downmanner.Thisisastep-by-stepexampleshowinghowasinglevectortileencodesgeometryinthegrid.Itfollowsthecommandsofthe"pen"toencodetworings.Step0AnemptyvectortileThevectortiletotherightisa10x10gridwith2cellbuffer.Let'sencodesomegeometrytothegridstartingwithabluepolygon.Thefollowingcommandswillberelativetothepen(blackdot).NextstepEncodingattributesAttributesareencodedinaseriesoftagsthatexistwithinafeatureinthevectorthathaveintegervaluesthatreferencekeysandvaluesdesignatingtheoriginalkey:valuepairsfromthegeometry.Forlargegeometry,thisremovesredundancyforattributesthathavethesamekeysandsimilarvalues.TakealookattheoriginalGeoJSONFeatureCollectionontheleftandseehowitsindividualpartsareencodedintothepropertagsofthevectortileprotobuf.HoveroverthefeaturesandthepropertiesoftheGeoJSON.Originalgeojson{ "type":"FeatureCollection", "features":[ { "geometry":{...}, "type":"Feature", "properties":{ "hello":"world", "h":"world", "count":1.23 } }, { "geometry":{...}, "type":"Feature", "properties":{ "hello":"again", "count":2 }} ]}Finalvectortilelayers{ version:2 name:"points" features:{ id:1 tags:0tags:0tags:1tags:0tags:2tags:1type:Point geometry:... }features{ id:2tags:0 tags:2 tags:2 tags:3 type:Point geometry:... }keys:"hello"keys:"h"keys:"count"values:{string_value:"world"}values:{double_value:1.23}values:{string_value:"again"}values:{int_value:2}extent:4096}WindingorderWindingorderreferstothedirectionthevectortiledrawsaring,eitherclockwiseorcounter-clockwise.Manygeometriesaremultipolygonswith"holes,"whicharealsorepresentedaspolygonrings.Itisimportanttobeabletoinferwindingordertoextractsourcedatafromavectortileandunderstandifthegeometryispartofamultipolygonorauniquepolygon.Extractingtheoriginaldatafromimageshasbeendifficultonmapsinthepast,becauseofthelossofunderlyingmetadatafromthegeometrythatmighthavebeenusedtocreatetheimage.Yet,withtheintroductionofclientsiderenderingofvectortilesviaGLtechnologies,therawgeometrydatahasbecomeusefulforasourceofinformationoutsideofrendering.Inorderforrendererstoappropriatelydistinguishwhichpolygonsareholesandwhichareuniquegeometries,thespecificationrequiresallpolygonstobevalid(OGCvalidity).Anypolygoninteriorringmustbeorientedwiththewindingorderoppositethatoftheirparentexteriorringandallinteriorringsmustdirectlyfollowtheexteriorringtowhichtheybelong.Exteriorringsmustbeorientedclockwiseandinteriorringsmustbeorientedcounter-clockwise(whenviewedinscreencoordinates).Thefollowingexamplegeometriesshowhowencodingaring'swindingordercanaffecttherenderedresult.Eachexampleassumesallringsarepartofthesamemultipolygon.Note:theYaxisispositive-downwardinvectortilecoordinates!DescriptionWindingorderRenderedAsinglering,inclockwiseorderisrenderedasasingle,solidpolygon.Ring1:ClockwiseTworingswiththesamewindingorderwillrenderastwouniquepolygonsoverlapping.Ring1:ClockwiseRing2:ClockwiseTworings,thefirst(exterior)ringisinclockwiseorder,whilethesecondiscounter-clockwise.Thisresultsina"hole"inthefinalrender.Ring1:ClockwiseRing2:Counter-ClockwiseThreeringsinamultipolygonthatalternatewindingorder.Ring1:ClockwiseRing2:Counter-ClockwiseRing3:ClockwiseImplementationsImplementationsoftheMapboxVectorTileSpecificationarefarandwide.Manyofthemfallintooneofthefollowingcategories:Parsers&generators:librariesthatreadand/orencodevectortiles,somealsohavecommandlineutilitiesClients:web-basedtoolsthatrendervectortilesthatconformtothespecificationApplications:browser-basedtoolsforcreatingandvisualizingvectortilesServers:supportrenderingandservingupvectortiles(note:thespecificationdoesn'tgointohowtodothisexplicitly)VisitMapboxVectorTilesforalistoftoolsimplementingvectortiles.Whatthespecdoesn'tcoverThisspecificationisexplicitinthewayavectortileshouldpackdata.But,therearesomerelatedconceptsthatthisspecificationdoesnotcover.HowtousevectortilesasadatasetThisspecificationISNOTintendedtoexplainhowtousevectortilesasadataset.Thisissomethingthathasbeenconsideredforthefuture,butitwilllikelybeaseparatespecification.Thisspecificationdoesnotcoverhowtostore,request,orsharevectortiles.ConsiderthisspecificationlikehowthePNGspecexplainshowtopackdata.Howtoencodeattributesthataren'tstringsornumbersAttributesingeometricdata,suchasthepropertiesobjectinGeoJSONcanincludemorethanstringsandnumbers.Theycanbearraysorobjects.Thespecificationdoesn'tcoverhowtoencodethesevaluesandisuptotheencodertodecide.ToolslikeMapnikwillturnarraysandobjectsintostrings,whichrequiresthedecodertoparsethem.Forexample,ifyouhadaGeoJSONpropertycalledcategoriesanditwasanarray:"categories":["one","two","three"] Itwouldbeconvertedintoastringandstoredintheprotobuflikethis:keys:"categories" values:{ string_value:"[\"one\",\"two\",\"three\"]" } ClippingThespecificationdoesnotexplainhowgeographicdatashouldbeclippedbetweenvectortilessinceclipping,likesimplification,canbeexecutedinmanyways.Mapboxspecificallyclipsfeaturesatabufferaroundthetile(seetheencodingexampleabove).Anygeometrywithinthisbufferisassumedtocarryovertoanothertile.Thisisupforconsiderationforafuturerelease.Note:encodedgeometryinvectortilescanextendbeyondtheboundofthetile.Thismeansfeaturesarenotrequiredtobeclipped.Acommonquestion,whenitcomestoclippingis"howdorenderersknowwhichlinestoconnectforclippedgeometry?".ThisisthereasonMapboxaddsabuffertovectortilesandclippedgeometry.Whenitistimetorender,Mapboxsetsthecanvastotheexacttilesize,whichsetstheedgesoutsideofthevisualframe,thusthetilesalllineup.So,thereisnoneedtoknowwhichnodesarepartofothersforrenderingpurposes.Although,youcouldusetheidfieldintheprotobuftostoreinformationnecessaryforreconstructingpolygons.SimplificationTheconversionfromgeographiccoordinates(latitudeandlongitude)tovectortilecoordinates(x,y)isanimportantstep,butcanbeimplementedinmanydifferentwaysbeforevectortileencoding.Itisnotincludedinthisspecification,buttherearesomeimportantGOTCHAsworthnoting.SimplificationcancauseinvalidpolygonsaccordingtotheOGCstandardsbyoversimplifyingpolygonringstothepointwheretheiredgesoverlap.Seebelowhowsimplifyingonelinechangestherenderingofapolygonbypushingtheinteriorringoutsideoftheexteriorring.1/4Polygonwitha"hole"2/4Exterior(blue)andinterior(red)rings3/4Simplifiedexteriorring4/4InvalidgeometryWhenspatialcoordinatesareconvertedtotilecoordinates,theyareroundedtointegers.Simplifying(rounding)thecoordinatescanreversethewindingorder.Consideratrianglepolygonthatissimplifiedtothevectortilegrid.Theroundedpointcancrossoverthepolygonand"flip"it,renderingitswindingorderreversed.1/4Polygonpre-simplification2/4Simplifyapointtothegrid3/4Simplifythesecondpointtothegrid4/4SimplifyingthefinalpointflipsthetriangleandreversesthewindingorderShareyourfeedback