# Chaotic Pendulum Lab

Chaotic Pendulum Lab is a browser-based 3D multi-pendulum visualizer built as an AI-assisted creative coding project.

It combines Three.js, D3.js, GLSL shaders, numerical simulation, interactive UI controls, motion trails, reactive starfields, fireworks effects, and energy/divergence charts into a single offline-capable HTML application.

## 日本語概要

Chaotic Pendulum Lab は、生成AI支援で制作したブラウザ完結型の3D多重振り子ビジュアライザーです。

Three.jsによる3D描画、D3.jsによるエネルギー・発散グラフ、GLSLシェーダによる星空・軌跡・小花火表現を組み合わせ、カオス的な運動を視覚的に楽しめる単一HTMLアプリとして実装しました。

## Demo

GitHub Pages demo:

[https://analyst-mm-2749261.github.io/chaotic-pendulum-lab/]

## Quick Start

Open `index.html` in a modern browser.

This repository includes an offline-capable bundled HTML version. The app-specific code and third-party JavaScript/CSS dependencies are bundled into `index.html`, so the app can run without external CDN access after download.

Recommended browsers:

- Google Chrome / Microsoft Edge on desktop
- Safari / Chrome on modern mobile devices
- Any modern browser with WebGL support

## Features

- 3D multi-pendulum simulation
- Interactive camera controls
- RK4-based numerical integration
- Constraint-based rod dynamics
- Colorful motion trails
- Reactive starfield effects
- Fireworks-style background particles
- Energy chart with D3.js
- Divergence chart for chaos visualization
- Ghost trajectory mode
- Preset-based initial conditions
- Mobile-friendly control panel
- Screenshot export
- Offline-capable single HTML bundle

## Technical Highlights

### Three.js / WebGL Rendering

The pendulum system is rendered in real time with Three.js. The scene includes glowing bobs, rods, motion trails, reactive background effects, and camera controls.

### GLSL Shader Effects

Custom shaders are used for glowing trails, starfields, reactive background effects, and fireworks-like particles. The visual effects are designed to respond to the motion of the pendulum rather than being static decoration.

### D3.js Charts

D3.js is used to render energy and divergence charts alongside the 3D simulation. This makes it possible to observe both the visual motion and the numerical behavior of the system.

### Chaos Visualization

The ghost trajectory mode runs a slightly perturbed pendulum in parallel. By observing the distance between the original and ghost trajectories, the app visualizes sensitivity to initial conditions.

### Offline Bundle

The app is distributed as a single bundled HTML file. Third-party JavaScript/CSS dependencies are included for offline use. See `THIRD_PARTY_LICENSES.md` for details.

## Development Process

This project was developed through an AI-assisted, human-directed workflow.

Generative AI tools were used to support implementation, debugging, refactoring, shader design, UI iteration, and documentation. The overall concept, visual direction, interaction design, feature selection, testing, and final integration decisions were made by the repository owner.

This repository is intended as a portfolio project demonstrating AI-assisted creative coding, browser-based simulation design, and interactive visualization.

## Related Articles

Japanese technical articles:

- [3D多重振り子シミュレータの物理・カオス・演出を読み解く](https://zenn.dev/hajimeteradio3/articles/9f72eb65a06c2a)
- [小花火演出の作り込み：物理に同期する粒子表現](https://zenn.dev/hajimeteradio3/articles/14eef33aa5f5de)


## Screenshots

<p align="center">
  <img src="screenshots/main-view.PNG" alt="Main view" width="260">
  <img src="screenshots/fireworks-mode.PNG" alt="Fireworks mode" width="260">
</p>

<p align="center">
  <img src="screenshots/control-panel.PNG" alt="Control panel">
  <img src="screenshots/chaos-analysis.PNG" alt="Chaos analysis" width="260">
</p>

## Limitations

- This is a visual and educational simulation, not a physically certified engineering tool.
- Numerical behavior may vary depending on browser, device performance, and graphics capabilities.
- Very high visual settings may reduce performance on mobile devices.
- The app is optimized for modern browsers with WebGL support.
- Because the app is distributed as a bundled HTML file, the file size is larger than a CDN-based version.

## Privacy

The app runs locally in the browser. It does not require a backend server and does not intentionally send user data to an external service.

## License

The application-specific code is released under the license specified in `LICENSE`.

Bundled third-party libraries remain under their original licenses. See `THIRD_PARTY_LICENSES.md`.