Skip to content

Symbol Reference

Fu Zhen edited this page Mar 6, 2018 · 8 revisions
Clone this wiki locally

Maptalks's symbol system is inspired by CartoCSS and also lends some data types from mapbox-gl-style-spec.

This reference contains content from CartoCSS Documentation which is licensed with Apache 2.0.

Contents

  1. A List
  2. Rules of Symbol Categories and Geometry Types
  3. Symbol Properties
  4. Data Types

List

The following is a complete list of the symbol properties.

  • opacity
  • shadowBlur
  • shadowColor
  • shadowOffsetX
  • shadowOffsetY
Marker Text Polygons and Lines
  • markerOpacity
  • markerWidth
  • markerHeight
  • markerDx
  • markerDy
  • markerHorizontalAlignment
  • markerVerticalAlignment
  • markerPlacement
  • markerRotation
  • markerFile
  • markerType
  • markerFill
  • markerFillPatternFile
  • markerFillOpacity
  • markerLineColor
  • markerLineWidth
  • markerLineOpacity
  • markerLineDasharray
  • markerLinePatternFile
  • markerPath
  • markerPathWidth
  • markerPathHeight
  • textPlacement
  • textFaceName
  • textFont
  • textWeight
  • textStyle
  • textSize
  • textFill
  • textOpacity
  • textHaloFill
  • textHaloRadius
  • textHaloOpacity
  • textWrapWidth
  • textWrapCharacter
  • textLineSpacing
  • textHorizontalAlignment
  • textVerticalAlignment
  • textAlign
  • textRotation
  • textDx
  • textDy
  • lineColor
  • lineWidth
  • lineDasharray
  • lineOpacity
  • lineJoin
  • lineCap
  • linePatternFile
  • lineDx
  • lineDy
  • polygonFill
  • polygonOpacity
  • polygonPatternFile

Rules of Symbol Categories and Geometry Types

Categories Can be applied to
Marker Markers, Polygons, Lines
Text Markers, Polygons, Lines
Line Polygons, Lines
Polygon Polygons

Symbol Properties

All

opacity float

Default Value : 1

The overall opacity of the geometry.


shadowBlur number

Default Value : 0

level of the shadow around the geometry, see MDN's explanation


shadowColor color

Default Value : black

color of the shadow around the geometry, a CSS style color


shadowOffsetX float

Default Value : 0

A float specifying the distance that the shadow will be offset in horizontal distance.


shadowOffsetY float

Default Value : 0

A float specifying the distance that the shadow will be offset in vertical distance.

Marker Common Properties

markerOpacity Number

Default Value: 1 (The stroke-opacity and fill-opacity of the marker.)

The overall opacity of the marker.


markerWidth float

Default Value: 10 for Vector Marker and none for others

The width of the marker.


markerHeight float

Default Value: 10 for Vector Marker and none for others

The height of the marker.


markerDx float

Default Value: 0 (Marker will not be displaced.)

Displace marker by fixed amount, in pixels, +/- along the X axis. A positive value will shift the marker right.


markerDy float

Default Value: 0 (Marker will not be displaced.)

Displace marker by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the marker down.


markerHorizontalAlignment keyword

left middle right

Default Value: middle for markerFile, middle or top for different markerType

The marker's horizontal alignment from it's centerpoint.


markerVerticalAlignment keyword

top middle bottom

Default Value: bottom for markerFile, middle or bottom for different markerType

The marker's vertical alignment from it's centerpoint.


markerPlacement keyword

point vertex line vertex-first vertex-last

Default Value: point (Place markers at the center point (centroid) of the geometry.)

Attempt to place markers on a point, in the center of a polygon, or if markerPlacement:line, then multiple times along a line. Vertex places on the vertexes of polygons or lines. The 'vertex-first' and 'vertex-last' options can be used to place markers at the first or last vertex of lines or polygons.


markerRotation float

Default Value : none (Marker will not rotate)

The degree that marker rotates around marker's placing point. The rotation begins at right side of X-axis (0 degree) and is in a counterclockwise direction.

Image Marker

markerFile string

Default Value: none

A file that this marker shows at each placement. If no file is given, it may throw an error of failing to create any symbolizer.

Values of markerFile can be anything that HTML Image element supported:

  • URL: http://www.foo.com/foo.png or images/foo.png
  • Base64: A png: data:image/png;base64,iVBORw0.. or a SVG: data:image/svg+xml;base64,PD94bWwgdm..

Vector Marker

markerType keyword

ellipse cross x diamond bar square triangle pin pie

The vector marker's shape.


markerFill color

Default Value: blue (The marker fill color is blue.)

The color of the area of the marker.


markerFillPatternFile string

Default Value: none

Image to use as a repeated pattern fill within a marker. Any format that HTML Image can accept.


markerFillOpacity float

Default Value: 1 (Color is fully opaque.)

The fill opacity of the marker.


markerLineColor color

Default Value: black (The marker will be drawn with a black outline.)

The color of the stroke around the marker.


