A Grammar of Graphics for Virtual Reality Data Visualization using A-Frame
npm install gg-aframelayer-point
spin
mod-oscillate - add additional dimensions to layer-point by
scale-shape - automatically map raw values into usable geometry names
data-binding updated to debounce calls to update handlers when
data-binding component and system help get data from any source into
gg-aframe plots and keep it synchronized for interactive plots. It can be
data-binding system holds a central data store, receives updates to that
data-binding component is added to any entity in a scene,
data-binding attribute
'update-data' event with a
data object that contains arrays as members within the event detail object.
js
document.querySelector('a-scene').emit('update-data', {data: {array1: [...], array2: [...]}})
`
Each array will be added to the store if new or updated if it already exists,
and updates will propagate to any bound components. Any data store arrays
not included in the update will be left as-is.
$3
Add this component to bind arrays from the central store to components on
an entity. Multiple bindings can be added to an entity with the
data-binding__id="" syntax, where id is a unique identifier for
each data-binding component instance.
| Property | Description | Default Value |
| -------- | ----------- | ------------- |
| source | Name of an array in the data store | ''* |
| target | Name of schema property, as 'component.property', on a sibling component to bind (optional) | '' |
\* If source is omitted, will attempt to use the component multiple id as the
source name. Note: this only works for source names that are all lower case.
Once bound, the target property will be assigned to be the same array object
as the data store. data-binding will ensure the target component's
update method is called whenever the data store is updated.
Alternatively, omit target property and
access the boundData property of the component
or in the details of data-changed events.
Treat the bound data as read-only. If modified in the target component or
bound-data component, changes will be reflected across the entire system to
all bindees, but they will not be notified of the change, causing loss of sync.
Instead, use the update-data event on the system to make changes to the data.
| Event Type | Description | Details object |
| --- | --- | --- |
| 'data-changed' | Update received from the data-binding system | boundData: the bound array |
Plot Container
The plot container holds all other plot elements as children, and handles
some high level management and defaults.
$3
Place the plot component on the parent entity containing
all layers, guides, et cetera.
At present, it merely manages the locations of any guide-legend entities.
In the future, it will also be able to set default theme values and
aesthetic mappings for all children.
plot adds a collision zone that covers the plot area
itself (not including the guides) to support interactivity. This consists of
box geometry and static-body components.
Layers
A plot can have one or more layers which add the visual aspects to a plot by
mapping data to aesthetic properties to create marks such as points or lines.
Aesthetic properties are always arrays.
Required aesthetics for a layer must have a value for each mark and
have the same length. Optional aesthetics can either have one value for each
mark or a single default value that will be used for all marks.
If not specified,
optional aesthetic default values will be determined by the theme.
Layers expect aesthetic data to already be scaled, e.g. x, y, and z
in a range of 0 to 1.
$3
layer-point creates a 3D scatterplot by placing primitive geometries as marks
at x, y, and z coordinates.
| Aesthetic Property | Description | Default Value |
| -------- | ----------- | ------------- |
| x | x coordinates | Required |
| y | y coordinates | Required |
| z | z coordinates | Required |
| shape | Geometry primitive for each mark | [] |
| size | Size of each mark (scaling percentage) | [] |
| color | Color of each mark | [] |
| spin | Rotation speed of each mark (radians per second) | [] |
More layers to come...
Modifiers
This is an experimental API for layer add-ons. Modifier components
can be added to entities
alongside layers to add additional functionality or alter behavior.
$3
Add additional dimensions to a layer by animating a positional aesthetic
back-and-forth between two values.
| Property | Description | Default |
| --- | --- | --- |
| layer | Name of layer component to modify | 'layer-point' |
| x | x coordinates to oscillate towards | [] |
| y | y coordinates to oscillate towards | [] |
| z | z coordinates to oscillate towards | [] |
| duration | Milliseconds per movement | 1000 |
Compatible layers: layer-point
Guides
Guides explain the scaling and mapping in a plot.
$3
Add ticks, labels, title, and interaction zones for a positional aesthetic.
| Property | Description | Default Value |
| -------- | ----------- | ------------- |
| axis | x, y, or z axis | 'x' |
| title | Array of length 1. Name of axis mapping. | [''] |
| breaks | Array. Positions along the axis for ticks. | [] |
| labels | Array. Text to display at each break. | [] |
title, breaks, and labels are arrays and can be bound with data-binding.
guide-axis adds collision zones to its entity to support interactivity.
These consist of a plane geometry and box static-body for the axis
planes on each side of the plot. These can be interactively
highlighted by toggling the visible property of material on the
guide-axis entity, and the color and texture are set by the
highlightColor and highlightTexture properties of theme
(textures are rotated so that the
top of the image aligns with larger values on the axis).
$3
Add a legend for a non-positional aesthetic
| Property | Description | Default Value |
| -------- | ----------- | ------------- |
| aesthetic | color, shape, or size | 'color' |
| title | Array of length 1. Name of axis mapping. | [''] |
| breaks | Array. Aesthetic values to display | [] |
| labels | Array. Text to display at each break | [] |
title, breaks, and labels are arrays and can be bound with data-binding.
guide-legend adds collision a zone to its entity consisting
of a plane geometry and box static-body set just behind the
labels and marks of the guide. This can be interactively
highlighted by toggling the visible property of material on the
guide-axis entity, and the color and texture are set by the
highlightColor and highlightTexture properties of theme.
Scales
Scales map from raw data into aesthetic values. Scales are added to the
plot entity and will perform data mapping for all layers and
guides which utilize the aesthetic.
$3
Map data into geometric shapes for the shape aesthetic.
#### API
scale-shape takes a single property naming the set of shapes to use from
the list below.
| Name | Description | Max Levels |
| --- | --- | --- |
| identity | Does no mapping. Use when the data in the shape variable has already been mapped to geometry names. | |
| primitives | Default. Map up to 10 levels using all available primitive geometries | 10: sphere, box, cone, torus, torusKnot, cylinder, tetrahedron, octahedron, dodecahedron, and icosahedron |
| spinnable | Shapes which can clearly portray rotation for the spin aesthetic | 6: tetrahedron, box, octahedron, dodecahedron, icosahedron, torus |
| sizable | Shapes which are scaled to have equivalent volume in order to accurately portray variations in the size aesthetic | 6: sphere, box, icosahedron, dodecahedron, octahedron, tetrahedron |
| platonic | The platonic solids in increasing order of complexity. Suitable for ranked/ordered scales and best graphical performance | 5: tetrahedron, box, octahedron, dodecahedron, icosahedron |
$3
While additional scales are still in development,
use your favorite visualization library to
scale the data before passing it in. See my
adit application for an example
of doing this using ggplot2 in R.
Themes
Themes determine the values to use for properties that aren't mapped to data,
such as label font size, as well as default values to use for optional
aesthetics.
$3
Layers, guides, and the plot container all have the theme component attached.
| Property | Description | Default Value |
| -------- | ----------- | ------------- |
| size | Size of geometric marks, approximately equal to radius | 0.01 |
| shape | Primitive shape for geometric marks | 'sphere' |
| color | Color of geometric marks | 'black' |
| spin | Rotation speed of geometric marks (radians per second) | 0 |
| font | A-Frame text component font specification | 'roboto' |
| fontScale | Text scale factor | '0.75' |
| fontColor | Text color | '#000' |
| guideWidth | Size of legends | '0.3' |
| guideHeight | Size of legends | '0.3' |
| guideMargin | Padding within legends | '0.1' |
$3
#### Browser
Install and use by directly including the browser files:
`html
My A-Frame Scene
geometry material="color: red; transparent: true; opacity: 0.5; side: back"
position="0 1.6 -1.25" rotation="0 35 0">
data-binding__x="target: layer-point.x"
data-binding__y="target: layer-point.y"
data-binding__z="target: layer-point.z"
data-binding__size="target: layer-point.size"
data-binding__shape="target: layer-point.shape"
data-binding__color="target: layer-point.color"
data-binding__spin="target: layer-point.spin">
data-binding__breaks="target: guide-axis.breaks"
data-binding__labels="target: guide-axis.labels"
data-binding__xtitle="target: guide-axis.title">
data-binding__breaks="target: guide-axis.breaks"
data-binding__labels="target: guide-axis.labels"
data-binding__ytitle="target: guide-axis.title">
data-binding__breaks="target: guide-axis.breaks"
data-binding__labels="target: guide-axis.labels"
data-binding__ztitle="target: guide-axis.title">
data-binding__colortitle="target: guide-legend.title"
data-binding__colorbreaks="target: guide-legend.breaks">
data-binding__shapetitle="target: guide-legend.title">
data-binding__sizetitle="target: guide-legend.title"
data-binding__sizelabels="target: guide-legend.labels"
data-binding__sizebreaks="target: guide-legend.breaks">
`
#### npm
Install via npm:
`bash
npm install --save gg-aframe
`
Then require and use.
`js
require('aframe');
require('gg-aframe');
``