@ccp-nc/crystvis-js 0.6.1 → 0.7.1

package/lib/formats/magres.js

@@ -120,6 +120,146 @@ const MagresParsers = {
     isc: parseTwoAtomLine
 };
 
+/**
+ * Parse the magres_old block to extract hyperfine (HF) tensors and the
+ * magnetogyric ratios table.
+ *
+ * The magres_old block is free-text output produced by older CASTEP versions.
+ * Each atom section looks like:
+ *
+ *   ============
+ *   Atom: H        1
+ *   ============
+ *   H        1 Coordinates  ...
+ *
+ *   TOTAL tensor
+ *
+ *      a11   a12   a13
+ *      a21   a22   a23
+ *      a31   a32   a33
+ *
+ *   H        1 Eigenvalue  A_xx  ...
+ *   ...
+ *   H        1 Iso:  ... (MHz)
+ *
+ * The tensor values are in MHz.
+ *
+ * The header table looks like either:
+ *   H      Isotope   1             GAMMA =  2.6752E+08 rad T-1 s-1
+ *   H:Mu    User defined.            GAMMA =  8.5162E+08 rad T-1 s-1
+ *
+ * @param {string}  text        Contents of the magres_old block
+ * @param {Array}   mlabels     Array of [species, index] pairs for each atom
+ * @param {int}     N           Number of atoms
+ * @returns {Object}            { hf_data: Array<TensorData|null>,
+ *                                gamma_ratios: Object<string, {isotope, gamma}> }
+ */
+function parseMagresOldBlock(text, mlabels, N) {
+    const lines = text.split('\n');
+    const hf_data = new Array(N).fill(null);
+    const gamma_ratios = {};   // species label → { isotope: int|null, gamma: float }
+
+    let current_sp = null;
+    let current_idx = null;
+    // 'idle' | 'reading_rows' | 'waiting_eigenvalue_label'
+    let state = 'idle';
+    let tensor_rows = [];
+    let pending_tensor = null;
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+
+        // Parse magnetogyric ratio table lines:
+        //   "H      Isotope   1             GAMMA =  2.6752E+08 rad T-1 s-1"
+        //   "H:Mu    User defined.            GAMMA =  8.5162E+08 rad T-1 s-1"
+        const gamma_iso_match = line.match(/^(\S+)\s+Isotope\s+(\d+)\s+GAMMA\s*=\s*([+-]?[\d.]+E[+-]?\d+)/i);
+        if (gamma_iso_match) {
+            gamma_ratios[gamma_iso_match[1]] = {
+                isotope: parseInt(gamma_iso_match[2]),
+                gamma: parseFloat(gamma_iso_match[3])
+            };
+            continue;
+        }
+        const gamma_user_match = line.match(/^(\S+)\s+User defined\.\s+GAMMA\s*=\s*([+-]?[\d.]+E[+-]?\d+)/i);
+        if (gamma_user_match) {
+            gamma_ratios[gamma_user_match[1]] = {
+                isotope: null,
+                gamma: parseFloat(gamma_user_match[2])
+            };
+            continue;
+        }
+
+        // Look for "Atom: ELEM INDEX"
+        const atom_match = line.match(/^Atom:\s+(\S+)\s+(\d+)$/);
+        if (atom_match) {
+            current_sp = atom_match[1];
+            current_idx = parseInt(atom_match[2]);
+            state = 'idle';
+            tensor_rows = [];
+            pending_tensor = null;
+            continue;
+        }
+
+        // Look for the "TOTAL tensor" header (exact match – not "TOTAL Shielding Tensor" etc.)
+        if (line === 'TOTAL tensor') {
+            state = 'reading_rows';
+            tensor_rows = [];
+            pending_tensor = null;
+            continue;
+        }
+
+        if (state === 'reading_rows' && current_sp !== null) {
+            if (line === '') continue;
+
+            const parts = line.split(/\s+/).filter(s => s !== '');
+            const nums = parts.map(parseFloat);
+
+            if (nums.length === 3 && nums.every(n => !isNaN(n))) {
+                tensor_rows.push(nums);
+                if (tensor_rows.length === 3) {
+                    // Matrix complete – wait for Eigenvalue label to confirm it's HF
+                    pending_tensor = tensor_rows.slice();
+                    state = 'waiting_eigenvalue_label';
+                    tensor_rows = [];
+                }
+            } else {
+                // Unexpected non-numeric line – abort
+                state = 'idle';
+                tensor_rows = [];
+            }
+            continue;
+        }
+
+        if (state === 'waiting_eigenvalue_label' && current_sp !== null) {
+            if (line === '') continue;
+
+            // Look for "SPECIES INDEX Eigenvalue LABEL VALUE"
+            // HF tensors use A_xx / A_yy / A_zz.
+            // EFG uses V_xx, shielding uses sigma_xx – we skip those.
+            const eval_match = line.match(/Eigenvalue\s+(\S+)/);
+            if (eval_match) {
+                const label = eval_match[1]; // e.g. A_xx, V_xx, sigma_xx
+                if (label.startsWith('A_')) {
+                    // Confirmed hyperfine – store the tensor
+                    const idx = _.findIndex(mlabels, x =>
+                        x[0] === current_sp && x[1] === current_idx
+                    );
+                    if (idx >= 0) {
+                        hf_data[idx] = new TensorData(pending_tensor);
+                    }
+                }
+                // Any other label (V_xx, sigma_xx, …) – silently discard
+                state = 'idle';
+                pending_tensor = null;
+            }
+            // Non-eigenvalue lines (could be blank) – keep waiting
+            continue;
+        }
+    }
+
+    return { hf_data, gamma_ratios };
+}
+
 function load(contents, filename='magres') {
 
     const known_blocks = ['atoms', 'magres'];
@@ -275,7 +415,10 @@ function load(contents, filename='magres') {
         for (let i = 0; i < ablock.atom.lines.length; ++i) {
             let l = ablock.atom.lines[i];
 
-            elems.push(l[0]);
+            // CASTEP custom species use the form ELEMENT:LABEL (e.g. H:Mu).
+            // Strip the colon-suffix to recover a valid element symbol while
+            // keeping the full species identifier in mlabels/labels for lookup.
+            elems.push(l[0].split(':')[0]);
             mlabels.push([l[1], parseInt(l[2])]);
             labels.push(l[1]);
             pos.push(_.map(l.slice(3,6), function(x) {
@@ -360,6 +503,18 @@ function load(contents, filename='magres') {
 
     }
 
+    // Parse hyperfine tensors and gamma ratios from magres_old block
+    const magres_old_text = blocks['magres_old'];
+    if (magres_old_text && typeof magres_old_text === 'string') {
+        const { hf_data, gamma_ratios } = parseMagresOldBlock(magres_old_text, mlabels, N);
+        if (hf_data.some(d => d !== null)) {
+            atoms.set_array('hf', hf_data);
+        }
+        if (Object.keys(gamma_ratios).length > 0) {
+            atoms.info['hf-gyromagnetic-ratios'] = gamma_ratios;
+        }
+    }
+
     let structs = {};
     structs[filename] = atoms;
 

package/lib/model.js

@@ -1776,6 +1776,37 @@ class Model {
         return new ModelView(this, indices);
     }
 
+    /**
+     * Reconstruct a {@link ModelView} from a plain array of atom-image indices,
+     * as produced by {@link ModelView#toIndices}.  This is the stable public API
+     * for deserialising a saved selection.
+     *
+     * @param  {number[]} indices
+     * @return {ModelView}
+     */
+    viewFromIndices(indices = []) {
+        return this.view(indices);
+    }
+
+    /**
+     * Reconstruct a {@link ModelView} from an array of crystallographic site
+     * labels (`crystLabel`), as produced by {@link ModelView#toLabels}.  This
+     * is resilient to atom-index reordering across reloads.
+     *
+     * @param  {string[]} labels
+     * @return {ModelView}
+     */
+    viewFromLabels(labels = []) {
+        const wanted = new Set(labels);
+        const indices = [];
+        for (let i = 0; i < this._atom_images.length; ++i) {
+            if (wanted.has(this._atom_images[i].crystLabel)) {
+                indices.push(i);
+            }
+        }
+        return this.view(indices);
+    }
+
     /**
      * Set a property on a series of atom images
      *

package/lib/modelview.js

@@ -440,6 +440,30 @@ class ModelView {
             return this;
     }
 
+    // ─── Serialisation helpers ───────────────────────────────────────────────────
+
+    /**
+     * Return a plain array of the atom-image indices in this view.
+     * Use this to serialise a selection; restore it with
+     * {@link Model#viewFromIndices}.
+     *
+     * @return {number[]}
+     */
+    toIndices() {
+        return Array.from(this._indices);
+    }
+
+    /**
+     * Return the crystallographic site labels (`crystLabel`) of the atoms
+     * in this view.  Use this to serialise a selection in a way that is
+     * robust to atom reordering; restore with {@link Model#viewFromLabels}.
+     *
+     * @return {string[]}
+     */
+    toLabels() {
+        return this._images.map(a => a.crystLabel);
+    }
+
 }
 
 export {

package/lib/render.js

@@ -116,7 +116,8 @@ class Renderer {
 
         // Raycast for clicks
         this._rcastlist = [];
-        this._r.domElement.addEventListener('pointerdown', this._raycastClick.bind(this));
+        this._boundRaycastClick = this._raycastClick.bind(this);
+        this._r.domElement.addEventListener('pointerdown', this._boundRaycastClick);
 
         // Groups
         this._groups = {
@@ -162,7 +163,7 @@ class Renderer {
     }
 
     _animate() {
-        requestAnimationFrame(this._animate.bind(this));
+        this._animFrameId = requestAnimationFrame(this._animate.bind(this));
         this._render();
     }
 
@@ -335,6 +336,48 @@ class Renderer {
         _.pull(this._sboxlist, sbl);
     }
 
+    /**
+     * Tear down the renderer, cancelling the animation loop, removing all canvas
+     * event listeners (orbit controls, raycaster, selection box), disconnecting any
+     * ResizeObserver, and releasing the WebGL context.  After this call the instance
+     * must not be used again.
+     */
+    dispose() {
+        // 1. Stop the animation loop
+        if (this._animFrameId != null) {
+            cancelAnimationFrame(this._animFrameId);
+            this._animFrameId = null;
+        }
+
+        // 2. Remove the raycaster's own pointerdown listener
+        this._r.domElement.removeEventListener('pointerdown', this._boundRaycastClick);
+        this._rcastlist = [];
+        this._sboxlist = [];
+
+        // 3. Dispose OrbitControls (removes its own listeners from the canvas)
+        if (this._oc) {
+            this._oc.dispose();
+            this._oc = null;
+        }
+
+        // 4. Dispose the selection box helper (removes its listeners and overlay)
+        if (this._sboxhelp) {
+            this._sboxhelp.dispose();
+            this._sboxhelp = null;
+        }
+
+        // 5. Stop watching for container resize
+        if (this._resizeObs) {
+            this._resizeObs.disconnect();
+            this._resizeObs = null;
+        }
+
+        // 6. Release the WebGL context and GPU resources
+        this._r.dispose();
+        this._r.domElement.remove();
+        this._r = null;
+    }
+
     /**
      * Set properties of ambient light
      * 
@@ -413,6 +456,58 @@ class Renderer {
         return this._oc.target;
     }
 
+    /**
+     * Return a plain serialisable snapshot of the current camera state.
+     *
+     * @return {{ position: {x,y,z}, target: {x,y,z}, zoom: number }}
+     */
+    getCameraState() {
+        const pos = this._c.position;
+        const tgt = this._oc.target;
+        return {
+            position: { x: pos.x, y: pos.y, z: pos.z },
+            target:   { x: tgt.x, y: tgt.y, z: tgt.z },
+            zoom:     this._c.zoom,
+        };
+    }
+
+    /**
+     * Restore a camera snapshot produced by {@link Renderer#getCameraState}.
+     *
+     * @param {{ position?: {x,y,z}, target?: {x,y,z}, zoom?: number }} state
+     */
+    setCameraState(state) {
+        if (!state) return;
+
+        if (state.position) {
+            this._c.position.set(state.position.x, state.position.y, state.position.z);
+        }
+        if (state.target) {
+            this._oc.target.set(state.target.x, state.target.y, state.target.z);
+        }
+        if (typeof state.zoom === 'number') {
+            this._c.zoom = state.zoom;
+            this._c.updateProjectionMatrix();
+        }
+        this._oc.update();
+    }
+
+    /**
+     * Subscribe to camera-change events fired by OrbitControls whenever
+     * the user rotates, pans, or zooms.  The callback receives a camera
+     * state snapshot identical to the one returned by {@link Renderer#getCameraState}.
+     *
+     * @param  {Function} callback  `callback(cameraState)` called on each change
+     * @return {Function}           Unsubscribe function — call it to remove the listener
+     */
+    onCameraChange(callback) {
+        const handler = () => callback(this.getCameraState());
+        this._oc.addEventListener('change', handler);
+        return () => {
+            if (this._oc) this._oc.removeEventListener('change', handler);
+        };
+    }
+
 
     /**
      * Remove all currently rendered objects.

package/lib/selbox.js

@@ -256,6 +256,10 @@ var SelectionHelper = (function() {
         this.isDown = false;
         this.selectOverCallback = null;
 
+        // AbortController lets us remove all listeners in one call via dispose()
+        this._ac = new AbortController();
+        const signal = this._ac.signal;
+
         this.domElement.addEventListener('pointerdown', function(event) {
 
             if (event.shiftKey) {
@@ -263,7 +267,7 @@ var SelectionHelper = (function() {
                 this.onSelectStart(event);
             }
 
-        }.bind(this), false);
+        }.bind(this), { signal });
 
         this.domElement.addEventListener('pointermove', function(event) {
 
@@ -273,7 +277,7 @@ var SelectionHelper = (function() {
 
             }
 
-        }.bind(this), false);
+        }.bind(this), { signal });
 
         this.domElement.addEventListener('pointerup', function(event) {
 
@@ -282,7 +286,7 @@ var SelectionHelper = (function() {
                 this.onSelectOver(event);
             }
 
-        }.bind(this), false);
+        }.bind(this), { signal });
 
         this.domElement.addEventListener('keyup', function(event) {
 
@@ -291,10 +295,20 @@ var SelectionHelper = (function() {
                 this.onSelectOver(event);
             }
 
-        }.bind(this), false);
+        }.bind(this), { signal });
 
     }
 
+    SelectionHelper.prototype.dispose = function() {
+        // Remove all canvas event listeners registered by this helper
+        this._ac.abort();
+        // Remove the overlay element from the DOM
+        if (this.element) {
+            this.element.remove();
+            this.element = null;
+        }
+    };
+
     SelectionHelper.prototype.onSelectStart = function(event) {
 
         this.element.css({