Marks

Marks visually encode data using geometric primitives. A Vega marks specification includes the following properties:

Property Data Type Required Description
type string X Graphical marks type or shape.
from object
  • lines
  • polys
 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.

Examples

Associate the points geometric primitive with tweets data items.

vegaSpec = {
    "width": 384,
    "height": 564,
    "data": [
        {
            "name": "tweets",
            "sql": "SELECT  ... elided ... "
        }
    ],
    "scales": [ ... elided ... ],
    "marks": [
        {
            "type": "points",
            "from": { data: "tweets" },
            "properties": { ... elided ... }
        },
        { ... elided ... }
    ]
};

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.

const exampleVega = {
  "width:" 384,
  "height:" 564,
  "data:" [ ... elided ... ],
  "scales:" [
    {
      "name:" "x",
      "type:" "linear",
      "domain:" [-3650484.1235206556,7413325.514451755],
      "range:" "width"
    },
    {
      "name:" "y",
      "type:" "linear",
      "domain:" [-5778161.9183506705, 10471808.487466192],
      "range:" "height"
    }
  ],
  "marks:" [
    {
      "type:" "points",
      "from:" { "data:" "tweets" },
      "properties:" {
        "x:" { "scale:" "x", "field:" "x" },
        "y:" { "scale:" "y","field:" "y"}
      }
    }
  ]
};

Marks Properties

type

The marks property must include a type property that specifies the geometric primitive to use to render the data.

marks type Description
points Render marks as points. See Points Type.
lines Render marks as lines. See Lines Type.
polys Render marks as a polygon. See Polys Type.
symbol Render marks as a shape. See Symbol Type.

Points Type

The points marks type renders data as a point.

Vega supports the following points properties:

Property Data Type Description
fillColor color 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 The fill opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.
opacity number The line opacity as a whole, from transparent (0) to opaque (1). If used with fillOpacity, the values are multiplied together to determine final opacity.
size number Graphical primitive size, in pixels. Must be a scale/data reference or a number.
x number Primary x-coordinate, in pixels. Must be a scale/data reference or a number for points, or a scale/data reference for polys. See Value Reference.
y number Primary y-coordinate, in pixels. Must be a scale/data reference or a number for points, or a scale/data reference for polys. See Value Reference.
z number Primary depth-coordinate, in pixels. Must be a scale/data reference or a number for points. See Value Reference.

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.

Example: Define a point with size, color, and opacity:

{
  "width" : 1024,
  "height" : 1024,
  "data": [
    {
      "name" : "table",
        "values": [
          {"x": 412, "y": 512, "val": 0.9,"color": "red"},
          {"x": 512, "y": 512, "val": 0.3, "color": "violet"},
          {"x": 612, "y": 512, "val": 0.5,"color": "green"}
        ]
     }
      ],
  "marks" : [
    {
      "type" : "points",
      "from" : {"data" : "table"},
        "properties" : {
          "x" : { "field" : "x" },
          "y" : { "field" : "y" },
          "fillColor" : {
              "field" : "color"
                      },
                      "size" : 150.0,
                      "fillOpacity" : {
                              "field" : "val"
                      },
                      "opacity" : 0.8
               }
             }
       ]
     }

Lines Type

The lines marks type renders data as a line.

The data format property must be specified as lines. This causes the rendering engine to assume a lines database table layout and to xtract line-related columns from the table.

Vega supports the following lines properties:

Property Data Type Description
lineJoin string

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

The miter limit at which to bevel a line join, in pixels.

Must be a positive number. Default = 10.0
opacity number The line opacity as a whole, from transparent (0) to opaque (1). If used with strokeOpacity, the values are multiplied together to determine final opacity.
strokeColor color

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 The stroke opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.
strokeWidth number Stroke width, in pixels. Must be a scale/data reference or a number.
x number Primary x-coordinate, in pixels. Must be a scale/data reference or a number for lines, or a scale/data reference for polys. See Value Reference.
y number Primary y-coordinate, in pixels. Must be a scale/data reference or a number for lines, or a scale/data reference for polys. See Value Reference.

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.

Example:

{
  "type": "lines",
  "from": {"data": "table"},
  "properties": {
    "x": {
      "field": "x",
      "scale": "x"
    },
    "y": {
      "field": "y",
      "scale": "y"
    },
    "strokeColor": {
      "scale": "strokeColor",
      "field": "color"
    },
    "strokeWidth": 2,
    "lineJoin": "miter",
    "miterLimit": 10
  }
}

Polys Type

The polys type renders data as a polygon, and the data from property must be set to polys.

Because 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.

Vega supports the following polys properties:

Property Data Type Description
fillColor color 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 The fill opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.
lineJoin string

Line join method:

bevel Extension of an endpoint.

miter Clipped extension of an endpoint.

round Semi-circle at an endpoint.
miterLimit number

The miter limit at which to bevel a line join, in pixels.

Must be a positive number. Default = 10.0
opacity number The polygon opacity as a whole, from transparent (0) to opaque (1). If used with strokeOpacity or fillOpacity, the values are multiplied together to determine final opacity.
strokeColor color

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 Stroke opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.
strokeWidth number Stroke width, in pixels. Must be a scale/data reference or a number.
x number Primary x-coordinate, in pixels. Must be a scale/data reference or a number for points, or a scale/data reference for polys. See Value Reference.
y number Primary y-coordinate, in pixels. Must be a scale/data reference or a number for points, or a scale/data reference for polys. See Value Reference.

Example:

