@ccp-nc/crystvis-js 0.6.1 → 0.7.0

package/.mocharc.yml

@@ -0,0 +1,4 @@
+require:
+  - ./test/setup-dom.cjs
+spec: test/*.js
+reporter: spec

package/.vscode/settings.json

@@ -1,3 +1,7 @@
 {
-    "python.pythonPath": "/home/phony_stark/miniconda2/bin/python"
+  "files.watcherExclude": {
+    "**/node_modules/**": true,
+    "**/.git/objects/**": true,
+    "**/.git/subtree-cache/**": true
+  }
 }

package/CHANGELOG.md

@@ -5,26 +5,44 @@ All notable changes to crystvis-js will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.6.0] - 2025-07-18
-
-### Changed
-- Updated Three.js from version 0.137 to 0.178
-- Fixed color handling across all primitives to work with new Three.js color management
-- Fixed shader handling for GLSL 3.0 compatibility
-- Improved text rendering with better color handling and transparency
-- Refined material properties for better appearance in the new renderer
+## [0.7.0] - 2026-03-11
 
 ### Added
-- Documentation on Three.js migration
-- Improved error handling for shader compilation
-- Better color space handling for all primitives
+- `CrystVis.dispose()` — full teardown of the WebGL context, animation loop, orbit
+  controls, resize observer and all event listeners. `isDisposed` getter reflects state.
+  Methods throw if called on a disposed instance. (#17)
+- `CrystVis.getCameraState()` / `setCameraState(state)` — snapshot and restore the
+  camera position, target and zoom level as a plain serialisable object. (#20)
+- `CrystVis.onCameraChange(callback)` — subscribe to live camera-change events
+  (rotate / pan / zoom); returns an unsubscribe function. (#20)
+- `CrystVis.getModelSource(name)` — retrieve the raw file text and extension originally
+  passed to `loadModels()`. (#20)
+- `CrystVis.getModelParameters(name)` — retrieve the merged loading parameters used when
+  a model was last loaded or reloaded. (#20)
+- `CrystVis.getModelMeta(name)` — retrieve `{ prefix, originalName }` metadata stored at
+  load time. (#20)
+- `CrystVis.onModelListChange(callback)` — subscribe to events fired whenever the set of
+  loaded models changes (load, delete, unloadAll); returns an unsubscribe function. (#20)
+- `CrystVis.onDisplayChange(callback)` — subscribe to events fired whenever the displayed
+  model changes; callback receives the new model name or `null`. (#20)
+- `CrystVis.unloadAll()` — remove all loaded models atomically (one renderer clear, one
+  set of change events). (#20)
+- `ModelView.toIndices()` — serialise a selection to a plain index array. (#20)
+- `ModelView.toLabels()` — serialise a selection to an array of crystallographic site
+  labels (`crystLabel`), resilient to atom-index reordering. (#20)
+- `Model.viewFromIndices(indices)` — reconstruct a `ModelView` from a saved index array. (#20)
+- `Model.viewFromLabels(labels)` — reconstruct a `ModelView` from a saved label array. (#20)
+- `Renderer.getCameraState()` / `setCameraState(state)` / `onCameraChange(callback)` —
+  lower-level camera state API used by `CrystVis`. (#20)
+- Visualisation of hyperfine tensors from `magres_old` blocks in Magres files as
+  ellipsoids. (#19)
 
 ### Fixed
-- Color issues when upgrading to Three.js 0.178
-- Text rendering and transparency problems
-- Shader compilation errors with GLSL 3.0
-- EllipsoidMesh color handling with different material types
-- Proper handling of atoms and bond materials
+- `loadModels()` return value corrected in README and JSDoc: it returns a status object
+  (keys = model names, values = `0` or error string), not an array. (#18)
+
+### Changed
+- Updated several dependencies. (#12, #13, #16)
 
 ## [0.6.1] - 2026-01-22
 
@@ -34,3 +52,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  - Improved Extended XYZ parsing: stricter handling of atom lines and properties to avoid accidental token merging when input contains stray newlines.
  - Parser now reports clearer errors for malformed Extended XYZ files.
 
+## [0.6.0] - 2025-07-18
+
+### Added
+- Documentation on Three.js migration.
+- Improved error handling for shader compilation.
+- Better color space handling for all primitives.
+
+### Changed
+- Updated Three.js from version 0.137 to 0.178.
+- Fixed color handling across all primitives to work with new Three.js color management.
+- Fixed shader handling for GLSL 3.0 compatibility.
+- Improved text rendering with better color handling and transparency.
+- Refined material properties for better appearance in the new renderer.
+
+### Fixed
+- Color issues when upgrading to Three.js 0.178.
+- Text rendering and transparency problems.
+- Shader compilation errors with GLSL 3.0.
+- EllipsoidMesh color handling with different material types.
+- Proper handling of atoms and bond materials.

package/README.md

@@ -36,7 +36,7 @@ You can then create a visualizer for your webpage by simply importing and instan
 ```js
 import CrystVis from 'crystvis-js';
 
-const visualizer = CrystVis('#target-id', 800, 600)
+const visualizer = new 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:
@@ -44,7 +44,80 @@ will create an 800x600 canvas with the visualizer inside the element specified b
 ```js
 var loaded = visualizer.loadModels(contents);
 console.log('Models loaded: ', loaded);
-visualizer.displayModel(loaded[0])
+// loaded is an object: keys are model names, values are 0 (success) or an error string
+var modelName = Object.keys(loaded)[0];
+if (loaded[modelName] !== 0) {
+    console.error('Failed to load model:', loaded[modelName]);
+} else {
+    visualizer.displayModel(modelName);
+}
+```
+
+### API highlights
+
+Full JSDoc documentation is available at [ccp-nc.github.io/crystvis-js](https://ccp-nc.github.io/crystvis-js/).
+
+#### Camera state — save, restore and react to view changes
+
+```js
+// Snapshot the current camera (position, target, zoom) — plain JSON-serialisable object
+const snap = visualizer.getCameraState();
+// { position: {x,y,z}, target: {x,y,z}, zoom: 1 }
+
+// Restore a previously saved snapshot
+visualizer.setCameraState(snap);
+
+// React to every rotate/pan/zoom (returns an unsubscribe function)
+const unsub = visualizer.onCameraChange(state => {
+    console.log('Camera moved:', state);
+});
+unsub(); // stop listening
+```
+
+#### Lifecycle events — react to model and display changes
+
+```js
+// Fired whenever models are loaded, deleted, or all cleared
+const unsubList = visualizer.onModelListChange(names => {
+    console.log('Loaded models:', names);
+});
+
+// Fired whenever displayModel() completes; receives model name or null
+const unsubDisplay = visualizer.onDisplayChange(name => {
+    console.log('Now displaying:', name);
+});
+
+// Remove all loaded models in one atomic operation
+visualizer.unloadAll();
+```
+
+#### Model metadata — access source and parameters after loading
+
+```js
+// Retrieve the raw file text and extension originally passed to loadModels()
+const src = visualizer.getModelSource(modelName);
+// { text: '...', extension: 'cif' }
+
+// Retrieve the merged loading parameters (supercell, molecularCrystal, …)
+const params = visualizer.getModelParameters(modelName);
+
+// Retrieve prefix and original structure name
+const meta = visualizer.getModelMeta(modelName);
+// { prefix: 'cif', originalName: 'struct' }
+```
+
+#### Selection serialisation — save and reconstruct atom subsets
+
+```js
+// Serialise a selection to plain data
+const indices = visualizer.selected.toIndices(); // number[]
+const labels  = visualizer.selected.toLabels();  // string[] (crystLabel per atom)
+
+// Reconstruct from indices later
+visualizer.selected = visualizer.model.viewFromIndices(indices);
+
+// Reconstruct from labels — resilient to atom-index reordering on reload
+visualizer.selected = visualizer.model.viewFromLabels(labels);
 ```
 
 ### Preparing for development

package/audit.txt

@@ -1,37 +1,24 @@
 ## Security Audit
 # npm audit report
 
-elliptic  *
-Elliptic Uses a Cryptographic Primitive with a Risky Implementation - https://github.com/advisories/GHSA-848j-6mx2-7j84
-No fix available
-node_modules/elliptic
-
-1 low severity vulnerability
-
-Some issues need review, and may require choosing
-a different dependency.
-
-## Security Audit
-# npm audit report
-
-diff  <8.0.3
+diff  6.0.0 - 8.0.2
 jsdiff has a Denial of Service vulnerability in parsePatch and applyPatch - https://github.com/advisories/GHSA-73rr-hh4g-fpgx
 fix available via `npm audit fix --force`
-Will install mocha@0.13.0, which is a breaking change
+Will install mocha@11.3.0, which is a breaking change
 node_modules/diff
-  mocha  0.14.0 - 12.0.0-beta-3
+  mocha  8.0.0 - 12.0.0-beta-3
   Depends on vulnerable versions of diff
+  Depends on vulnerable versions of serialize-javascript
   node_modules/mocha
 
-elliptic  *
-Elliptic Uses a Cryptographic Primitive with a Risky Implementation - https://github.com/advisories/GHSA-848j-6mx2-7j84
-No fix available
-node_modules/elliptic
+serialize-javascript  <=7.0.2
+Severity: high
+Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.toISOString() - https://github.com/advisories/GHSA-5c6j-r48x-rmvq
+fix available via `npm audit fix --force`
+Will install mocha@11.3.0, which is a breaking change
+node_modules/serialize-javascript
 
-3 low severity vulnerabilities
+3 vulnerabilities (1 low, 2 high)
 
-To address all issues possible (including breaking changes), run:
+To address all issues (including breaking changes), run:
   npm audit fix --force
-
-Some issues need review, and may require choosing
-a different dependency.

package/changes.txt

@@ -1,27 +1,2 @@
 ## Updated Packages
--    "chroma-js": "^3.1.2",
-+    "chroma-js": "^3.2.0",
--    "mathjs": "^14.5.3",
-+    "mathjs": "^14.9.1",
--    "@babel/eslint-parser": "^7.28.0",
--    "chai": "^5.2.1",
-+    "@babel/eslint-parser": "^7.28.6",
-+    "chai": "^5.3.3",
--    "elliptic": ">=6.6.1",
--    "esbuild": "^0.25.6",
--    "eslint": "^9.31.0",
-+    "elliptic": "^6.6.1",
-+    "esbuild": "^0.25.12",
-+    "eslint": "^9.39.2",
--    "glob": "^11.0.3",
--    "jpeg-js": ">=0.4.4",
--    "jsdoc": "^4.0.4",
-+    "glob": "^11.1.0",
-+    "jpeg-js": "^0.4.4",
-+    "jsdoc": "^4.0.5",
--    "mocha": "^11.7.1",
--    "msdf-bmfont-xml": "^2.7.0",
-+    "mocha": "^11.7.5",
-+    "msdf-bmfont-xml": "^2.8.0",
--    "serve": "^14.2.4"
-+    "serve": "^14.2.5"
+See package.json diff for details

package/demo/demo.css

@@ -18,13 +18,18 @@
     left: 0;
 }
 
-#colorgrid {
-    display: grid;
-    grid-template-rows: repeat(10, 1fr);
-    grid-template-columns: repeat(30, 1fr);
-
-    width: 300px;
-    height: 300px;
-
-    background-color: #000000;
-}
+#error-banner {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    padding: 10px 16px;
+    background-color: #b00020;
+    color: #fff;
+    font-family: sans-serif;
+    font-size: 14px;
+    font-weight: bold;
+    z-index: 9999;
+    box-sizing: border-box;
+    cursor: pointer;
+}

package/demo/index.html

@@ -16,6 +16,8 @@
             Loading...
         </div>
 
+        <div id="error-banner" style="display:none"></div>
+
         <div style="float: right; width: 30%">
             <table>
                    <caption>Input controls</caption>
@@ -52,12 +54,19 @@
                                 <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
+                                <input id="ellipsoid-check" type="checkbox" name="" value="false" onchange="changeEllipsoids()" disabled>Show MS ellipsoids<br>
+                                Scale: <input id="ms-scale" type="range" min="0.001" max="0.5" step="0.001" value="0.05" oninput="changeMsScale()" disabled> <span id="ms-scale-val">0.050</span>
+                            </td>
+                        </tr>
+                        <tr>
+                            <td colspan="" rowspan="" headers="">
+                                <input id="hf-ellipsoid-check" type="checkbox" name="" value="false" onchange="changeHFEllipsoids()" disabled>Show HF ellipsoids<br>
+                                Scale: <input id="hf-scale" type="range" min="0.001" max="1.0" step="0.001" value="0.1" oninput="changeHfScale()" disabled> <span id="hf-scale-val">0.100</span>
                             </td>
                         </tr>
                         <tr>
                           <td>
-                            <input id="isosurf-check" type="checkbox" name="" value="false" onchange="changeIsosurface()">Show isosurface
+                            <input id="isosurf-check" type="checkbox" name="" value="false" onchange="changeIsosurface()" disabled>Show isosurface
                           </td>
                           <td>
                               <input type="text" id="vdw-f" size="5" value="1.0"> Van der Waals scaling
@@ -77,11 +86,29 @@
                             </td>
                             
                         </tr>
+                        <tr>
+                            <td colspan="2"><hr style="margin:6px 0"><strong>Camera state</strong></td>
+                        </tr>
+                        <tr>
+                            <td>
+                                <input type="button" value="Save view" onclick="saveCamera()">
+                                <input type="button" value="Restore view" onclick="restoreCamera()">
+                            </td>
+                            <td>
+                                <input type="button" value="Copy JSON" onclick="copyCameraJSON()">
+                                <input type="button" value="Apply JSON" onclick="applyPastedJSON()">
+                            </td>
+                        </tr>
+                        <tr>
+                            <td colspan="2">
+                                <textarea id="camera-json" rows="5" style="width:100%;font-family:monospace;font-size:11px;box-sizing:border-box" placeholder="Camera state will appear here…" spellcheck="false"></textarea>
+                            </td>
+                        </tr>
+                        <tr>
+                            <td colspan="2" id="camera-status" style="font-size:11px;color:#555"></td>
+                        </tr>
                    </tbody>
            </table> 
-           <div id='colorgrid'>
-               
-           </div>
         </div>
 
     </div>

package/demo/main.js

@@ -3,43 +3,15 @@
 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;
 visualizer.theme = 'dark';
 
-// 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);
-
-    }
+function showError(msg) {
+    var banner = document.getElementById('error-banner');
+    banner.textContent = msg + '  (click to dismiss)';
+    banner.style.display = 'block';
+    banner.onclick = function() { banner.style.display = 'none'; };
 }
 
 window.loadFile = function() {
@@ -57,17 +29,54 @@ window.loadFile = function() {
     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
-        });
+        var loaded;
+        try {
+            loaded = visualizer.loadModels(reader.result, extension, name, {
+                supercell: [sx, sy, sz],
+                molecularCrystal: mcryst,
+                vdwScaling: vdwf
+            });
+        } catch (e) {
+            showError('Could not load file: ' + e.message);
+            return;
+        }
 
-        visualizer.displayModel(Object.keys(loaded)[0]);
+        var modelName = Object.keys(loaded)[0];
+        if (loaded[modelName] !== 0) {
+            showError('Failed to load "' + modelName + '": ' + loaded[modelName]);
+            return;
+        }
+        visualizer.displayModel(modelName);
         visualizer.displayed = visualizer.model.find({
             'all': []
         });
 
+        // Update checkbox/slider states based on available data in the loaded model
+        var model = visualizer.model;
+
+        var ellipsoidCheck = document.getElementById('ellipsoid-check');
+        var msSlider = document.getElementById('ms-scale');
+        var hasMs = model.hasArray('ms');
+        ellipsoidCheck.disabled = !hasMs;
+        msSlider.disabled = !hasMs;
+        if (!hasMs && ellipsoidCheck.checked) {
+            ellipsoidCheck.checked = false;
+            visualizer.displayed.removeEllipsoids('ms');
+        }
+
+        var hfEllipsoidCheck = document.getElementById('hf-ellipsoid-check');
+        var hfSlider = document.getElementById('hf-scale');
+        var hasHf = model.hasArray('hf');
+        hfEllipsoidCheck.disabled = !hasHf;
+        hfSlider.disabled = !hasHf;
+        if (!hasHf && hfEllipsoidCheck.checked) {
+            hfEllipsoidCheck.checked = false;
+            visualizer.displayed.removeEllipsoids('hf');
+        }
+
+        // Isosurface only makes sense once a model (with a cell) is loaded
+        document.getElementById('isosurf-check').disabled = false;
+
     };
 }
 
@@ -89,21 +98,55 @@ window.changeLabels = function() {
 
 window.changeEllipsoids = function() {
     var val = document.getElementById('ellipsoid-check').checked;
+    var scale = parseFloat(document.getElementById('ms-scale').value);
     if (val) {
         visualizer.displayed.find({
             'elements': 'H'
         }).addEllipsoids((a) => {
             return a.getArrayValue('ms');
         }, 'ms', {
-            scalingFactor: 0.05,
+            scalingFactor: scale,
             opacity: 0.2
         });
-
     } else {
         visualizer.displayed.removeEllipsoids('ms');
     }
 }
 
+window.changeMsScale = function() {
+    document.getElementById('ms-scale-val').textContent = parseFloat(document.getElementById('ms-scale').value).toFixed(3);
+    if (document.getElementById('ellipsoid-check').checked) {
+        window.changeEllipsoids();
+    }
+}
+
+window.changeHFEllipsoids = function() {
+    var val = document.getElementById('hf-ellipsoid-check').checked;
+    var scale = parseFloat(document.getElementById('hf-scale').value);
+    if (val) {
+        // Show HF (hyperfine) tensor ellipsoids for all atoms that have data
+        visualizer.displayed.addEllipsoids((a) => {
+            try {
+                return a.getArrayValue('hf');
+            } catch(e) {
+                return null;
+            }
+        }, 'hf', {
+            scalingFactor: scale,
+            opacity: 0.3
+        });
+    } else {
+        visualizer.displayed.removeEllipsoids('hf');
+    }
+}
+
+window.changeHfScale = function() {
+    document.getElementById('hf-scale-val').textContent = parseFloat(document.getElementById('hf-scale').value).toFixed(3);
+    if (document.getElementById('hf-ellipsoid-check').checked) {
+        window.changeHFEllipsoids();
+    }
+}
+
 var isosurface = null;
 window.changeIsosurface = function() {
     var val = document.getElementById('isosurf-check').checked;
@@ -152,4 +195,68 @@ window.displayMessage = function() {
 // clear messages
 window.clearMessages = function() {
     visualizer.clearNotifications();
-}
+}
+
+// ─── Camera state demo ───────────────────────────────────────────────────────
+
+// Keep a snapshot of the last saved camera state so Restore can use it.
+var _savedCameraState = null;
+
+/** Pretty-print a camera state snapshot into the textarea. */
+function updateCameraTextarea(state) {
+    var ta = document.getElementById('camera-json');
+    if (ta) ta.value = JSON.stringify(state, null, 2);
+}
+
+/** Mark the status line briefly then clear it. */
+function setCameraStatus(msg) {
+    var el = document.getElementById('camera-status');
+    if (!el) return;
+    el.textContent = msg;
+    clearTimeout(el._timer);
+    el._timer = setTimeout(() => { el.textContent = ''; }, 2500);
+}
+
+// Live-update the textarea whenever the user rotates / pans / zooms.
+visualizer.onCameraChange(function(state) {
+    updateCameraTextarea(state);
+});
+
+/** Save the current camera position so it can be restored later. */
+window.saveCamera = function() {
+    _savedCameraState = visualizer.getCameraState();
+    updateCameraTextarea(_savedCameraState);
+    setCameraStatus('View saved.');
+};
+
+/** Restore the most recently saved camera snapshot. */
+window.restoreCamera = function() {
+    if (!_savedCameraState) {
+        setCameraStatus('Nothing saved yet — click Save view first.');
+        return;
+    }
+    visualizer.setCameraState(_savedCameraState);
+    setCameraStatus('View restored.');
+};
+
+/** Copy the current textarea JSON to the clipboard. */
+window.copyCameraJSON = function() {
+    var ta = document.getElementById('camera-json');
+    if (!ta || !ta.value) { setCameraStatus('Nothing to copy yet.'); return; }
+    navigator.clipboard.writeText(ta.value)
+        .then(() => setCameraStatus('Copied to clipboard.'))
+        .catch(() => { ta.select(); document.execCommand('copy'); setCameraStatus('Copied (fallback).'); });
+};
+
+/** Parse whatever is in the textarea and apply it as the camera state. */
+window.applyPastedJSON = function() {
+    var ta = document.getElementById('camera-json');
+    if (!ta || !ta.value) { setCameraStatus('Textarea is empty.'); return; }
+    try {
+        var state = JSON.parse(ta.value);
+        visualizer.setCameraState(state);
+        setCameraStatus('Camera state applied.');
+    } catch (e) {
+        setCameraStatus('Invalid JSON: ' + e.message);
+    }
+};