Wave.js

Web-based Atomic Viewer and Editor in JavaScript. Wave.js is a library for atomic visualization and editing written in JavaScript enabling visualization of material structures from atoms up on the web. The library is aimed to be used for the development of web applications in JavaScript.

The library was originally designed as part of and presently powers materials design capabilities of the Exabyte.io platform. For example, this page representing a crystal of Silicon online uses Wave.js.

Exabyte.io believe in a collaborative future of materials design on the web.

Functionality

As below:

• the package provides a web environment for the visualization of atomic structures and is written in ECMAScript 2015 (ES6) for use on the web
• ESSE Data Convention is employed to organize and store information [1] via Made.js
• THREE.js is used for 3d visualization purposes
• High-level classes for the representation of the viewer and modular ES6-compatible mixins for the associated functionality, ie:
  • Atoms,
  • Cell,
  • Controls,
  • Mouse,
  • and others to be added.
• wrapper components for React:
  • ThreeDEditor, with control trigger button panels
  • WaveComponent,

The package is written in a modular way easy to extend. Contributions can be in the form of additional functionality modules developed, or feature requests and bug/issue reports.

Installation

From NPM for use within a software project:

npm install @exabyte-io/wave.js

From source to contribute to development:

git clone [email protected]:Exabyte-io/wave.git

Contribution

This repository is an open-source work-in-progress and we welcome contributions.

Why contribute?

We regularly deploy the latest code containing all accepted contributions online as part of the Exabyte.io platform, so contributors will see their code in action there.

Adding new functionality

We suggest forking this repository and introducing the adjustments there to be considered for merging into this repository as explained in more details here, for example.

Source code conventions

Wave.js is written in EcmaScript 6th edition [2] with the application of object-oriented design patterns encapsulating key concepts following the conventions below.

1. One main class exposing the functionality with a set of mixins (implemented through mixwith) containing domain-specific functionality inside mixins folder

2. The implementation of the viewer uses a native HTML node to initialize a Three.js rendering context, components folder further contains the wrapper React components for convenient use in web applications.

TODO list

Desirable features for implementation:

• selection buffers
• scripting console
• other (TBA)

Tests

There are two types of tests: asserting Wave class functionality and testing React components. Wave class tests use snapshot testing in which an snapshot of the WebGL [3] context is taken and compared with the reference. The test will fail if the two snapshots do not match. This is admittedly a bit fragile, and future work may improve the test coverage such that this is no longer necessary. React component tests use Enzyme [4] that makes DOM manipulation and traversal easier.

Since snapshots may be slightly different depending on operating systems, they are versioned by the operating system on which they were generated. We currently support macos, ubuntu, and centos. This can be picked up in a test run by setting REACT_APP_BASE_OS=(current OS) and are tested both on ubuntu (on branches) and centos (on dev) in CI. A docker-compose.yml is provided for convenience which defaults to using ubuntu (see .env) so that there are 3 options for running tests:

# In an ubuntu container
docker-compose build
docker-compose run test

# OR in a centos container
BASE_OS=centos docker-compose build
BASE_OS=centos docker-compose run test

# OR if you're on a mac
npm install
npm test

Important Notes

1. Keep the tests directory structure similar to the main codebase directory structure. Every JS module in the main codebase should have a corresponding module in tests directory which implements the tests for provided functionality.

2. Add tests fixtures into fixtures directory. The fixtures will be automatically stored on Git LFS [6].

3. Add Jest configuration into setupFiles module.

4. Use setupFilesAfterEnv module to implement tests hooks.

5. Make sure to use async keyword for Wave class tests as they are asynchronous.

Dependencies

This package depends on Made.js, as well as a slightly modified version of Three.js. See package.json for the full list.

Links

1. Exabyte Source of Schemas and Examples (ESSE), Github Repository

2. ECMAScript 2015 Language Specifications

3. Headless GL, Github Repo

4. Enzyme, A JavaScript Testing Utility For React, Github Repo

5. Jest Testing Framework, Official Website

6. Git LFS, Official Website

Cove.js local development

In case you need to link Cove.js into the app for local development you need

1. Add local path of Cove.js to package.json

    "@exabyte-io/code.js": "file:../../cove.js"

2. Run the app

    npm start

If you need to re-link it again, remove node_modules in cove.js and the app, run npm install, then run npm start again.