@judah-silva/rnacanvas 0.0.1

package/README.md

@@ -0,0 +1,10 @@
+# 🧬 RNA Canvas
+
+A reusable, customizable 3D canvas component built with **Babylon.js** and **React**, designed for interactive molecular visualization and selection tools.
+
+## 📦 Installation
+
+```bash
+npm install @judah-silva/rnacanvas @babylonjs/core
+# or
+yarn add @judah-silva/rnacanvas @babylonjs/core

package/dist/index.d.mts

@@ -0,0 +1,528 @@
+import { Mesh, TransformNode, Scene, Matrix, Nullable, Quaternion, Observer, Engine, UniversalCamera } from '@babylonjs/core';
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+
+declare class Residue extends Group<MeshObject> {
+    constructor(name: string);
+    addChild(child: MeshObject): void;
+    hasMesh(uuid: string): boolean;
+}
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+
+declare class MeshObject {
+    private _mesh;
+    userData: Object;
+    constructor(name: string);
+    setParent(parent: Residue | null): void;
+    applyVertexData(positions: number[], indices: number[]): void;
+    applyHighlight(): void;
+    resetHighlight(): void;
+    /**
+     * Cretes a material with the given color and sets it to the mesh
+     * @param color String in the format of #RRGGBB
+     */
+    createAndSetMaterial(color: string): void;
+    setNewMesh(mesh: Mesh): MeshObject;
+    get mesh(): Mesh;
+    get uuid(): string;
+}
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+
+declare abstract class Group<T extends MeshObject | Group<MeshObject>> {
+    protected _node: TransformNode;
+    protected _children: Set<T>;
+    constructor(name: string, scene: Scene);
+    setParent(parent: Group<Group<MeshObject>> | null): void;
+    removeChild(child: T): void;
+    get node(): TransformNode;
+    get children(): Set<T>;
+}
+
+declare class Matrix4 {
+    private _matrix;
+    constructor();
+    fromArray(array: number[]): this;
+    get matrix(): Matrix;
+}
+
+declare class Quat {
+    private _quaternion;
+    constructor();
+    rotateByQuaternion(quaternion: Quat): void;
+    setToQuaternion(quaternion: Nullable<Quaternion>): void;
+    setFromMatrix(matrix: Matrix4): this;
+    setFromEuler(eulerAngle: Vec3): this;
+    get quaternion(): Quaternion;
+}
+
+declare class Vec3 {
+    private _vector3;
+    static Zero: Vec3;
+    constructor(x: number, y: number, z: number);
+    clone(): Vec3;
+    normalize(): void;
+    applyAxisAngle(axis: Vec3, angle: number): Vec3;
+    applyQuaternion(quat: Quat): void;
+    multiplyScalar(scalar: number): void;
+    add(vec: Vec3): void;
+    length(): number;
+    equals(other: Vec3): boolean;
+    get x(): number;
+    get y(): number;
+    get z(): number;
+}
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+
+interface userData {
+    atomInfo: Vec3[];
+    fileName: string;
+}
+/**
+ * A MotifObject is a collection of residue meshes in one object.
+ * It is a wrapper class around the Babylon TransformNode.
+ */
+declare class Motif extends Group<Residue> {
+    userData: userData;
+    private _quat;
+    constructor(name: string);
+    addChild(child: Residue): void;
+    setPosition(x: number, y: number, z: number): void;
+    translate(x: number, y: number, z: number): void;
+    rotate(axis: Vec3, angle: number): void;
+    rotateByQuaternion(quat: Quat): void;
+    setQuaternion(quat: Quat): void;
+    multiplyScalar(scalar: number): void;
+    private _nanCheck;
+    get uuid(): string;
+    get quat(): Quat;
+    get position(): Vec3;
+}
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+
+declare namespace Events {
+    enum EventType {
+        POINTER_DOWN = "pointerDown",
+        POINTER_UP = "pointerUp",
+        POINTER_MOVE = "pointerMove",
+        POINTER_WHEEL = "pointerWheel",
+        KEY_DOWN = "keyDown",
+        KEY_UP = "keyUp",
+        TOUCH_START = "touchStart",
+        TOUCH_END = "touchEnd",
+        TOUCH_MOVE = "touchMove",
+        PINCH_START = "pinchStart",
+        PINCH = "pinch",
+        PINCH_END = "pinchEnd",
+        OBJECT_SELECTED = "objectSelected",
+        OBJECT_DESELECTED = "objectDeselected",
+        RESIZE = "resize",
+        RENDER = "render",
+        ENGINE_STARTED = "engineStarted",
+        ENGINE_STOPPED = "engineStopped"
+    }
+    interface Event {
+        type: EventType | string;
+        originalEvent?: globalThis.Event;
+        canceled: boolean;
+        timestamp: number;
+    }
+    interface PointerEvent extends Event {
+        position: {
+            x: number;
+            y: number;
+        };
+        button?: number;
+        buttons?: number;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        shiftKey?: boolean;
+        metaKey?: boolean;
+        deltaX?: number;
+        deltaY?: number;
+        pickedResidue?: Residue;
+    }
+    interface KeyboardEvent extends Event {
+        key: string;
+        code: string;
+        ctrlKey: boolean;
+        altKey: boolean;
+        shiftKey: boolean;
+        metaKey: boolean;
+        repeat: boolean;
+        rotationAxis: Vec3;
+        translationDirection: Vec3;
+    }
+    interface PinchEvent extends Event {
+        scale: number;
+        center: {
+            x: number;
+            y: number;
+        };
+    }
+    interface SelectionEvent extends Event {
+        residue?: Residue;
+        motif?: Motif;
+        multiSelect?: boolean;
+    }
+}
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+
+/**
+ * Class to handle event registration, notification, and removal.
+ * Limited to managing events for one scene.
+ */
+declare class EventManager {
+    private _eventObservables;
+    private _pointerObserver;
+    private _keyboardObserver;
+    private _renderObserver;
+    private _activeKeys;
+    private _pendingDeselect;
+    constructor();
+    /**
+     * Dispose of the event listeners and triggers
+     */
+    dispose(): void;
+    /**
+     * Register an event of a certain type
+     * @param eventType String event type. Can be custom or standard.
+     * @param callback Callback function to run when the event is triggered
+     * @returns Babylon Observer instance for later removal
+     */
+    on<T extends Events.Event>(eventType: Events.EventType | string, callback: (event: T) => void): Observer<Events.Event>;
+    /**
+     * Remove a registered event observer
+     * @param observer Babylon Observer with the registered callback
+     */
+    off(observer: Observer<Events.Event>): void;
+    /**
+     * Emit a custom event, triggering listeners registered with that event type.
+     * @param eventType A string event type. Can be custom or standard.
+     * @param eventData Event info object partial.
+     */
+    emit(eventType: string, eventData: Partial<Events.Event>): void;
+    /**
+     * Method to notify listeners of a type of event
+     * @param eventType A string event type. Can be custom or standard.
+     * @param event Event info object
+     */
+    notifyObservers(eventType: string, event: Events.Event): void;
+    /**
+     * Method to set up pointer and keyboard events on the scene.
+     * Comes preset with POINTER_DOWN, POINTER_UP, POINTER_MOVE, KEYBOARD_DOWN, and KEYBOARD_UP event triggering.
+     * @param scene A RenderScene object
+     */
+    setupEventHandling(scene: RenderScene): void;
+    /**
+     * Initialize observables for all standard event types
+     */
+    private _initializeObservables;
+    /**
+     * Helper function to get the residue that contains a picked mesh using the transform node of a motif
+     * @param node {TransformNode} Motif's TransformNode
+     * @param meshUUID Stringified uniqueId of the picked mesh
+     * @param sceneChildren Map of Motifs that exist in the scene
+     * @returns The Residue that contains the picked mesh, or null if it does not exist
+     */
+    private _getResidueFromMotifNode;
+}
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+
+declare class RenderScene {
+    private _canvas;
+    private _scene;
+    private _engine;
+    private _camera;
+    private _children;
+    private _eventManager;
+    private _isDisposed;
+    isRunning: boolean;
+    constructor(canvas: HTMLCanvasElement, hexColor: string, cameraPositionZ: number, renderWidth: number, renderHeight: number);
+    start(): void;
+    stop(): void;
+    dispose(): void;
+    add(motif: Motif): void;
+    remove(motif: Motif): void;
+    setBackgroundColor(hexColor: string): void;
+    private _reattachToScene;
+    private _handleResize;
+    /**
+   * Returns the Babylon.js Scene object.
+   */
+    get scene(): Scene;
+    /**
+     * Returns the engine.
+     */
+    get engine(): Engine;
+    /**
+     * Returns the camera.
+     */
+    get camera(): UniversalCamera;
+    /**
+     * Returns the event manager
+     */
+    get eventManager(): EventManager;
+    /**
+     * Returns the set of children.
+     */
+    get children(): Map<string, Motif>;
+    /**
+     * Returns the current render width
+     */
+    get renderWidth(): number;
+    /**
+     * Returns the current render height
+     */
+    get renderHeight(): number;
+}
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <jusilva@csumb.edu>
+ */
+
+declare function updateAllMotifs(motifMeshArray: Motif[]): Promise<void>;
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Sameer Dingore <sdingore@csumb.edu>
+ * @author Judah Silva
+ */
+
+/**
+ * ________________________________________________________________________________________________
+ */
+/**
+ *  reads the json file and returns the motif structure mesh as THREE.Group
+ * @param motifJSONFileName
+ * json file name with coordinates of the motif
+ * @param motifColorHex
+ * color of the motif structure
+ * @param highLightColorHex
+ * color of the highlighted motif structure
+ * @returns {Promise<Motif>}
+ * @async
+ */
+declare function getMotif(motifJSONFileName: string, motifColorHex?: string): Promise<Motif>;
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva
+ */
+/**
+ * ________________________________________________________________________________________________
+ */
+/**
+ * Get the vertices and indices from the nucleotide data
+ * @param nucleotideData {number[][]}
+ * @returns Object of { vertices: number[][], indices: number[][] }
+ */
+declare function getPoints(nucleotideData: number[][]): {
+    vertices: number[][];
+    indices: number[][];
+};
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Sameer Dingore <sdingore@csumb.edu>
+ */
+
+/**
+ * ________________________________________________________________________________________________
+ */
+interface MotifProps {
+    motif: Motif;
+    locked: boolean;
+    position?: Vec3;
+    rotation?: Quat;
+}
+/**
+ * ________________________________________________________________________________________________
+ */
+interface CustomEventProps {
+    event: Events.Event;
+    eventType: Events.EventType;
+    callback: (event: Events.Event) => void;
+}
+/**
+ * ________________________________________________________________________________________________
+ */
+interface CanvasProps {
+    title?: string;
+    rendererWidth?: number;
+    rendererHeight?: number;
+    rendererBackgroundColor?: string;
+    rendererSizeIsWindow?: boolean;
+    cameraPositionZ?: number;
+    motifProps: MotifProps[];
+    customEventProps?: CustomEventProps[];
+}
+
+/**
+ * Copyright (c) 2025 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Sameer Dingore <sdingore@csumb.edu>
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+
+/**
+ * ________________________________________________________________________________________________
+ */
+/**
+ * Canvas component renders the 3D canvas and the motifs on it.
+ * @param param0 {CanvasProps} A CanvasProps object
+ * @function Canvas {JSX.Element}
+ * @returns {JSX.Element}
+ */
+declare function Canvas({ rendererHeight, rendererWidth, rendererBackgroundColor, rendererSizeIsWindow, cameraPositionZ, motifProps, customEventProps, }: CanvasProps): JSX.Element;
+
+/**
+ * Copyright (c) 2025 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <silva.judah7@outlook.com>
+ */
+interface ScoreInfo {
+    score: number;
+    selId: string;
+    refId: string;
+}
+declare enum CanvasAttributeTypes {
+    SELECTED_MOTIFS = "selectedMotifs",
+    LOCKED_MOTIF_IDS = "lockedMotifIds",
+    HLOCKED_MOTIF_IDS = "hardLockedMotifIds",
+    SCORE_RMSD = "scoreRMSD",
+    KABSCH_RMSD = "kabschRMSD"
+}
+declare class CanvasDataManager {
+    private static _selectedMotifIds;
+    private static _lockedMotifIds;
+    private static _hardLockedMotifIds;
+    private static _scoreRMSD;
+    private static _kabschRMSD;
+    private static _listeners;
+    static get selectedMotifIds(): Set<string>;
+    static setSelectedMotifIds(selectedMotifIds: Set<string>): void;
+    static get lockedMotifIds(): string[];
+    static setLockedMotifIds(lockedMotifIds: string[]): void;
+    static get hardLockedMotifIds(): string[];
+    static setHardLockedMotifIds(hardLockedMotifIds: string[]): void;
+    static get scoreRMSD(): ScoreInfo[][];
+    static setScoreRMSD(scoreRMSD: ScoreInfo[][]): void;
+    static get kabschRMSD(): number[][];
+    static setKabschRMSD(kabschRMSD: number[][]): void;
+    static subscribe(canvasAttributeType: CanvasAttributeTypes, callback: () => void): () => void;
+}
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Sameer Dingore <sdingore@csumb.edu>
+ * @author Judah Silva <jusilva@csumb.edu>
+ */
+
+/**
+ * @param motif1 The motif to rotate to
+ * @param motif2 The motif that will be rotated
+ * @returns An object with the best rotation matrix and best rmsd
+ */
+declare function kabschSlidingWindow(motif1: Motif, motif2: Motif): {
+    matrix: number[][];
+    rmsd: number;
+};
+declare function calculateAllKabschRMSD(motifMeshArray: Motif[]): number[][];
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <jusilva@csumb.edu>
+ */
+
+declare function calculateRMSD(selectedMotifMeshArray: Motif[], motifMeshArray: Motif[]): ScoreInfo[][];
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Sameer Dingore <sdingore@csumb.edu>
+ * @author Shahidul Islam <sislam@csumb.edu>
+ */
+
+/**
+ * Calculates the RMSD between two arrays of vector points
+ * @param coordinates1 An array of Vector3 coordinates
+ * @param coordinates2 An array of Vector3 coordinates
+ * @returns The RMSD score of the two coordinate arrays
+ */
+declare function getRMSD(coordinates1: Vec3[], coordinates2: Vec3[]): number;
+/**
+ * Calculates the RMSD score between the two motifs
+ * @param motif1 A Motif object
+ * @param motif2 A Motif object
+ * @returns The RMSD score of the motifs
+ */
+declare function getRMSD(motif1: Motif, motif2: Motif): number;
+declare function calculateRMSDSlide(coordinates1: Vec3[], coordinates2: Vec3[]): number;
+
+/**
+ * Copyright (c) 2024 RNA3DS Lab CSUMB.
+ * All code written for RNA3DS Lab is protected under the terms of the NDA.
+ * No code shall be distributed or modified without the permission of the PI.
+ * @author Judah Silva <jusilva@csumb.edu>
+ */
+
+declare function rotateAllPoints(atomCoords: Vec3[], quat: Quat): Vec3[];
+
+export { Canvas, CanvasAttributeTypes, CanvasDataManager, type CanvasProps, type CustomEventProps, EventManager, Events, Group, Matrix4, MeshObject, Motif, type MotifProps, Quat, RenderScene, Residue, type ScoreInfo, Vec3, calculateAllKabschRMSD, calculateRMSD, calculateRMSDSlide, getMotif, getPoints, getRMSD, kabschSlidingWindow, rotateAllPoints, updateAllMotifs };