marks Property

Marks visually encode data using geometric primitives.
General JSON format:
1
"marks": [
2
  {
3
    "type": points | line | polys | symbol,
4
    "from": { data: <dataSourceID> },
5
    "properties": { <propName>: <propVal> }, ... { <propName>: <propVal> }
6
    "transform": { <transformType>: <transformName> }
7
  },
8
  {
9
    ...
10
  }
11
],
Copied!
A Vega marks specification includes the following properties:
Property
Data Type
Required
Description
​type​
string
X
Graphical marks type or shape:
points
lines
polys
symbol
​from​
object
​
Database table associated with the marks.
​properties​
object
X
Visual encoding rules. Valid properties depend on marks type.
​transform​
object
​
Transforms applied to a mark.
Each marks property is associated with the specified data property.
Marks are rendered in marks property array order.
Marks property values can be constants or as data references. You can use the scales property to transform marks property values to the visualization area.
Apply the x and y scales to the x and y database table columns to scale the data to the visualization area width and height. For example:
1
const exampleVega = {
2
  "width:" 384,
3
  "height:" 564,
4
  "data:" [ ... elided ... ],
5
  "scales:" [
6
    {
7
      "name:" "x",
8
      "type:" "linear",
9
      "domain:" [-3650484.1235206556,7413325.514451755],
10
      "range:" "width"
11
    },
12
    {
13
      "name:" "y",
14
      "type:" "linear",
15
      "domain:" [-5778161.9183506705, 10471808.487466192],
16
      "range:" "height"
17
    }
18
  ],
19
  "marks:" [
20
    {
21
      "type:" "points",
22
      "from:" { "data:" "tweets" },
23
      "properties:" {
24
        "x:" { "scale:" "x", "field:" "x" },
25
        "y:" { "scale:" "y","field:" "y"}
26
      }
27
    }
28
  ]
29
};
Copied!
marks Properties
type
Marks must include a type property that specifies the geometric primitive to use to render the data.
Marks Type
Description
​points``
Render marks as points.
​lines``
Render marks as lines.
​polys``
Render marks as a polygon.
​symbol``
Render marks as a shape.
points Type
Specify x and y coordinate values using either constants, or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be constants.
points Examples
Define a point with size, color, and opacity:
1
{
2
  "width" : 1024,
3
  "height" : 1024,
4
  "data": [
5
    {
6
      "name" : "table",
7
        "values": [
8
          {"x": 412, "y": 512, "val": 0.9,"color": "red"},
9
          {"x": 512, "y": 512, "val": 0.3, "color": "violet"},
10
          {"x": 612, "y": 512, "val": 0.5,"color": "green"}
11
        ]
12
     }
13
      ],
14
  "marks" : [
15
    {
16
      "type" : "points",
17
      "from" : {"data" : "table"},
18
        "properties" : {
19
          "x" : { "field" : "x" },
20
          "y" : { "field" : "y" },
21
          "fillColor" : {
22
              "field" : "color"
23
                      },
24
                      "size" : 150.0,
25
                      "fillOpacity" : {
26
                              "field" : "val"
27
                      },
28
                      "opacity" : 0.8
29
               }
30
             }
31
       ]
32
     }
