Skip to content

VTS Geodata Format

David Levinsky edited this page Apr 12, 2019 · 51 revisions

VTS Geodata Format

Geo data file format

This file format is used to describe geographic features. This file only specifies geo data features and groups, but does not specifies which features will be rendered and how they will be renderer. Which features will be rendered is defined in separate geo layer style sheet file.

For geo data files will be used JSON file format.

Example of geo data file format

{
    "version": 1,
    "groups": [{
        "bbox": [
            [471662.7, 5555582.6, 225],
            [472440.8, 5555892.9, 241]
        ],
        "resolution": 4096,
        "points": [{
            "points": [
                [612, 140, 6]
            ],

            "properties": {
                "kind": "restaurant",
                "name": "U Bílého Lva"
            }   
        }],

        "lines": [{
            "d-lines" : [[
                [612, 140, 6],
                [20, 10, 0],
                [12, 7, 1]
            ]],

            "properties": {
                "kind": "road",
                "name": "Na Bělidle"
            }   
        }]

        "polygons": [{
            "vertices": [
                612, 140, 6,
                20, 10, 0,
                120, 70, 1
            ]
            "surface": [
                0, 1, 2
            ],
            "borders": [
                [0, 1, 2]
            ],
            "middle" : [220, 40, 0]

            "properties": {
                "kind": "filed",
                "name": "Šafářovo Pole"
            }   

        }]

    }]
}

Example of empty tile

{
    "version": 1,
    "groups": []
}

Coordinates

The coordinates are in physical SRS and are encoded in normalized form as unsigned integers. Each dimension of the group bounding box is thus divided into n positions (n is defined by resolution). Each vertex is rounded to the nearest discrete position within the bounding box.

Auxiliary structures

Vec3 = [double, double, double]  # array of three doubles
Vec3ui = [uint, uint, uint]  # array of three uints
Vec3iz = [int, int, int]  # array of three integers encoded in zig zag format
RGB = [uint8, uint8, uint8]  # array of three uints
BBox = [Vec3, Vec3]         # two points representing minimum and maximum extends
                              of bounding box 

Root structure

{
    version : uint          # file format version
    groups : [Group]        # array of groups containing geo features
}

Group structure

Group = {
    bbox : BBox             # bounding box enclosing all elements
                              in group
    resolution : Number,    # set resolution of the coordinates,
                              which is number of units per bbox
                              dimension (default=4096)
    id : string             # optional: id of group
    points : [PointArray]   # optional: array of PointArrays
    lines : [LineString]    # optional: array of LineStrings
    polygons : [Polygons]   # optional: array of Polygons
}

PointArray structure

PointArray = {
    id : string             # optional: id is needed for switching
                              feature states like hover-style, ...

    points : [Vec3ui]       # optional: array of points 
    d-points : [Vec3iz]     # optional: compressed alternative
                              to points, each array member
                              stores delta values to previous
                              member
                                         
    properties: {}          # custom properties can be added
}

LineString structure

LineString = {
    id : string             # optional: id is needed for switching
                              feature states like hover-style, ...

    lines : [[Vec3ui]]      # optional: array of lines where line is
                              defined as array of points
    d-lines : [[Vec3iz]]    # optional: compressed alternative
                              to lines, array of lines where line is
                              defined as array of points, where
                              each array member stores delta values
                              to previous member

    properties: {}          # custom properties can be added
}

Polygons structure

Polygons = {
    id : string             # optional: id is needed for switching
                              feature states like hover-style, ...

    vertices : [uint]       # array of vertex coordinates, where
                              coordinates are represented as
                              uint x, uint y, unit z 
    surface : [uint]        # array of face indices, where face
                              is defined as: uint vertexIndex1,
                              uint vertexIndex2, uint vertexIndex3
    borders : [[uint]]      # array of line strings, where line
                              string is defined as array of vertex
                              indices

    middle : [Vec3ui]       # optional: center of the face, which can be
                              used for placing label

    properties: {}          # custom properties can be added
}

Geo layer styles structure

The geo data can by visualized by render layers. Each render layer specifies which features in which group will by rendered. Feature selection is provided by filter conditions and group conditions. The render layer are defined by geo later style sheets which are stored in JSON file format.

Example of geo layer styles structure

