# 学科引擎SubjEngine

**Repository Path**: codekpy/subj-engine

## Basic Information

- **Project Name**: 学科引擎SubjEngine
- **Description**: 概述：EduTools 是一套面向高中教学的交互式网页教材与实验演示集合，包含物理、化学等学科的可视化模拟与教学工具。
特点：基于轻量 HTML/CSS/JavaScript（使用 Tailwind 等工具），界面响应式、交互友好、参数可调，便于课堂演示与学生自主探索。
目标受众：高中教师与学生，也适合作为教材补充与课堂实验预习资源。
贡献与部署：源码友好、便于扩展，欢迎加入项目
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://subj-engine.cloudroo.top/
- **GVP Project**: No

## Statistics

- **Stars**: 11
- **Forks**: 5
- **Created**: 2025-12-13
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SubjEngine · Subject Engine

> **Making Knowledge Visible, Making Learning More Vivid** | 让知识可视化，让学习更生动

SubjEngine is an open-source platform that aggregates interactive subject simulation animations. It transforms abstract concepts from Physics, Chemistry, Mathematics, and Information Technology into visual, interactive demonstrations. The project features **24+** high-quality simulation demos with multi-dimensional search, favorites, download, and Canvas recording capabilities.

[![Gitee](https://img.shields.io/badge/Gitee-subj--engine-0071e3?style=flat-square)](https://gitee.com/codekpy/subj-engine.git)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](LICENSE)

---

## Table of Contents

- [Core Features](#core-features)
- [Project Structure](#project-structure)
- [Technology Stack](#technology-stack)
- [Quick Start](#quick-start)
- [Subject Overview](#subject-overview)
- [Sub-projects](#sub-projects)
- [Data Format](#data-format)
- [Contributing](#contributing)
- [Development Guide](#development-guide)
- [License](#license)
- [Acknowledgments](#acknowledgments)

---

## Core Features

### Multi-Subject Coverage
Covers **Physics**, **Chemistry**, **Mathematics**, and **Information Technology**, spanning from middle school to high school elective levels, with **24+** interactive demos.

### Modern UI/UX
- **Apple-Inspired Design**: SF Pro font, glassmorphism aesthetics, immersive dark mode
- **Smart Filtering**: Keyword search, subject filter, grade filter, hot tag cloud
- **Favorites System**: localStorage-based persistent favorites
- **Recommended Scrolling**: Two rows of horizontally scrolling featured projects

### Unified Viewer
All demos load through `viewer.html` with support for:
- iframe nested loading of demo pages
- Project info display (name, author, subject, summary)
- Previous/Next navigation and related recommendations
- **Download**: Single file or ZIP package download

### Canvas Recording
Built-in `canvas-recorder.js` component supports:
- Record/stop/download controls
- Multi-format export (WebM / MP4 / GIF)
- Video cropping (set start/end time)
- Real-time recording duration display

### 3D Interactive Visualization
Three.js-based chemistry tools:
- **Molecule Viewer**: Molecular search, VSEPR model, lone pair display
- **MolForge Editor**: Molecule building, editing, import/export
- **Crystal Cell Viewer**: Multi-structure crystal 3D display

---

## Project Structure

```
SubjEngine/
├── index.html                    # Homepage (Apple-style, scrolling + masonry)
├── viewer.html                   # Unified viewer (iframe nested loading)
├── list.json                     # Demo entries data (24+ projects)
├── author.json                   # Creator info (3 contributors)
├── plan.md                       # Project development plan
├── task.md                       # Task progress tracking
├── prompt.md                     # Development guide & template
├── blog-post.md                  # Promotional blog post
├── LICENSE                       # Apache 2.0
│
├── Physics/                      # Physics simulations (13 demos)
├── Chemistry/                    # Chemistry simulations
│   ├── CrystalCell/              #    Crystal cell 3D viewer (Vite + TS)
│   ├── MolForge/                 #    3D molecule editor (Vite + TS)
│   ├── MoleculeViewer/           #    3D molecule viewer (Vite + TS)
│   ├── PeriodicLab/              #    Periodic trends interactive lab
│   └── virtual-lab/              #    Virtual chemistry lab
├── Math/                         # Math simulations (2 demos)
├── Information/                  # IT simulations (2 demos)
│
├── static/                       # Public static resources
│   ├── css/                      #    Styles (Tailwind, Font Awesome, etc.)
│   ├── js/                       #    JS libs (Tailwind, MathJax, Three.js, recorder...)
│   ├── fonts/                    #    Font files
│   ├── img/                      #    Images
│   └── webfonts/                 #    Web fonts
│
├── tools/                        # Utility pages
│   └── editor.html               #    Browser-based list.json editor
│
├── docs/                         # Documentation screenshots
└── .trae/                        # AI-assisted dev records & specs
```

---

## Technology Stack

| Category | Technology | Notes |
|----------|-----------|-------|
| **Frontend** | HTML5 / CSS3 / JavaScript (ES6+) | Vanilla, no framework |
| **TypeScript** | TypeScript 5.3+ | Used in 3 Vite sub-projects |
| **CSS** | [Tailwind CSS](https://tailwindcss.com/) 3.4 | Local file, no build step |
| **Icons** | [Font Awesome](https://fontawesome.com/) 4.7 / 6.4 | Local files |
| **Math** | [MathJax](https://www.mathjax.org/) 3 | Local file, LaTeX support |
| **3D Graphics** | [Three.js](https://threejs.org/) r160 | Used in 3 chemistry sub-projects |
| **2D Graphics** | HTML5 Canvas API | Core rendering for all demos |
| **Build Tool** | [Vite](https://vitejs.dev/) 5 | 3 TypeScript sub-projects |
| **Recording** | MediaRecorder API | Canvas recording & export |
| **ZIP** | JSZip | CDN, ZIP packaging |

---

## Quick Start

### Prerequisites

- Modern browser (Chrome 90+ / Firefox 90+ / Edge 90+ / Safari 15+)
- Optional: Python 3.x or Node.js (for local preview)

### Local Preview

**Option 1: Python**
```powershell
cd f:\program\StarBit\code\EduTools
python -m http.server 8000
```

**Option 2: Node.js**
```powershell
cd f:\program\StarBit\code\EduTools
npx http-server -p 8000
```

### Access Pages

- **Homepage**: [http://localhost:8000/](http://localhost:8000/)
- **Unified Viewer**: `http://localhost:8000/viewer.html?demo=Physics/lorentz-force-circular-motion.html`
- **Editor Tool**: [http://localhost:8000/tools/editor.html](http://localhost:8000/tools/editor.html)

### Build Vite Sub-projects

```powershell
# 1. Crystal Cell
cd Chemistry/CrystalCell
npm install
npm run build

# 2. Molecule Viewer
cd ../MoleculeViewer
npm install
npm run build

# 3. MolForge
cd ../MolForge
npm install
npm run build
```

---

## Subject Overview

### Physics — 13 Demos

| Project | File | Grade | Description |
|---------|------|-------|-------------|
| Lorentz Force Circular Motion | `lorentz-force-circular-motion.html` | XB2 | Charged particle motion in magnetic field |
| Force Composition & Decomposition | `Composition&decomposition&forces.html` | B1 | Parallelogram and triangle rules |
| Universal Gravitation | `CalculationOfUniversalGravitationOfCelestialBodies.html` | B2 | Newton's law interactive calculation |
| Kinematics Simulation | `kinematics-simulation.html` | B1 | Uniform acceleration, free fall, projectile |
| Wave Interference | `wave-interference-simulation.html` | XB1 | Dual-source wave superposition |
| Double-Slit Interference | `double-slit-interference.html` | XB1 | Young's experiment, fringe calculation |
| Gas Molecular Motion | `gas-molecule-motion.html` | XB3 | Maxwell-Boltzmann distribution |
| Ideal Gas Law | `ideal-gas-law.html` | XB3 | PV=nRT interactive verification |
| Lens Imaging | `middle-school-physics-lens-imaging-simulation.html` | J3 | Convex/concave lens ray tracing |
| Scaling Circle Analysis | `放缩圆分析临界问题.html` | XB2 | Lorentz force scaling circle |
| Rotating Circle | `旋转圆2.html` | XB2 | Lorentz force rotating circle |
| Electromagnetic Flowmeter | `电磁流量计 .html` | XB2 | Flowmeter working principle |
| Electric Field Lines | `Eletrical_lineDemo/index.html` | B3 | Opposite charge field distribution |

### Chemistry — 6 Modules

| Project | Path | Description |
|---------|------|-------------|
| Reaction Rate | `Chemical Reaction Rate Simulation.html` | Rate factor simulation |
| Virtual Lab | `virtual-lab/` | 14 instruments + 16 reagents + real-time reactions |
| Molecule Viewer | `MoleculeViewer/` | 3D molecule viewer, VSEPR, lone pairs |
| MolForge Editor | `MolForge/` | 3D molecule construction, editing, import/export |
| Crystal Cell | `CrystalCell/` | Simple/FCC/Diamond/CaF₂ structures |
| Periodic Lab | `PeriodicLab/` | Ionization energy, electronegativity trends |

### Mathematics — 2 Demos

| Project | File | Description |
|---------|------|-------------|
| Sequence Animation | `sequence-animation.html` | Arithmetic/geometric sequence visualization |
| Reciprocal Function | `ReciprocalSimulator.html` | Dynamic function demonstration |

### Information Technology — 2 Demos

| Project | File | Description |
|---------|------|-------------|
| Pathfinding Algorithms | `pathfinding-algorithms.html` | DFS/BFS/Dijkstra/A* visualization |
| High-Precision Calculation | `high-precision-calculation.html` | Large number arithmetic visualization |

---

## Sub-Projects

### Chemistry Virtual Lab
A realistic interactive chemistry experiment platform.
- **14 Instruments**: Beakers, test tubes, flasks, burners, etc.
- **16 Reagents**: 3 acids + 3 bases + 3 salts + 3 indicators + 4 metals
- **Real-time Reaction Engine**: Acid-base, metal-acid, double displacement, indicator color change
- **Visual Effects**: Liquid color mixing, bubble animation, precipitation, temperature change
- **8 Preset Experiments**: Ready-to-use classic experiments

### 3D Molecule Viewer
Full-screen 3D molecule viewer built with Three.js + TypeScript + Vite.
- **Molecule Search**: 10+ built-in molecules (H₂O, CO₂, CH₄, NH₃, etc.)
- **3D Interaction**: OrbitControls for rotation/zoom
- **Axis Gizmo**: Blender-style coordinate reference, click to switch views
- **VSEPR Model**: Molecular geometry switching
- **Lone Pair Display**: Visualized lone electron pairs
- **Dual Rendering**: Coordinate-defined and angle-calculated atom positions

### 3D MolForge Editor
Full-featured 3D molecular editor.
- **Molecular Construction**: Add/delete atoms, create/edit bonds
- **Preset Templates**: Water, methane, ethane, benzene, ethanol, etc.
- **Transform Tools**: Select, move, rotate, scale (with axis locking)
- **Keyboard Shortcuts**: Dual-mode shortcuts for edit/view
- **Measurement Tools**: Bond length, angle, dihedral (view mode)
- **Import/Export**: PNG/GLTF/GLB/PDB/JSON formats
- **Auto-Rotate**: One-click Y-axis rotation
- **Fullscreen Mode**: Immersive view with hidden UI

### Crystal Cell 3D Viewer
Three.js-based crystal structure visualization.
- **Four Structures**: Simple cubic, FCC, Diamond, CaF₂
- **Atom Group Control**: Independent display of vertex/face/inner atoms
- **Interaction**: Click atoms to highlight, orthographic camera
- **Display Controls**: Border/bond/label toggles, auto-rotate

### Periodic Trends Lab
Interactive main group element (IA-VIIA & 0) periodic trends tool.
- **Four View Modes**: Card/list/compare/periodic table
- **Visualized Trends**: Ionization energy, electronegativity, bond polarity
- **Element Selection**: Click for detailed information

### Pathfinding Algorithms Demo
Full visualization of four classic pathfinding algorithms.
- **Algorithms**: DFS (stack), BFS (queue), Dijkstra (priority queue), A\* (heuristic)
- **Map Editor**: Draw/erase obstacles, set start/end points
- **Preset Maps**: Open, random, maze, U-shaped wall
- **Controls**: Start/pause/step/reset + speed adjustment
- **Visualization**: Real-time queue display, pseudocode highlighting, step descriptions
- **Statistics**: Visited nodes, queue length, path length, runtime

---

## Data Format

### list.json Entry Format

```json
{
  "name": "Lorentz Force Circular Motion Demo",
  "link": "Physics/lorentz-force-circular-motion.html",
  "summary": "Demonstrates uniform circular motion under Lorentz force",
  "author": "CodeKpy-豆包",
  "contact": "codekpy@foxmail.com",
  "time": "2026-04-12",
  "subject": "物理",
  "grade": "XB2",
  "tags": ["Lorentz Force", "Circular Motion", "Magnetic Field"]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Project name |
| `link` | string | Demo file path (relative to root) |
| `summary` | string | Project summary |
| `author` | string | Author name |
| `contact` | string | Contact email |
| `time` | string | Creation/update date (YYYY-MM-DD) |
| `subject` | string | Subject (物理/化学/数学/信息技术) |
| `grade` | string | Grade level (J3, B1, XB2, etc.) |
| `tags` | string[] | Tag array |

---

## Contributing

We welcome all forms of contributions!

### Adding a New Demo

1. **Create Demo File**: Create HTML file in the corresponding subject directory (see [prompt.md](prompt.md) for template)
2. **Follow UI Specs**: Use Tailwind CSS + Font Awesome, maintain consistent style
3. **Update list.json**: Add a new entry
4. **Submit PR**: Via [Gitee](https://gitee.com/codekpy/subj-engine.git)

### Using the Editor

1. Open `tools/editor.html`
2. Load current `list.json`
3. Edit entries in the browser UI
4. Export JSON and replace the local file

### Git Workflow

```powershell
git clone https://gitee.com/codekpy/subj-engine.git
git checkout -b feat/your-new-demo
git add list.json Physics/your-demo.html
git commit -m "feat: add new physics demo"
git push origin feat/your-new-demo
```

---

## Development Guide

Refer to [prompt.md](prompt.md) for the standard template and specifications:

- **Layout**: CSS Grid `lg:grid-cols-[320px_1fr]`, responsive to single column on small screens
- **Colors**: Blue theme (primary `#2563eb`, secondary `#4f46e5`)
- **Canvas Rendering**: All simulation content via Canvas API, white background
- **Modals**: Theory/analysis content in modals with MathJax support
- **Local Resources**: All static assets are local files, no CDN dependency
- **Recording**: Integrate `canvas-recorder.js` for recording/download

### Developing Vite Sub-projects

```powershell
# Dev mode
cd Chemistry/MoleculeViewer
npm run dev

# Production build
npm run build

# Preview build
npm run preview
```

---

## License

This project is open-sourced under **Apache License 2.0**. See [LICENSE](LICENSE) for details.

---

## Acknowledgments

### Contributors

| Contributor | Role | Contribution |
|-------------|------|-------------|
| **CodeKpy** | Project Lead & Developer | Frontend architecture, animations, core features |
| **资深小白程序员** | Contributor | Electric field line demo |
| **郑老师** | Teacher & Contributor | Lorentz force series demos |

### Open Source Projects

- [Tailwind CSS](https://tailwindcss.com/) — Modern CSS framework
- [Font Awesome](https://fontawesome.com/) — Icon library
- [MathJax](https://www.mathjax.org/) — Math formula rendering
- [Three.js](https://threejs.org/) — 3D graphics engine
- [Vite](https://vitejs.dev/) — Frontend build tool
- [JSZip](https://stuk.github.io/jszip/) — ZIP library

---

## Related Links

- **Gitee Repository**: [https://gitee.com/codekpy/subj-engine.git](https://gitee.com/codekpy/subj-engine.git)
- **Online Demo**: [https://subj-engine.cloudroo.top/](https://subj-engine.cloudroo.top/)
- **Contact**: [codekpy@foxmail.com](mailto:codekpy@foxmail.com)
- **Issues**: [Gitee Issues](https://gitee.com/codekpy/subj-engine/issues)

---

<p align="center">
  <strong>SubjEngine · Making Knowledge Visible, Making Learning More Vivid</strong>
</p>