# 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](/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/data-property.md) property. Marks are rendered in marks property array order. Marks property values can be constants or as data references. You can use the [scales](/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/scales-property.md) 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](/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/data-property.md) 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](/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/projections-property.md) 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.heavy.ai/v8.3.0/apis-and-interfaces/vega/vega-reference-overview/marks-property.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.