## AI Night Vision Camera – Exhibition Setup

This project is a browser-based camera installation. It runs entirely on each laptop using a local web server and a modern browser.

The core files are:
- `index.html` – main experience (UI, camera, and AI logic)
- `yolo11n_web_model/` – YOLO model files used by the “Detection Protocol: YOLO-Vision” mode

The AI libraries (`@tensorflow/tfjs`, `@tensorflow-models/coco-ssd`, `@tensorflow-models/mobilenet`, `yolo-tfjs-vision`) are loaded from CDNs over the internet.

---

## 1. Minimum Requirements (Per Laptop)

- **Hardware**
  - Built‑in or USB **webcam**
  - Reasonably modern CPU/GPU (anything from ~2018+ should be fine)
  - Minimum 8 GB RAM recommended

- **Operating System**
  - **Windows 10/11**, **macOS 12+**, or a recent **Linux** distribution.

- **Browser**
  - **Google Chrome 115+** or **Microsoft Edge (Chromium-based, up to date)**.
  - Camera permissions enabled for the browser.

- **Runtime for local server** (choose one):
  - **uv + Python 3.10+** (recommended Python path; use uv to install/manage Python), or
  - **Python 3.7+** (fallback if you do not use uv), or
  - **Node.js 18+** (only needed if you prefer the Node-based `http-server` option).

- **Network**
  - Internet access to load AI libraries from CDNs:
    - `https://cdn.jsdelivr.net`
    - `https://codeskulptor-demos.commondatastorage.googleapis.com` (sound effect)

---

## 2. Folder Layout & Distribution

On each exhibition laptop, place the project in a single folder, e.g. `ai-night-vision/`, with at least:

- `ai-night-vision/`
  - `index.html`
  - `yolo11n_web_model/`
    - `model.json`
    - `*.bin` weight files
  - `start.sh` (Linux/macOS launcher)
  - `start.bat` (Windows launcher)
  - `README_EXHIBITION.md` (this file)

**Distribution suggestion**

- Create a zip archive `ai-night-vision.zip` containing this folder.
- Copy `ai-night-vision.zip` to each exhibition laptop (USB stick, network share, or cloud storage).
- On each laptop, unzip it to a simple path (e.g. Desktop or Documents).

---

## 3. Running the Piece (One-Step Launcher – Recommended)

Use these steps on each laptop. This is the expected daily startup procedure for gallery staff.

### Step 1 – Confirm uv/Python (one-time per laptop)

- **Windows**
  - Press `Win` key, type `cmd`, press Enter.
  - Preferred: check uv first:
    - `uv --version`
  - Run:
    - `python --version` **or**
    - `python3 --version`
  - If Python is missing, install it via uv (`uv python install 3.12`) or install from `https://www.python.org`.

- **macOS / Linux**
  - Open **Terminal**.
  - Preferred: check uv first:
    - `uv --version`
  - Run:
    - `python3 --version`
  - If Python is missing, install it via uv (`uv python install 3.12`).

### Step 2 – Start with the launcher script

1. Unzip `ai-night-vision.zip` (if not already).
2. Open the unzipped `ai-night-vision/` folder.
3. Launch using one file:
   - **Windows**: double-click `start.bat`
   - **macOS / Linux**: open terminal in this folder and run:

```bash
chmod +x start.sh
./start.sh
```

The launcher automatically starts a local HTTP server and opens:

```text
http://localhost:8000/index.html
```

When the browser asks for **camera access**, click **Allow**.

### Step 3 – Using the interface during the exhibition

Once the page is open:

- Use the **resolution selector** for 480p / 720p / 1080p.
- Use the **model selector** to switch between:
  - `Detection Protocol: COCO-SSD`
  - `Analysis Protocol: MobileNet`
  - `Detection Protocol: YOLO-Vision`
- Use buttons:
  - `Toggle Detection` – start/stop AI processing.
  - `Toggle Night Vision` – apply “night vision” camera effect.
  - `Sound FX` – enable/disable detection sound effects.
  - `Hide UI (H)` – hide/show controls and status overlay. You can also press `H` on the keyboard.

If something becomes unresponsive:

- First try pressing the browser’s **refresh** button.
- If that isn’t enough, close the browser tab, stop the launcher terminal (`Ctrl+C`), then run the launcher again.

### Step 4 – Fallback manual startup (if launcher is blocked)

If script execution is restricted on a specific laptop, run the server manually:

- **Preferred (with uv, any OS)**:

```bash
uv run python -m http.server 8000
```

- **Windows** (Command Prompt in `ai-night-vision/`):

```bat
python -m http.server 8000
```

- **macOS / Linux** (Terminal in `ai-night-vision/`):

```bash
python3 -m http.server 8000
```

Then open `http://localhost:8000/index.html` in Chrome/Edge.

---

## 4. Alternative: Node.js `http-server` (Optional)

If a laptop already has Node.js installed and you prefer this approach:

1. Install `http-server` **once** per laptop:

```bash
npm install -g http-server
```

2. In a terminal inside the `ai-night-vision/` folder, run:

```bash
http-server -p 8000
```

3. Open `http://localhost:8000/index.html` in Chrome/Edge as above.

---

## 5. Exhibition Hardening Checklist

For a smooth gallery experience, apply these settings on each laptop:

- **Full-screen display**
  - In Chrome / Edge, press `F11` (Windows/Linux) or `Ctrl+Cmd+F` (macOS) to enter full-screen.
  - Ensure the cursor is moved away from the center of the image.

- **Prevent sleep / screen saver**
  - In OS power settings, set the computer to **never sleep** and **never turn off display** during opening hours.
  - Disable screen savers and automatic lock where possible.

- **Camera permissions**
  - In Chrome site settings, confirm that `http://localhost:8000` is allowed to use the **camera**.
  - Do this once per laptop and test before the exhibition opens.

- **Startup routine suggestion**
  - At the beginning of each day:
    1. Start the local server (Python or Node).
    2. Open `http://localhost:8000/index.html`.
    3. Allow camera access.
    4. Enter full-screen.
    5. Verify detection is working (e.g. walk in front of the camera and toggle detection).

---

## 6. Future: Fully Offline Version (Planned)

Currently, the page loads TensorFlow.js, model definitions, and the YOLO wrapper from CDNs. If you ever need to run this piece **without any internet connection**, the code can be adapted as follows:

- **Mirror the CDN scripts locally**
  - Download the exact `.js` files currently loaded from:
    - `https://cdn.jsdelivr.net/npm/@tensorflow/tfjs`
    - `https://cdn.jsdelivr.net/npm/@tensorflow/tfjs-backend-webgpu`
    - `https://cdn.jsdelivr.net/npm/@tensorflow-models/coco-ssd`
    - `https://cdn.jsdelivr.net/npm/@tensorflow-models/mobilenet`
    - `https://cdn.jsdelivr.net/npm/yolo-tfjs-vision@latest/dist/yolo.umd.js`
  - Save them into a local subfolder, e.g. `vendor/`, and change the `<script>` tags in `index.html` to point to these local copies.

- **Confirm no external URLs remain**
  - Ensure any fonts, sounds, or other assets are either local files (e.g. in an `assets/` folder) or reliably reachable.

Once this refactor is done, the `ai-night-vision/` folder will be fully self-contained and can run with **no network connection at all** using the same local-server instructions above.