bravais 0.2.0 → 0.3.0

package/dist/types/cif/errors.d.ts

@@ -1,4 +1,11 @@
+import { StructureError } from "../structure/errors.js";
+/** The text is not CIF the tokenizer and parser accept. */
+export declare class CifSyntaxError extends Error {
+    /** 1-based line of the problem. */
+    readonly line: number;
+    constructor(message: string, line: number);
+}
 /** The CIF parses but does not describe a structure this package can use. */
-export declare class CifStructureError extends Error {
+export declare class CifStructureError extends StructureError {
     constructor(message: string);
 }

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

@@ -1,15 +1,11 @@
-import type { Lattice, Site, SpaceGroupInfo, SymmetryOperation } from "../structure/types.js";
+import type { StructureListing } from "../structure/types.js";
 import { type CifBlock } from "./parser.js";
-import { CifStructureError } from "./errors.js";
-export { CifStructureError };
-export interface ParsedCifStructure {
-    lattice: Lattice;
-    sites: Site[];
-    /** Null when the file lists no operators; see `spaceGroup` then. */
-    operations: SymmetryOperation[] | null;
-    spaceGroup: SpaceGroupInfo;
-}
+/**
+ * A data block's lattice, merged sites, operations (null when the file lists
+ * none; see `spaceGroup` then) and space-group tags.
+ */
+export type ParsedCifStructure = StructureListing;
 /** True when the block carries atom coordinates (the one a viewer wants). */
 export declare function isStructureBlock(block: CifBlock): boolean;
-/** Lattice, merged sites, operators and space-group tags of one data block. */
+/** Lattice, merged sites, operations and space-group tags of one data block. */
 export declare function parseCifStructure(block: CifBlock): ParsedCifStructure;

package/dist/types/cif/{symmetry-operators.d.ts → symmetry-operations.d.ts}

@@ -3,4 +3,4 @@ import type { SymmetryOperation } from "../structure/types.js";
  * 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;
+export declare function parseSymmetryOperation(text: string): SymmetryOperation;

package/dist/types/cif/tokenizer.d.ts

@@ -4,12 +4,6 @@ export interface CifToken {
     text: string;
     line: number;
 }
-/** The text is not CIF the tokenizer and parser accept. */
-export declare class CifSyntaxError extends Error {
-    /** 1-based line of the problem. */
-    readonly line: number;
-    constructor(message: string, line: number);
-}
 /**
  * Split CIF 1.1 text into tokens. Comments are dropped; quoted strings and
  * semicolon text fields become single value tokens holding their content.

package/dist/types/index.d.ts

@@ -1,22 +1,22 @@
 import type { Structure } from "./structure/types.js";
+export { CifStructureError, CifSyntaxError } from "./cif/errors.js";
+export { StructureDataError, StructureError } from "./structure/errors.js";
+export { readStructure, type SiteData, type StructureData, } from "./structure/from-data.js";
 export { parseCif, type CifBlock, type CifDocument, type CifLoop, } from "./cif/parser.js";
-export { CifSyntaxError } from "./cif/tokenizer.js";
-export { CifStructureError, parseCifStructure, type ParsedCifStructure, } from "./cif/structure.js";
-export { parseSymmetryOperator } from "./cif/symmetry-operators.js";
+export { parseCifStructure, type ParsedCifStructure } from "./cif/structure.js";
+export { parseSymmetryOperation } from "./cif/symmetry-operations.js";
 export { SpaceGroupLookupError, ensureMoyo, operationsForSpaceGroup, } from "./symmetry/moyo.js";
 export { SymmetryAnalysisError, symmetryDataset, type SymmetryDataset, type SymmetryOptions, } from "./symmetry/dataset.js";
 export { typesetSymbol } from "./symmetry/symbol.js";
 export { expandStructure } from "./structure/expand.js";
 export { latticeFromParameters, latticeFromVectors, } from "./structure/lattice.js";
-export { buildScene, structureElements } from "./scene/build.js";
+export type { Bond } from "./structure/bonds.js";
+export type { Lattice, LatticeParameters, Mat3, Site, SpaceGroupInfo, Species, Structure, SymmetryOperation, Vec3, } from "./structure/types.js";
+export { buildScene, structureElements, type BuildSceneOptions, type SceneAtom, type SceneLayer, type StructureScene, } from "./scene/build.js";
 export { createViewer, type Viewer, type ViewerOptions, } from "./render/viewer.js";
 export { createThumbnailRenderer, type ThumbnailRenderer, } from "./render/thumbnails.js";
-export type { SceneLayer } from "./scene/build.js";
 export type { ViewState } from "./render/view-state.js";
 export { elementColor, elementColorAssignments, ensureElementColors, resetElementColors, } from "./render/palette.js";
-export type { BuildSceneOptions, SceneAtom, StructureScene, } from "./scene/build.js";
-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 file. Its symmetry comes from the
  * file's list of symmetry operations or, without one, from its space-group

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

@@ -1,11 +1,6 @@
-import { Box3, OrthographicCamera, Quaternion, Vector3 } from "three";
+import { Box3, OrthographicCamera, Quaternion } from "three";
 import type { Mat3 } from "../structure/types.js";
 import type { ViewState } from "./view-state.js";
-/** Camera outward direction and up vector of the standard view of a cell. */
-export declare function standardViewVectors(cell: Mat3): {
-    outward: Vector3;
-    up: Vector3;
-};
 /** Distance of the orthographic camera from its target; only the clipping depends on it. */
 export declare function cameraDistance(span: number): number;
 export declare function standardQuaternion(cell: Mat3): Quaternion;
@@ -15,11 +10,6 @@ export declare function standardView(cell: Mat3): ViewState;
 export declare function applyViewState(camera: OrthographicCamera, view: Pick<ViewState, "quaternion" | "target">, distance: number, span: number): void;
 /** The orientation of a camera as a view-state quaternion. */
 export declare function quaternionTuple(quaternion: Quaternion): [number, number, number, number];
-/** Size of `bounds` projected on the screen plane of `quaternion`. */
-export declare function projectedSize(bounds: Box3, quaternion: Quaternion): {
-    width: number;
-    height: number;
-};
 /** Orthographic zoom (pixels per ångström) that fits `bounds` in the viewport. */
 export declare function fitZoom(bounds: Box3, quaternion: Quaternion, width: number, height: number): number;
 /** Frustum of an orthographic camera in pixel units, so `zoom` is pixels per ångström. */

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

@@ -8,7 +8,6 @@ export declare class AxesGizmo {
     /** 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);

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

@@ -1,14 +1,10 @@
 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;
 export declare const HEADLIGHT_INTENSITY = 2.2;
 export declare const HEADLIGHT_OFFSET: readonly [number, number, number];
 export declare const BACKGROUND_COLOR = "#fafafa";
-export declare const CELL_FRAME_COLOR = "#444444";
 /** The part of a partially occupied site nobody occupies: a faint, see-through tint. */
 export declare const VACANCY_COLOR = "#f2f2f2";
-export declare const VACANCY_OPACITY = 0.3;
 /** Added to a vacancy texel's start fraction so the shader can tell it apart. */
 export declare const VACANCY_FLAG = 2;
 /**

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

@@ -1,12 +1,10 @@
 import { Box3, Group } from "three";
 import type { SceneLayer } from "../scene/build.js";
-import type { Mat3, Vec3 } from "../structure/types.js";
+import type { Mat3 } from "../structure/types.js";
 export interface SceneModel {
     group: Group;
-    /** Cell row vectors of the first layer, the frame everything is centred on. */
+    /** Cell row vectors of the first layer; `group` moves its centre to the origin. */
     cell: Mat3;
-    /** Centre of that cell, which `group` moves to the origin. */
-    center: Vec3;
     /** Bounds of every atom and cell corner of every layer, in the centred frame. */
     bounds: Box3;
     /** Largest cell edge length of any layer. */
@@ -15,7 +13,6 @@ export interface SceneModel {
     elements: string[];
     dispose(): void;
 }
-export declare function cellCenter(cell: Mat3): Vec3;
 /**
  * Build the three.js objects for the layers, centred on the first cell. A
  * layer at opacity 0 is not drawn but still counts toward the centre, the

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

@@ -15,7 +15,6 @@ export interface Oklch {
     h: number;
 }
 export declare function hexToOklab(hex: string): Oklab;
-export declare function isInGamut(lab: Oklab): boolean;
 export declare function oklabToHex(lab: Oklab): string;
 export declare function oklabToOklch(lab: Oklab): Oklch;
 export declare function oklchToOklab(lch: Oklch): Oklab;

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

@@ -12,8 +12,6 @@ export interface Bond {
     /** Distance between them in ångström. */
     length: number;
 }
-/** VESTA's bond-search maximum for an element pair, or null when VESTA draws none. */
-export declare function bondCutoff(elementA: string, elementB: string): number | null;
 /**
  * Bonds between the given atoms by VESTA's cutoff table. Only pairs VESTA
  * lists get bonds, so no metal-metal or anion-anion sticks appear. The bonds

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

@@ -1,7 +1,6 @@
 /** Element symbols in atomic-number order. */
 export declare const ELEMENT_SYMBOLS: string[];
-/** Deuterium keeps its own symbol for display and counts as hydrogen. */
-export declare const DEUTERIUM = "D";
+/** True for an element symbol as written, such as "Fe", or "D" for deuterium. */
 export declare function isElementSymbol(symbol: string): boolean;
 /**
  * The element behind a CIF atom label or type symbol: `Fe3+`, `O2-`, `Co1`,

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

@@ -0,0 +1,8 @@
+/** A structure, read from a CIF or given as data, that this package cannot use. */
+export declare class StructureError extends Error {
+    constructor(message: string);
+}
+/** Structure data `readStructure` cannot use: a field is missing or malformed. */
+export declare class StructureDataError extends StructureError {
+    constructor(message: string);
+}

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

@@ -1,12 +1,10 @@
 import type { SymmetryOperation, Vec3 } from "./types.js";
 /** Generated equivalents this close in fractional coordinates are one atom. */
 export declare const EQUIVALENT_TOLERANCE = 0.001;
-/** Fold a coordinate into [0, 1); a value within `nearOne` below 1 becomes 0. */
-export declare function wrap(value: number, nearOne?: number): number;
+/** Fold a coordinate into [0, 1); a value within `tolerance` below 1 becomes 0. */
+export declare function wrap(value: number, tolerance?: number): number;
 /** Fold a fractional position into the cell. */
 export declare function wrapVector(fractional: Vec3): Vec3;
-/** Periodic distance of two fractional positions, per axis, below `tolerance`. */
-export declare function samePosition(p: Vec3, q: Vec3, tolerance: number): boolean;
 /**
  * Fractional positions bucketed by where they fall in the cell, so finding
  * those within a tolerance of a position, across the periodic boundaries,

package/dist/types/structure/from-data.d.ts

@@ -0,0 +1,57 @@
+import type { LatticeParameters, Mat3, SpaceGroupInfo, Structure, SymmetryOperation, Vec3 } from "./types.js";
+/** One site of `StructureData`: a position and the species that share it. */
+export interface SiteData {
+    /** Name of the site; `site1`, `site2` and so on by its place in the list when absent. */
+    label?: string | null;
+    /** Fractional coordinates; wrapped into the cell. */
+    fractional: Vec3;
+    /** The species at this position; an occupancy defaults to 1. */
+    species: {
+        element: string;
+        occupancy?: number | null;
+    }[];
+}
+/**
+ * A crystal structure as plain data, for structures read or built outside
+ * this package. It survives JSON and `structuredClone`, so it can cross
+ * workers, processes and IPC.
+ */
+export interface StructureData {
+    /**
+     * Cell lengths in ångström and angles in degrees, set with c along z and a
+     * in the xz plane as in pymatgen, or the three cell vectors as rows in
+     * Cartesian ångström, used as given. Vectors win when both are given.
+     */
+    lattice: LatticeParameters | {
+        vectors: Mat3;
+    };
+    /**
+     * The sites as listed: an asymmetric unit that `operations` or
+     * `spaceGroup` expands, or every atom of the cell. Species within 1e-4 of
+     * one position belong to one site, as the rows of a CIF do.
+     */
+    sites: SiteData[];
+    /**
+     * x' = R x + t on fractional coordinates, as `SymmetryOperation`s with R
+     * row-major, or as strings such as `"-x, y+1/2, -z"`. They must include
+     * the identity. When absent or null, `spaceGroup` supplies them, and
+     * without a space group the sites list every atom of the cell.
+     */
+    operations?: (SymmetryOperation | string)[] | null;
+    /** The space group by Hall symbol, Hermann-Mauguin symbol or number. */
+    spaceGroup?: Partial<SpaceGroupInfo> | null;
+}
+/**
+ * Read a structure given as data instead of a CIF, such as one a CIF reader
+ * outside this package produced, so it can be expanded, drawn and analysed
+ * like a structure from `readCif`. The data is checked and then read the way
+ * a CIF's atoms are: positions wrapped into the cell, species at one position
+ * joined into a site and sorted by occupancy, overfull sites scaled to a full
+ * one, and the symmetry checked against the atoms, or looked up from the
+ * space group.
+ *
+ * Throws `StructureDataError` for data that is missing or malformed, or
+ * whose operations do not fit its atoms, and `SpaceGroupLookupError` for an
+ * unknown space group.
+ */
+export declare function readStructure(data: StructureData): Promise<Structure>;

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

@@ -0,0 +1,19 @@
+import type { Site, Vec3 } from "./types.js";
+/** Rows this close in fractional coordinates describe one site. */
+export declare const SITE_MERGE_TOLERANCE = 0.0001;
+/** One species at one position, as a CIF atom-site row lists it. */
+export interface SiteRow {
+    label: string;
+    element: string;
+    occupancy: number;
+    fractional: Vec3;
+}
+/**
+ * Sites from rows of one species at one position, the way a CIF lists its
+ * atoms. Positions are wrapped into the cell. Rows within
+ * `SITE_MERGE_TOLERANCE` of an earlier row join its site, which keeps that
+ * row's label, adds up the occupancy of a repeated element and sorts its
+ * species by descending occupancy. A site whose occupancies add up to more
+ * than 1 is scaled down to a full site.
+ */
+export declare function assembleSites(rows: Iterable<SiteRow>): Site[];

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

@@ -33,13 +33,13 @@ export interface SymmetryOperation {
     rotation: number[];
     translation: Vec3;
 }
-/** What a CIF says about its space group; null for what it leaves out. */
+/** What a CIF or structure data says about its space group; null for what it leaves out. */
 export interface SpaceGroupInfo {
     /** Number in the International Tables, 1 to 230. */
     number: number | null;
-    /** Hermann-Mauguin symbol as written in the file. */
+    /** Hermann-Mauguin symbol as written in the source. */
     symbol: string | null;
-    /** Hall symbol as written in the file. */
+    /** Hall symbol as written in the source. */
     hallSymbol: string | null;
 }
 export interface Structure {
@@ -49,4 +49,15 @@ export interface Structure {
     operations: SymmetryOperation[];
     spaceGroup: SpaceGroupInfo;
 }
+/**
+ * A structure as its source lists it, before its symmetry is settled: the
+ * operations are null when the source gives none, and `spaceGroup` then
+ * decides them.
+ */
+export interface StructureListing {
+    lattice: Lattice;
+    sites: Site[];
+    operations: SymmetryOperation[] | null;
+    spaceGroup: SpaceGroupInfo;
+}
 export declare const IDENTITY_OPERATION: SymmetryOperation;

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

@@ -38,10 +38,10 @@ export interface OperationSetting {
     operations: SymmetryOperation[];
 }
 /**
- * Every setting the space group a CIF names admits, spglib's standard one
- * first: one for most symbols, several for a short symbol such as `P 21/c`
- * or a rhombohedral symbol without `:H` or `:R`. A bare number gives the
- * standard setting alone.
+ * Every setting the named space group admits, spglib's standard one first:
+ * one for most symbols, several for a short symbol such as `P 21/c` or a
+ * rhombohedral symbol without `:H` or `:R`. A bare number gives the standard
+ * setting alone.
  */
 export declare function operationSettings(info: SpaceGroupInfo): Promise<OperationSetting[]>;
 /**

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

@@ -1,11 +1,14 @@
-import { type ParsedCifStructure } from "../cif/structure.js";
-import { type SymmetryOperation } from "../structure/types.js";
+import type { StructureError } from "../structure/errors.js";
+import { type StructureListing, type SymmetryOperation } from "../structure/types.js";
+/** The error a reader reports with, such as `CifStructureError`. */
+export type StructureErrorClass = new (message: string) => StructureError;
 /**
- * The operations a parsed CIF's atoms are expanded with: the file's own
- * loop, checked to fit the atoms, or else the setting of its space group
- * that fits them. A symbol admitting several settings, such as a
- * rhombohedral group with no `:H` or `:R`, is settled by the atoms when the
- * list is already expanded, since only the right setting maps it onto
- * itself, and otherwise by the cell shape, then by the standard setting.
+ * The operations a listing's atoms are expanded with: its own operations,
+ * checked to fit the atoms, or else the setting of its space group that fits
+ * them. A symbol admitting several settings, such as a rhombohedral group
+ * with no `:H` or `:R`, is settled by the atoms when the list is already
+ * expanded, since only the right setting maps it onto itself, and otherwise
+ * by the cell shape, then by the standard setting. Operations that do not
+ * fit are reported as `ErrorClass`.
  */
-export declare function resolveOperations(parsed: ParsedCifStructure): Promise<SymmetryOperation[]>;
+export declare function resolveOperations(parsed: StructureListing, ErrorClass: StructureErrorClass): Promise<SymmetryOperation[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bravais",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A minimal crystal structure viewer for the web: reads CIF files and draws them with three.js.",
   "license": "MIT",
   "author": "Jiacheng Wang",