Coordinates

VEGA specifications ("specs") define plot size using width and height. These coordinates are used to specify mark positions and sizes (typically mapping data values through scales), and map directly to pixel positions.

MorphCharts specs also define plot size using width and height, optionally adding depth. These coordinates are also used to specify mark positions and sizes. However, they do not map directly to pixel positions, for the following reasons:

• A camera (a PerspectiveCamera by default) to define the view. The position and size of a mark on the screen will depend on camera properties such as distance and field of view.
• mark positions can optionally define a z-coordinate.
• The camera view is rendered onto a canvas defined by a width and height. This allows the user to change the size of the image, without changing the scene.

Since plot size no longer maps directly to pixel size, we can define plot size using arbitrary units, such as height, width, and depth as a unit size of 1. However, since many spec properties use VEGA defaults (e.g. fontSize) it may be more convenient to use typical VEGA plot sizes.

Plot Coordinates

{
  "width": 640,
  "height": 360,
  "depth": 640,
  ...
  "marks": [
    {
      "type": "rect",
      "encode": {
        "enter": {
          "x": {"value": 320},
          "y": {"value": 180},
          "z": {"value": 320},
          "width": {"value": 32},
          "height": {"value": 32},
          "depth": {"value": 32}
        }
      }
    }
  ]
}

Plot coordinates define the plot dimensions at the top-level of the spec, as well as the position and size of marks. The plot in Listing 1 is 640x360x640 (WxHxD) units in size. The mark is a 32x32x32 cube in the center of the plot at [320, 180, 320] (XYZ).

Note that mark positions and sizes are typically mapped indirectly from data values using a scale, rather than using literal values.

Camera Coordinates

Camera coordinates are defined by a unit cube which encloses the maximum plot dimension (width, height, depth). Using camera coordinates can be convenient, as they are independent of plot size. For example, the center of the plot is always at [0.5, 0.5, 0.5] in camera coordinates, regardless of the plot size.

A camera and lights can optionally be included in the spec, and can be defined in either camera coordinates or plot coordinates.

"camera": {
  "position": [0, 1, 2]
}
...

"lights": [
  {
    "type": "rect",
    "position": [-1, 1, 1],
    "size": 0.5
  }
]

To specify camera and light properties in plot coordinates rather than camera coordinates, use the world prefix, for example worldPosition instead of position.

If the same property is specified in both camera and plot coordinates, the camera coordinates take precedence. For example, if position and worldPosition are both specified for a light, the light will be positioned according to position.

Rendering Coordinates

The canvas size is defined by the renderer and specified in pixels. The size of the canvas is set when creating the renderer, either implicitly from the <canvas> element's size or explicitly via an options object:

const renderer = new WebGPURenderer.Main(canvas, {
  width: 1920,
  height: 1080
});

Rendering coordinates are independent of plot coordinates — changing the canvas size changes the image resolution without affecting the scene.