// Specifications for various object types used in 3Dmol.js // This is primarily for documentation import { Matrix4, Vector3 } from "WebGL"; import { AtomStyleSpec, BondStyle, GLModel } from "./GLModel"; import { GLViewer } from "./GLViewer"; import { ColorSpec } from "./colors"; /** * Atom representation. Depending on the input file format, not all fields may be defined. */ export interface AtomSpec { /** Parent residue name */ resn?: string; /** Residue label name */ lresn?: string; /** Atom's x coordinate */ x?: number; /** Atom's y coordinate */ y?: number; /** Atom's z coordinate */ z?: number; /** Atom's color, as hex code or built-in color string */ color?: ColorSpec; /** Hex code for color to be used for surface patch over this atom */ surfaceColor?: ColorSpec; /** Element abbreviation (e.g. 'H', 'Ca', etc) */ elem?: string; /** Set to true if atom is a heteroatom */ hetflag?: boolean; /** Chain this atom belongs to, if specified in input file (e.g 'A' for chain A) */ chain?: string; /** Label chain (not author) */ lchain?: string; /** Residue number */ resi?: number; /** Label residues number (not author) */ lresi?: number; icode?: string; rescode?: string; /** Atom's serial id number */ serial?: number; /** Index of atom in molecule */ index?: number; /** Atom name; may be more specific than 'elem' (e.g 'CA' for alpha carbon) */ atom?: string; /** Array of atom ids this atom is bonded to */ bonds?: number[]; /** Secondary structure identifier (for cartoon render; e.g. 'h' for helix) */ ss?: string; ssbegin?: boolean; ssend?: boolean; /** true if this atom forms only single bonds or no bonds at all */ singleBonds?: boolean; /** Array of this atom's bond orders, corresponding to bonds identfied by 'bonds' */ bondOrder?: number[]; /** Optional mapping of additional properties */ properties?: Record<string, any>; /** Atom b factor data */ b?: number; /** If applicable, this atom's record entry from the input PDB file (used to output new PDB from models) */ pdbline?: string; /** Set this flag to true to enable click selection handling for this atom */ clickable?: boolean; /** Callback click handler function to be executed on this atom and its parent viewer */ callback?: (atom: AtomSpec, viewer: GLViewer) => void; /** Set this flag to true to enable hover selection handling for this atom */ hoverable?: boolean; /** Callback hover handler function to be executed on this atom and its parent viewer */ hover_callback?: (atom: AtomSpec, viewer: GLViewer) => void; /** Callback handling "unhover" to be executed on this atom and its parent viewer */ unhover_callback?: (atom: AtomSpec, viewer: GLViewer) => void; /** for selection, inverts the meaning of the selection */ invert?: boolean; /** style of atom */ style?: AtomStyleSpec; /** custom bond styling by position in bonds */ bondStyles?: BondStyle[]; intersectionShape?: any; capDrawn?: boolean; model?: number; contextMenuEnabled?: boolean; hbondDistanceSq?: number; hbondOther?: any; altLoc?: string; reschain?: number; uMat?: Record<string, number>; symmetries?: Vector3[]; sym?: any; dx?: number; dy?: number; dz?: number; } /** * Atom selection object. Used to specify what atoms should be selected. Can include * any field from {@link AtomSpec} in which case atoms must equal the specified value. * All fields must match for the selection to hold. If values * are provided as a list, then only one value of the list must match. * @extends AtomSpec * @example * $3Dmol.download("pdb:2EJ0",viewer,{},function(){ * viewer.setStyle({chain:'B'},{cartoon:{color:'spectrum'}}); * viewer.setStyle({chain:'B',invert:true},{cartoon:{}}); * viewer.setStyle({bonds: 0},{sphere:{radius:0.5}}); //water molecules * viewer.setStyle({resn:'PMP',byres:true,expand:5},{stick:{colorscheme:"greenCarbon"}}); * viewer.setStyle({resi:["91-95","42-50"]},{cartoon:{color:"green",thickness:1.0}}); * viewer.render(); * }); */ export interface AtomSelectionSpec extends Omit<AtomSpec, "bonds" | "model" | "index" | "resi"> { /** a single model or list of models from which atoms should be selected. Can also specify by numerical creation order. Reverse indexing is allowed (-1 specifies last added model). */ model?: GLModel | number | GLModel[] | number[]; /** frame index of individual frame to style; will apply to all frames if not set */ frame?: number; /** index of the atom or atoms to select */ index?: number | number[]; /** overloaded to select number of bonds, e.g. {bonds: 0} will select all nonbonded atoms */ bonds?: number; /** overloaded to allow ranges and lists of residues, e.g. {resi: "5-10"} or {resi: [5,10,32]} */ resi?: number | SelectionRange | (number | SelectionRange)[]; /** user supplied function that gets passed an {@link AtomSpec} and should return true if the atom should be selected */ predicate?: (atom: AtomSpec) => boolean; /** if set, inverts the meaning of the selection */ invert?: boolean; /** if set, expands the selection to include all atoms of any residue that has any atom selected */ byres?: boolean; /** expands the selection to include all atoms within a given distance from the selection */ expand?: number | string; /** intersects the selection with the set of atoms within a given distance from another selection */ within?: WithinSelectionSpec; /** take the intersection of the provided lists of {@link AtomSelectionSpec}s */ and?: AtomSelectionSpec[] & { __cached_results?: any }; /** take the union of the provided lists of {@link AtomSelectionSpec}s */ or?: AtomSelectionSpec[] & { __cached_results?: any }; /** take the inverse of the provided {@link AtomSelectionSpec} */ not?: AtomSelectionSpec; contextMenuEnabled?: boolean; } /** * Within selection object. Used to find the subset of an atom selection that is within * some distance from another atom selection. When added as a field of an {@link AtomSelectionSpec}, * intersects the set of atoms in that selection with the set of atoms within a given * distance from the given {@link AtomSelectionSpec}. * @example * $3Dmol.download("pdb:2EJ0",viewer,{},function(){ * viewer.setStyle({chain: 'A', within:{distance: 10, sel:{chain: 'B'}}}, {sphere:{}}); * viewer.render(); * });// stylizes atoms in chain A that are within 10 angstroms of an atom in chain B * */ export interface WithinSelectionSpec { /** the distance in angstroms away from the atom selection to include atoms in the parent selection */ distance?: number; /** if set, selects atoms not within distance range for intersection */ invert?: boolean; /** the selection of atoms against which to measure the distance from the parent atom selection */ sel?: AtomSelectionSpec; } export type Cryst = { a: number; b: number; c: number; alpha: number; beta: number; gamma: number; origin: Vector3; size: { x: number; y: number; z: number }; unit: Vector3; matrix4: Matrix4; matrix: unknown; }; export type SelectionRange = `${number}-${number}`;