Copied!
Associate the points geometric primitive with tweets data items.
1
vegaSpec = {
2
    "width": 384,
3
    "height": 564,
4
    "data": [
5
        {
6
            "name": "tweets",
7
            "sql": "SELECT  ... elided ... "
8
        }
9
    ],
10
    "scales": [ ... elided ... ],
11
    "marks": [
12
        {
13
            "type": "points",
14
            "from": { data: "tweets" },
15
            "properties": { ... elided ... }
16
        },
17
        { ... elided ... }
18
    ]
19
};
Copied!
lines Type
Specifying the data format property as lines causes the rendering engine to assume a lines database table layout and to extract line-related columns from the table.
Specify x and y coordinate values using either constants, or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be constants.
lines Example
1
{
2
  "type": "lines",
3
  "from": {"data": "table"},
4
  "properties": {
5
    "x": {
6
      "field": "x",
7
      "scale": "x"
8
    },
9
    "y": {
10
      "field": "y",
11
      "scale": "y"
12
    },
13
    "strokeColor": {
14
      "scale": "strokeColor",
15
      "field": "color"
16
    },
17
    "strokeWidth": 2,
18
    "lineJoin": "miter",
19
    "miterLimit": 10
20
  }
21
}
Copied!
polys Type
The polys type renders data as a polygon. When the data format property is polys, the rendering engine assumes a polys database table layout and extracts the poly-related columns from the table. A polys database table layout implies that the first data column is the vertex x- and y-positions. The vertices are interleaved x and y values, such that vertex[0] = vert0.x, vertex[1] = vert0.y, vertex[2] = vert1.x, and vertex[3] = vert1.y, for example. The next three positions of a polys database table are the triangulated indices, and line loop and drawing information for unpacking multiple, associated polygons that can be packed as a single data item.
polys Example
1
const exampleVega = {
2
  "width": 1004,
3
  "height": 336,
4
  "data": [
5
    {
6
      "name": "polys",
7
      "format": "polys",
8
      "sql": "SELECT ... elided ..."
9
    }
10
  ],
11
  "scales": [ ... elided ... ]
12
  "marks": [
13
    {
14
      "type": "polys",
15
      "from": {
16
        "data": "polys"
17
      },
18
      "properties": {
19
        "x": {
20
          "scale": "x",
21
          "field": "x"
22
        },
23
        "y": {
24
          "scale": "y",
25
          "field": "y"
26
        },
27
        "fillColor": {
28
          "scale": "polys_fillColor",
29
          "field": "avgContrib"
30
        },
31
        "strokeColor": "white",
32
        "strokeWidth": 0,
33
        "lineJoin": "miter",
34
        "miterLimit": 10
35
      }
36
    }
37
  ]
38
}
Copied!
symbol Type
The symbol marks type renders data as one of the supported shapes.
Currently, in symbol mark types, strokes are not visible beneath other marks, regardless of opacity settings.
Specify x and y coordinate values using either constants or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be specified using constant values.
symbol Examples
1
const exampleVega = {
2
  "width": 733,
3
  "height": 530,
4
  "data": [
5
    {
6
      "name": "heatmap_query",
7
      "sql": "SELECT ... elided ... "
8
    }
9
  ],
10
  "scales": [ ... elided ... ],
11
  ],
12
  "marks": [
13
    {
14
      "type": "symbol",
15
      "from": {
16
        "data": "heatmap_query"
17
      },
18
      "properties": {
19
        "shape": "square",
20
        "x": { "field": "x" },
21
        "y": { "field": "y" },
22
        "width": 1,
23
        "height": 1,
24
        "fillColor": { "scale": "heat_color", "field": "cnt" }
25
      }
26
    }
27
  ]
