Vector Tile Specification - GitHub

A Vector Tile represents data based on a square extent within a projection. A Vector Tile SHOULD NOT contain information about its bounds and projection. The ... Skiptocontent {{message}} mapbox / vector-tile-spec Public Notifications Star 657 Fork 173 Code Issues 41 Pullrequests 2 Projects 1 Wiki Security Insights More Code Issues Pullrequests Projects Wiki Security Insights Permalink master Branches Tags Couldnotloadbranches Nothingtoshow Loading {{refName}} default Couldnotloadtags Nothingtoshow {{refName}} default Loading vector-tile-spec/2.1/README.md Gotofile Gotofile T Gotoline L Copypath Copypermalink     Cannotretrievecontributorsatthistime VectorTileSpecification 1.Purpose 2.FileFormat 2.1.FileExtension 2.2.MultipurposeInternetMailExtensions(MIME) 3.ProjectionandBounds 4.InternalStructure 4.1.Layers 4.2.Features 4.3.GeometryEncoding 4.3.1.CommandIntegers ExampleCommandIntegers 4.3.2.ParameterIntegers 4.3.3.CommandTypes 4.3.3.1.MoveToCommand 4.3.3.2.LineToCommand 4.3.3.3.ClosePathCommand 4.3.4.GeometryTypes 4.3.4.1.UnknownGeometryType 4.3.4.2.PointGeometryType 4.3.4.3.LinestringGeometryType 4.3.4.4.PolygonGeometryType 4.3.5.ExampleGeometryEncodings 4.3.5.1.ExamplePoint 4.3.5.2.ExampleMultiPoint 4.3.5.3.ExampleLinestring 4.3.5.4.ExampleMultiLinestring 4.3.5.5.ExamplePolygon 4.3.5.6.ExampleMultiPolygon 4.4.FeatureAttributes 4.5.Example 491lines(357sloc) 22.9KB Raw Blame OpenwithDesktop Viewraw Viewblame VectorTileSpecification Thekeywords"MUST","MUSTNOT","REQUIRED","SHALL","SHALLNOT", "SHOULD","SHOULDNOT","RECOMMENDED","MAY",and"OPTIONAL"in thisdocumentaretobeinterpretedasdescribedinRFC2119. 1.Purpose Thisdocumentspecifiesaspace-efficientencodingformatfortiledgeographicvectordata.Itisdesignedtobeusedinbrowsersorserver-sideapplicationsforfastrenderingorlookupsoffeaturedata. 2.FileFormat TheVectorTileformatusesGoogleProtocolBuffersasaencodingformat.ProtocolBuffersarealanguage-neutral,platform-neutralextensiblemechanismforserializingstructureddata. 2.1.FileExtension ThefilenameextensionforVectorTilefilesSHOULDbemvt.Forexample,afilemightbenamedvector.mvt. 2.2.MultipurposeInternetMailExtensions(MIME) WhenservingVectorTilestheMIMEtypeSHOULDbeapplication/vnd.mapbox-vector-tile. 3.ProjectionandBounds AVectorTilerepresentsdatabasedonasquareextentwithinaprojection.AVectorTileSHOULDNOTcontaininformationaboutitsboundsandprojection.ThefileformatassumesthatthedecoderknowstheboundsandprojectionofaVectorTilebeforedecodingit. WebMercatoristheprojectionofreference,andtheGoogletileschemeisthetileextentconventionofreference.Together,theyprovidea1-to-1relationshipbetweenaspecificgeographicalarea,ataspecificlevelofdetail,andapathsuchashttps://example.com/17/65535/43602.mvt. VectorTilesMAYbeusedtorepresentdatawithanyprojectionandtileextentscheme. 4.InternalStructure ThisspecificationdescribesthestructureofdatawithinaVectorTile.ThereadershouldhaveanunderstandingoftheVectorTileprotobufschemadocumentandthestructuresitdefines. 4.1.Layers AVectorTileconsistsofasetofnamedlayers.Alayercontainsgeometricfeaturesandtheirmetadata.Thelayerformatisdesignedsothatthedatarequiredforalayeriscontiguousinmemory,andsothatlayerscanbeappendedtoaVectorTilewithoutmodifyingexistingdata. AVectorTileSHOULDcontainatleastonelayer.AlayerSHOULDcontainatleastonefeature. AlayerMUSTcontainaversionfieldwiththemajorversionnumberoftheVectorTilespecificationtowhichthelayeradheres.Forexample,alayeradheringtoversion2.1ofthespecificationcontainsaversionfieldwiththeintegervalue2.TheversionfieldSHOULDbethefirstfieldwithinthelayer.DecodersSHOULDparsetheversionfirsttoensurethattheyarecapableofdecodingeachlayer.WhenaVectorTileconsumerencountersaVectorTilelayerwithanunknownversion,itMAYmakeabest-effortattempttointerpretthelayer,oritMAYskipthelayer.IneithercaseitSHOULDcontinuetoprocesssubsequentlayersintheVectorTile. AlayerMUSTcontainanamefield.AVectorTileMUSTNOTcontaintwoormorelayerswhosenamevaluesarebyte-for-byteidentical.PriortoappendingalayertoanexistingVectorTile,anencoderMUSTchecktheexistingnamefieldsinordertopreventduplication. Eachfeatureinalayer(seebelow)mayhaveoneormorekey-valuepairsasitsmetadata.Thekeysandvaluesareindicesintotwolists,keysandvalues,thataresharedacrossthelayer'sfeatures. Eachelementinthekeysfieldofthelayerisastring.Thekeysincludeallthekeysoffeaturesusedinthelayer,andeachkeymaybereferencedbyitspositionalindexinthissetofkeys,withthefirstkeyhavinganindexof0.ThesetofkeysSHOULDNOTcontaintwoormorevalueswhicharebyte-for-byteidentical. Eachelementinthevaluesfieldofthelayerencodesavalueofanyofseveraltypes(seebelow).Thevaluesrepresentallthevaluesoffeaturesusedinthelayer,andeachvaluemaybereferencedbyitspositionalindexinthissetofvalues,withthefirstvaluehavinganindexof0.ThesetofvaluesSHOULDNOTcontaintwoormorevaluesofthesametypewhicharebyte-for-byteidentical. Inordertosupportvaluesofvaryingstring,boolean,integer,andfloatingpointtypes,theprotobufencodingofthevaluefieldconsistsofasetofoptionalfields.AvalueMUSTcontainexactlyoneoftheseoptionalfields. AlayerMUSTcontainanextentthatdescribesthewidthandheightofthetileinintegercoordinates.ThegeometrieswithintheVectorTileMAYextendpasttheboundsofthetile'sareaasdefinedbytheextent.Geometriesthatextendpastthetile'sareaasdefinedbyextentareoftenusedasabufferforrenderingfeaturesthatoverlapmultipleadjacenttiles. Forexample,ifatilehasanextentof4096,coordinateunitswithinthetilereferto1/4096thofitssquaredimensions.Acoordinateof0isonthetoporleftedgeofthetile,andacoordinateof4096isonthebottomorrightedge.Coordinatesfrom1through4095inclusivearefullywithintheextentofthetile,andcoordinateslessthan0orgreaterthan4096arefullyoutsidetheextentofthetile.Apointat(1,10)or(4095,10)iswithintheextentofthetile.Apointat(0,10)or(4096,10)isontheedgeoftheextent.Apointat(-1,10)or(4097,10)isoutsidetheextentofthetile. 4.2.Features AfeatureMUSTcontainageometryfield. AfeatureMUSTcontainatypefieldasdescribedintheGeometryTypessection. AfeatureMAYcontainatagsfield.Feature-levelmetadata,ifany,SHOULDbestoredinthetagsfield. AfeatureMAYcontainanidfield.Ifafeaturehasanidfield,thevalueoftheidSHOULDbeuniqueamongthefeaturesoftheparentlayer. 4.3.GeometryEncoding GeometrydatainaVectorTileisdefinedinascreencoordinatesystem.Theupperleftcornerofthetile(asdisplayedbydefault)istheoriginofthecoordinatesystem.TheXaxisispositivetotheright,andtheYaxisispositivedownward.CoordinateswithinageometryMUSTbeintegers. Ageometryisencodedasasequenceof32bitunsignedintegersinthegeometryfieldofafeature.EachintegeriseitheraCommandIntegeroraParameterInteger.Adecoderinterpretstheseasanorderedseriesofoperationstogeneratethegeometry. Commandsrefertopositionsrelativetoa"cursor",whichisaredefinablepoint.Forthefirstcommandinafeature,thecursorisat(0,0)inthecoordinatesystem.Somecommandsmovethecursor,affectingsubsequentcommands. 4.3.1.CommandIntegers ACommandIntegerindicatesacommandtobeexecuted,asacommandID,andthenumberoftimesthatthecommandwillbeexecuted,asacommandcount. AcommandIDisencodedasanunsignedintegerintheleastsignificant3bitsoftheCommandInteger,andisintherange0through7,inclusive.Acommandcountisencodedasanunsignedintegerintheremaining29bitsofaCommandInteger,andisintherange0throughpow(2,29)-1,inclusive. AcommandID,acommandcount,andaCommandIntegerarerelatedbythesebitwiseoperations: CommandInteger=(id&0x7)|(count<<3) id=CommandInteger&0x7 count=CommandInteger>>3 AcommandIDspecifiesoneofthefollowingcommands: Command Id Parameters ParameterCount MoveTo 1 dX,dY 2 LineTo 2 dX,dY 2 ClosePath 7 Noparameters 0 ExampleCommandIntegers Command ID Count CommandInteger BinaryRepresentation[Count][Id] MoveTo 1 1 9 [00000000000000000000000000001][001] MoveTo 1 120 961 [00000000000000000000001111000][001] LineTo 2 1 10 [00000000000000000000000000001][010] LineTo 2 3 26 [00000000000000000000000000011][010] ClosePath 7 1 15 [00000000000000000000000000001][111] 4.3.2.ParameterIntegers CommandsrequiringparametersarefollowedbyaParameterIntegerforeachparameterrequiredbythatcommand.ThenumberofParameterIntegersthatfollowaCommandIntegerisequaltotheparametercountofacommandmultipliedbythecommandcountoftheCommandInteger.Forexample,aCommandIntegerwithaMoveTocommandwithacommandcountof3willbefollowedby6ParameterIntegers. AParameterIntegeriszigzagencodedsothatsmallnegativeandpositivevaluesarebothencodedassmallintegers.ToencodeaparametervaluetoaParameterIntegerthefollowingformulaisused: ParameterInteger=(value<<1)^(value>>31) Parametervaluesgreaterthanpow(2,31)-1orlessthan-1*(pow(2,31)-1)arenotsupported. ThefollowingformulaisusedtodecodeaParameterIntegertoavalue: value=((ParameterInteger>>1)^(-(ParameterInteger&1))) 4.3.3.CommandTypes Foralldescriptionsofcommandstheinitialpositionofthecursorshallbedescribedtobeatthecoordinates(cX,cY)wherecXisthepositionofthecursorontheXaxisandcYisthepositionofthecursorontheYaxis. 4.3.3.1.MoveToCommand AMoveTocommandwithacommandcountofnMUSTbeimmediatelyfollowedbynpairsofParameterIntegers.Eachpair(dX,dY): Definesthecoordinate(pX,pY),wherepX=cX+dXandpY=cY+dY. WithinPOINTgeometries,thiscoordinatedefinesanewpoint. WithinLINESTRINGgeometries,thiscoordinatedefinesthestartingvertexofanewline. WithinPOLYGONgeometries,thiscoordinatedefinesthestartingvertexofanewlinearring. Movesthecursorto(pX,pY). 4.3.3.2.LineToCommand ALineTocommandwithacommandcountofnMUSTbeimmediatelyfollowedbynpairsofParameterIntegers.Eachpair(dX,dY): Definesasegmentbeginningatthecursor(cX,cY)andendingatthecoordinate(pX,pY),wherepX=cX+dXandpY=cY+dY. WithinLINESTRINGgeometries,thissegmentextendsthecurrentline. WithinPOLYGONgeometries,thissegmentextendsthecurrentlinearring. Movesthecursorto(pX,pY). Foranypairof(dX,dY)thedXanddYMUSTNOTbothbe0. 4.3.3.3.ClosePathCommand AClosePathcommandMUSThaveacommandcountof1andnoparameters.ThecommandclosesthecurrentlinearringofaPOLYGONgeometryviaalinesegmentbeginningatthecursor(cX,cY)andendingatthestartingvertexofthecurrentlinearring. Thiscommanddoesnotchangethecursorposition. 4.3.4.GeometryTypes ThegeometryfieldisdescribedineachfeaturebythetypefieldwhichmustbeavalueintheenumGeomType.Thefollowinggeometrytypesaresupported: UNKNOWN POINT LINESTRING POLYGON Geometrycollectionsarenotsupported. 4.3.4.1.UnknownGeometryType Thespecificationpurposefullyleavesanunknowngeometrytypeasanoption.ThisgeometrytypeencodesexperimentalgeometrytypesthatanencoderMAYchoosetoimplement.DecodersMAYignoreanyfeaturesofthisgeometrytype. 4.3.4.2.PointGeometryType ThePOINTgeometrytypeencodesapointormultipointgeometry.ThegeometrycommandsequenceforapointgeometryMUSTconsistofasingleMoveTocommandwithacommandcountgreaterthan0. IftheMoveTocommandforaPOINTgeometryhasacommandcountof1,thenthegeometryMUSTbeinterpretedasasinglepoint;otherwisethegeometryMUSTbeinterpretedasamultipointgeometry,whereineachpairofParameterIntegersencodesasinglepoint. 4.3.4.3.LinestringGeometryType TheLINESTRINGgeometrytypeencodesalinestringormultilinestringgeometry.ThegeometrycommandsequenceforalinestringgeometryMUSTconsistofoneormorerepetitionsofthefollowingsequence: AMoveTocommandwithacommandcountof1 ALineTocommandwithacommandcountgreaterthan0 IfthecommandsequenceforaLINESTRINGgeometrytypeincludesonlyasingleMoveTocommandthenthegeometryMUSTbeinterpretedasasinglelinestring;otherwisethegeometryMUSTbeinterpretedasamultilinestringgeometry,whereineachMoveTosignalsthebeginningofanewlinestring. 4.3.4.4.PolygonGeometryType ThePOLYGONgeometrytypeencodesapolygonormultipolygongeometry,eachpolygonconsistingofexactlyoneexteriorringthatcontainszeroormoreinteriorrings.Thegeometrycommandsequenceforapolygonconsistsofoneormorerepetitionsofthefollowingsequence: AnExteriorRing ZeroormoreInteriorRings EachExteriorRingandInteriorRingMUSTconsistofthefollowingsequence: AMoveTocommandwithacommandcountof1 ALineTocommandwithacommandcountgreaterthan1 AClosePathcommand AnexteriorringisDEFINEDasalinearringhavingapositiveareaascalculatedbyapplyingthesurveyor'sformulatotheverticesofthepolygonintilecoordinates.Inthetilecoordinatesystem(withtheYaxispositivedownandXaxispositivetotheright)thismakestheexteriorring'swindingorderappearclockwise. AninteriorringisDEFINEDasalinearringhavinganegativeareaascalculatedbyapplyingthesurveyor'sformulatotheverticesofthepolygonintilecoordinates.Inthetilecoordinatesystem(withtheYaxispositivedownandXaxispositivetotheright)thismakestheinteriorring'swindingorderappearcounterclockwise. IfthecommandsequenceforaPOLYGONgeometrytypeincludesonlyasingleexteriorringthenthegeometryMUSTbeinterpretedasasinglepolygon;otherwisethegeometryMUSTbeinterpretedasamultipolygongeometry,whereineachexteriorringsignalsthebeginningofanewpolygon.IfapolygonhasinteriorringstheyMUSTbeencodeddirectlyaftertheexteriorringofthepolygontowhichtheybelong. LinearringsMUSTbegeometricobjectsthathavenoanomalousgeometricpoints,suchasself-intersectionorself-tangency.ThepositionofthecursorbeforecallingtheClosePathcommandofalinearringSHALLNOTrepeatthesamepositionasthefirstpointinthelinearringasthiswouldcreateazero-lengthlinesegment.AlinearringSHOULDNOThaveanareacalculatedbythesurveyor'sformulaequaltozero,asthiswouldsignifyaringwithanomalousgeometricpoints. PolygongeometriesMUSTNOThaveanyinteriorringsthatintersectandinteriorringsMUSTbeenclosedbytheexteriorring. 4.3.5.ExampleGeometryEncodings 4.3.5.1.ExamplePoint Anexampleencodingofapointlocatedat: (25,17) Thiswouldrequireasinglecommand: MoveTo(+25,+17) Encodedas:[95034] ||`>Decoded:((34>>1)^(-(34&1)))=+17 |`>Decoded:((50>>1)^(-(50&1)))=+25 |=====relativeMoveTo(+25,+17)==createpoint(25,17) `>[00001001]=commandid1(MoveTo),commandcount1 4.3.5.2.ExampleMultiPoint Anexampleencodingoftwopointslocatedat: (5,7) (3,2) Thiswouldrequiretwocommands: MoveTo(+5,+7) MoveTo(-2,-5) Encodedas:[17101439] ||||`>Decoded:((9>>1)^(-(9&1)))=-5 |||`>Decoded:((3>>1)^(-(3&1)))=-2 |||===relativeMoveTo(-2,-5)==createpoint(3,2) ||`>Decoded:((34>>1)^(-(34&1)))=+7 |`>Decoded:((50>>1)^(-(50&1)))=+5 |=====relativeMoveTo(+5,+7)==createpoint(5,7) `>[00010001]=commandid1(MoveTo),commandcount2 4.3.5.3.ExampleLinestring Anexampleencodingofalinewiththepoints: (2,2) (2,10) (10,10) Thiswouldrequirethreecommands: MoveTo(+2,+2) LineTo(+0,+8) LineTo(+8,+0) Encodedas:[94418016160] ||====relativeLineTo(+8,+0)==LinetoPoint(10,10) ||====relativeLineTo(+0,+8)==LinetoPoint(2,10) |`>[00010010]=commandid2(LineTo),commandcount2 |===relativeMoveTo(+2,+2) `>[00001001]=commandid1(MoveTo),commandcount1 4.3.5.4.ExampleMultiLinestring Anexampleencodingoftwolineswiththepoints: Line1: (2,2) (2,10) (10,10) Line2: (1,1) (3,5) Thiswouldrequirethefollowingcommands: MoveTo(+2,+2) LineTo(+0,+8) LineTo(+8,+0) MoveTo(-9,-9) LineTo(+2,+4) Encodedas:[94418016160917171048] ||||===relativeLineTo(+2,+4)==LinetoPoint(3,5) |||`>[00001010]=commandid2(LineTo),commandcount1 |||=====relativeMoveTo(-9,-9)==Startnewlineat(1,1) ||`>[00001001]=commandid1(MoveTo),commandcount1 ||====relativeLineTo(+8,+0)==LinetoPoint(10,10) ||====relativeLineTo(+0,+8)==LinetoPoint(2,10) |`>[00010010]=commandid2(LineTo),commandcount2 |===relativeMoveTo(+2,+2) `>[00001001]=commandid1(MoveTo),commandcount1 4.3.5.5.ExamplePolygon Anexampleencodingofapolygonfeaturethathasthepoints: (3,6) (8,12) (20,34) (3,6)PathClosingasLastPoint Wouldencodedbyusingthefollowingcommands: MoveTo(3,6) LineTo(5,6) LineTo(12,22) ClosePath Encodedas:[9612181012244415] ||`>[00001111]commandid7(ClosePath),commandcount1 ||=====relativeLineTo(+12,+22)==LinetoPoint(20,34) ||=====relativeLineTo(+5,+6)==LinetoPoint(8,12) |`>[00010010]=commandid2(LineTo),commandcount2 |====relativeMoveTo(+3,+6) `>[00001001]=commandid1(MoveTo),commandcount1 4.3.5.6.ExampleMultiPolygon Anexampleofamorecomplexencodingoftwopolygons,onewithahole.Thepositionofthepointsforthepolygonsareshownbelow.ThewindingorderofthepolygonsisVERYimportantinthisexampleasitsignifiesthedifferencebetweeninteriorringsandanewpolygon. Polygon1: ExteriorRing: (0,0) (10,0) (10,10) (0,10) (0,0)PathClosingasLastPoint Polygon2: ExteriorRing: (11,11) (20,11) (20,20) (11,20) (11,11)PathClosingasLastPoint InteriorRing: (13,13) (13,17) (17,17) (17,13) (13,13)PathClosingasLastPoint Thispolygonwouldbeencodedwiththefollowingsetofcommands: MoveTo(+0,+0) LineTo(+10,+0) LineTo(+0,+10) LineTo(-10,+0)//Cursorat0,10afterthiscommand ClosePath//EndofPolygon1 MoveTo(+11,+1)//NOTETHATTHISISRELATIVETOLASTLINETO! LineTo(+9,+0) LineTo(+0,+9) LineTo(-9,+0)//Cursorat11,20afterthiscommand ClosePath//Thisisanewpolygonbecauseareaispositive! MoveTo(+2,-7)//NOTETHATTHISISRELATIVETOLASTLINETO! LineTo(+0,+4) LineTo(+4,+0) LineTo(+0,-4)//Cursorat17,13 ClosePath//Thisisaninteriorringbecauseareaisnegative! Encodedas:[90026200020190159222261800181701594132608800715] ||||||||`>[00001111](ClosePath) |||||||`>[00011010]=(LineTo),commandcount3 ||||||`>[00001001]=commandid1(MoveTo),commandcount1 |||||`>[00001111](ClosePath) ||||`>[00011010]=(LineTo),commandcount3 |||`>[00001001]=commandid1(MoveTo),commandcount1 ||`>[00001111](ClosePath) |`>[00011010]=(LineTo),commandcount3 `>[00001001]=commandid1(MoveTo),commandcount1 4.4.FeatureAttributes Featureattributesareencodedaspairsofintegersinthetagfieldofafeature.Thefirstintegerineachpairrepresentsthezero-basedindexofthekeyinthekeyssetofthelayertowhichthefeaturebelongs.Thesecondintegerineachpairrepresentsthezero-basedindexofthevalueinthevaluessetofthelayertowhichthefeaturebelongs.EverykeyindexMUSTbeuniquewithinthatfeaturesuchthatnootherattributepairwithinthatfeaturehasthesamekeyindex.AfeatureMUSThaveanevennumberoftagfields.AfeaturetagfieldMUSTNOTcontainakeyindexorvalueindexgreaterthanorequaltothenumberofelementsinthelayer'skeysorvaluesset,respectively. 4.5.Example Forexample,aGeoJSONfeaturelike: { "type":"FeatureCollection", "features":[ { "geometry":{ "type":"Point", "coordinates":[ -8247861.1000836585, 4970241.327215323 ] }, "type":"Feature", "properties":{ "hello":"world", "h":"world", "count":1.23 } }, { "geometry":{ "type":"Point", "coordinates":[ -8247861.1000836585, 4970241.327215323 ] }, "type":"Feature", "properties":{ "hello":"again", "count":2 } } ] } Couldbestructuredlike: layers{ version:2 name:"points" features:{ id:1 tags:0 tags:0 tags:1 tags:0 tags:2 tags:1 type:Point geometry:9 geometry:2410 geometry:3080 } features{ id:2 tags:0 tags:2 tags:2 tags:3 type:Point geometry:9 geometry:2410 geometry:3080 } 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 } Keepinmindtheexactvaluesforthegeometrywoulddifferbasedontheprojectionandextentofthetile. Go Youcan’tperformthatactionatthistime. Yousignedinwithanothertaborwindow.Reloadtorefreshyoursession. Yousignedoutinanothertaborwindow.Reloadtorefreshyoursession.