| Copyright | (c) Azavea, 2016 |
|---|---|
| License | Apache 2 |
| Maintainer | Colin Woodbury <cwoodbury@azavea.com> |
| Safe Haskell | None |
| Language | Haskell2010 |
Geography.VectorTile.Protobuf
Contents
Description
Raw Vector Tile data is stored as binary protobuf data. This module reads and writes raw protobuf ByteStrings between a data type which closely matches the current Mapbox vector tile spec defined here: https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto
As this raw version of the data is hard to work with, in practice we convert
to a more canonical Haskell type for further processing.
See VectorTile for the user-friendly version.
Please import this module qualified to avoid namespace clashes:
import qualified Geography.VectorTile.Protobuf as PB
- data RawVectorTile = RawVectorTile {}
- data RawLayer = RawLayer {}
- data RawVal = RawVal {}
- data RawFeature = RawFeature {}
- data GeomType
- = Unknown
- | Point
- | LineString
- | Polygon
- class ProtobufGeom g where
- data Command
- commands :: [Word32] -> Either Text [Command]
- uncommands :: [Command] -> [Word32]
- zig :: Int -> Word32
- unzig :: Word32 -> Int
- tile :: RawVectorTile -> Either Text VectorTile
- layer :: RawLayer -> Either Text Layer
- features :: [Text] -> [RawVal] -> [RawFeature] -> Either Text (Vector (Feature Point), Vector (Feature LineString), Vector (Feature Polygon))
- value :: RawVal -> Either Text Val
- untile :: VectorTile -> RawVectorTile
- unlayer :: Layer -> RawLayer
- unfeature :: ProtobufGeom g => [Text] -> [Val] -> Feature g -> RawFeature
- unval :: Val -> RawVal
- decode :: ByteString -> Either Text RawVectorTile
- encode :: RawVectorTile -> ByteString
- decodeIO :: FilePath -> IO (Either Text RawVectorTile)
- encodeIO :: RawVectorTile -> FilePath -> IO ()
Types
Contains a pseudo-map of metadata, to be shared across all RawFeatures
of this RawLayer.
Constructors
| RawLayer | |
The Value types of metadata fields.
Constructors
| RawVal | |
The four potential Geometry types. The spec allows for encoders to set
Unknown as the type, but our decoder ignores these.
Constructors
| Unknown | |
| Point | |
| LineString | |
| Polygon |
class ProtobufGeom g where Source #
Any classical type considered a GIS "geometry". These must be able
to convert between an encodable list of Commands.
Minimal complete definition
Methods
fromCommands :: [Command] -> Either Text (Vector g) Source #
toCommands :: Vector g -> [Command] Source #
Instances
| ProtobufGeom Polygon Source # | A valid An Exterior Ring, followed by 0 or more Interior Rings. Any Ring must have a Performs no sanity checks for malformed Interior Rings. |
| ProtobufGeom LineString Source # | A valid A |
| ProtobufGeom Point Source # | A valid |
Commands
The possible commands, and the values they hold.
commands :: [Word32] -> Either Text [Command] Source #
Attempt to parse a list of Command/Parameter integers, as defined here:
https://github.com/mapbox/vector-tile-spec/tree/master/2.1#43-geometry-encoding
uncommands :: [Command] -> [Word32] Source #
Convert a list of parsed Commands back into their original Command
and Z-encoded Parameter integer forms.
Z-Encoding
Protobuf Conversions
From Protobuf
Generally the tile function is the only one needed here. Usage:
import qualified Geography.VectorTile.Protobuf as PB PB.decode someBytes >>= PB.tile
Note that since the Data.ProtocolBuffers library does not handle default values, we handle those specifically defined in vector_tile.proto explicitely here. See:
https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto
tile :: RawVectorTile -> Either Text VectorTile Source #
Convert a RawVectorTile of parsed protobuf data into a useable
VectorTile.
layer :: RawLayer -> Either Text Layer Source #
Convert a single RawLayer of parsed protobuf data into a useable
Layer.
features :: [Text] -> [RawVal] -> [RawFeature] -> Either Text (Vector (Feature Point), Vector (Feature LineString), Vector (Feature Polygon)) Source #
Convert a list of RawFeatures of parsed protobuf data into Vectors
of each of the three legal ProtobufGeom types.
The long type signature is due to two things:
Features are polymorphic at the high level, but not at the parsed protobuf mid-level. In a[RawFeature], there are features of points, linestrings, and polygons all mixed together.RawLayers andRawFeatures are strongly coupled at the protobuf level. In order to achieve higher compression ratios,RawLayers contain all metadata in key/value lists to be shared across theirRawFeatures, while thoseRawFeatures store only indices into those lists. As a result, this function needs to be passed those key/value lists from the parentRawLayer, and a more isomorphic:
feature :: ProtobufGeom g => RawFeature -> Either Text (Feature g)
is not possible.
value :: RawVal -> Either Text Val Source #
Convert a RawVal parsed from protobuf data into a useable
Val. The higher-level Val type better expresses the mutual exclusivity
of the Value types.
To Protobuf
To convert from high-level data back into a form that can be encoded into raw protobuf bytes, use:
import qualified Geography.VectorTile.Protobuf as PB PB.encode $ PB.untile someTile
This is a pure process and will succeed every time.
untile :: VectorTile -> RawVectorTile Source #
Encode a high-level VectorTile back into its mid-level
RawVectorTile form.
unlayer :: Layer -> RawLayer Source #
Encode a high-level Layer back into its mid-level RawLayer form.
unfeature :: ProtobufGeom g => [Text] -> [Val] -> Feature g -> RawFeature Source #
Encode a high-level Feature back into its mid-level RawFeature form.
ByteString Encoding / Decoding
decode :: ByteString -> Either Text RawVectorTile Source #
Attempt to decode a ByteString of raw protobuf data into a mid-level
representation of a RawVectorTile.
encode :: RawVectorTile -> ByteString Source #
Encode a mid-level representation of a RawVectorTile into raw protobuf data.
decodeIO :: FilePath -> IO (Either Text RawVectorTile) Source #
Given a filename, attempt to decode bytes read from that file.
encodeIO :: RawVectorTile -> FilePath -> IO () Source #
Write a mid-level representation of a RawVectorTile to a file as raw
protobuf data.