bravais 0.1.3 → 0.2.0

package/dist/types/cif/symmetry-operators.d.ts

@@ -1,6 +1,6 @@
 import type { SymmetryOperation } from "../structure/types.js";
 /**
- * Parse one Jones-faithful operator such as `-x+1/2, y, -z+1/2` or
- * `2/3+x,1/3+y,1/3+z` into a rotation matrix and translation.
+ * Parse a symmetry operation as CIF files write it, such as
+ * `-x+1/2, y, -z+1/2`, into a rotation matrix and translation.
  */
 export declare function parseSymmetryOperator(text: string): SymmetryOperation;

package/dist/types/index.d.ts

@@ -18,12 +18,12 @@ export type { BuildSceneOptions, SceneAtom, StructureScene, } from "./scene/buil
 export type { Bond } from "./structure/bonds.js";
 export type { Lattice, LatticeParameters, Mat3, Site, SpaceGroupInfo, Species, Structure, SymmetryOperation, Vec3, } from "./structure/types.js";
 /**
- * Read the first structure in a CIF. Symmetry comes from the file's operator
- * loop, checked to fit its atoms, or from moyo by the file's space-group
- * symbol or number, in the setting its atoms or its cell select; a file
- * naming neither is taken as listing every atom (P1). Throws
- * `CifSyntaxError` for text that is not CIF, `CifStructureError` for a
- * CIF without a usable structure, and `SpaceGroupLookupError` for a space
- * group the symmetry table does not know.
+ * Read the first structure in a CIF file. Its symmetry comes from the
+ * file's list of symmetry operations or, without one, from its space-group
+ * symbol or number; a file with neither is read as listing every atom.
+ *
+ * Throws `CifSyntaxError` for text that is not valid CIF,
+ * `CifStructureError` for a file without a usable structure, and
+ * `SpaceGroupLookupError` for an unknown space group.
  */
 export declare function readCif(text: string): Promise<Structure>;

package/dist/types/render/gizmo.d.ts

