# marks Property Marks visually encode data using geometric primitives. General JSON format: ``` "marks": [ { "type": points | line | polys | symbol, "from": { data: }, "properties": { : }, ... { : } "transform": { : } }, { ... } ], ``` A Vega `marks` specification includes the following properties: | Property | Data Type | Required | Description | | ------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------- | | [type](#type) | string | X |

Graphical marks type or shape:

  • points
  • lines
  • polys
  • symbol
| | [from](#from) | object | | Database table associated with the marks. | | [properties](#properties) | object | X | Visual encoding rules. Valid properties depend on marks `type`. | | [transform](#transform) | object | | Transforms applied to a mark. | Each marks property is associated with the specified [data](https://docs.heavy.ai/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/data-property) property. Marks are rendered in marks property array order. Marks property values can be constants or as data references. You can use the [scales](https://docs.heavy.ai/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/scales-property) 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: ``` 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 Marks must include a `type` property that specifies the geometric primitive to use to render the data. | Marks Type | Description | | ---------------------------- | -------------------------- | | [`points`](#points-type)\`\` | Render marks as points. | | [`lines`](#lines-type)\`\` | Render marks as lines. | | [`polys`](#polys-type)\`\` | Render marks as a polygon. | | [`symbol`](#symbol-type)\`\` | 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: ``` { "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 } } ] } ``` 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 ... } ] }; ``` #### **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** ``` { "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`.` When the `data` [format](https://docs.omnisci.com/latest/6_vegaReference-data.html#vegarefdataformat) 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** ``` 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 [supported shapes](#properties). {% hint style="info" %} Currently, in `symbol` mark types, strokes are not visible beneath other marks, regardless of opacity settings. {% endhint %} 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 ``` 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](https://docs.heavy.ai/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/data-property) 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. The property value is specified using one of the [Value Reference](#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](#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](#value-reference). | | `x2` | number | symbol | Secondary x-coordinate, in pixels. See [Value Reference](#value-reference). | | `xc` | number | symbol | Center x-coordinate, in pixels. Incompatible with `x` and `x2`. See [Value Reference](#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). | | `y2` | number | symbol | Secondary y-coordinate, in pixels. See [Value Reference](#value-reference). | | `yc` | number | symbol | Center y-coordinate, in pixels. Incompatible with `y` and `y2`. See [Value Reference](#value-reference). | | `z` | number | points, symbol | Primary depth-coordinate, in pixels. Must be a scale/data reference or a number. See [Value Reference](#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](#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](#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](#field-reference) format. | 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](https://docs.heavy.ai/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/projections-property) to be applied to the mark. Each transform is specified as a key:value pair in the `transform` object: ``` }, "transform": { "": "" } ``` 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" } } ] ``` {% hint style="info" %} Currently, the only supported transform is `projection`. {% endhint %}