@ccp-nc/crystvis-js 0.6.1 → 0.7.1

package/lib/visualizer.js

@@ -85,6 +85,34 @@ class CrystVis {
         // Vanilla (no get/set needed)
         this.cifsymtol = 1e-2; // Parameter controlling the tolerance to symmetry when loading CIF files
 
+        // Disposal state
+        this._isDisposed = false;
+
+        // Model source / parameter / metadata stores (keyed by model name)
+        this._model_sources = {};     // { text, extension }
+        this._model_parameters = {};  // parameters passed to loadModels / reloadModel
+        this._model_meta = {};        // { prefix, originalName }
+
+        // Lifecycle / camera-change callbacks
+        this._model_list_change_cbs = [];
+        this._display_change_cbs    = [];
+        this._camera_change_cbs     = [];
+
+        // Subscribe to camera changes from the renderer
+        this._camera_unsub = this._renderer.onCameraChange((state) => {
+            this._camera_change_cbs.forEach(cb => cb(state));
+        });
+
+    }
+
+    /**
+     * Whether this instance has been disposed.
+     * Once true, most methods will throw rather than silently fail.
+     * @readonly
+     * @type {boolean}
+     */
+    get isDisposed() {
+        return this._isDisposed;
     }
 
     /**
@@ -253,6 +281,146 @@ class CrystVis {
             this._atom_box_event = this._defaultAtomBox.bind(this);
     }
 
+    // ─── Private event emitters ─────────────────────────────────────────────────
+
+    _emitModelListChange() {
+        const names = Object.keys(this._models);
+        this._model_list_change_cbs.forEach(cb => cb(names));
+    }
+
+    _emitDisplayChange() {
+        this._display_change_cbs.forEach(cb => cb(this._current_mname));
+    }
+
+    // ─── Camera state API ────────────────────────────────────────────────────────
+
+    /**
+     * Return a plain serialisable snapshot of the current camera state.
+     *
+     * @return {{ position: {x,y,z}, target: {x,y,z}, zoom: number }}
+     */
+    getCameraState() {
+        return this._renderer.getCameraState();
+    }
+
+    /**
+     * Restore a camera snapshot produced by {@link CrystVis#getCameraState}.
+     * Safe to call after `displayModel()`.
+     *
+     * @param {{ position?: {x,y,z}, target?: {x,y,z}, zoom?: number }} state
+     */
+    setCameraState(state) {
+        this._renderer.setCameraState(state);
+    }
+
+    /**
+     * Subscribe to camera-change events (rotate, pan, zoom).
+     * The callback receives a snapshot identical to {@link CrystVis#getCameraState}.
+     *
+     * @param  {Function} callback  `callback(cameraState)`
+     * @return {Function}           Unsubscribe function
+     */
+    onCameraChange(callback) {
+        this._camera_change_cbs.push(callback);
+        return () => {
+            this._camera_change_cbs = this._camera_change_cbs.filter(cb => cb !== callback);
+        };
+    }
+
+    // ─── Lifecycle event APIs ────────────────────────────────────────────────────
+
+    /**
+     * Subscribe to model-list change events (model added or deleted).
+     * The callback receives the new list of model names.
+     *
+     * @param  {Function} callback  `callback(modelNames: string[])`
+     * @return {Function}           Unsubscribe function
+     */
+    onModelListChange(callback) {
+        this._model_list_change_cbs.push(callback);
+        return () => {
+            this._model_list_change_cbs = this._model_list_change_cbs.filter(cb => cb !== callback);
+        };
+    }
+
+    /**
+     * Subscribe to display-change events fired whenever `displayModel()` completes.
+     * The callback receives the name of the newly displayed model (or `null` when cleared).
+     *
+     * @param  {Function} callback  `callback(modelName: string|null)`
+     * @return {Function}           Unsubscribe function
+     */
+    onDisplayChange(callback) {
+        this._display_change_cbs.push(callback);
+        return () => {
+            this._display_change_cbs = this._display_change_cbs.filter(cb => cb !== callback);
+        };
+    }
+
+    // ─── Model source / parameter / metadata APIs ────────────────────────────────
+
+    /**
+     * Return the raw file text and format extension originally passed to
+     * `loadModels()` for the named model.
+     *
+     * @param  {String} name  Model name
+     * @return {{ text: string, extension: string }|null}
+     */
+    getModelSource(name) {
+        const src = this._model_sources[name];
+        return src ? { ...src } : null;
+    }
+
+    /**
+     * Return the loading parameters that were used when the named model was
+     * last loaded / reloaded (a clone of the merged parameter object).
+     *
+     * @param  {String} name  Model name
+     * @return {Object|null}
+     */
+    getModelParameters(name) {
+        const p = this._model_parameters[name];
+        return p ? JSON.parse(JSON.stringify(p)) : null;
+    }
+
+    /**
+     * Return metadata stored alongside the named model:
+     * `{ prefix, originalName }`.
+     *
+     * @param  {String} name  Model name
+     * @return {{ prefix: string, originalName: string }|null}
+     */
+    getModelMeta(name) {
+        const m = this._model_meta[name];
+        return m ? { ...m } : null;
+    }
+
+    // ─── Atomic unload ───────────────────────────────────────────────────────────
+
+    /**
+     * Remove *all* loaded models and reset the view in a single atomic operation
+     * (only one render pass after everything is cleared, unlike calling
+     * `deleteModel()` in a loop).
+     */
+    unloadAll() {
+        if (this._isDisposed) {
+            throw new Error('CrystVis: cannot call unloadAll() on a disposed instance');
+        }
+
+        // Clear the displayed model (handles renderer.clear(), selection reset, etc.)
+        // displayModel() with no args also emits _emitDisplayChange()
+        this.displayModel();
+
+        this._models           = {};
+        this._model_sources    = {};
+        this._model_parameters = {};
+        this._model_meta       = {};
+
+        this._emitModelListChange();
+    }
+
+    // ─── Internal atom-click/box defaults ────────────────────────────────────────
+
     _defaultAtomLeftClick(atom, event) {
         var i = atom.imgIndex;
         this.selected = new ModelView(this._current_model, [i]);
@@ -315,6 +483,50 @@ class CrystVis {
      *                           which the center of the camera should be rendered with
      *                           respect to the center of the canvas
      */
+    /**
+     * Release all resources held by this instance: cancels the animation loop,
+     * removes all canvas event listeners, disposes OrbitControls and the
+     * THREE.WebGLRenderer, and nulls internal references.  After calling this
+     * method the instance must not be used again.
+     */
+    dispose() {
+        if (this._isDisposed) {
+            return;
+        }
+        this._isDisposed = true;
+
+        // Unsubscribe camera-change listener before tearing down the renderer
+        if (this._camera_unsub) {
+            this._camera_unsub();
+            this._camera_unsub = null;
+        }
+
+        // Tear down the renderer (animation loop, orbit controls, WebGL context)
+        if (this._renderer) {
+            this._renderer.dispose();
+            this._renderer = null;
+        }
+
+        // Drop model and view references
+        this._current_model = null;
+        this._current_mname = null;
+        this._displayed = null;
+        this._selected = null;
+        this._models = {};
+        this._model_sources = {};
+        this._model_parameters = {};
+        this._model_meta = {};
+
+        // Drop event callbacks
+        this._atom_click_events = {};
+        this._atom_click_defaults = {};
+        this._atom_box_event = null;
+        this._notifications = [];
+        this._model_list_change_cbs = [];
+        this._display_change_cbs    = [];
+        this._camera_change_cbs     = [];
+    }
+
     centerCamera(center = [0, 0, 0], shift = [0, 0]) {
         const renderer = this._renderer;
 
@@ -336,9 +548,16 @@ class CrystVis {
      *  - `vdwScaling`: scale van der Waals radii by a constant factor
      *  - `vdwElementScaling`: table of per-element factors to scale VdW radii by
      *                                          
-     * @return {Object}             Names of the models we tried to load, and values of true/false for successful loading or not
+     * @return {Object}             Status map of the models we tried to load. Keys are the model names (strings that can be
+     *                              passed directly to `displayModel()`). Values are `0` for a successful load, or an error
+     *                              message string if loading failed. Example: to display the first loaded model, use
+     *                              `visualizer.displayModel(Object.keys(loaded)[0])` and check
+     *                              `loaded[modelName] !== 0` to detect errors.
      */
     loadModels(contents, format = 'cif', prefix = null, parameters = {}) {
+        if (this._isDisposed) {
+            throw new Error('CrystVis: cannot call loadModels() on a disposed instance');
+        }
         // clear existing notifications
         this.clearNotifications();
 
@@ -379,9 +598,13 @@ class CrystVis {
                 continue;
             }
             this._models[nn] = new Model(s, parameters);
+            this._model_sources[nn]     = { text: contents, extension: format };
+            this._model_parameters[nn]  = JSON.parse(JSON.stringify(parameters));
+            this._model_meta[nn]        = { prefix: prefix, originalName: n };
             status[nn] = 0; // Success
         }
 
+        this._emitModelListChange();
         return status;
     }
 
@@ -392,6 +615,9 @@ class CrystVis {
      * @param  {Object} parameters Loading parameters as in .loadModels()
      */
     reloadModel(name, parameters = {}) {
+        if (this._isDisposed) {
+            throw new Error('CrystVis: cannot call reloadModel() on a disposed instance');
+        }
         // clear existing notifications from scene
         this.clearNotifications();
 
@@ -409,6 +635,7 @@ class CrystVis {
         parameters = _.merge(model_parameter_defaults, parameters);
 
         this._models[name] = new Model(s, parameters);
+        this._model_parameters[name] = JSON.parse(JSON.stringify(parameters));
 
         if (current) {
             this.displayModel(name);
@@ -422,6 +649,9 @@ class CrystVis {
      *                          clear the renderer window.
      */
     displayModel(name = null) {
+        if (this._isDisposed) {
+            throw new Error('CrystVis: cannot call displayModel() on a disposed instance');
+        }
 
         if (this._current_model) {
             // clear notifications from previous model
@@ -435,6 +665,7 @@ class CrystVis {
 
         if (!name) {
             // If called with nothing, just quit here
+            this._emitDisplayChange();
             return;
         }
 
@@ -464,6 +695,7 @@ class CrystVis {
         this._renderer.resetOrbitCenter(c[0], c[1], c[2]);
 
         this._displayed.show();
+        this._emitDisplayChange();
     }
 
     /**
@@ -482,6 +714,10 @@ class CrystVis {
         }
 
         delete this._models[name];
+        delete this._model_sources[name];
+        delete this._model_parameters[name];
+        delete this._model_meta[name];
+        this._emitModelListChange();
     }
 
     /**

package/outdated.txt

@@ -1,12 +1,9 @@
-Package               Current   Wanted   Latest  Location                           Depended by
-@babel/eslint-parser   7.28.0   7.28.6   7.28.6  node_modules/@babel/eslint-parser  crystvis-js
-chai                    5.2.1    5.3.3    6.2.2  node_modules/chai                  crystvis-js
-chroma-js               3.1.2    3.2.0    3.2.0  node_modules/chroma-js             crystvis-js
-esbuild                0.25.6  0.25.12   0.27.2  node_modules/esbuild               crystvis-js
-eslint                 9.31.0   9.39.2   9.39.2  node_modules/eslint                crystvis-js
-glob                   11.1.0   11.1.0   13.0.0  node_modules/glob                  crystvis-js
-jquery                  3.7.1    3.7.1    4.0.0  node_modules/jquery                crystvis-js
-jsdoc                   4.0.4    4.0.5    4.0.5  node_modules/jsdoc                 crystvis-js
-mathjs                 14.5.3   14.9.1   15.1.0  node_modules/mathjs                crystvis-js
-mocha                  11.7.1   11.7.5   11.7.5  node_modules/mocha                 crystvis-js
-three                 0.178.0  0.178.0  0.182.0  node_modules/three                 crystvis-js
+Package  Current   Wanted   Latest  Location              Depended by
+chai       5.3.3    5.3.3    6.2.2  node_modules/chai     crystvis-js
+esbuild  0.25.12  0.25.12   0.27.3  node_modules/esbuild  crystvis-js
+eslint    9.39.2   9.39.4   10.0.3  node_modules/eslint   crystvis-js
+glob      11.1.0   11.1.0   13.0.6  node_modules/glob     crystvis-js
+jquery     3.7.1    3.7.1    4.0.0  node_modules/jquery   crystvis-js
+mathjs    14.9.1   14.9.1   15.1.1  node_modules/mathjs   crystvis-js
+serve     14.2.5   14.2.6   14.2.6  node_modules/serve    crystvis-js
+three    0.178.0  0.178.0  0.183.2  node_modules/three    crystvis-js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccp-nc/crystvis-js",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "A Three.js based crystallographic visualisation tool",
   "main": "index.js",
   "type": "module",
@@ -69,15 +69,16 @@
   },
   "homepage": "https://github.com/ccp-nc/crystvis-js#readme",
   "dependencies": {
-    "@ccp-nc/crystcif-parse": "^0.2.9",
+    "@ccp-nc/crystcif-parse": "^0.3.0",
     "@jkshenton/three-bmfont-text": "^4.0.1",
     "buffer": "^6.0.3",
     "chroma-js": "^3.2.0",
     "isosurface": "^1.0.0",
     "jquery": "^3.7.1",
     "load-bmfont": "^1.4.2",
-    "lodash": "^4.17.21",
+    "lodash": "^4.17.23",
     "mathjs": "^14.9.1",
+    "mendeleev": "^1.2.2",
     "three": "^0.178.0",
     "yargs-parser": "^22.0.0"
   },
@@ -88,16 +89,17 @@
     "clean-jsdoc-theme": "^4.3.0",
     "datauri": "^4.1.0",
     "esbuild": "^0.25.12",
-    "eslint": "^9.39.2",
+    "eslint": "^9.39.4",
     "gh-pages": "^6.3.0",
     "glob": "^11.1.0",
     "jpeg-js": "^0.4.4",
     "jsdoc": "^4.0.5",
+    "jsdom": "^27.0.1",
     "minimist": "^1.2.8",
     "mocha": "^11.7.5",
     "msdf-bmfont-xml": "^2.8.0",
     "npm-watch": "^0.13.0",
-    "serve": "^14.2.5"
+    "serve": "^14.2.6"
   },
   "overrides": {
     "minimist": "$minimist"

package/test/data/hf_mu_test.magres

@@ -0,0 +1,62 @@
+#$magres-abinitio-v1.0
+# Synthetic magres file for testing H:Mu custom-species handling
+[calculation]
+calc_code CASTEP
+calc_code_version 25.1
+calc_pspot H:Mu 1|0.6|13|15|17|10(qc=8)
+[/calculation]
+[atoms]
+units lattice Angstrom
+lattice          1.0000000000000000E+01          0.0000000000000000E+00          0.0000000000000000E+00          0.0000000000000000E+00          1.0000000000000000E+01          0.0000000000000000E+00          0.0000000000000000E+00          0.0000000000000000E+00          1.0000000000000000E+01
+units atom Angstrom
+atom H       H    1          1.0000000000000000E+00          2.0000000000000000E+00          3.0000000000000000E+00
+atom H:Mu    H:Mu 1          4.0000000000000000E+00          5.0000000000000000E+00          6.0000000000000000E+00
+[/atoms]
+[magres]
+[/magres]
+[magres_old]
+==========================================================================
+  Using the following values of the magnetogyric ratio                    
+  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
+==========================================================================
+
+============
+Atom: H        1
+============
+H        1 Coordinates      1.000    2.000    3.000   A
+
+TOTAL tensor
+
+               1.0000      0.0000      0.0000
+               0.0000      2.0000      0.0000
+               0.0000      0.0000      3.0000
+
+H        1 Eigenvalue  A_xx       1.0000      
+H        1 Eigenvector A_xx       1.0000      0.0000      0.0000
+H        1 Eigenvalue  A_yy       2.0000      
+H        1 Eigenvector A_yy       0.0000      1.0000      0.0000
+H        1 Eigenvalue  A_zz       3.0000      
+H        1 Eigenvector A_zz       0.0000      0.0000      1.0000
+
+H        1 Iso:        2.0000 (MHz)
+============
+Atom: H:Mu     1
+============
+H:Mu     1 Coordinates      4.000    5.000    6.000   A
+
+TOTAL tensor
+
+             -10.0000      1.0000      0.0000
+               1.0000     -20.0000      0.0000
+               0.0000      0.0000     -30.0000
+
+H:Mu     1 Eigenvalue  A_xx     -10.0000      
+H:Mu     1 Eigenvector A_xx       1.0000      0.0000      0.0000
+H:Mu     1 Eigenvalue  A_yy     -20.0000      
+H:Mu     1 Eigenvector A_yy       0.0000      1.0000      0.0000
+H:Mu     1 Eigenvalue  A_zz     -30.0000      
+H:Mu     1 Eigenvector A_zz       0.0000      0.0000      1.0000
+
+H:Mu     1 Iso:       -20.0000 (MHz)
+[/magres_old]

package/test/data/hf_test.magres

@@ -0,0 +1,61 @@
+#$magres-abinitio-v1.0
+# Synthetic magres file for testing HF tensor parsing from magres_old block
+[calculation]
+calc_code CASTEP
+calc_code_version 25.1
+[/calculation]
+[atoms]
+units lattice Angstrom
+lattice          1.0000000000000000E+01          0.0000000000000000E+00          0.0000000000000000E+00          0.0000000000000000E+00          1.0000000000000000E+01          0.0000000000000000E+00          0.0000000000000000E+00          0.0000000000000000E+00          1.0000000000000000E+01
+units atom Angstrom
+atom H       H   1          1.0000000000000000E+00          2.0000000000000000E+00          3.0000000000000000E+00
+atom C       C   1          4.0000000000000000E+00          5.0000000000000000E+00          6.0000000000000000E+00
+[/atoms]
+[magres]
+[/magres]
+[magres_old]
+==========================================================================
+  Using the following values of the magnetogyric ratio
+  H      Isotope   1             GAMMA =  2.6752E+08 rad T-1 s-1
+  C      Isotope  13             GAMMA =  6.7283E+07 rad T-1 s-1
+==========================================================================
+
+============
+Atom: H        1
+============
+H        1 Coordinates      1.000    2.000    3.000   A
+
+TOTAL tensor
+
+               1.2345     -0.5678      0.1234
+              -0.5678      2.3456      0.4567
+               0.1234      0.4567      3.4567
+
+H        1 Eigenvalue  A_xx       0.9985
+H        1 Eigenvector A_xx       0.9730      0.2304     -0.0220
+H        1 Eigenvalue  A_yy       2.4022
+H        1 Eigenvector A_yy      -0.2282      0.9623      0.1486
+H        1 Eigenvalue  A_zz       3.6361
+H        1 Eigenvector A_zz       0.0530     -0.1432      0.9884
+
+H        1 Iso:        2.3456 (MHz)
+============
+Atom: C        1
+============
+C        1 Coordinates      4.000    5.000    6.000   A
+
+TOTAL tensor
+
+               5.0000      1.0000      0.0000
+               1.0000      5.0000      0.0000
+               0.0000      0.0000      3.0000
+
+C        1 Eigenvalue  A_xx       3.0000
+C        1 Eigenvector A_xx       0.0000      0.0000      1.0000
+C        1 Eigenvalue  A_yy       4.0000
+C        1 Eigenvector A_yy      -0.7071      0.7071      0.0000
+C        1 Eigenvalue  A_zz       6.0000
+C        1 Eigenvector A_zz       0.7071      0.7071      0.0000
+
+C        1 Iso:        4.3333 (MHz)
+[/magres_old]