DXR - Grammar Docs

Grammar Docs

This documentation describes the high-level grammar that can be used to specify visualizations in DXR. DXR's grammar was intentionally designed to be similar to that of Vega-Lite in order to make it easier for a subset of the visualization community, i.e., Vega-Lite users, to transition into immersive vis development. We highly recommend that you visit Vega-Lite's website, if you miss to find something here, since their documentation is more robust in some cases.

Please use the Grammar Docs link on the top of the page for faster navigation. You can also visit the multi-tab Google Sheets grammar docs.

How to Read the Docs

Instead of using a schema, DXR's grammar is currently documented in a Google spreadsheet that shows the JSON specification syntax where name-value pairs are used to describe the visualization properties.

Nested properties are shown in the first columns (Property: Level #), e.g., the channel property (level 2) can be described by specifying its field, type, and scale properties (level 3). Below is a subset of the grammar documentation that shows some of the core properties in the grammar. Nesting levels are color coded in the spreadsheet and in the example vis specs below for illustration purposes only, i.e., level 1 is shown in red font, level 2 in blue, level 3 in green, and level 4 in purple.

Possible values for some properties are provided for guidance, e.g., for the data url, a *.json file (e.g., cars.json) or a *.csv file (e.g., streamline.csv) can be provided. The JSON Type column specifies what type the property value should be in. A JSON object is simply a collection of name-value pairs enclosed in { }, an array is a collection of comma separated values enclosed in [ ], a number is interpreted as a float in DXR, while a boolean can be either a true or false value.

Vis Specs Example

Note that the above visualization contains interaction components toggleFilter and thresholdFilter that allow interactive filtering of the visualized data according to selected data attributes.

Vis Specs Inferrence

In order to enable concise specifications, DXR provides an inference mechanism which takes in a concise vis specs and infers the best default parameters to describe a complete visualization. Below is an example showing the input vis specs from the user (left), and the resulting inferred complete vis specs (right), which generates the same visualization as the one above. This inferrence is similar in spirit to the Vega-Lite to Vega compilation, though in DXR's case, the input and inferred output has the same syntax and grammar.

During development, you can expand the vis specs to the inferred version by checking the "Enable Specs Expansion" option in the Inspector window (shown below) when the DXRVis object is selected.

Input Concise Vis Specs

To expand the vis specs to the inferred version, check the "Enable Specs Expansion" option in the Inspector window when the DXRVis object is selected as shown below, then click the "Update Vis" button.

Grammar Docs

How to Read the Docs

Vis Specs Example

Vis Specs Inferrence

Input Concise Vis Specs

Inferred Complete Vis Specs