const exampleVega = {
  "width": 1004,
  "height": 336,
  "data": [
    {
      "name": "polys",
      "format": "polys",
      "sql": "SELECT ... elided ..."
    }
  ],
  "scales": [ ... elided ... ]
  "marks": [
    {
      "type": "polys",
      "from": {
        "data": "polys"
      },
      "properties": {
        "x": {
          "scale": "x",
          "field": "x"
        },
        "y": {
          "scale": "y",
          "field": "y"
        },
        "fillColor": {
          "scale": "polys_fillColor",
          "field": "avgContrib"
        },
        "strokeColor": "white",
        "strokeWidth": 0,
        "lineJoin": "miter",
        "miterLimit": 10
      }
    }
  ]
}

Symbol Type

The symbol marks type renders data as one of the following shapes:

Shape Literal Description
circle Circle
cross Cross
diamond Diamond
hexagon-horiz Horizontal hexagon
hexagon-vert Vertical hexagon
square Square
triangle-down Triangle pointing down
triangle-left Triangle pointing left
triangle-right Triangle pointing right
triangle-up Triangle pointing up

Vega supports the following symbol properties:

Property Data Type Description
fillColor color 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 The fill opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.
height number Mark height, in pixels.
stroke color Stroke color.
lineJoin string

Stroke line join method:

  • miter (default)
  • round
  • bevel
miterLimit number Miter limit at which to bevel a line join.
opacity number The symbol opacity as a whole, from transparent (0) to opaque (1).
shape string Shape name listed in the above table.
strokeWidth number Stroke width, in pixels.
strokeOpacity number Stroke opacity, from transparent (0) to opaque (1). If used with opacity, the values are multiplied together to determine final opacity.
width number Mark width, in pixels.
x number Primary x-coordinate, in pixels. Must be a scale/data reference or a number for symbol, or a scale/data reference for polys. See Value Reference.
x2 number Secondary x-coordinate, in pixels. See Value Reference.
xc number Center x-coordinate, in pixels. Incompatible with x and x2. See Value Reference.
y number Primary y-coordinate, in pixels. Must be a scale/data reference or a number for symbol, or a scale/data reference for polys. See Value Reference.
y2 number Secondary y-coordinate, in pixels. See Value Reference.
yc number Center y-coordinate, in pixels. Incompatible with y and y2. See Value Reference.
z number Primary depth-coordinate, in pixels. Must be a scale/data reference or a number for symbol. See Value Reference.

Note: 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.

Examples:

const exampleVega = {
  "width": 733,
  "height": 530,
  "data": [
    {
      "name": "heatmap_query",
      "sql": "SELECT ... elided ... "
    }
  ],
  "scales": [ ... elided ... ],
  ],
  "marks": [
    {
      "type": "symbol",
      "from": {
        "data": "heatmap_query"
      },
      "properties": {
        "shape": "square",
        "x": { "field": "x" },
        "y": { "field": "y" },
        "width": 1,
        "height": 1,
        "fillColor": { "scale": "heat_color", "field": "cnt" }
      }
    }
  ]
};

The following example defines symbol mark types including fill, stroke, and general opacity properties:

{
  "width" : 1024,
  "height" : 1024,
  "data": [
      {
          "name" : "table",
          "values": [
              {"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},
              {"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},
              {"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}
          ]
      }
  ],
  "marks" : [
      {
          "type" : "symbol",
          "from" : {"data" : "table"},
          "properties" : {
                      "shape" : "circle",
              "xc" : { "field" : "x" },
              "yc" : { "field" : "y" },
                      "width": 150.0,
                  "height": 150.0,
              "opacity": 0.9,
              "fillOpacity": {
                  "field": "fillOpacity"
              },
              "fillColor" : {
                  "field": "color2"
              },
                      "strokeWidth" : 10.0,
                      "strokeColor" : {
                  "field": "color"
              },
              "strokeOpacity": {
                  "field": "strokeOpacity"
              }
          }
      }
   ]
}

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.

vegaSpec = {
    "width": 384,
    "height": 564,
    "data": [
        {
          "name": "tweets",
          "sql": "SELECT ... elided ... "
        }
    ],
    "scales": [ ... elided ... ],
    "marks": [
        {
            "type": "polys",
            "from": {"data": "tweets"},
            "properties": { ... elided ... }
        }
    ]
};

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.

Typically, a single mark instance is generated per input data element, except for polys, which use multiple data elements to represent a line or area shape.

The properties property defines visual encoding rules. The property value is specified using one of the Value Reference options.

See Points Type, Polys Type, and Symbol Type for a list of properties supported by each marks type.

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. See Data.
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. See Scales.

Examples:

Statically set the point fillColor and size.

"marks:" [
  {
    "type:" "points",
    "from:" {
      "data:" "tweets"
    },
    "properties:" {

         ... elided ...

      "fillColor": "blue",
      "size": 3
      }
    }
  }
]

For the x marks property, apply the x scale transform to the implicit x-coordinate data column.

"marks": [
  {
    "type": "polys",
    "from": {
      "data": "polys"
    },
    "properties": {
      "x": {
        "scale": "x",
        "field": "x"
      },

      ... elided ...

    }
  }
]

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:

"fill": {
 "r": {"value": 255},
 "g": {"scale": "green", "field": "g"},
 "b": {"value": 0}
}

Use the rgb color space for the color field:

"fillColor": {
    "field": "color",
    "colorSpace": "rgb"
}

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:

},
"transform": {
      "<key>": "<value>"
}

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.

"projections": [
{
  "name": "my_mercator_projection",
  "type": "mercator",
  "bounds": {
    "x": [-120.0, 120.0],
    "y": [-20.0, 20.0]
  }
}
]
"marks": [
{
  "type": "symbol",
  "from": { "data": "fec_contributions_oct" },
  "properties": { ... elided ... }
  "transform": {
    "projection": "my_mercator_projection"
  }
}
]

Note: Currently, the only supported transform is projection.