markerLineWidth float

Default Value: 1 (The marker will be drawn with an outline of 1 pixels wide.)

The width of the stroke around the marker, in pixels. This is positioned on the boundary, so high values can cover the area itself.


markerLineOpacity float

Default Value: 1 (Color is fully opaque.)

The opacity of marker's stroke.


markerLineDasharray numbers

Default Value: none (The line will be drawn without dashes.)

A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns.


markerLinePatternFile string

Default Value: none

An image file to be repeated and warped along marker's line. Any format that HTML Image can accept.


markerPath string|object|objects

Default Value: ''none``

A SVG path or pathes to define the marker's shape, if set it will override markerType. Possible values:

  • Path string:

    M8 23l0 0 0 0 0 0 0 0 0 0c-4,-5 -8,-10 -8,-14 0,-5 4,-9 8,-9l0 0 0 0c4,0 8,4 8,9 0,4 -4,9 -8,14z M5,9 a3,3 0,1,0,0,-0.9Z

  • A Path Object with Style Properties (same with SVG):

        {
            'path' : 'M8 23l0 0 0 0 0 0 0 0 0 0c-4,-5 -8,-10 -8,-14 0,-5 4,-9 8,-9l0 0 0 0c4,0 8,4 8,9 0,4 -4,9 -8,14z M5,9 a3,3 0,1,0,0,-0.9Z',
            'fill' : '#DE3333',
            'stroke' : '#000'
        }
  • An Array of Path Objects:

    [
        {transform:"matrix(1,0,0,1,200,200)", path:"M-122.304 84.285C-122.304 84.285 -122.203 86.179 -123.027 86.16C-123.851 86.141 -140.305 38.066 -160.833 40.309C-160.833 40.309 -143.05 32.956 -122.304 84.285z","stroke-width":"0.172",stroke:"#000",fill:"#fff"},
        {transform:"matrix(1,0,0,1,200,200)", path:"M-118.774 81.262C-118.774 81.262 -119.323 83.078 -120.092 82.779C-120.86 82.481 -119.977 31.675 -140.043 26.801C-140.043 26.801 -120.82 25.937 -118.774 81.262z","stroke-width":"0.172",stroke:"#000",fill:"#fff"}
    ]

markerPathWidth float