{
    "constants" : {
       "@road-width" : { "lod-scaled": [10, 3] },
       "@wide-road-width" : { "lod-scaled": [10, 4] },
       "@road-color" : [255,124,10,255],
       "@road-visible" : { "discrete": [[4, false], [5, true]] },
       "@black" : [0,0,0,255],
       "@icon-restaurant" : ["icons", 0, 0, 24, 24]
    },

    "fonts": {
      "noto-basic": "https://cdn.melown.com/libs/vtsjs/fonts/noto-basic/1.0.0/noto.fnt"
    },

    "bitmaps" : {
       "icons" : "http://mapserver.mapy.cz/img/map-icons.png"
    },

    "layers" : {
        "roads" : {
            "filter" : ["==", "$kind", "road"],
            "line-width" : "@road-width",
            "line-color" : "@road-color",
            "line-flat" : true,
            "visible" : "@road-visible",
        },
        "wide-roads" : {
            "filter" : ["==", "$kind", "highway"],
            "inherit" : "roads-border-only",
            "line-width" : "@wide-road-width"
        },
        "roads-with-border" : {
            "filter" : ["skip"],
            "inherit" : "roads",
            "next-pass" : [[0,"roads-border-only"]]
        },
        "roads-border-only" : {
            "filter" : ["skip"],
            "inherit" : "wide-roads",
            "line-color" : "@black"
        },
        "restaurant" : {
            "filter" : ["==", "$kind", "restaurant"],
            "icon" : true,
            "icon-source" : "@icon-restaurant",
            "label" : true,
            "label-font" : ["noto-basic"]
        }
    }
}

Root structure

{
    constants : {}
    fonts : {}
    bitmaps : {}
    layers : {}
}

Constants

The constants define values which can be used across all styles. The constants have following form:

    constants : {
       @key : value
       ...
    }

Fonts

This structure defines fonts which can be used across all styles in labels. The fonts have following form:

    fonts : {
       @fontId: url
       ...
    }

Bitmaps

This structure defines bitmaps which can be used across all styles as icons. The bitmaps have following form:

    bitmaps : {
       @bitmapId: url
       ...
    }

Layers

This structure defines render layers. The layers have following form:

    layers : {
       @layerId: Layer
       ...
    }

Auxiliary structures

Vec2 = [double x, double y]  # array of two doubles
RGBA = [uint8 r, uint8 g, uint8 b, uint8 a]  # array of four uints
Icon = [string bitmapId,         # id of bitmap stored in bitmaps structure
        uint left,               # coordinates of left top corner of icon
        uint top,                  in pixels
        uint width,              # size of icon in pixels
        uint height]  
LineTexture = [string bitmapId,  # id of bitmap stored in bitmaps structure
               uint top,         # vertical texture offset in pixels
               uint height]      # vertical texture size in pixels
RenderPass = [int zIndex, string layerId]
DepthOffset = [double globalFactor, double distanceFactor, double tiltFactor]
Stick = [double maxHeight, double minHeight, double width, uint8 red, uint8 green, uint8 blue, uint8 alpha]
Margin = [double horizontalMargin, double verticalMargin] # margin values are in pixels
LabelOutline = [double outlineThinness, double textThinness, double textBlurriness, double outlineBlurriness]

   # thinness values have range from 0 to 1.0,
     the label glyphs are represented by signed distance fields
     where value 0 represents most outer contour of the glyph,
     value 1.0 represents most inner contour of the glyph.

   # bluriness - reasonable range of values for blurriness is from 0 to 20
     where value 0 represents no blur applied
     value 20 represents maximum blur applied
   HysteresisParams = [uint timeToAppear, uint timeToDisappear, string uniqueId, bool fadeEnabled]

   # timeToAppear, timeToDisappear - time is in miliseconds

Classification structures

LineStyle = enum {               # enum value represented by string
    solid,
    textured
}
Units = enum {               # enum value represented by string
    pixels,
    meters,
    ratio
}
PointStyle = enum {              # enum value represented by string
    solid
}
TextAlign = enum {               # enum value represented by string
    left,
    right,
    center
}
Origin = enum {               # enum value represented by string
    top-left,
    top-right,
    top-center,
    center-left,
    center-right,
    center-center,
    bottom-left,
    bottom-right,
    bottom-center
}