28
};
Copied!
The following example defines symbol mark types including fill, stroke, and general opacity properties:
1
{
2
  "width" : 1024,
3
  "height" : 1024,
4
  "data": [
5
      {
6
          "name" : "table",
7
          "values": [
8
              {"x": 200,  "x2": 0.0, "y": 200.0, "y2": 0.0, "val" : 0, "color" : "red", "color2": "yellow", "opacity": 1.0, "fillOpacity":0.75, "strokeOpacity": 0.25},
9
              {"x": 220.806,  "x2": 0.0, "y": 263.75, "y2": 0.0, "val" : 1, "color" : "blue", "color2": "green", "opacity": 0.5, "fillOpacity": 0.5, "strokeOpacity": 0.5},
10
              {"x": 240.61216,  "x2": 0.0, "y": 327.5, "y2": 0.0, "val" : 0, "color" : "maroon", "color2": "magenta", "opacity": 0.1, "fillOpacity": 0.25, "strokeOpacity": 0.75}
11
          ]
12
      }
13
  ],
14
  "marks" : [
15
      {
16
          "type" : "symbol",
17
          "from" : {"data" : "table"},
18
          "properties" : {
19
                      "shape" : "circle",
20
              "xc" : { "field" : "x" },
21
              "yc" : { "field" : "y" },
22
                      "width": 150.0,
23
                  "height": 150.0,
24
              "opacity": 0.9,
25
              "fillOpacity": {
26
                  "field": "fillOpacity"
27
              },
28
              "fillColor" : {
29
                  "field": "color2"
30
              },
31
                      "strokeWidth" : 10.0,
32
                      "strokeColor" : {
33
                  "field": "color"
34
              },
35
              "strokeOpacity": {
36
                  "field": "strokeOpacity"
37
              }
38
          }
39
      }
40
   ]
41
}
Copied!
from
The from field specifies the input database table to use.
Data Source Field
Data Type
Description
data
string
Name of the data source. The data name must be defined in the data property.
Example
Use the tweets database table for marks input data.
1
vegaSpec = {
2
    "width": 384,
3
    "height": 564,
4
    "data": [
5
        {
6
          "name": "tweets",
7
          "sql": "SELECT ... elided ... "
8
        }
9
    ],
10
    "scales": [ ... elided ... ],
11
    "marks": [
12
        {
13
            "type": "polys",
14
            "from": {"data": "tweets"},
15
            "properties": { ... elided ... }
16
        }
17
    ]
18
};
Copied!
If from is not specified, the data source is implicitly a single point with the value defined in the points properties.
properties
The properties property specifies type-dependent visual encoding that define the position and appearance of mark instances. The property value is specified using one of the Value Reference options.
Typically, a single mark instance is generated per input data element, except for polys, which uses multiple data elements to represent a line or area shape.
The following table describes the various marks properties and lists the types for which the property is valid.
Property
Data Type
Valid Primitive Types
Description
angle
number
symbol
Amount of rotation about the defined center of rotation. The center of rotation depends on the properties that specify the symbol location:
x and y: Lower-left corner.
x and yc: Left center.
xc and y: Bottom center.
xc and yc: Center.
Must be a numerical constant or a scale that provides numerical values.
In the following example, the triangle-down symbol is rotated 30 degrees about the downward point:
angleUnit
string
symbol
Optional. Unit of measure for the rotation of a symbol around the center of rotation, defined in angle. Either degrees (default) or radians.
fillColor
color
points, polys, symbol
Fill color. Must be a scale/data reference, a string, or a color represented by a 32-bit integer or unsigned integer. See Color Value Reference.
fillOpacity
number
points, polys, symbol
The fill opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.
height
number
symbol
Mark height, in pixels.
lineJoin
string
line, polys, symbol
Line join method:
bevel - Extension of a line end
miter - Clipped extension of a line end
round - Semi-circle at a line end
miterLimit
number
line, polys, symbol
The miter limit at which to bevel a line join, in pixels.
Must be a positive number. Default = 10.0
opacity
number
all
The line opacity as a whole, from transparent (0) to opaque (1). If used with fillOpacity (points, polys, symbol) or strokeOpacity (lines), the values are multiplied together to determine final opacity.
shape
string
symbol
Shape name:
circle
cross
diamond
hexagon-horiz
hexagon-vert
square
triangle-down
triangle-left
triangle-right
triangle-up
wedge
size
number
points
Graphical primitive size, in pixels. Must be a scale/data reference or a number.
stroke
color
symbol
Stroke color.
strokeColor
color
line, polys
Stroke color. Must be a scale/data reference, a string, or a color represented by a 32-bit integer or unsigned integer. See Color Value Reference.
Default color = white
strokeOpacity
number
line, polys, symbol
Stroke opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.
strokeWidth
number
line, polys, symbol
Stroke width, in pixels. Must be a scale/data reference or a number.
width
number
symbol
Mark width, in pixels.
x
number
all
Primary x-coordinate, in pixels. Must be a scale/data reference for polys, or a scale/data reference or a number for points, lines, or symbol. See Value Reference.
x2
number
symbol
Secondary x-coordinate, in pixels. See Value Reference.
xc
number
symbol
Center x-coordinate, in pixels. Incompatible with x and x2. See Value Reference.
y
number
all
Primary y-coordinate, in pixels. Must be a scale/data reference for polys, or a scale/data reference or a number for points, lines, or symbol. See Value Reference.
Value Reference
A value reference describes how to specify marks properties values. The value can be a constant or data object reference:
Name
Type Description
​
value
Any
Constant value. If field is specified, value is ignored.
field
​Field Reference​
Perform a lookup on the current data value. The marks from property determines the source data table and the field name must be a column defined in the data property.
scale
​Field Reference​
Name of a scale transform to apply to the mark. If the input is an object, it indicates a field value from which to dynamically look up the scale name and follows the Field Reference format.
Examples:
Statically set the point fillColor and size.
1
"marks:" [
2
  {
3
    "type:" "points",
4
    "from:" {
5
      "data:" "tweets"
6
    },
7
    "properties:" {
8
​
9
         ... elided ...
10
​
11
      "fillColor": "blue",
12
      "size": 3
13
      }
14
    }
15
  }
