Skip to content

Marks

Jump to bottom Edit New page
jheer edited this page Apr 25, 2013 · 20 revisions

Wiki ▸ Documentation ▸ Marks

Marks are the basic visual building block of a visualization. Similar to other mark-based frameworks such as Protovis, marks provide basic shapes whose properties can be set according to backing data. Mark properties can be simple constants or data fields, and Scales can be used to map from data to property values. The basic supported mark types are rectangles (rect), plotting symbols (symbol), general paths or polygons (path), circular arcs (arc), filled areas (area), lines (line), images (image) and text labels (text).

Each mark supports a set of visual properties which determine the position and appearance of mark instances. Typically one mark instance is generated per input data element; the exceptions are the line and area mark types, which represent multiple data elements as a contiguous line or area shape. There are three primary property sets: enter, exit and update. Enter properties are evaluated when data is processed for the first time and a mark instance is newly added to a scene. Similarly, exit properties are evaluated when the data backing a mark is removed, and so the mark is leaving the visual scene. The update properties are evaluated for all existing (non-exiting) mark instances. In addition, an optional hover set determines visual properties when the mouse cursor hovers over a mark instance. Upon mouse out, the update set is applied.

A mark definition typically looks something like this:

{
  "type": "rect",
  "from": {"data": "table"},
  "properties": {
    "enter": {...},
    "exit": {...},
    "update": {...},
    "hover": {...}
  }
}

Top-Level Mark Properties

  • type [String] - The mark type (rect, path, arc, etc.)
  • name [String] - A unique name for the mark instance (optional).
  • description [String] - An optional description of this mark. Can be used as a comment.
  • from [Object] - An object describing the data this mark set should visualize. The supported properties are data (the name of the data set to use) and transform (to provide an array of data transformations to apply). If the data property is not defined, the mark will attempt to inherit data from its parent group mark, if any. Otherwise, a default, single element data set is assumed.
  • properties [Object] - An object containing the property set definitions.
  • key - [String] A data field to use as a unique key for data binding. When a visualization's data is updated, the key value will be used to match data elements to existing mark instances. Use a key field to enable object constancy for transitions over dynamic data. If no key value is provided, the index in the data array is instead used to match data to mark instances.
  • delay - [ValueRef -> Number] The transition delay, in milliseconds, for mark updates. The delay can be set in conjunction with the backing data (possibly through a scale transform) to provide staggered animations.
  • ease - [String] The transition easing function for mark updates. The supported easing types are linear, quad, cubic, sin, exp, circle, and bounce, plus the modifiers in, out, in-out, and out-in. The default is cubic-in-out. For more details please see the D3 ease function documentation.

Mark Property Sets

The rest of this page describes the available mark properties in greater detail. All visual mark property definitions are specified as name-value pairs in a property set (such as update, enter, or exit). The name is simply the name of the visual property. The value should be a ValueRef, as defined below.

Value References

A value reference (or ValueRef) specifies the value for a given mark property. The value may be a constant or a value in the backing data, and may include the application of a scale transform to either.

  • value - [*] A constant value. If field is specified, this value is ignored.
  • field - [String] A field (property) from which to pull a data value. The corresponding data set is determined by the mark's from property. Dot notation ("data.price") is used to access nested properties; if a dot character is actually part of the property name, you must escape the dot with a backslash: "some\.field".
  • scale - [String] The name of a scale transform to apply.
  • mult - [Number] A multiplier for the value, equivalent to (mult * value). Multipliers are applied after any scale transformation.
  • offset - [Number] A simple additive offset to bias the final value, equivalent to (value + offset). Offsets are added after any scale transformation and multipliers.
  • band - [Boolean] If true, and scale is specified, uses the range band of the scale as the retrieved value. This option is useful for determining widths with an ordinal scale.

Examples

  • {"value": 5} - The constant value 5.
  • {"field": "data.price"} - The value of data.price, for the current datum.
  • {"field": "index", "mult": 20} - The value of index for the current datum, multiplied by 20.
  • {"scale": "x", "value": 0} - The result of running the value 0 through the scale named x.
  • {"scale": "y", "field": "data.price"} - The result of running data.price for the current datum through the scale named y.
  • {"scale": "x", "band": true} - The range band width of the ordinal scale x. Note that the scale must be ordinal!
  • {"scale": "x", "band": true, "offset": -1} - The range band width of the ordinal scale x, reduced (negative offset) by one pixel.

