{"id":13733667,"url":"https://github.com/vriajs/vria","last_synced_at":"2025-10-24T01:31:12.131Z","repository":{"id":49358970,"uuid":"304720050","full_name":"vriajs/vria","owner":"vriajs","description":"A Web-based Framework for Creating Immersive Analytics Experiences","archived":false,"fork":false,"pushed_at":"2021-06-17T12:48:50.000Z","size":4703,"stargazers_count":48,"open_issues_count":0,"forks_count":15,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-01-30T22:18:54.651Z","etag":null,"topics":["augmented-reality","charts","data-visualization","immersive-analytics","virtual-reality","visualization","webxr"],"latest_commit_sha":null,"homepage":"https://vriajs.github.io/vria","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vriajs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-16T19:24:26.000Z","updated_at":"2024-11-06T04:25:59.000Z","dependencies_parsed_at":"2022-08-27T11:03:46.285Z","dependency_job_id":null,"html_url":"https://github.com/vriajs/vria","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vriajs%2Fvria","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vriajs%2Fvria/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vriajs%2Fvria/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vriajs%2Fvria/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vriajs","download_url":"https://codeload.github.com/vriajs/vria/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237901410,"owners_count":19384384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["augmented-reality","charts","data-visualization","immersive-analytics","virtual-reality","visualization","webxr"],"created_at":"2024-08-03T03:00:47.181Z","updated_at":"2025-10-24T01:31:03.250Z","avatar_url":"https://github.com/vriajs.png","language":"JavaScript","funding_links":[],"categories":["Research"],"sub_categories":["Motion Controllers inside Unity!"],"readme":"![VRIA GitHub Teaser](https://pbutcher.uk/files/vria/img/vria-github-teaser.png)\n\n---\n\n\u003cimg align=\"right\" width=\"200\" height=\"82\" src=\"https://pbutcher.uk/files/vria/img/vria-github-logo.png\"\u003e\n\n# VRIA\n\n[![NPM](https://img.shields.io/npm/v/vria.svg?color=blue)](https://www.npmjs.com/package/vria) [![LICENSE](https://img.shields.io/github/license/vriajs/vria?color=blue)](https://github.com/vriajs/vria/blob/master/LICENSE)\n\nA Web-Based Framework for Creating Immersive Analytics Experiences\n\nTry it in your browser: https://vriajs.github.io/vria\n\n## Contents\n\n- [What is VRIA?](#what-is-vria)\n  - [VRIA Grammar](#vria-grammar)\n  - [What's in the package?](#whats-in-the-package)\n- [Basic usage](#basic-usage)\n- [VRIA `aframe-react` Component and API](#vria-aframe-react-component-and-api)\n  - [Props API Reference](#props-api-reference)\n    - [config](#config)\n    - [onConfigParsed](#onconfigparsed)\n    - [additionalFilters](#additionalfilters)\n    - [onFilter](#onfilter)\n    - [setFilters](#setfilters)\n    - [onSelection](#onselection)\n    - [setSelection](#setselection)\n    - [customMarks](#custommarks)\n    - [options](#options)\n  - [Config Validation](#config-validation)\n- [VRIA Builder](#vria-builder)\n- [VRIA Boilerplate](#vria-boilerplate)\n- [Team](#team)\n- [Publications](#publications)\n  - [Citation](#citation)\n- [License](#license)\n\n---\n\n## What is VRIA?\n\nVRIA is a Web-based framework for creating Immersive Analytics experiences in virtual and augmented reality. Built with [React](https://reactjs.org), [A-Frame](https://aframe.io), and [D3](https://d3js.org), VRIA lets you rapidly create interactive, immersive data visualizations with a declarative grammar described in JSON. Powered by [WebXR](https://immersiveweb.dev/), the scenes you create with VRIA can be accessed immediately on a growing number of [supported devices](https://immersiveweb.dev/#supporttable) and [browsers](https://caniuse.com/webxr). Extra functionality can be added to immersive scenes with VRIA's API.\n\n### VRIA Grammar\n\nVRIA visualizations are defined with a declarative grammar described in JSON. VRIA's grammar is similar to those of [Vega-Lite](https://vega.github.io/vega-lite) and [DxR](https://github.com/ronellsicat/DxR).\n\nPlease refer to the [VRIA Grammar Definition](https://docs.google.com/spreadsheets/d/1WdzG45G8_wPnhOeLuEgZEYGCOWJqBhzJeYFBL7Pbdf0) and/or the [VRIA JSON Schema](https://github.com/vriajs/vria/tree/master/src/grammar/schema/vria-schema-v1.0.json).\n\n### What's in the package?\n\nVRIA's NodeJS module is separated into three parts:\n\n1. The VRIA `aframe-react` component and API. [[docs](#vria-aframe-react-component)]\n2. The VRIA Builder: An end-to-end tool for learning and rapidly prototyping immersive Web-based visualizations. [[docs](#vria-builder)]\n3. A boilerplate environment to create your first standalone VRIA application. [[docs](#vria-boilerplate)]\n\n---\n\n## Basic Usage\n\nTo get started with VRIA, you can experiment with the hosted version of the VRIA Builder online: https://vriajs.github.io/vria\n\nTo add VRIA to a new or existing project you will need:\n\n- [NodeJS](https://nodejs.org) (\u003e= v10.0).\n- You will also need to install [`react`](https://npmjs.org/package/react) and [`react-dom`](https://npmjs.org/package/react-dom) if you haven't already. The easiest way to get started with a new React project is via [create-react-app](https://create-react-app.dev/docs/getting-started/) _(recommended)_.\n  - Alternatively, you can add React later and start off by installing VRIA on its own by cloning this repository and using the `boilerplate/` directory to create your first VRIA app [[docs](#vria-boilerplate)]. The VRIA Builder is also available to install locally in the `builder/` directory [[docs](#vria-builder)].\n- Finally, you will need to include the A-Frame library script in the `\u003chead\u003e` of your `index.html` file:\n\n```html\n\u003cscript src=\"https://aframe.io/releases/1.0.4/aframe.min.js\"\u003e\u003c/script\u003e\n```\n\n### Installing VRIA\n\nYou can add VRIA to a new or existing application by installing it with [Yarn](https://yarnpkg.com) or [NPM](https://npmjs.org):\n\n```bash\nyarn add vria\n```\n\nor\n\n```bash\nnpm install vria\n```\n\nYou can then include VRIA in your project:\n\n```jsx\nimport VRIA from 'vria';\n```\n\n### Run the development server\n\nIf you are using `create-react-app` you can run either `yarn start` or `npm start` to start the development server.\n\nYour app will now be running at `localhost:3000`.\n\nYou can then include VRIA in your project, something like this:\n\n```jsx\n// index.js\n\nimport React from 'react';\nimport ReactDOM from 'react-dom';\nimport { Scene } from 'aframe-react';\nimport VRIA from 'vria';\n\nconst config = {\n  title: 'My first VRIA app',\n  data: {\n    values: [\n      { a: 'A', b: 1 },\n      { a: 'B', b: 2 }\n    ]\n  },\n  mark: 'bar',\n  encoding: {\n    x: { field: 'a', type: 'nominal' },\n    y: { field: 'b', type: 'quantitative' }\n  }\n};\n\nconst App = () =\u003e (\n  \u003cScene\u003e\n    \u003cVRIA config={config} /\u003e\n  \u003c/Scene\u003e\n);\n\nReactDOM.render(\u003cApp /\u003e, document.getElementById('root'));\n```\n\n### Create a production build\n\nYou can build your app for production to the `build/` directory by running either `yarn build` or `npm run build`.\n\n---\n\n## VRIA `aframe-react` Component and API\n\nThe VRIA `aframe-react` component is an A-Frame entity, wrapped up in a React component. It can be passed A-Frame props (e.g. `position` and `rotation` etc.), as well as props to access VRIA API features.\n\nYou can include other A-Frame components and assets inside the `\u003cScene\u003e` element. Entities can be added with [aframe-react](https://www.npmjs.com/package/aframe-react)'s `\u003cEntity\u003e` component:\n\n```jsx\n\u003cScene\u003e\n  \u003ca-assets timeout='70000'\u003e\n    \u003cimg src='myimage.jpg' id='myimage' /\u003e\n  \u003c/a-assets\u003e\n  \u003cEntity\n    primitive='a-image'\n    width='1.5'\n    height='1.5'\n    src='#myimage'\n    rotation='-90 -90 0'\n    position='0 0 0'\n  /\u003e\n  \u003cVRIA config={config} /\u003e\n  \u003cEntity environment={{ preset: 'default' }} /\u003e\n\u003c/Scene\u003e\n```\n\nIn the above example the `config` prop is used to load a VRIA vis-config as JSON. The `config` prop is the only required prop, and all visualization functionality can be acheived with it. See [VRIA Grammar](#vria-grammar).\n\nVRIA exposes a set of props that can be used to integrate a scene with other libraries and user-defined features. For example, additional filters can be added to other features of a multi-variate dataset with user-defined interaction components (e.g. buttons, sliders etc.).\n\n### Props API Reference\n\n- [config](#config)\n- [onConfigParsed](#onconfigparsed)\n- [additionalFilters](#additionalfilters)\n- [onFilter](#onfilter)\n- [setFilters](#setfilters)\n- [onSelection](#onselection)\n- [setSelection](#setselection)\n- [customMarks](#custommarks)\n- [options](#options)\n\n#### `config`\n\n_required_ **[object]**\n\nThe `config` prop contains a VRIA vis-config as JSON and must be supplied when the VRIA component is rendered. See [VRIA Grammar](#vria-grammar) for details on how to structure a VRIA vis-config.\n\n#### `onConfigParsed`\n\n_optional_ **[function]**\n\nThe `onConfigParsed` prop should be passed a function which will be called whenever VRIA compiles a vis-config update. This function will be passed an object containing the following:\n\n| Property         | Type                                                                                            | Description                               |\n| ---------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------- |\n| `compiledConfig` | _object_                                                                                        | The compiled VRIA vis-config              |\n| `dataset`        | _object array_                                                                                  | The parsed dataset                        |\n| `domainMap`      | [_Map()_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) | The state of visualization domain filters |\n| `scales`         | _object array_                                                                                  | Scale functions from each VRIA view       |\n\nExample usage:\n\n```jsx\n\u003cVRIA\n  config={config}\n  onConfigParsed={({ compiledConfig, dataset, domainMap, scales }) =\u003e {\n    // Do something once the vis-config is compiled\n  }}\n/\u003e\n```\n\n#### `additionalFilters`\n\n_optional_ **[object array]**\n\nThe `additionalFilters` prop is used to list field names and domains of the dataset that the user would like to filter from the visualization. From this it is possible to create a custom filter component for each of these additional fields. Fields must not already be included in any of the encoding channels in the vis-config. Custom filters can have the following properties:\n\n| Key      | Required | Default                                                                                                          | Possible Values                                                  | Description                                                                     |\n| -------- | -------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| `field`  | Yes      | -                                                                                                                | _string_: field name                                             | A field of the dataset                                                          |\n| `type`   | Yes      | -                                                                                                                | _string_: `quantitative` \\| `nominal` \\| `ordinal` \\| `temporal` | Field data type                                                                 |\n| `zero`   | No       | false                                                                                                            | _boolean_                                                        | Whether the domain should start from zero (quantitative only)                   |\n| `domain` | No       | For quantitative data types: extent [min, max] or [0, max] if `zero`ed. Other data types: complete set of values | _number array_ \\| _string array_                                 | Set the domain of this field. This sets the filtered state of a field's domain. |\n\nFor example, a vis-config already containing the fields `horsepower` and `miles_per_gallon` can have `top_speed` and `cylinders` added as additional filters:\n\n```jsx\n\u003cVRIA\n  config={config}\n  additionalFilters={[\n    {\n      field: 'top_speed',\n      type: 'quantitative'\n    },\n    {\n      field: 'cylinders',\n      type: 'ordinal',\n      domain: [4, 5, 6]\n    }\n  ]}\n/\u003e\n```\n\nNotice how `cylinders` has a domain specified. This would have the effect of filtering the dataset based on this domain whereas `top_speed` does not yet have a domain filter applied.\n\nAdditional filters are normally specified when a visualization is created so that they may later be filtered with the [`onFilter`](#onfilter) callback and [`setFilters`](#setfilters) function.\n\n#### `onFilter`\n\n_optional_ **[function]**\n\nThe `onFilter` prop should be passed a function that will be called whenever a filter is updated in a VRIA visualization or by a user-defined filter that is attached to the [`setFilters`](#setfilters) prop.\n\nThis function will be passed a [Map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) containing the current state of all field domains in a VRIA visualization, including any domains that were specified in the [`additionalFilters`](#additionalFilters) prop.\n\nThis prop can be used to send the state of VRIA filters across the network in a multi-user environment, or for use in other parts of your application.\n\n| Argument    | Type                                                                                            | Description                                              |\n| ----------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------- |\n| `domainMap` | [_Map()_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) | Current state of visualization filters by field=\u003edomain. |\n\nExample usage:\n\n```jsx\n\u003cVRIA\n  config={config}\n  onFilter={(domainMap) =\u003e {\n    // Do something with the current visualization filter state\n  }}\n/\u003e\n```\n\n#### `setFilters`\n\n_optional_ **[Map()]**\n\nThe `setFilters` prop should be passed a [Map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) containing the updated state of all field domains in a VRIA visualization, including any domains that were specified in the [`additionalFilters`](#additionalFilters) prop. The latest filter state can be retrieved from the [`onFilter`](#onfilter) prop whenever the filter state changes.\n\nThis prop can be used to set the state of VRIA filters received from across the network in a multi-user environment, or to update the visualization filters from elsewhere in your application.\n\n#### `onSelection`\n\n_optional_ **[object]**\n\nThe `onSelection` prop should be passed a function that will be called whenever a selection is made in a VRIA visualization. The function will be passed an object containing the following properties:\n\n| Property  | Type                                                                                            | Description                                                                        |\n| --------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |\n| `data`    | _array_                                                                                         | An array of objects containing data points from the selection                      |\n| `dataMap` | [_Map()_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) | A mapping of each mark's class name to its respective data point in the selection. |\n| `marks`   | _array_                                                                                         | An array of the class names of each mark in the selection                          |\n\nThis prop can be used to send the state of VRIA selections across the network in a multi-user environment, or for use in other parts of your application.\n\n```jsx\n\u003cVRIA\n  config={config}\n  onSelection={(selection) =\u003e {\n    // Do something with the current selection state\n  }}\n/\u003e\n```\n\n#### `setSelection`\n\n_optional_ **[object]**\n\nThe `setSelection` prop should be passed an object containing details of a selection to be made in a VRIA visualization. It should match the structure of the object received from the [`onSelection`](#onselection) prop.\n\nThis prop can be used to set the state of VRIA selections from across the network in a multi-user environment, or to update the visualization selections from elsewhere in your application.\n\n#### `customMarks`\n\n_optional_ **[object]**\n\nCustom marks can be added to visualizations via the vis-config and `customMarks` prop. Custom marks are A-Frame entities or models. A custom mark can make use of data from all encoding channels in a vis-config which are accessible to them as props. Here is an example of a custom mark:\n\n```jsx\nconst customMark = (props) =\u003e (\n  \u003cEntity scale={`${props.width} ${props.height} ${props.depth}`}\u003e\n    \u003cEntity\n      primitive='a-box'\n      height='0.6'\n      position='0 -0.3 0'\n      color={props.color}\n    /\u003e\n    \u003cEntity\n      primitive='a-box'\n      height='0.4'\n      depth='0.6'\n      position='0 0.2 0'\n      color={props.color}\n    /\u003e\n  \u003c/Entity\u003e\n);\n```\n\nThis example makes use of the dimension and color encoding channels, but every encoding channel is available to use via props. To include this mark in a visualization, the name of the mark should be used in place of the mark type in the vis-config. More than one custom mark can be used at a time inside the `customMarks` prop object. Here's how the `customMarks` prop would look with our mark definition above.\n\n```jsx\n\u003cVRIA config={config} customMarks={{ customMark, otherCustomMark }} /\u003e\n```\n\n#### `options`\n\n_optional_ **[object]**\n\nThe `options` prop is used to pass overrides for some general VRIA settings:\n\n| Option        | Default | Possible Values                                 | Description                                                                 |\n| ------------- | ------- | ----------------------------------------------- | --------------------------------------------------------------------------- |\n| `userHeight`  | 1.6     | _number_                                        | The height of the user in the scene in metres                               |\n| `handedness`  | both    | _string_: `left` \\| `right` \\| `both` \\| `none` | Which controllers to render                                                 |\n| `multiSelect` | false   | _boolean_                                       | Whether to accept single or multiple concurrent mark selections from a user |\n| `chartColor`  | #000000 | _string_                                        | The base color of all chart components                                      |\n| `selectColor` | #00FF00 | _string_                                        | The color a mark will change to when it is selected by the user             |\n\nFor example, to change the `chartColor` to white and `selectColor` to red:\n\n```jsx\n\u003cVRIA\n  config={config}\n  options={{\n    chartColor: '#FFFFFF',\n    selectColor: '#FF0000'\n  }}\n/\u003e\n```\n\n### Config validation\n\nAlthough VRIA will validate your vis-config at runtime, sometimes you may wish to valid a VRIA vis-config against the VRIA JSON Schema before passing it to VRIA. To do this you can run it through the validator with the `validateVisConfig` named export:\n\n```jsx\nimport { validateVisConfig, schema } from 'vria';\nimport config from './config';\n\n// Validate a vis-config\nconsole.log(validateVisConfig(config));\n```\n\nThis example also shows you how to access the VRIA JSON Schema if you wish to do your own validation.\n\n---\n\n## VRIA Builder\n\nThe VRIA Builder: An end-to-end tool for learning and rapidly prototyping immersive Web-based visualizations. It is available online at: https://vriajs.github.io/vria and as part of this package.\n\nTo use the VRIA builder locally, follow these instructions:\n\n1. Clone or fork the VRIA Git repository\n2. Navigate to `builder/`\n3. Run `yarn install` or `npm install`\n4. Run `yarn start` or `npm start`\n\nThe builder is now running at `localhost:3000`\n\nRun `yarn build` or `npm run build` to create a production ready build of the VRIA builder to `builder/build`.\n\n---\n\n## VRIA Boilerplate\n\nThe VRIA Boilerplate is a way to quickly get started with VRIA without starting a new project from scratch. To use the boilerplate application, follow these instructions:\n\n1. Clone or fork the VRIA Git repository\n2. Navigate to `boilerplate/`\n3. Run `yarn install` or `npm install`\n4. Run `yarn start` or `npm start`\n\nThe boilerplate example is now running at `localhost:3000`\n\nRun `yarn build` or `npm run build` to create a production ready build of your app to `boilerplate/build`.\n\n---\n\n## Team\n\nVRIA is in ongoing development by the Visualization, Modeling and Graphics Research Group at Bangor University, UK, led by [Peter Butcher](https://twitter.com/pwsbutcher) and [Panagiotis Ritsos](https://twitter.com/ritsos_p).\n\n---\n\n## Publications\n\n_VRIA: A Web-based Framework for Creating Immersive Analytics Experiences_\n\n📃 Journal article available on IEEE Xplore: https://ieeexplore.ieee.org/document/8954824\n\nPublished in: [IEEE Transactions on Visualization and Computer Graphics](https://ieeexplore.ieee.org/xpl/RecentIssue.jsp?punumber=2945) (Early Access) - Presented virtually at [IEEE VIS 2020](http://ieeevis.org/year/2020/welcome).\n\n### Citation\n\n```bib\n@ARTICLE{8954824,\n  author={P. W. S. {Butcher} and N. W. {John} and P. D. {Ritsos}},\n  journal={IEEE Transactions on Visualization and Computer Graphics},\n  title={VRIA: A Web-based Framework for Creating Immersive Analytics Experiences},\n  year={2020},\n  volume={},\n  number={},\n  pages={1-1},\n}\n```\n\n---\n\n## License\n\nMIT © Copyright 2020 [Peter W. S. Butcher](https://twitter.com/pwsbutcher), [Nigel W. John](https://twitter.com/nigeljohn12) and [Panagiotis D. Ritsos](https://twitter.com/ritsos_p) - University of Chester, UK (Visualization, Interaction and Graphics Research Group) and Bangor University, UK (Visualization, Modeling and Graphics Research Group) - All rights reserved\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvriajs%2Fvria","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvriajs%2Fvria","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvriajs%2Fvria/lists"}