@@ -2,14 +2,17 @@ import { OrthographicCamera, Quaternion, Scene, type WebGLRenderer } from "three
 import type { Mat3 } from "../structure/types.js";
 /** The a, b, c axes of the cell drawn in a corner, following the camera. */
 export declare class AxesGizmo {
-    private readonly fontFamily;
     readonly scene: Scene<import("three").Object3DEventMap>;
     readonly camera: OrthographicCamera;
     private readonly axes;
+    /** The a, b and c arrows, built once and turned to each new cell. */
+    private readonly arrows;
     private readonly headlight;
     private readonly inverse;
+    private readonly direction;
     /** `fontFamily` is the interface font the axis letters are drawn in. */
     constructor(fontFamily: string);
+    /** Point the arrows along the cell's a, b and c axes. */
     setCell(cell: Mat3): void;
     /** Draw into the bottom-left `size` pixels of a renderer whose main pass is done. */
     render(renderer: WebGLRenderer, cameraQuaternion: Quaternion, size: number): void;

package/dist/types/render/materials.d.ts

@@ -1,4 +1,4 @@
-import { DataTexture, LineBasicMaterial, MeshStandardMaterial, type Material } from "three";
+import { DataTexture, LineBasicMaterial, MeshStandardMaterial } from "three";
 export declare const METALNESS = 0.1;
 export declare const ROUGHNESS = 0.6;
 export declare const AMBIENT_LIGHT_INTENSITY = 0.8;
@@ -40,4 +40,3 @@ export declare const GIZMO_AXIS_STENCIL = 1;
  * axis letters can tell what they are drawn over.
  */
 export declare function createGizmoMaterial(color: string, stencilRef: number): MeshStandardMaterial;
-export declare function disposeMaterial(material: Material | Material[]): void;

package/dist/types/render/model.d.ts

@@ -22,3 +22,12 @@ export declare function cellCenter(cell: Mat3): Vec3;
  * bounds and the span.
  */
 export declare function createSceneModel(layers: SceneLayer[]): SceneModel;
+/**
+ * A placeholder atom, bond and cell frame in every material a structure is
+ * drawn with, opaque and see-through, so their shaders can compile before
+ * the first structure arrives. It gives no element a colour.
+ */
+export declare function createShaderWarmup(): {
+    group: Group;
+    dispose(): void;
+};

package/dist/types/render/palette.d.ts

@@ -1,12 +1,11 @@
-/** Assign session colours to `elements` before drawing them, most common first. */
+/** Give these elements their colours now, the more common ones first, so colours do not depend on drawing order. */
 export declare function ensureElementColors(elements: readonly string[]): void;
-/** The session colour of an element, assigned now if it is new. */
+/** The colour of an element as a hex string such as `#e15949`, given on first use. */
 export declare function elementColor(element: string): string;
-/** Elements seen in this session with their colours, in order of first appearance. */
+/** Every element given a colour so far, with its colour, in the order given. */
 export declare function elementColorAssignments(): [string, string][];
 /**
- * Forget the session's colours, for when every structure is cleared. The
- * palette is shared by every viewer and thumbnail renderer in the page,
- * which pick up new colours at their next draw.
+ * Forget every colour given so far, for example when all structures are
+ * closed. Viewers and thumbnails pick up new colours at their next draw.
  */
 export declare function resetElementColors(): void;

package/dist/types/render/thumbnails.d.ts

@@ -6,12 +6,13 @@ export interface ThumbnailRenderer {
      * Models are cached by `key` and rebuilt when the layers array changes.
      */
     render(key: string, layers: SceneLayer[], view: ViewState | null, canvas: HTMLCanvasElement): void;
-    /** Drop the cached model of `key`. */
+    /** Forget the cached model of `key`. */
     release(key: string): void;
+    /** Free the shared WebGL context and every cached model. */
     dispose(): void;
 }
 /**
- * One shared WebGL context that paints small previews into ordinary 2D
- * canvases, so a list of structures does not open a context per card.
+ * Draw small previews into ordinary canvases from one shared WebGL context,
+ * so a list of structures does not need a context for each.
  */
 export declare function createThumbnailRenderer(): ThumbnailRenderer;

package/dist/types/render/view-state.d.ts

@@ -1,7 +1,7 @@
 import type { Vec3 } from "../structure/types.js";
 /**
- * A camera pose an app can store, restore and carry between a viewer and a
- * thumbnail: the same state reads the same at any canvas size.
+ * A view an app can save and restore, or pass between a viewer and a
+ * thumbnail. It looks the same at any canvas size.
  */
 export interface ViewState {
     /** Orientation of the camera as [x, y, z, w], three.js order. */

package/dist/types/render/viewer.d.ts

@@ -8,32 +8,32 @@ export interface ViewerOptions {
 }
 export interface Viewer {
     /**
-     * Replace what is drawn with scenes from `buildScene`, usually of expanded
-     * structures. The view resets to the standard orientation unless `view`
-     * is given.
+     * Draw these scenes from `buildScene`, replacing what was shown. The view
+     * resets to the standard orientation unless `view` is given.
      */
     setLayers(layers: SceneLayer[], view?: ViewState | null): void;
     /** Remove everything drawn. */
     clear(): void;
-    /** The current pose, or null while nothing is loaded. */
+    /** The current view, or null while nothing is shown. */
     getView(): ViewState | null;
-    /** Restore a pose from `getView`, of this or another viewer. */
+    /** Restore a view from `getView`, of this or another viewer. */
     setView(view: ViewState): void;
     /** Back to the standard orientation, fitted to the viewport. */
     resetView(): void;
-    /** Refit to the element's size; call after layout changes the viewer's box. */
+    /** Fit the canvas to the container again; the viewer does this itself when the container resizes. */
     resize(): void;
-    /** Draw a frame now. */
+    /** Draw a frame now, or as soon as the shaders finish compiling. */
     render(): void;
-    /** Called after the user moves the camera. Returns the unsubscribe function. */
+    /** Call `listener` when the user rotates or zooms. Returns a function that removes it. */
     onInteraction(listener: () => void): () => void;
-    /** Take the viewer out of its container and release its WebGL resources. */
+    /** Remove the viewer from its container and free its WebGL resources. */
     dispose(): void;
 }
 /**
- * Mount a crystal viewer in `container`. The viewer fills the container and
- * follows its size, so the container needs a height of its own. The call
- * gives the container the class `bravais-viewer` and adds, once per
- * document, a `<style id="bravais-styles">` for the overlays.
+ * Create a viewer inside `container`. It fills the container and follows
+ * its size, so give the container a height. Adds the class `bravais-viewer`
+ * to the container and one small stylesheet to the page. Its shaders start
+ * compiling in the background at once, and drawing waits until they are
+ * ready.
  */
 export declare function createViewer(container: HTMLElement, options?: ViewerOptions): Viewer;

package/dist/types/scene/build.d.ts

@@ -23,26 +23,24 @@ export interface StructureScene {
     /** Elements present, in order of first appearance, deuterium as hydrogen. */
     elements: string[];
 }
-/** One structure drawn in a viewer; several overlay, each with its own opacity. */
+/** One structure to draw. A viewer can overlay several, each with its own opacity. */
 export interface SceneLayer {
     scene: StructureScene;
     /**
-     * 1 draws the layer solid; a lower value draws it translucent over the
-     * others; 0 draws nothing, yet the layer still frames the view, so a viewer
-     * switching between two states of a structure can keep one centre and
-     * scale. Default 1.
+     * From 0 to 1; default 1. Below 1 the layer is drawn see-through over the
+     * others. At 0 it is not drawn but still counts when fitting the view, so
+     * switching between two versions of a structure keeps the same framing.
      */
     opacity?: number;
 }
 export interface BuildSceneOptions {
-    /** Draw image atoms: boundary sites repeated on the opposite faces, edges and corners. Default true. */
+    /** Repeat atoms on the cell's faces, edges and corners on the opposite side too. Default true. */
     imageAtoms?: boolean;
 }
 /** Every chemical element on any site, in order of first appearance. */
 export declare function structureElements(structure: Structure): string[];
 /**
- * Atoms, bonds and cell of a structure as the renderer draws them. The sites
- * are drawn as listed and `operations` are not applied: pass
- * `expandStructure(structure)` to draw the full cell.
+ * Prepare a structure for drawing: its atoms, bonds and cell. Sites are
+ * drawn as listed; pass `expandStructure(structure)` to draw the whole cell.
  */
 export declare function buildScene(structure: Structure, options?: BuildSceneOptions): StructureScene;

package/dist/types/structure/expand.d.ts

@@ -1,6 +1,7 @@
 import { type Structure } from "./types.js";
 /**
- * Apply every operation to every site and keep the distinct positions: the
- * full cell as an explicit list of sites (P1).
+ * Fill the unit cell: apply every symmetry operation to every site and keep
+ * each distinct position once. The result lists every atom, with the
+ * identity as its only operation.
  */
 export declare function expandStructure(structure: Structure): Structure;

package/dist/types/structure/lattice.d.ts

@@ -1,10 +1,10 @@
 import type { Lattice, LatticeParameters, Mat3, Vec3 } from "./types.js";
 /**
- * Cartesian row vectors for cell parameters, in the convention pymatgen uses
- * by default: c along z and a in the xz plane.
+ * A lattice from cell lengths in ångström and angles in degrees. The c axis
+ * points along z and a lies in the xz plane, as in pymatgen.
  */
 export declare function latticeFromParameters(parameters: LatticeParameters): Lattice;
-/** Cell parameters of three Cartesian row vectors. */
+/** A lattice from its three cell vectors, in ångström. */
 export declare function latticeFromVectors(vectors: Mat3): Lattice;
 export declare function fractionalToCartesian(lattice: Lattice, fractional: Vec3): Vec3;
 export declare function distance(p: Vec3, q: Vec3): number;

package/dist/types/symmetry/dataset.d.ts

@@ -35,9 +35,7 @@ export interface SymmetryDataset {
     standard: Structure;
 }
 /**
- * Analyse the symmetry of what a structure actually contains. The structure
- * is expanded to every atom in its cell and handed to moyo, which finds the
- * space group from the atoms alone, so the result does not depend on how,
- * or whether, the file named it.
+ * Find the space group of a structure from its atoms alone, whatever the
+ * file says. See `SymmetryDataset` for what the result holds.
  */
 export declare function symmetryDataset(structure: Structure, options?: SymmetryOptions): Promise<SymmetryDataset>;

package/dist/types/symmetry/moyo.d.ts

@@ -4,10 +4,8 @@ export declare class SpaceGroupLookupError extends Error {
     constructor(message: string);
 }
 /**
- * Load the bundled moyo WebAssembly module, once. It is a separate file of
- * the package that nothing loads until a structure needs it. Every function
- * that needs moyo calls this itself, so calling it is only a way to pay the
- * start-up cost early. A failed load is not cached: the next call tries
+ * Load moyo, the symmetry library, ahead of first use. This is optional:
+ * everything that needs moyo loads it. If loading fails, the next call tries
  * again.
  */
 export declare function ensureMoyo(): Promise<void>;
@@ -47,9 +45,9 @@ export interface OperationSetting {
  */
 export declare function operationSettings(info: SpaceGroupInfo): Promise<OperationSetting[]>;
 /**
- * The operations of a space group named by Hall symbol, Hermann-Mauguin
- * symbol or number: those of the setting a suffix such as `:H` selects,
- * otherwise of the standard setting. Throws `SpaceGroupLookupError` when
- * the table has no such group.
+ * The symmetry operations of a space group given by Hall symbol,
+ * Hermann-Mauguin symbol or number, in the setting a suffix such as `:H`
+ * names, or else the standard setting. Throws `SpaceGroupLookupError` for
+ * an unknown group.
  */
 export declare function operationsForSpaceGroup(info: SpaceGroupInfo): Promise<SymmetryOperation[]>;

package/dist/types/symmetry/symbol.d.ts

@@ -1,10 +1,8 @@
 /**
- * A Hermann-Mauguin symbol the way textbooks print it: no spaces, screw
- * axes with subscripts and rotoinversion axes with a bar, so `F m -3 m`
- * becomes Fm3̅m and `P 2_1/c` becomes P2₁/c. The ASCII forms of moyo and
- * spglib (`2_1`) and of CIF files (`21`, the digits run together) are both
- * read. A setting suffix such as `:H` is kept after a space. A symbol
- * written without spaces is only given bars and underscore subscripts,
- * since `F432` cannot be told from a screw axis without them.
+ * Write a space-group symbol the way textbooks print it: `F m -3 m` becomes
+ * Fm3̅m and `P 2_1/c` becomes P2₁/c. A setting suffix such as `:H` is kept.
+ * A screw axis written as two digits, as CIF files do (`P 1 21/c 1`), is
+ * recognised only when the symbol has spaces, since in `F432` the digits
+ * are separate axes.
  */
 export declare function typesetSymbol(symbol: string): string;

package/examples/CoO.cif

@@ -0,0 +1,254 @@
+#------------------------------------------------------------------------------
+#$Date: 2024-05-06 10:39:41 +0300 (Mon, 06 May 2024) $
+#$Revision: 291735 $
+#$URL: file:///home/coder/svn-repositories/_RELOADED_COD/cod-reloaded/cif/9/00/86/9008618.cif $
+#------------------------------------------------------------------------------
+#
+# This file is available in the Crystallography Open Database (COD),
+# http://www.crystallography.net/. The original data for this entry
+# were provided the American Mineralogist Crystal Structure Database,
+# http://rruff.geo.arizona.edu/AMS/amcsd.php
+#
+# The file may be used within the scientific community so long as
+# proper attribution is given to the journal article from which the
+# data were obtained.
+#
+data_9008618
+loop_
+_publ_author_name
+'Wyckoff, R. W. G.'
+_publ_section_title
+;
+ Second edition. Interscience Publishers, New York, New York
+ rocksalt structure
+;
+_journal_name_full               'Crystal Structures'
+_journal_page_first              85
+_journal_page_last               237
+_journal_volume                  1
+_journal_year                    1963
+_chemical_formula_structural     CoO
+_chemical_formula_sum            'Co O'
+_space_group_IT_number           225
+_symmetry_space_group_name_Hall  '-F 4 2 3'
+_symmetry_space_group_name_H-M   'F m -3 m'
+_cell_angle_alpha                90
+_cell_angle_beta                 90
+_cell_angle_gamma                90
+_cell_length_a                   4.2667
+_cell_length_b                   4.2667
+_cell_length_c                   4.2667
+_cell_formula_units_Z            4
+_cell_volume                     77.674
+_database_code_amcsd             0011296
+_exptl_crystal_density_diffrn    6.408
+_cod_original_sg_symbol_H-M      'F m 3 m'
+_cod_database_code               9008618
+_amcsd_formula_title             CoO
+loop_
+_space_group_symop_operation_xyz
+x,y,z
+x,1/2+y,1/2+z
+1/2+x,y,1/2+z
+1/2+x,1/2+y,z
+z,-x,y
+z,1/2-x,1/2+y
+1/2+z,-x,1/2+y
+1/2+z,1/2-x,y
+-y,z,-x
+-y,1/2+z,1/2-x
+1/2-y,z,1/2-x
+1/2-y,1/2+z,-x
+x,-y,z
+x,1/2-y,1/2+z
+1/2+x,-y,1/2+z
+1/2+x,1/2-y,z
+-z,x,-y
+-z,1/2+x,1/2-y
+1/2-z,x,1/2-y
+1/2-z,1/2+x,-y
+y,-z,x
+y,1/2-z,1/2+x
+1/2+y,-z,1/2+x
+1/2+y,1/2-z,x
+-x,y,-z
+-x,1/2+y,1/2-z
+1/2-x,y,1/2-z
+1/2-x,1/2+y,-z
+x,-z,-y
+x,1/2-z,1/2-y
+1/2+x,-z,1/2-y
+1/2+x,1/2-z,-y
+-z,y,x
+-z,1/2+y,1/2+x
+1/2-z,y,1/2+x
+1/2-z,1/2+y,x
+y,-x,-z
+y,1/2-x,1/2-z
+1/2+y,-x,1/2-z
+1/2+y,1/2-x,-z
+-x,z,y
+-x,1/2+z,1/2+y
+1/2-x,z,1/2+y
+1/2-x,1/2+z,y
+z,-y,-x
+z,1/2-y,1/2-x
+1/2+z,-y,1/2-x
+1/2+z,1/2-y,-x
+-y,x,z
+-y,1/2+x,1/2+z
+1/2-y,x,1/2+z
+1/2-y,1/2+x,z
+x,z,y
+x,1/2+z,1/2+y
+1/2+x,z,1/2+y
+1/2+x,1/2+z,y
+-z,-y,-x
+-z,1/2-y,1/2-x
+1/2-z,-y,1/2-x
+1/2-z,1/2-y,-x
+y,x,z
+y,1/2+x,1/2+z
+1/2+y,x,1/2+z
+1/2+y,1/2+x,z
+-x,-z,-y
+-x,1/2-z,1/2-y
+1/2-x,-z,1/2-y
+1/2-x,1/2-z,-y
+z,y,x
+z,1/2+y,1/2+x
+1/2+z,y,1/2+x
+1/2+z,1/2+y,x
+-y,-x,-z
+-y,1/2-x,1/2-z
+1/2-y,-x,1/2-z
+1/2-y,1/2-x,-z
+z,x,-y
+z,1/2+x,1/2-y
+1/2+z,x,1/2-y
+1/2+z,1/2+x,-y
+-y,-z,x
+-y,1/2-z,1/2+x
+1/2-y,-z,1/2+x
+1/2-y,1/2-z,x
+x,y,-z
+x,1/2+y,1/2-z
+1/2+x,y,1/2-z
+1/2+x,1/2+y,-z
+-z,-x,y
+-z,1/2-x,1/2+y
+1/2-z,-x,1/2+y
+1/2-z,1/2-x,y
+y,z,-x
+y,1/2+z,1/2-x
+1/2+y,z,1/2-x
+1/2+y,1/2+z,-x
+-x,-y,z
+-x,1/2-y,1/2+z
+1/2-x,-y,1/2+z
+1/2-x,1/2-y,z
+-z,x,y
+-z,1/2+x,1/2+y
+1/2-z,x,1/2+y
+1/2-z,1/2+x,y
+y,-z,-x
+y,1/2-z,1/2-x
+1/2+y,-z,1/2-x
+1/2+y,1/2-z,-x
+-x,y,z
+-x,1/2+y,1/2+z
+1/2-x,y,1/2+z
+1/2-x,1/2+y,z
+z,-x,-y
+z,1/2-x,1/2-y
+1/2+z,-x,1/2-y
+1/2+z,1/2-x,-y
+-y,z,x
+-y,1/2+z,1/2+x
+1/2-y,z,1/2+x
+1/2-y,1/2+z,x
+x,-y,-z
+x,1/2-y,1/2-z
+1/2+x,-y,1/2-z
+1/2+x,1/2-y,-z
+-x,z,-y
+-x,1/2+z,1/2-y
+1/2-x,z,1/2-y
+1/2-x,1/2+z,-y
+z,-y,x
+z,1/2-y,1/2+x
+1/2+z,-y,1/2+x
+1/2+z,1/2-y,x
+-y,x,-z
+-y,1/2+x,1/2-z
+1/2-y,x,1/2-z
+1/2-y,1/2+x,-z
+x,-z,y
+x,1/2-z,1/2+y
+1/2+x,-z,1/2+y
+1/2+x,1/2-z,y
+-z,y,-x
+-z,1/2+y,1/2-x
+1/2-z,y,1/2-x
+1/2-z,1/2+y,-x
+y,-x,z
+y,1/2-x,1/2+z
+1/2+y,-x,1/2+z
+1/2+y,1/2-x,z
+-x,-z,y
+-x,1/2-z,1/2+y
+1/2-x,-z,1/2+y
+1/2-x,1/2-z,y
+z,y,-x
+z,1/2+y,1/2-x
+1/2+z,y,1/2-x
+1/2+z,1/2+y,-x
+-y,-x,z
+-y,1/2-x,1/2+z
+1/2-y,-x,1/2+z
+1/2-y,1/2-x,z
+x,z,-y
+x,1/2+z,1/2-y
+1/2+x,z,1/2-y
+1/2+x,1/2+z,-y
+-z,-y,x
+-z,1/2-y,1/2+x
+1/2-z,-y,1/2+x
+1/2-z,1/2-y,x
+y,x,-z
+y,1/2+x,1/2-z
+1/2+y,x,1/2-z
+1/2+y,1/2+x,-z
+-z,-x,-y
+-z,1/2-x,1/2-y
+1/2-z,-x,1/2-y
+1/2-z,1/2-x,-y
+y,z,x
+y,1/2+z,1/2+x
+1/2+y,z,1/2+x
+1/2+y,1/2+z,x
+-x,-y,-z
+-x,1/2-y,1/2-z
+1/2-x,-y,1/2-z
+1/2-x,1/2-y,-z
+z,x,y
+z,1/2+x,1/2+y
+1/2+z,x,1/2+y
+1/2+z,1/2+x,y
+-y,-z,-x
+-y,1/2-z,1/2-x
+1/2-y,-z,1/2-x
+1/2-y,1/2-z,-x
+loop_
+_atom_site_label
+_atom_site_fract_x
+_atom_site_fract_y
+_atom_site_fract_z
+Co 0.00000 0.00000 0.00000
+O 0.50000 0.50000 0.50000
+loop_
+_cod_related_entry_id
+_cod_related_entry_database
+_cod_related_entry_code
+1 ChemSpider 8117730
+2 AMCSD 0011296

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bravais",
-  "version": "0.1.3",
-  "description": "Crystal structure viewer: reads CIFs, applies their symmetry, repeats boundary sites, finds bonds with VESTA's cutoffs and renders with three.js.",
+  "version": "0.2.0",
+  "description": "A minimal crystal structure viewer for the web: reads CIF files and draws them with three.js.",
   "license": "MIT",
   "author": "Jiacheng Wang",
   "repository": {
@@ -30,13 +30,13 @@
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "import": "./dist/bravais.js",
       "default": "./dist/bravais.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "examples/CoO.cif",
     "CHANGELOG.md",
     "THIRD_PARTY_NOTICES.md"
   ],