Layers structure

All layers properties are optional. If property is not defined then default value is assigned.

Layer = {
   filter : FilterCondition          # see section about filters conditions
                                       (default = null)
   inherit : string                  # id of style from which will be properties
                                       inherited (default = "")
   importance-source : double        # sets how much is feature important when
                                       is number of features reduced by 
                                       mapFeaturesReduceMode. See Browser
                                       documentation. Supported value range is
                                       0 - 100. Scale is interpreted as 
                                       logarithmic. This feature works only when
                                       mapFeaturesReduceMode value is set to
                                       scr-count7. (default = null)
   importance-weight : double        # sets additional weight to importance-source
                                       value (default = 1)
   hysteresis: HysteresisParams      # set how fast feature apear or disapear to
                                       the map (default = null)

   line : bool                       # draw line feature (default = false)
   line-flat : bool                  # instead of having uniform pixel width the 
                                       line will be drawn as a flat line parallel 
                                       to the ellipsoid surface if set
                                       (default = false)
   line-width : double               # width of line in meters (flat line) or in
                                       pixels (default = 1)
   line-width-units : Units          # for line-flat == false are supported units 
                                        "pixels" and "ratio". The "ratio" means ratio 
                                         of screenHeight (default = "pixels") 
                                       for line-flat == true are supported units 
                                         "meters" and "ratio". The "ratio" means ratio
                                         of viewExtent (default = "meters") 
   line-style : LineStyle            # (default = "solid") 
   line-style-texture : LineTexture  # sets which texture will be used textured lines
   line-style-background : RGBA      # sets color for transparent parts of textured
                                     # lines (default = [0,0,0,0])
                                     # (default = null)
   line-color : RGBA                 # (default = [255,255,255,255])

   line-label : bool                 # draw line label, line labels can be used only
                                     for flat lines (default = false)
   line-label-font : [string]        # see label-font
   line-label-color : RGBA           # (default = [255,255,255,255])
   line-label-color2 : RGBA          # color of the text outline
                                       (default = [0,0,0,255])
   line-label-outline : LabelOutline # style of the text outline
                                       (default = [0.25,0.75,2.2,2.2])
   line-label-source : string        # name of feature property from which will be
                                       label text used (default = "$name")
   line-label-size : double          # font size in meters (default = 1)
   line-label-offset : double        # offset of label from center of line
                                       (default = 0)
   point : bool                      # draw point (default = false)
   point-flat : bool                 # sets whether point will have uniform shape or
                                       will have flat shape (default = false)
   point-radius: double              # radius of point in meters(flat point) or in
                                       pixels (default = 1)
   point-style: PointStyle           # (default = "solid") 
   point-color : RGBA                # (default = [255,255,255,255])

   icon : bool                       # draw icon (default = false)
   icon-source : Icon                # sets which icon will be drawn (default = null)
   icon-scale : double               # (default = 1)
   icon-offset : Vec2                # offset in pixels (default = [0,0])
   icon-origin : Origin              # (default = "bottom-center")
   icon-stick : Stick                # applies stick to the icon
                                       (default = null)

   label : bool                      # draw label (default = false)
   label-font : [string]             # array of the font Ids set which fonts will
                                       be used for the labels. Fonts array forms
                                       cascade. If the glyph is not found in the
                                       first font, the next font in the array is
                                       used. This way is searched whole array of
                                       the fonts until is font containing desired
                                       glyph found. (default = [#default])
   label-source : string             # name of feature property from which will be
                                       label text used (default = "$name")
   label-size : double               # font size in pixels (default = 10)
   label-color : RGBA                # (default = [0,0,0,255])
   label-color2 : RGBA               # color of the text outline
                                       (default = [0,0,0,255])
   label-outline : LabelOutline      # style of the text outline
                                       (default = [0.25,0.75,2.2,2.2])
   label-offset : Vec2               # offset in pixels (default = [0,0])
   label-origin : Origin             # (default = "bottom-center")
   label-align : TextAlign           # (default = "center")
   label-width : double              # sets width at which text will be wrapped
                                       (default = 200)
   label-stick : Stick               # applies stick to the label
                                       (default = null)
   label-no-overlap : bool           # prevents overlapping labels by hiding labels
                                       which are rendered later (default = true)
   label-no-overlap-margin : Margin  # sets margin around label
                                       (default = [5,5])

   polygon : bool                    # draw polygon (default = false)
   polygon-color : RGBA              # color of polygon surface

   z-index : int                     # sets render order, range from -255 to 255
                                       (default = 0)
   zbuffer-offset : DepthOffset      # sets zbuffer offset of rendered feature
                                       (default = [0,0,0])

   selected-layer : string           # sets which layer will be used when feature
                                       is selected (default = "")
   selected-hover-layer : string     # sets which layer will be used when feature
                                       is selected and hovered (default = "")
   enter-event : bool                # enables enter events (default = false)
   leave-event : bool                # enables leave events (default = false)
   hover-event : bool                # enables hover events (default = false)
   hover-layer : string              # enables change of layer when hover event
                                       occurs (default = "")
   click-event : bool                # enables click events (default = false)
   advanced-hit : bool               # when advanced hit is enabled then hover and
                                     # click events report which inner element of
                                     # the feature is interacted

   visible : bool                    # sets whether feature will be visible
                                       (default = true)
   visibility : double               # set from which distance will be feature
                                       visible. Null value means no visibility
                                       check. (default = null)
   visibility-abs : Vec2             # Sets local view extents value range [min,max]
                                       in which is feature visible. You can imagine
                                       local view extent as a distance from the camera
                                       in meters (default = null)
   visibility-rel : Vec4             # Sets view extents value range in which is
                                       feature visible. In this case you can imagine
                                       view extent as a value >= 0. Where 1 means that
                                       displayed feature is as large as screen (vertically).
                                       Size of the feature in the real world is defined
                                       by its radius (meters). Used form: [radius,
                                       radiusMultiplicator, minViewExtent, maxViewExtent]
                                       (default = null)
   culling : double                  # sets angle (between eye and feature ground normal)
                                       after which feature will not visible. For example 
                                       when features on the opposite side of the planet
                                       should not be visible use value 90. (default = 180)

   next-pass : [RenderPass]          # feature can be rendered multiple times with
                                       different layers. The z-index value in
                                       RenderPass structure overwrites z-index value
                                       in referred layer. (default = null)
}

Filters

The filters decides which feature will be rendered by style layer. Each style layer goes through all features and these features for which filter result positive are rendered with that style layer. Supported filter are:

["==", value1, value2]       # value1 == value2
["!=", value1, value2]       # value1 != value2
[">", value1, value2]       # value1 > value2
["<", value1, value2]       # value1 < value2
[">=", value1, value2]       # value1 >= value2
["<=", value1, value2]       # value1 <= value2

["has", property]               # property exists
["!has", property]              # property not exists

["in", property, value1, value2, .. ]    # property value is present in listed values
["!in", property, value1, value2, .. ]   # property value is not present in listed values

["all", filter1, filter2, ... ]     # all filters are positive
["any", filter1, filter2, ... ]     # any filter is positive
["none", filter1, filter2, ... ]    # none of filters is positive

If layer is rendered by multi-pass mechanism then layer filter is ignored. There is special filter value ["skip"], which designates that layer will be only processed in mutipass render or in case that layer is referred by hover or click event.

Filters can access special system properties:

  • #id contains name of the feature
  • #group contains name of group in which is rendered feature stored
  • #type identifies feature type. Possible values are "point", "line", "polygon"
  • #tileSize size of the tile (usually in meters)
  • #lod the LOD of the tile
  • #language returns user language
  • #dpr device pixel ratio (where 1 equals to 96 dpi)

Style property values

Style property values can be assigned directly:

    "property" : 123

or can use constant:

    "property" : "@name-of-constant"

or can use property of PointArray or LineString object:

    "property" : "$name-of-property"

or can use local variable (read more):

    "property" : "&name-of-local-variable"

or can use function.

String values can be composed from several sources

You can include properties, constants or function values (see more about functions below) into the string.

Example:
"property" : "Value of kind property is: {$kind}" 
Example of included function values:
"property" : "Absolute value of temperature property is: {{"abs" : "$temperature"}}" 

Local variables

You can declare these variables similar way as you set layer properties values. Local variables have to start with ampersand character. Main advantage is that you can declare variable inside layer definition and reuse computed value as many times as you want. Local variables exist only inside layer in which they were declared.

SomeLayer : {
   "&ColorAsLocalVariable" : [255,0,0,255],
   "label": true,
   "label-color": "&ColorAsLocalVariable",
   "line": true,
   "line-color": "&ColorAsLocalVariable"
}

Functions

Math functions with one parameter:

Supported function are: 'sgn', 'sin', 'cos', 'tan', 'asin', 'acos', 'atan', 'sqrt', 'abs', 'deg2rad', 'rad2deg'

Example:
"property" : { "abs" : "$someProperty" }  

Math functions with two parameters:

Supported function are: 'add', 'sub', 'mul', 'div', 'pow', 'atan2'

Example:
"property" : { "add" : ["$someProperty", "@someConstant"] }  

Min, Max functions:

Sets minimum or maximum value from provided array.

"property" : { "min" : [value1, value2, ...] }

Example:
"property" : { "min" : [20, "$someProperty", "$someProperty2"] }  

Conditional functions:

Sets property value based on result of condition. The condition expression has same syntax as filters.

"property" : { "if" : [condition, valueWhenTrue, valueWhenFalse] }

Example:
"property" : { "if" : [["has", "$someProperty"], true, false] }  

String functions:

Supported functions are: 'strlen' - length of the string, 'str2num' - converts string to the number, 'lowercase', 'uppercase', 'capitalize', 'has-fonts' - returns whether the font array contain all glyphs for the string, 'has-latin' - returns whether string contains some Latin characters, 'is-cjk' - returns whether string contain only CJK (Chinese, Japanese, Korean) characters, 'trim' - removes white chars at the beginning and end of the string

Example:
"property" : { "lowercase" : "$someProperty" }  

Discrete2 function:

Finds closest key <= property value and returns value from corresponding to [key,value] pair. property values outside key range are mapped to value corresponding to the closest key. [key,value] pairs must be sorted by key in ascending order. Value of property must be numeric, values from [key, value] pairs may be numeric, boolean or color.

"property" : { "discrete2" : [property, [[key, value],...]] }

Examples:
"property" : { "discrete2" : ["$population",  [[1000, 20], [2000, 30]]] }  

"property" : { "discrete2" : ["@road-width",  [[10, 25], [20, 45]]] }  

"property" : { "discrete2" : ["#lod",  [[5, [0,0,0,255]], [7, [255,0,0,255]]]] }  

Linear2 function:

Returns a linear interpolation of values from [key, value] pairs adjacent to property value. property values outside key range are mapped to value corresponding to the closest key. [key,value] pairs must be sorted by key in ascending order. Value of property must be numeric, values from [key, value] pairs may be numeric or color.

"property" : { "linear2" : [property, [[key, value],...]] }

Examples:
"property" : { "linear2" : ["$elevation",  [[1000, 42], [8000, 85]]] }  

"property" : { "linear2" : ["#lod",  [[5, [0,255,0,255]], [17, [255,0,0,255]]]] }  

Lod-scaled function:

This function takes as input LOD and corresponding value for that LOD and returns value scaled for the current LOD. The value of the second function parameter can be only number. Third parameter is optional. Default value for the third parameter is 1. Smaller values than 1 means that values became larger relatively to previous LOD level. Larger values than 1 means that values became smaller relatively to previous LOD level.

Note: Returns value*(2*baseFactor)lod - #lod , where #lod is actual LOD at time of evaluation.

"property" : { "lod-scaled" : [lod, value, baseFactor] }

Example:
"property" : { "lod-scaled" : [5, 20, 1] }        

Log-scaled function:

This function converts input value in to the logarithmic scale. You have to provide maximum range of the input value (maxInputValue). Resulting value is usually in the range 0 - 100. You can specify your own range by setting optional parameters (outputRangeStart, outputRangeEnd). This function is usually used for computation of importance-source value.

"property" : { "log-scale" : [inputValue, maxInputValue, optional outputRangeStart, optional outputRangeEnd] }

Example:
"property" : { "log-scale" : [2400, 8848] }        

VTS Browser API

VTS Browser Core API

VTS File Format

VTS Browser Inspector Mode

Clone this wiki locally