openchemlib 9.22.1 → 9.24.0

package/dist/openchemlib.d.ts

@@ -246,6 +246,17 @@ export interface Rectangle {
   height: number;
 }
 
+export interface Coordinates {
+  /** X-coordinate. */
+  x: number;
+
+  /** Y-coordinate. */
+  y: number;
+
+  /** Z-coordinate. */
+  z: number;
+}
+
 export declare class Molecule {
   /**
    * Construct a new molecule.
@@ -1804,6 +1815,33 @@ export declare class Molecule {
 
   scaleCoords(f: number): void;
 
+  /**
+   * Returns a copy of the atom's 3D coordinates. Mutating it does not change the
+   * molecule; use `setCoordinates` (or `setAtomX`/`setAtomY`/`setAtomZ`) to
+   * write the values back.
+   */
+  getCoordinates(atom: number): Coordinates;
+
+  setCoordinates(atom: number, coordinates: Coordinates): void;
+
+  /**
+   * 3D translation of every atom by a `{ x, y, z }` vector (`translateCoords` is
+   * 2D and ignores z).
+   */
+  translate(coordinates: Coordinates): void;
+
+  /**
+   * Rotates every atom in 3D by a 3x3 matrix. OpenChemLib uses the row-vector
+   * convention: `x' = x*m[0][0] + y*m[1][0] + z*m[2][0]` (and likewise for y, z).
+   */
+  rotate(matrix: number[][]): void;
+
+  /** Translate the molecule so its center of gravity is at the origin. */
+  center(): void;
+
+  /** Center of gravity (all atoms with equal weight); `{ x: 0, y: 0, z: 0 }` if there are no atoms. */
+  getCenterOfGravity(): Coordinates;
+
   zoomAndRotateInit(x: number, y: number): void;
 
   zoomAndRotate(zoom: number, angle: number, selected: boolean): void;
@@ -3617,6 +3655,60 @@ export declare class SSSearcherWithIndex {
   createIndex(molecule: Molecule): number[];
 }
 
+export type MCSRingMatchMode =
+  | 'cleaveRings'
+  | 'keepRings'
+  | 'keepAromaticRings';
+
+export interface MCSOptions {
+  /**
+   * How rings of the fragment are handled when building common substructures.
+   * - `cleaveRings`: rings may be broken, so a partial ring can be part of the result.
+   * - `keepRings`: a ring is only kept if it is entirely part of the common substructure.
+   * - `keepAromaticRings`: same as `keepRings` but restricted to aromatic rings.
+   * @default 'cleaveRings'
+   */
+  ringMatchMode?: MCSRingMatchMode;
+}
+
+/**
+ * Computes the maximum common substructure (MCS) between two molecules.
+ */
+export declare class MCS {
+  /**
+   * Creates a new maximum common substructure finder.
+   */
+  constructor(options?: MCSOptions);
+
+  /**
+   * Sets the pair of molecules to compare. `molecule` should contain at least
+   * as many bonds as `fragment`. If `fragment` contains more than one disconnected
+   * structure, only the biggest one is considered.
+   * @param molecule - the (usually larger) target molecule.
+   * @param fragment - the molecule whose common substructure with `molecule` is searched.
+   */
+  set(molecule: Molecule, fragment: Molecule): void;
+
+  /**
+   * Returns the maximum common substructure as a `Molecule`, or `null` if no
+   * common substructure was found.
+   */
+  getMCS(): Molecule | null;
+
+  /**
+   * Returns the score of the maximum common substructure, defined as the number
+   * of bonds of the MCS divided by the larger bond count of the two input molecules.
+   * `getMCS()` (or `getAllCommonSubstructures()`) must be called first.
+   */
+  getScore(): number;
+
+  /**
+   * Returns all distinct common substructures (the largest first), or `null` if
+   * none was found.
+   */
+  getAllCommonSubstructures(): Molecule[] | null;
+}
+
 export declare class Transformer {
   constructor(reactant: Molecule, product: Molecule, name: string);
   setMolecule(molecule: Molecule, countMode: number): number;