Default Value: 80 (The markerPath's width is 10 pixels.)

Applied to markerPath, width property of the generated SVG element, like the width in <svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="6.9956" height="8.9987"


markerPathHeight float

Default Value: 80

Applied to markerPath, height property of the generated SVG element, like the height in <svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="6.9956" height="8.9987"

Text

textPlacement keyword

point vertex line vertex-first vertex-last

Default Value: point (One text will be placed per geometry.)

How this label should be placed. Point placement places one label on top of a point geometry and at the centroid of a polygon or the middle point of a line, line places along lines multiple times per feature, vertex places on the vertexes of polygons, and 'vertex-first' and 'vertex-last' options can be used to place labels at the first or last vertex of lines or polygons.


textFaceName string

Default Value: monospace

Font name and style to render a label in.

symbol.textFaceName = '"microsoft yahei"';

textFont string

Default Value: none

Same as the CSS font property, defines the font family, boldness, size, and the style of the text, if set it will override textFaceName.

/* style | variant | weight | stretch | size/line-height | family */
symbol.textFont = 'italic small-caps bolder condensed 16px/3 cursive';

textWeight keyword

normal bold bolder lighter 100 200 300 400 500 600 700 800 900

Default Value : normal

Same as the CSS font-weight, Specifies the font weight.


textStyle keyword

normal italic oblique

Default Value : normal

Same as the CSS font-style, Specifies the font style.


textSize number

Default Value : 10 (Font size of 10 will be used to render text.)

Text size in pixels.


textFill color

Default Value : '#000' (The text will be rendered black.)

Specifies the color for the text.


textOpacity number

Default Value : 1 (Fully opaque.)

A number from 0 to 1 specifying the opacity for the text.


textHaloFill color

Default Value : #fff (The halo will be rendered white.)

Specifies the color of the halo around the text.


textHaloRadius number

Default Value: 0 (no halo.)

Specify the radius of the halo in pixels.


textHaloOpacity float

Default Value: 1 (Fully opaque.)

A number from 0 to 1 specifying the opacity for the text halo.


textWrapWidth unsigned

Default Value: 0 (Text will not be wrapped.)

Length of a chunk of text in pixels before wrapping text. If set to zero, text doesn't wrap.


textWrapCharacter string

Default Value: none (Lines will be wrapped when whitespace is encountered.)

Use this character to wrap long text, e.g. '\n'


textLineSpacing unsigned

Default Value: 0 _(The default font spacing will be used.)

Vertical spacing adjustment between lines in pixels.


textHorizontalAlignment keyword

left middle right

Default Value: middle

The text's horizontal alignment from it's centerpoint.


textVerticalAlignment keyword

top middle bottom

Default Value: middle

The text's vertical alignment from it's centerpoint.


textAlign keyword

left right center

Default Value: center

Define how text is justified.


textRotation float

Default Value : none (text will not rotate)

The degree that text rotates around text's placing point. The rotation begins at right side of X-axis (0 degree) and is in a counterclockwise direction.

textDx float

Default Value: 0 (Text will not be displaced.)

Displace text by fixed amount, in pixels, +/- along the X axis.


textDy float

Default Value: 0 (Text will not be displaced.)

Displace text by fixed amount, in pixels, +/- along the Y axis.

Polygons and Lines

lineColor color

Default Value: black (black and fully opaque (alpha = 1), same as rgb(0,0,0) or rgba(0,0,0,1).)

The color of a drawn line.


lineWidth float

Default Value: 1 (The line will be rendered 1 pixel wide.)

The width of a line in pixels.


lineDasharray numbers

Default Value: none (The line will be drawn without dashes.)

A pair of length values [a,b], where (a) is the dash length and (b) is the gap length respectively. More than two values are supported for more complex patterns.


lineOpacity float

Default Value: 1 (Color is fully opaque.)

The opacity of a line.


lineJoin keyword

miter``miter-revert``round``bevel

Default Value: miter (The line joins will be rendered using a miter look.)

The behavior of lines when joining.


lineCap keyword

butt``round``square

Default Value: butt (The line endings will be rendered using a butt look.)

The display of line endings.


linePatternFile string

Default Value: none

An image file to be repeated and warped along a line. Any format that HTML Image can accept.


lineDx float

Default Value: 0 (Line will not be displaced.)

Displace line by fixed amount, in pixels, +/- along the X axis.


lineDy float

Default Value: 0 (Line will not be displaced.)

Displace line by fixed amount, in pixels, +/- along the Y axis.


polygonFill color

Default Value: The color white will be used for fill.

Fill color to assign to a polygon.


polygonOpacity float

Default Value: 1 (Color is fully opaque.)

The opacity of the polygon.


polygonPatternFile uri

Default Value: none

Image to use as a repeated pattern fill within a polygon. Any format that HTML Image can accept.


Data Types

Color

Possible values of color:

  • HTML-style hex values, rgb, rgba, hsl, and hsla. Predefined HTML colors names, like yellow and blue, are also permitted.
{
  "lineColor": "#ff0",
  "lineColor": "#ffff00",
  "lineColor": "rgb(255, 255, 0)",
  "lineColor": "rgba(255, 255, 0, 1)",
  "lineColor": "hsl(100, 50%, 50%)",
  "lineColor": "hsla(100, 50%, 50%, 1)",
  "lineColor": "yellow"
}
  • Gradient color, like it in Canvas, can be either linear gradient color or radial gradient color, the form of gradient color is a JSON object with type, places and color stops:
{
    /**
    * Type of the gradient color
    * optional
    * possible values : linear | radial
    * default value: linear
    */
    type : 'linear', 
    /**
    * optional
    * default value:
    *   linear : [0, 0, 1, 0],
    *   radial : [0.5, 0.5, 1, 0.5, 0.5, 0]
    * Places of gradient.
    * For linear gradient: [x0, y0, x1, y1]
    *   x0 The x axis of the coordinate of the start point, a ratio (from 0 to 1) of geometry's width from left to right, e.g. 0.5 for the middle
    *   y0 The y axis of the coordinate of the start point, a ratio (from 0 to 1) of geometry's height from top to bottom, e.g. 1 for the bottom
    *   x1 The x axis of the coordinate of the end point.
    *   y1 The y axis of the coordinate of the end point.
    * ---------------
    * For radial gradient: [x0, y0, r0, x1, y1, r1]
    *   x0 The x axis of the coordinate of the start circle, a ratio (from 0 to 1) of geometry's width from left to right, e.g. 0.5 for the middle
    *   y0 The y axis of the coordinate of the start circle, a ratio (from 0 to 1) of geometry's height from top to bottom, e.g. 1 for the bottom
    *   r0 The radius of the start circle, a ratio (from 0 to 1) of geometry's width, e.g. 0.5 to be half of the geometry's width
    *   x1 The x axis of the coordinate of the end circle.
    *   y1 The y axis of the coordinate of the end circle.
    *   r1 The radius of the end circle.
    */
    places : [0, 0, 1, 0], 
    /**
    * Color stops, an array of number pairs([offset, color])
    * required
    * Same as Canvas's color stops:
    * https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient/addColorStop
    */
    colorStops : [
        [0.00, 'rgba(255, 0, 0, 1)'],
        [1 / 4, 'orange'],
        [2 / 4, 'green'],
        [3 / 4, 'aqua'],
        [1.00, 'white']
    ]
}

Function

Value of All the symbol properties can be set to be a data type of function.

Function is a data type derived from mapbox-gl-style (version 0.18.0 with additional support of "identity"), as it defines:

A function allow you to make the appearance of a map feature change with the current zoom level and/or the feature's properties.

You can find more in the spec.