🧪 3d-mole

A high-performance, open-source 3D and 2D chemical structure visualizer built with Next.js 15, Three.js, and the PubChem PUG REST API.

---

🌟 Overview

3d-mole (github.com/anshk1234/3D-Mole) provides researchers, chemists, students, and educators with a minimalist, ultra-fast interface for rendering, inspecting, and analyzing molecular structures in real-time. By fetching 3D SDF conformers and high-resolution 2D skeletal structures directly from PubChem, 3d-mole delivers interactive visualization with zero server latency.

---

✨ Key Features

🧊 Interactive 3D Conformer Viewer

• Multiple Display Modes: Render molecules in Ball & Stick, Spacefilling (VDW), Sticks, or Wireframe representations.
• Raycasting & Atom Selection: Click any atom in 3D space to inspect its element, index, and 3D coordinates $(x, y, z)$.
• Distance Measurement: Select two atoms sequentially to calculate exact interatomic Euclidean distance in Angstroms ($\text{\AA}$).
• Dynamic Lighting & Controls: Full camera controls (orbit, pan, zoom), toggleable smooth auto-rotation, camera view reset, and high-res PNG snapshot exporter.
• Preserved Canvas Lifecycle: Smooth theme toggling without resetting or flickering 3D webgl contexts.

📐 High-Resolution 2D Structure Rendering

• Vector Skeletal Graphics: Clean PubChem 2D diagrams featuring stereobonds, double/triple bonds, and heteroatom color coding.
• Interactive Canvas: Smooth zoom controls ($60%$ to $220%$) and high-resolution PNG download.

📊 Chemical Properties & Molecular Insights

• Key Metrics Grid: Instant calculation/display for Molecular Weight ($\text{g/mol}$), Topological Polar Surface Area ($\text{TPSA}$ in $\text{\AA}^2$), Lipophilicity ($\text{LogP}$ / $\text{XLogP3}$), and Hydrogen Bond Donor/Acceptor counts.
• Structural Identifiers: Copyable IUPAC Name, Canonical SMILES, and InChIKey, alongside direct links to PubChem compound entries.

🖤 Minimalist & Premium UI

• OLED Black / Minimalist Theme: Obsidian dark mode #000000 paired with crisp typography and subtle border accents.
• Light Mode Support: Clean, high-contrast light mode for printing or daylight viewing.
• Responsive Layout: Seamless navigation across split side-by-side mode, dedicated 3D mode, and 2D mode.

---

🛠️ Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• 3D Graphics Engine: Three.js
• Styling: Tailwind CSS v4
• Icons: Lucide React
• Data Source: PubChem PUG REST API

---

🚀 Getting Started

Prerequisites

Ensure you have the following installed on your system:

• Node.js: v18.0.0 or higher
• npm: v9.0.0 or higher (or pnpm / yarn)

Installation

1. Clone the repository:

   git clone https://github.com/anshk1234/3D-Mole.git
   cd 3D-Mole

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

4. Open in browser: Navigate to http://localhost:3000 to access the application.

---

🏗️ Production Build & Deployment

To build the application for production:

# Create optimized production build
npm run build

# Start production server
npm run start

Deploying to Vercel / Cloud Run

Since 3d-mole is a client-rendered React/Next.js application leveraging external public APIs, it can be deployed with zero backend configuration on platform hosts such as Vercel, Netlify, or Docker/Cloud Run.

---

📁 Project Structure

3d-mole/
├── app/
│   ├── globals.css         # Tailwind CSS imports & global styles
│   ├── layout.tsx          # Root application layout
│   └── page.tsx            # Main application visualizer view
├── components/
│   ├── MoleculeHeader.tsx   # Search bar, presets, view switchers, theme toggle
│   ├── Molecule3DViewer.tsx # Three.js 3D conformer canvas & controls
│   ├── Normal2DViewer.tsx   # 2D structure viewer with zoom & export
│   └── MoleculeDetails.tsx  # Property metrics grid & chemical table
├── lib/
│   └── pubchem.ts          # PubChem REST API fetching & SDF parser
├── types/
│   └── chemistry.ts        # TypeScript definitions for compounds & atoms
├── package.json
└── README.md

---

🔬 How It Works (PubChem PUG REST Integration)

1. Search Query Resolution: Resolves user queries (e.g. caffeine, C8H10N4O2, CID 2519) to PubChem Compound Identifiers (CID) via: https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/name/{query}/cids/JSON
2. 2D & Property Data: Fetches structural properties and standard 2D vector diagrams via PubChem's JSON and SVG endpoints.
3. 3D SDF Conformer Parser: Fetches 3D atomic coordinates in Structure-Data File (.sdf) format via: https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/cid/{cid}/SDF?record_type=3d
4. Three.js Scene Builder: Parses the SDF block into atomic nodes (element, radius, CPK color, coordinates) and bond connectors, rendering spheres and cylinders in a 3D webgl scene.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue for bug reports or feature requests.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.