Shared Visual Properties

  • x [ValueRef -> Number] - The first (typically left-most) x-coordinate.
  • x2 [ValueRef -> Number] - The second (typically right-most) x-coordinate.
  • width [ValueRef -> Number] - The width of the mark (if supported).
  • y [ValueRef -> Number] - The first (typically top-most) y-coordinate.
  • y2 [ValueRef -> Number] - The second (typically bottom-most) y-coordinate.
  • height [ValueRef -> Number] - The height of the mark (if supported).
  • opacity [ValueRef -> Number] - The overall opacity.
  • fill [ValueRef -> Color] - The fill color.
  • fillOpacity [ValueRef -> Number] - The fill opacity.
  • stroke [ValueRef -> Color] - The stroke color.
  • strokeWidth [ValueRef -> Number] - The stroke width, in pixels.
  • strokeOpacity [ValueRef -> Number] - The stroke opacity.

For marks involving Cartesian extents (e.g., rect marks), the horizontal dimensions are determined by (in order of precedence) the x and x2 properties, the x and width properties, and the x2 and width properties. If all three of x, x2 and width are specified, the width value is ignored. The y, y2 and height properties are treated similarly. For marks without Cartesian extents (e.g., path, arc, etc) the same calculations are applied, but are only used to determine the mark's ultimate x and y position. That is, a width property may affect the ultimate position, but otherwise is not visualized.

rect

  • (No additional properties.)

symbol

  • size [ValueRef -> Number] - The pixel area of the symbol. For example: in the case of circles, the radius is determined in part by the square root of the size value.
  • shape [ValueRef -> String] - The symbol shape to use. One of circle (default), square, cross, diamond, triangle-up, or triangle-down

path

  • path [ValueRef -> PathString] - A path definition in the form of an SVG Path string.

arc

  • innerRadius [ValueRef -> Number] - The inner radius of the arc, in pixels.
  • outerRadius [ValueRef -> Number] - The outer radius of the arc, in pixels.
  • startAngle [ValueRef -> Number] - The start angle of the arc, in radians.
  • endAngle [ValueRef -> Number] - The end angle of the arc, in radians.

area

  • interpolate [ValueRef -> String] - The line interpolation method to use. One of linear, step-before, step-after, basis, basis-open, cardinal, cardinal-open, monotone.
  • tension [ValueRef -> Number] - Depending on the interpolation type, sets the tension parameter.

line

  • interpolate [ValueRef -> String] - The line interpolation method to use. One of linear, step-before, step-after, basis, basis-open, basis-closed, bundle, cardinal, cardinal-open, cardinal-closed, monotone.
  • tension [ValueRef -> Number] - Depending on the interpolation type, sets the tension parameter.

image

  • url [ValueRef -> String] - The URL from which to retrieve the image.
  • align [ValueRef -> String] - The horizontal alignment of the image. One of left, right, center.
  • baseline [ValueRef -> String] - The vertical alignment of the image. One of top, middle, bottom.

text

  • text [ValueRef -> String] - The text to display.
  • align [ValueRef -> String] - The horizontal alignment of the text. One of left, right, center.
  • baseline [ValueRef -> String] - The vertical alignment of the text. One of top, middle, bottom.
  • dx [ValueRef -> Number] - The horizontal margin, in pixels, between the text label and its anchor point. The value is ignored if the align property is center.
  • dy [ValueRef -> Number] - The vertical margin, in pixels, between the text label and its anchor point. The value is ignored if the baseline property is middle.
  • angle [ValueRef -> Number] - The rotation angle of the text, in degrees.
  • font [ValueRef -> String] - The typeface to set the text in (e.g., Helvetica Neue).
  • fontSize [ValueRef -> Number] - The font size, in pixels.
  • fontWeight [ValueRef -> String] - The font weight (e.g., bold).
  • fontStyle [ValueRef -> String] - The font style (e.g., italic).
Add a custom footer
Add a custom sidebar
Clone this wiki locally