16
]
Copied!
For the x marks property, apply the x scale transform to the implicit x-coordinate data column.
1
"marks": [
2
  {
3
    "type": "polys",
4
    "from": {
5
      "data": "polys"
6
    },
7
    "properties": {
8
      "x": {
9
        "scale": "x",
10
        "field": "x"
11
      },
12
​
13
      ... elided ...
14
​
15
    }
16
  }
17
]
Copied!
Field Reference
A field reference is either a string literal or an object. For object values, the following properties are supported:
Property
Type
Description
Property Name
FieldRef
Perform a lookup on the property name. This is the default operation when a field reference is a string.
Color Value Reference
Typically, color values are specified as a single RGB color value. To specify specific color fields or use a different color space, use one of the following color value reference formats:
Property Value Field
Data Type
Description
field
string
Name of the attribute from the data: sql field.
colorSpace
string
Space in which the color is defined:
Hue-Chroma-Luminance color space. See HCL color space.
Use r, g, and b property names.
Hue, saturation, and lightness color space. See HSL and HSV color space.
Use h, s, and l property names.
Lab color space. A perceptual color space with distances based on human color judgments. The L dimension represents luminance, the A dimension represents green-red opposition and the B dimension represents blue-yellow opposition. See Lab color space.
Use l, a, and b property names.
RGB color space. A version of LAB, which uses polar coordinates for the AB plane. See RGB color space.
Use h, c, and l property names.
Examples
Set the red and blue channels of an RGB color as constants, and uses a scale transform to determine the green channel:
1
"fill": {
2
  "r": {"value": 255},
3
  "g": {"scale": "green", "field": "g"},
4
  "b": {"value": 0}
5
}
Copied!
Use the rgb color space for the color field:
1
"fillColor": {
2
    "field": "color",
3
    "colorSpace": "rgb"
4
}
Copied!
transform
The transform object specifies any Vega projections to be applied to the mark. Each transform is specified as a key:value pair in the transform object:
1
},
2
"transform": {
3
      "<key>": "<value>"
4
}
Copied!
The value references an existing Vega object by name.
For example, the following transform references the projection my_mercator_projection defined in the top-level Vega projections property.
1
"projections": [
2
{
3
  "name": "my_mercator_projection",
4
  "type": "mercator",
5
  "bounds": {
6
    "x": [-120.0, 120.0],
7
    "y": [-20.0, 20.0]
8
  }
9
}
10
]
11
"marks": [
12
{
13
  "type": "symbol",
14
  "from": { "data": "fec_contributions_oct" },
15
  "properties": { ... elided ... }
16
  "transform": {
17
    "projection": "my_mercator_projection"
18
  }
19
}
20
]
Copied!
Currently, the only supported transform is projection.
scales Property
Migration
Last modified 8mo ago
Export as PDF
Copy link
Contents