@ccp-nc/crystvis-js 0.4.13

package/README.md

@@ -0,0 +1,76 @@
+# crystvis-js
+
+A [Three.js](https://threejs.org/) based crystallographic visualisation tool. It reads multiple file formats and renders them with WebGL to a `canvas` element, allowing the user to interact with them. A few of the key functionality:
+
+* visualize popular file formats as ball-and-stick structures, easily embedded within a webpage, with orbit mouse control for rotation and zooming;
+* interactive visualisation responsive to user clicks via customizable callbacks;
+* high definition text labels;
+* advanced searching and selection functions to interact with specific subset of atoms (select by proximity, bonding, species and more);
+* smart visualisation of molecular crystal: reconstruct full molecules across the periodic boundary;
+* compute and display isosurfaces from volumetric data;
+* visualize tensor data as ellipsoids centred on atoms.
+
+### Supported formats 
+
+The currently supported file formats are the following:
+
+* **CIF**, using [crystcif-parse](https://github.com/stur86/crystcif-parse);
+* **XYZ**, including Extended XYZ such as the one written by the [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/);
+* **CELL**, input file supported by the DFT package [CASTEP](http://www.castep.org/);
+* **Magres**, output file format for simulated NMR parameters used by CASTEP and Quantum Espresso and developed by the [CCP for NMR Crystallography](https://www.ccpnc.ac.uk/).
+
+### Getting started 
+
+In order to install `crystvis-js`, simply use the Node Package Manager:
+
+```bash
+npm install crystvis-js --save
+```
+
+You can then create a visualizer for your webpage by simply importing and instantiating it:
+
+```js
+import CrystVis from 'crystvis-js';
+
+const visualizer = CrystVis('#target-id', 800, 600)
+```
+
+will create an 800x600 canvas with the visualizer inside the element specified by the given selector. To load a model, simply load the contents of your file as a text string and then pass them to the visualizer's `loadModels` method:
+
+```js
+var loaded = visualizer.loadModels(contents);
+console.log('Models loaded: ', loaded);
+visualizer.displayModel(loaded[0])
+```
+
+### Preparing for development
+
+If you want to develop for crystvis-js, you should follow these steps:
+
+* fork the repository
+* clone the forked repository locally to your system
+* install all the required packages, *including the development dependencies*, with `npm install --production=false`
+
+You're then ready to develop. In particular you can use:
+
+* `npm test` to run with Mocha the suite of tests found in `./test`
+* `npm start` to start a server that includes the in-browser tests from `./test/test-html` as well as the demo from `./demo`
+* `npm run docs` to compile the documents
+* `npm run deploy-docs` to compile the documents and then deploy them to the `gh-pages` branch of your repository
+
+#### Fonts and shaders
+
+Some additional steps are necessary when dealing with fonts and shaders. You generally shouldn't worry about these when working 
+with most of the code, but in some special cases it might be necessary to do this.
+
+Fonts in crystvis-js need to be translated to a bitmap format to be usable. In other words, a regular font format (like a TTF file)
+must be rendered into a bitmap texture and a table of coordinates designating each letter to then be used in graphical rendering. This operation
+relies on the library `msdf-bmfont-xml` and is executed by running the command `npm run build-fonts`. The original fonts are found in
+the `./fonts` folder, and they get rendered to `./lib/assets/fonts`. This command needs only to be rerun *if the TTF files change*.
+
+Shaders are provided as `.frag` and `.vert` files. Both shaders and font textures need to baked directly into the JavaScript files in order to be 
+included in the final build. Since ESBuild (the package used to build crystvis-js) has a hard time dealing with them in the final pass, they get
+pre-baked with an additional step that only needs to be repeated whenever either of them changes. This consists of taking "template" JS files (for
+shaders it's `./lib/shaders/index.in.js`, for fonts `./lib/assets/fonts/bmpfonts.in.js`) and rebuilding them into final files with the 
+assets imported in data URL form. The script to do this is `npm run build-resources`. This command only needs to be rerun *if the fonts were rebuilt, if the shader
+code was edited, or if any of the two template files was changed*.

package/demo/demo.css

@@ -0,0 +1,30 @@
+#main-app {
+    position: relative;
+    background-color: #002030;
+    width: 40vw;
+    height: 60vh;
+
+    color: white;
+    font-size: 30pt;
+    font-weight: bold;
+    font-family: sans-serif;
+    text-align: center;
+    line-height: 30vh;
+}
+
+#main-app canvas {
+    position: absolute;
+    top: 0;
+    left: 0;
+}
+
+#colorgrid {
+    display: grid;
+    grid-template-rows: repeat(10, 1fr);
+    grid-template-columns: repeat(30, 1fr);
+
+    width: 300px;
+    height: 300px;
+
+    background-color: #000000;
+}

package/demo/index.html

@@ -0,0 +1,76 @@
+<!doctype html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <title></title>
+    <link rel="stylesheet" href="demo.css">
+
+    <script src="demo.js" type="text/javascript" charset="utf-8" async defer></script>
+</head>
+<body>
+    
+    <div style="width: 100%; height: 100%">
+
+        <div style="float: left" id="main-app">
+            Loading...
+        </div>
+
+        <div style="float: right; width: 30%">
+            <table>
+                   <caption>Input controls</caption>
+                   <tbody>
+                       <tr>
+                           <td>            
+                                <input id="file-load" type="file" value="Load file">
+                           </td>
+                           <td>
+                                Supercell: 
+                               <input id="scell-x" type="text" size="3">
+                               <input id="scell-y" type="text" size="3">
+                               <input id="scell-z" type="text" size="3">
+                           </td>
+                       </tr>
+                       <tr>
+                           <td>
+                               <input type="button" name="" value="Load file" onclick="loadFile()">
+                           </td>
+                           <td>
+                             <input id="molcryst-check" type="checkbox" name="" value="" placeholder="">Load as molecular crystal
+                           </td>
+                       </tr>
+                       <tr>
+                            <td>
+                                <input type="button" name="" value="Show unit cell" onclick="changeDisplayed({'cell': [[0,0,0]]})">
+                            </td>
+                            <td>
+                                <input type="button" name="" value="Show 5 Ang sphere" onclick="changeDisplayed({'sphere': [[0,0,0], 5.0]})">
+                            </td>
+                       </tr>
+                        <tr>
+                            <td colspan="" rowspan="" headers="">
+                                <input id="label-check" type="checkbox" name="" value="false" onchange="changeLabels()">Show labels
+                            </td>
+                            <td colspan="" rowspan="" headers="">
+                                <input id="ellipsoid-check" type="checkbox" name="" value="false" onchange="changeEllipsoids()">Show ellipsoids
+                            </td>
+                        </tr>
+                        <tr>
+                          <td>
+                            <input id="isosurf-check" type="checkbox" name="" value="false" onchange="changeIsosurface()">Show isosurface
+                          </td>
+                          <td>
+                              <input type="text" id="vdw-f" size="5" value="1.0"> Van der Waals scaling
+                          </td>
+                        </tr>
+                   </tbody>
+           </table> 
+           <div id='colorgrid'>
+               
+           </div>
+        </div>
+
+    </div>
+
+</body>
+</html>

package/demo/main.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const CrystVis = require('../lib/visualizer.js').CrystVis;
+const Primitives = require('../lib/primitives/index.js');
+
+const shiftCpkColor = require('../lib/utils').shiftCpkColor;
+
+var visualizer = new CrystVis('#main-app', 0, 0);
+visualizer.highlight_selected = true;
+
+// Generate color grid (for testing shiftCpkColor)
+const gridEl = document.getElementById('colorgrid');
+const gridSize = 10;
+
+function int2hex(c) {
+    c = c.toString(16);
+    return '0'.repeat(6-c.length) + c;
+}
+
+for (let i = 0; i < gridSize; ++i) {
+    for (let j = 0; j < gridSize; ++j) {
+
+        const hue = parseInt(j/gridSize*360);
+        const light = parseInt(i/(gridSize-1)*100);
+        const cbase = `hsl(${hue}, 100%, ${light}%)`;
+        const cplus = shiftCpkColor(cbase, 1.0);
+        const cminus = shiftCpkColor(cbase, -1.0);
+
+        let el = document.createElement('div');
+        el.style['background-color'] = '#' + int2hex(cminus);
+        gridEl.append(el);
+
+        el = document.createElement('div');
+        el.style['background-color'] = cbase;
+        gridEl.append(el);
+
+        el = document.createElement('div');
+        el.style['background-color'] = '#' + int2hex(cplus);
+        gridEl.append(el);
+
+    }
+}
+
+window.loadFile = function() {
+    var file = document.getElementById('file-load').files[0];
+    var reader = new FileReader();
+    var extension = file.name.split('.').pop();
+
+    var sx = parseInt(document.getElementById("scell-x").value) || 1;
+    var sy = parseInt(document.getElementById("scell-y").value) || 1;
+    var sz = parseInt(document.getElementById("scell-z").value) || 1;
+
+    var vdwf = parseFloat(document.getElementById("vdw-f").value) || 1;
+
+    reader.readAsText(file);
+    reader.onload = function() {
+        var mcryst = document.getElementById('molcryst-check').checked;
+        var name = file.name.split('.')[0];
+        var loaded = visualizer.loadModels(reader.result, extension, name, {
+            supercell: [sx, sy, sz],
+            molecularCrystal: mcryst,
+            vdwScaling: vdwf
+        });
+
+        visualizer.displayModel(Object.keys(loaded)[0]);
+        visualizer.displayed = visualizer.model.find({
+            'all': []
+        });
+
+    };
+}
+
+window.changeDisplayed = function(query) {
+    var select = visualizer.model.find(query);
+    visualizer.displayed = select;
+}
+
+window.changeLabels = function() {
+    var val = document.getElementById('label-check').checked;
+    if (val) {
+        visualizer.displayed.addLabels((a, i) => (a.crystLabel), 'labels', (a, i) => ({
+            shift: [1.2*a.radius, 0, 0]
+        }));
+    } else {
+        visualizer.displayed.removeLabels('labels');
+    }
+}
+
+window.changeEllipsoids = function() {
+    var val = document.getElementById('ellipsoid-check').checked;
+    if (val) {
+        visualizer.displayed.find({
+            'elements': 'H'
+        }).addEllipsoids((a) => {
+            return a.getArrayValue('ms');
+        }, 'ms', {
+            scalingFactor: 0.05,
+            opacity: 0.2
+        });
+
+    } else {
+        visualizer.displayed.removeEllipsoids('ms');
+    }
+}
+
+var isosurface = null;
+window.changeIsosurface = function() {
+    var val = document.getElementById('isosurf-check').checked;
+
+    // Create the data
+    var field = [];
+    for (let x = 0; x < 30; x += 1) {
+        field.push([]);
+        for (let y = 0; y < 30; y += 1) {
+            field[x].push([]);
+            for (let z = 0; z < 30; z += 1) {
+                var r = Math.pow(x-15, 2);
+                r += Math.pow(y-15, 2);
+                r += Math.pow(z-15, 2);
+                r = Math.sqrt(r);
+                var phi = Math.acos((z-15)/r);
+                field[x][y].push(r-Math.cos(3*phi)*0.2);
+            }
+        }
+    }
+
+
+    if (val) {
+        var cell =  visualizer.model.cell;
+        isosurface = new Primitives.IsosurfaceMesh(field, 7.0, cell, 
+            {
+                opacityMode: Primitives.IsosurfaceMesh.RENDER_WFRAME,
+                isoMethod: Primitives.IsosurfaceMesh.ISO_SURFACE_NETS
+            });
+        visualizer.addPrimitive(isosurface);
+        isosurface.color = '#ff0000';
+    } else {
+        if (isosurface) {
+            visualizer.removePrimitive(isosurface);
+        }
+    }
+
+}

package/docs-tutorials/Events.md

@@ -0,0 +1,57 @@
+User interactions with a model in CrystVis-js can be customised through the definition of callbacks for *events*. This means it's possible to bind arbitrary JavaScript code
+to the various ways in which a user can click on an atom in the model. To do this, one needs to use the `.onAtomClick()` method of a `CrystVis` object, as well as its flags.
+
+### Defining an event
+
+A custom event can be set by defining a callback function, then assigning that function to a specific click event. Here is an example:
+
+```js
+function myCallback(atom, event) {
+    alert(atom.element);
+}
+
+visualizer.onAtomClick(myCallback, CrystVis.LEFT_CLICK)
+```
+
+This code will result in binding a function that causes a popup to show with the chemical symbol of an atom's element whenever you left click on one.
+
+### Flags
+
+Which event a callback should be bound to is defined by the flags passed as the second argument to `.onAtomClick()`. These are the available flags:
+
+ * `CrystVis.LEFT_CLICK`
+ * `CrystVis.RIGHT_CLICK`
+ * `CrystVis.MIDDLE_CLICK`
+ * `CrystVis.CTRL_BUTTON`
+ * `CrystVis.ALT_BUTTON`
+ * `CrystVis.SHIFT_BUTTON`
+ * `CrystVis.CMD_BUTTON`
+
+Note that `CMD_BUTTON` is only used on Macs and equivalent to `CTRL_BUTTON` on other machines. These are bit flags, so they can be combined with addition or bitwise operators. For 
+example, `CrystVis.LEFT_CLICK + CrystVis.SHIFT_BUTTON` represents a click with the shift key down. Each combinations of flags can only hold one callback function; if `null` is passed
+instead of a callback, default behaviour is restored.
+
+### Default behaviour
+
+Most events by default are bound to nothing, mean, nothing will happen unless you define a specific behaviour for them. There are only three exceptions to this:
+
+* `CrystVis.LEFT_CLICK` defaults to selecting the clicked atom
+* `CrystVis.LEFT_CLICK + CrystVis.SHIFT_BUTTON` defaults to adding the clicked atom to selection
+* `CrystVis.LEFT_CLICK + CrystVis.CTRL_BUTTON` defaults to switching the clicked atom in or out of the selection
+
+To best see how the selection changes, set `.highlightSelected = true`.
+
+### Box selection
+
+In addition to the various events described above, there is a special behaviour. Clicking while pressing Shift on a point that does *not* have an atom allows the user to drag
+a box around multiple atoms, for example to select them in group. This behaviour can also be customized, by setting a callback with the method `.onAtomBox()`. Here is an example:
+
+```js
+function boxCallback(atomview) {
+    alert(atomview.map((atom) => atom.element));
+}
+
+visualizer.onAtomBox(boxCallback)
+```
+
+that will create an alert popup with a list of all the elements in the selected box.

package/docs-tutorials/Queries.md

@@ -0,0 +1,50 @@
+In CrystVis-js, it's possible to use the `.find()` method in `Model` and `ModelView` objects to retrieve atoms based on various search criteria. The `.find()` method takes as argument a *query*; these queries are structured in a way that's inspired by queries used for example in the MongoDB interface. It's worth taking a minute to learn how they work.
+
+### Basic structure of a query
+
+A query passed to the `.find()` method has to be an object. Typically, a query unit is structured as follows:
+
+```js
+var query = {
+    "query_name": ["argument_1", "argument_2", ...]
+}
+```
+
+where the appropriate actual name and arguments of course must be replaced. For example, one might use
+
+```js
+var H_atoms = model.find({
+    "elements": ["H"]
+})
+```
+
+to identify all hydrogen atoms within the model. The functions accepted for queries by a model are the following:
+
+* `all` (no arguments): return all atoms in the model
+* `indices` (`indices`): return all atoms with the given index or Array of indices
+* `elements` (`elems`): return all atoms with the given element or one of an Array of elements
+* `cell` (`ijk`): return atoms within the cell with indices i, j and k
+* `box` (`x0`, `x1`): return atoms inside a box defined by two corners (points or atoms)
+* `sphere` (`x0`, `r`): return atoms inside a sphere defined by a center (point or atom) and a radius
+* `bonded` (`atoms`, `distance`, `exact`): return atoms within a certain number of bonds ("distance") from one or more atoms. For example, asking for all atoms within one bond from the oxygen in a water molecule will return the whole molecule. If "exact" is set to true instead, only atoms at the exact distance will be returned. In the water molecule example, this would return only the hydrogens
+* `molecule` (`atoms`): return all atoms belonging to the same molecule as one of the atoms passed as argument
+
+### Boolean operators
+
+In addition to the simple functions described above, queries accept boolean operators that can be used to build more complex ones. For example one could use this query:
+
+```js
+var query = {
+    "$and": [{
+        "elements": [["H", "C"]]
+    }, {
+        "sphere": [[0, 0, 0], 4.0]
+    }]
+}
+```
+
+to retrieve all atoms of either hydrogen or carbon located within a radius of 4 Angstroms from the origin of the cell. A boolean operator takes more queries as arguments, which means they can be nested further for more complex searches. The accepted boolean operators are the following:
+
+* `$and` (`query_1`, `query_2`, ...): returns the intersection of all the passed queries
+* `$or` (`query_1`, `query_2`, ...): returns the union of all the passed queries
+* `$xor` (`query_1`, `query_2`, ...): return the exclusive OR of all queries (in other words, any atom that is returned by only one query but no other)

package/fonts/Rubik/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2015 The Rubik Project Authors (https://github.com/googlefonts/rubik),
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/fonts/Rubik/README.txt

@@ -0,0 +1,77 @@
+Rubik Variable Font
+===================
+
+This download contains Rubik as both variable fonts and static fonts.
+
+Rubik is a variable font with this axis:
+  wght
+
+This means all the styles are contained in these files:
+  Rubik-VariableFont_wght.ttf
+  Rubik-Italic-VariableFont_wght.ttf
+
+If your app fully supports variable fonts, you can now pick intermediate styles
+that aren’t available as static fonts. Not all apps support variable fonts, and
+in those cases you can use the static font files for Rubik:
+  static/Rubik-Light.ttf
+  static/Rubik-Regular.ttf
+  static/Rubik-Medium.ttf
+  static/Rubik-SemiBold.ttf
+  static/Rubik-Bold.ttf
+  static/Rubik-ExtraBold.ttf
+  static/Rubik-Black.ttf
+  static/Rubik-LightItalic.ttf
+  static/Rubik-Italic.ttf
+  static/Rubik-MediumItalic.ttf
+  static/Rubik-SemiBoldItalic.ttf
+  static/Rubik-BoldItalic.ttf
+  static/Rubik-ExtraBoldItalic.ttf
+  static/Rubik-BlackItalic.ttf
+
+Get started
+-----------
+
+1. Install the font files you want to use
+
+2. Use your app's font picker to view the font family and all the
+available styles
+
+Learn more about variable fonts
+-------------------------------
+
+  https://developers.google.com/web/fundamentals/design-and-ux/typography/variable-fonts
+  https://variablefonts.typenetwork.com
+  https://medium.com/variable-fonts
+
+In desktop apps
+
+  https://theblog.adobe.com/can-variable-fonts-illustrator-cc
+  https://helpx.adobe.com/nz/photoshop/using/fonts.html#variable_fonts
+
+Online
+
+  https://developers.google.com/fonts/docs/getting_started
+  https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide
+  https://developer.microsoft.com/en-us/microsoft-edge/testdrive/demos/variable-fonts
+
+Installing fonts
+
+  MacOS: https://support.apple.com/en-us/HT201749
+  Linux: https://www.google.com/search?q=how+to+install+a+font+on+gnu%2Blinux
+  Windows: https://support.microsoft.com/en-us/help/314960/how-to-install-or-remove-a-font-in-windows
+
+Android Apps
+
+  https://developers.google.com/fonts/docs/android
+  https://developer.android.com/guide/topics/ui/look-and-feel/downloadable-fonts
+
+License
+-------
+Please read the full license text (OFL.txt) to understand the permissions,
+restrictions and requirements for usage, redistribution, and modification.
+
+You can use them freely in your products & projects - print or digital,
+commercial or otherwise. However, you can't sell the fonts on their own.
+
+This isn't legal advice, please consider consulting a lawyer and see the full
+license for all details.