pixalynx/pixal-gps

simulator/README.md

# PIXAL GPS product studio

Interactive Three.js product rendering and assembly study for the three existing Pixal GPS PCBs. The original circuit design is unchanged.

```sh
bun install
bun run dev
# http://localhost:4186/
bun run build
```

Open **Complete kit**, **Tracker**, **Battery** or **Dock**. Drag to orbit, scroll to zoom. Use **Cutaway** to remove enclosure walls/covers and expose the electronics.

## Measurements

Enable **Measurements** and choose a piece. Dimension lines follow that piece during orbit and assembly. Selecting a piece opens the appropriate product view. Green dimensions are PCB export dimensions or nominal component envelopes; amber dimensions are inferred packaging. **Save render** includes visible measurement labels.

| Piece | Width × length × thickness/height (mm) | Basis |
| --- | --- | --- |
| Tracker PCB | 34 × 24 × 1.6 | Circuit JSON |
| Protection/contact PCB | 30 × 7 × 0.8 | Circuit JSON; older project notes say 26 × 7 |
| Dock PCB | 56 × 44 × 1.6 | Circuit JSON |
| Pouch cell | 30.5 × 40.5 × 5.4 | Nominal 503040-class cell in project notes; capacity label 600 mAh |
| Receiver coil | 30 × 29.6 × 1 | TDK candidate envelope in project notes |
| Transmitter coil | 50 × 50 × 3 | A11 candidate envelope; winding geometry simplified |
| Tracker enclosure | ≈42 × 60 × 18 | Inferred |
| Cartridge envelope | ≈35 × 57 × 8 | Inferred, including front access face |
| Dock enclosure | ≈64 × 64 × 12 | Inferred |

## Animation and export

- **Build assembly**: 18-second staged dock and tracker construction; pause/resume and a scrubbable progress slider.
- **Exploded view**: toggle separated/assembled parts.
- **Swap battery**: 11-second cartridge withdrawal, hold and reinsertion; opens the cutaway.
- **Dock & charge**: lift and align tracker over the dock, followed by an illustrative charging pulse. No electromagnetic or charge-state simulation is claimed.
- **Turntable**: continuous camera orbit.
- **Record animation**: records/restarts the active sequence to WebM; defaults to assembly, or a turntable clip when turntable alone is active. Keep the tab foreground during recording.
- **Save render**: high-resolution PNG with visible labels and a concept watermark.
- **3D model**: exports visible geometry to GLB at the current assembly state. Units are millimetres in this scene (scale by 0.001 for software interpreting glTF units strictly as metres). Procedural animations remain in the viewer; use the exported videos for playback elsewhere.

## Saved deliverables

- `renders/pixal-gps-kit.png`
- `renders/pixal-gps-exploded.png`
- `renders/pixal-gps-tracker-cutaway.png`
- `renders/pixal-gps-cartridge.png`
- `renders/pixal-gps-protection-measurements.png`
- `renders/pixal-gps-dock-cutaway.png`
- `renders/pixal-gps-assembly.mp4` and `.webm`
- `renders/pixal-gps-battery-exchange.mp4` and `.webm`
- `renders/pixal-gps-docking.mp4` and `.webm`
- `renders/pixal-gps-concept.glb`

## Fidelity and assumptions

`scripts/sync-hardware.py` snapshots existing Circuit JSON into `src/hardware.json`. The board outlines, thicknesses, fitted component locations, outer-layer traces, pad locations and hole positions derive from these exports. DNP components are omitted. Component bodies are simplified; many use exported land bounds instead of exact manufacturer bodies. Copper pours and all silkscreen detail are not reproduced. Rounded corners and drill slots are simplified in places. This is not a manufacturing model.

The protection PCB is translated +1.5 mm in X and placed at the tracker pogo row. All four nominal pad centres align with their corresponding pogo axes, with a 2.5 mm nominal working contact height. Cartridge rails, catch, shell, screws, LED light pipes, antenna shapes, cable routes and cell fit are inferred. There is no mechanical collision, tolerance-stack or insertion-life qualification. Internal clearances, swelling, insulation, grounding, coil wiring and programming/SIM access require engineering review.

The Rx coil stays in the tracker under the cartridge; ferrite faces the battery. Tx ferrite faces the dock PCB. Antennas are provisional envelopes, not selected or RF-qualified SKUs. No IP/weatherproof rating is implied.

[Fabrication review](../review/FAB-READINESS.md) records the electrical and production issues found without changing the design.

## Verification

Production build passes. Browser checks cover assembly completion and pause/resume, battery and docking video downloads, still-image and GLB downloads, all nine measurement choices, four-contact nominal alignment, modal dismissal and mobile document overflow. Screenshots were visually inspected; examples and the final browser log are in `output/playwright`. The GLB header and JSON chunk parse successfully. MP4 clips were transcoded from the recorded WebM clips and a midpoint frame was inspected.

`source-hashes.json` preserves hashes of the 25 original circuit/export files used for the model and review. `../review/evidence/source-preservation.txt` records that none changed.