gg-aframe
A Grammar of Graphics for Virtual Reality Data Visualization using A-Frame.
News
0.2.0
layer-point
- Now uses geometry instancing for 90FPS performance with 10,000+ points
- Rotation speed of each point now mappable with new aesthetic
spin
mod-oscillate
- add additional dimensions tolayer-point
by animating marks between two points in spacescale-shape
- automatically map raw values into usable geometry namesdata-binding
updated to debounce calls toupdate
handlers when multiple properties of a component are bound
Data Binding
The 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
thought of as a simplified, specialized version of the
A-Frame state component
that only handles array data. This allows you to have one central
data repository for the scene with a list of arrays that can be mapped and
synced to any A-Frame component's array properties. The central repository
simplifies the process of bringing data in from other libraries and sources,
as you only need to update in one place to affect the entire scene.
Arrays in the store can be reused to map
to multiple entities and components without any duplication of data,
and updates will cascade changes to mapped components.
data-binding system
The data-binding
system holds a central data store, receives updates to that
store through events, and notifies bindees of updates. It is activated
automatically if data-binding
component is added to any entity in a scene,
but it can also be forced to initialize by adding the data-binding
attribute
to the scene entity.
Updating data
Data is added or updated by emitting the 'update-data'
event with a
data
object that contains arrays as members within the event detail
object.
document
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.
data-binding component
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.
plot
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.
layer-point
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.
mod-oscillate
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.
guide-axis
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).
guide-legend
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.
scale-shape
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 |
Additional scales
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.
theme
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' |
Installation
Browser
Install and use by directly including the browser files:
My A-Frame Scene <!-- plot container location and appearance --> <!-- when the data-binding instance id matches the data store name, source is optional -->
npm
Install via npm:
npm install --save gg-aframe
Then require and use.
;;