Skip to content

feat(site): interactive 3D blueprint viewer for hardware diagrams#102

Merged
AndrewAltimit merged 9 commits intomainfrom
feat/blueprint-viewer
Mar 31, 2026
Merged

feat(site): interactive 3D blueprint viewer for hardware diagrams#102
AndrewAltimit merged 9 commits intomainfrom
feat/blueprint-viewer

Conversation

@AndrewAltimit
Copy link
Copy Markdown
Owner

@AndrewAltimit AndrewAltimit commented Mar 31, 2026

Summary

  • Interactive 3D blueprint viewer at site/blueprint.html with ?diagram= URL param, powered by Three.js
  • Two hardware diagrams: PSP USB-C adapter (passive bridge) and PSP hard reset relay (H-bridge wiring)
  • Real PSP-3001 3D model (FBX to GLB converted, wireframe + dark fill) replaces procedural approximation
  • Modular architecture: engine (blueprint-engine.js) + per-diagram files (blueprints/*.js) -- adding a new diagram is one JS file + one <script> tag
  • Journal entries 05 and 08 link to interactive blueprints from their static diagram images
  • Headless screenshot pipeline (scripts/blueprint-screenshot.js) for automated visual testing

Architecture

blueprint.html          -- 73-line HTML shell
js/blueprint-engine.js  -- reusable engine (orbit, explode, hover, tabs, shared PSP component)
js/blueprints/*.js      -- self-contained diagram data + build functions
models/psp.glb          -- PSP-3001 mesh (Git LFS, 2.7MB)

Key decisions

  • 3D text labels (world-space planes) instead of billboard sprites -- stays aligned with geometry during rotation
  • PSP model rotation calibrated via interactive test grid (PI/2 - 0.75 compensates for FBX export tilt)
  • Connector spacing matches real PSP hardware photos (Go!Cam teardown): 1 power pad per side, screw holes at edges
  • H-bridge wiring verified against actual relay module photos: swapped NC/NO pattern between relays
  • Data-driven tab system: diagrams declare {explode: N} per tab state, no hardcoded IDs in engine

Test plan

  • Open blueprint.html?diagram=psp-usb-adapter -- PSP model renders upright, adapter sits on top
  • Open blueprint.html?diagram=psp-relay -- relay, PSU, PC, actuator with correct H-bridge wiring
  • Explode slider separates components smoothly
  • Hover tooltips appear on component hover
  • Tab switching works (assembled/exploded, relay states)
  • Journal entries 05 and 08 link to interactive versions
  • node scripts/blueprint-screenshot.js psp-usb-adapter produces 6 screenshots

Generated with Claude Code

AI Agent Bot and others added 5 commits March 31, 2026 03:33
@claude
feat(site): interactive 3D blueprint viewer for hardware diagrams
2bbf04e 
Data-driven Three.js blueprint viewer at site/blueprint.html with
?diagram= URL param. Two diagrams: psp-relay (H-bridge actuator wiring)
and psp-usb-adapter (passive USB-C bridge with upright PSP model).
Journal entries 05 and 08 link to interactive versions from their
static diagram images. Includes headless screenshot test script.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude
refactor(site): modular blueprint viewer with shared engine and compo…
4fbfdeb 
…nents

Split 880-line monolith into 4 focused files:
- blueprint.html (73 lines) — thin HTML shell, loads scripts
- blueprint-engine.js (410 lines) — reusable engine: orbit controls,
  explode slider, hover tooltips, tabs, render loop, shared PSP body
  component (buildPSP), and drawing helpers
- blueprints/psp-relay.js (154 lines) — relay diagram data + build
- blueprints/psp-usb-adapter.js (154 lines) — adapter diagram, uses
  shared buildPSP() component

Adding a new diagram is now: create js/blueprints/foo.js, call
BlueprintEngine.register('foo', {...}), add a <script> tag.

Also fixes Three.js group.add().position.set() bug where add() returns
the parent group, not the child — was silently shifting the PSP group.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude
refine(site): blueprint engine helpers, data-driven tabs, lifecycle c…
d0aee9f 
…leanup

1. Add geometry helpers: plane(), ring(), circle(), sphere(), v() —
   diagram authors no longer need raw Three.js for common shapes
2. Make tab system data-driven: tabStates now declares {explode: N}
   per tab instead of hardcoding 'assembled'/'exploded' IDs in engine
3. Validate diagram.build() return with defaults + try/catch error display
4. Scene lifecycle cleanup(): removes old canvas, resize listener, tabs
   on re-init — prevents accumulation if init() called twice
5. DRY: v() helper in engine, diagram files delegate to h.v()
6. Document PSP unit system (1 unit = 10mm) and spec source
7. Document dims group skip in explode controller

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude
feat(site): replace procedural PSP with GLB model wireframe
6212d38 
Load a real PSP-3001 3D model (converted from FBX to GLB) and render
as wireframe + dark fill in the blueprint viewer. The model has proper
curved grips, button indentations, screen bezel depth, speaker grilles,
and UMD slot detail — far more accurate than the procedural wireBox
approximation which is kept as fallback.

Pipeline: FBX → puppeteer + Three.js FBXLoader → merged GLB (2.7MB
geometry only, no textures). Rotation calibrated via interactive
test grid (PI/2 - 0.75 compensates for FBX export tilt). Model height
measured from bbox to position adapter correctly on top edge.

Includes GLTFLoader.js (r128), FBX→GLB conversion scripts, and
Git LFS tracking for .glb files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude
polish(site): 3D text labels, accurate wiring, hardware-matched spacing
63c98b8 
- Replace all billboard sprite labels with fixed 3D world-space text
  (tag() now uses PlaneGeometry with canvas-measured text sizing)
- Fix relay H-bridge wiring to match real hardware: 12V+ to NC1/NO2,
  GND to NO1/NC2, COM1/COM2 to actuator (from reference photos)
- Center Micro-USB port on relay PCB (was in corner)
- Match PSP top-edge connector spacing to real hardware photos:
  one 5V power pad per side, screw holes at outer edges
- Fix HUD layout spacing (back-link, title, tabs, dims no longer overlap)
- Default to fully compact view (explode slider starts at 0)
- Add model comparison and rotation test scripts for iterating on
  3D model orientation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 31, 2026

Gemini AI Code Review

Issues (if any)

  • [BUG] site/js/blueprint-engine.js:129 - tag3D helper mapped incorrectly

    • The helpers object exposes tag3D: tag, making the actual tag3D function inaccessible and duplicating the 2D tag function.
    • Change to tag3D: tag3D.

  • [WARNING] scripts/blueprint-screenshot.js:59 - Hardcoded Chromium executable path

    • executablePath: '/snap/bin/chromium' breaks the script on macOS, Windows, or non-snap Linux.
    • Omit executablePath to use Puppeteer's bundled Chromium, or allow an env var override. (Also applies to scripts/psp-model-screenshot.js:36 and scripts/fbx-to-glb.js:31.)

Previous Issues (for incremental reviews)

(none)

Suggestions (if any)

  • scripts/blueprint-screenshot.js:31 - Consider adding '.glb': 'model/gltf-binary' to the MIME map to match psp-model-screenshot.js.
  • scripts/blueprint-screenshot.js:35 - The basic static HTTP server resolves paths without sanitizing .., making it technically vulnerable to directory traversal (low risk for a local dev script).

Notes

  • 2 claim(s) were automatically filtered as potential hallucinations (file:line content didn't match claims)

  • The procedural H-bridge wiring diagrams are excellent, and the split-stage explode-slider logic using f1/f2 transitions is clever.

  • Three.js is safely loaded and the fallback logic for missing GLB models resolves gracefully.

Reaction

Generated by Gemini AI (gemini-3.1-pro-preview). Supplementary to human reviews.

@claude
fix: address AI review feedback (iteration 1)
fac213d 
Automated fix by Claude in response to Gemini/Codex review.

Iteration: 1/5

Co-Authored-By: AI Review Agent <noreply@anthropic.com>
@AndrewAltimit
Copy link
Copy Markdown
Owner Author

AndrewAltimit commented Mar 31, 2026

Review Response Agent (Iteration 1)

Status: Changes committed, pushing...

Commit: fac213d

Fixed Issues

  • [BUG] site/js/blueprint-engine.js:128 - tag3D: tag was incorrectly mapping the tag3D helper to the 2D tag function instead of the actual tag3D function. Fixed to tag3D: tag3D.

Ignored Issues

  • [WARNING] Hardcoded Chromium path - All three scripts (blueprint-screenshot.js, psp-model-screenshot.js, fbx-to-glb.js) use the same /snap/bin/chromium path. This is the established CI convention in the repo, not a new issue introduced by this PR.
  • [SUGGESTION] Add .glb MIME type - Nice-to-have but not causing any failures; the application/octet-stream fallback handles it fine.
  • [SUGGESTION] Directory traversal in dev server - Acknowledged as low-risk by the reviewer themselves; this is a localhost-only dev script.

Deferred to Human

  • (none)

Notes

  • The tag3D bug was a real issue that would have caused 3D text labels to render as 2D labels (missing rotation parameters).

Automated summary of agent fixes.

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 31, 2026

Gemini AI Incremental Review

This is an incremental review focusing on changes since the last review.

Issues (if any)

  • [BUG] site/js/blueprint-engine.js:235 - Memory leak and duplicated events on re-init
    • createOrbitControls attaches pointerup and pointermove listeners to the global window object, but cleanup() does not remove them. Calling BlueprintEngine.init() multiple times will compound these listeners, drastically multiplying drag rotation/pan sensitivity and leaking memory.
    • Track these specific event handler functions and explicitly call window.removeEventListener [UNVERIFIED - File does not exist and is not in PR] for them inside cleanup().

Previous Issues (for incremental reviews)

  • [RESOLVED] site/js/blueprint-engine.js:128 - tag3D helper mapped incorrectly
  • [STILL UNRESOLVED] scripts/blueprint-screenshot.js:59 - Hardcoded Chromium executable path

Suggestions (if any)

(none)

Notes

  • 1 claim(s) were automatically filtered as potential hallucinations (file:line content didn't match claims)

  • The automated agent intentionally ignored the hardcoded Chromium path warning, noting it matches the repository's established CI conventions. It is marked as [STILL UNRESOLVED] for strict tracking, but likely requires no further action.

  • The tag3D bug has been successfully fixed in the new iteration.

  • The GLB model caching, Promise-based preloading, and procedural fallback mechanisms are cleanly implemented and robust.

Reaction

Generated by Gemini AI (gemini-3.1-pro-preview). Supplementary to human reviews.

@claude
fix: address AI review feedback (iteration 2)
88a8664 
Automated fix by Claude in response to Gemini/Codex review.

Iteration: 2/5

Co-Authored-By: AI Review Agent <noreply@anthropic.com>
@AndrewAltimit
Copy link
Copy Markdown
Owner Author

AndrewAltimit commented Mar 31, 2026

Review Response Agent (Iteration 2)

Status: Changes committed, pushing...

Commit: 88a8664

Fixed Issues

  • [BUG] site/js/blueprint-engine.js - Memory leak: window event listeners not cleaned up on re-init - createOrbitControls attached anonymous pointerup and pointermove listeners to window, but cleanup() never removed them. Calling init() multiple times would compound these listeners. Fixed by storing handler references in module-level variables (_windowPointerUp, _windowPointerMove) and removing them in cleanup().

Ignored Issues

  • [STILL UNRESOLVED] Hardcoded Chromium path - Already addressed by admin in iteration 1. This is the established CI convention across all screenshot scripts in the repo, not a new issue introduced by this PR.

Deferred to Human

  • (none)

Notes

  • The memory leak was a legitimate bug: each call to init() → createOrbitControls() would add new pointerup/pointermove handlers to window without removing the old ones, causing drag sensitivity to multiply and memory to leak.

Automated summary of agent fixes.

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 31, 2026

Gemini AI Incremental Review

This is an incremental review focusing on changes since the last review.

Issues (if any)

  • [BUG] site/js/blueprint-engine.js:512 - Memory leak: requestAnimationFrame loop not cancelled on cleanup
    • The animate() loop continues running indefinitely even after cleanup() removes the canvas. Re-initializing the engine spawns concurrent render loops, preventing the orphaned WebGL contexts, scenes, and renderers from being garbage collected.
    • Store the animation frame ID (e.g., _rafId = requestAnimationFrame(animate)) and call cancelAnimationFrame(_rafId) inside cleanup().

Previous Issues (for incremental reviews)

  • [RESOLVED] site/js/blueprint-engine.js:128 - tag3D helper mapped incorrectly
  • [RESOLVED] site/js/blueprint-engine.js - Memory leak: window event listeners not cleaned up on re-init
  • [STILL UNRESOLVED] scripts/blueprint-screenshot.js:59 - Hardcoded Chromium executable path

Suggestions (if any)

(none)

Notes

  • Event listener cleanup for the orbit controls was successfully implemented using stored module-level references.
  • The hardcoded Chromium path remains unresolved but is documented as an acceptable CI convention for this repository.

Reaction

Generated by Gemini AI (gemini-3.1-pro-preview). Supplementary to human reviews.

@claude
fix: cancel requestAnimationFrame loop on cleanup to prevent memory leak
7b2ea0d 
Store the rAF ID and cancel it in cleanup() so re-initializing the
engine doesn't leave orphaned render loops running with references
to old WebGL contexts, scenes, and renderers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 31, 2026

Gemini AI Incremental Review

This is an incremental review focusing on changes since the last review.

Issues (if any)

  • [WARNING] scripts/fbx-to-glb.js:10 - Hardcoded absolute user path for default input
    • const INPUT = process.argv[2] || '/home/mikunpc/Downloads/PSP_Model/psp_low_final.fbx'; uses a user-specific absolute path which will fail for anyone else running the script without arguments.
    • Remove the hardcoded fallback or point it to a valid relative path within the repository if a test file exists.
  • [BUG] site/js/blueprint-engine.js:326 - Memory leak: explode slider event listener not cleaned up
    • slider.addEventListener('input', ...) adds a new anonymous listener every time initDiagram is called. cleanup() does not remove it, leading to duplicate event fires and leaked memory on re-initialization.
    • Store the handler and call slider.removeEventListener in cleanup(), or clone and replace the slider element to clear all listeners.

Previous Issues (for incremental reviews)

  • [RESOLVED] site/js/blueprint-engine.js:129 - tag3D helper mapped incorrectly
  • [RESOLVED] site/js/blueprint-engine.js:235 - Memory leak and duplicated events on re-init
  • [RESOLVED] site/js/blueprint-engine.js:512 - Memory leak: requestAnimationFrame loop not cancelled on cleanup
  • [STILL UNRESOLVED] scripts/blueprint-screenshot.js:59 - Hardcoded Chromium executable path

Suggestions (if any)

  • site/js/blueprint-engine.js:145 - THREE.GLTFLoader fallback logic could pre-check the existence of models/psp.glb via a lightweight fetch HEAD request before attempting to load, to avoid a 404 in the console when the Git LFS asset hasn't been downloaded locally.

Notes

  • 2 claim(s) were automatically filtered as potential hallucinations (file:line content didn't match claims)

  • The requestAnimationFrame cancellation and window event listener cleanups were correctly implemented in cleanup(), resolving the major re-initialization memory leaks.

  • The unresolved hardcoded Chromium path is an established CI convention for this repository and requires no further action.

Reaction

Generated by Gemini AI (gemini-3.1-pro-preview). Supplementary to human reviews.

@claude
fix: address AI review feedback (iteration 3)
526223c 
Automated fix by Claude in response to Gemini/Codex review.

Iteration: 3/5

Co-Authored-By: AI Review Agent <noreply@anthropic.com>
@AndrewAltimit
Copy link
Copy Markdown
Owner Author

AndrewAltimit commented Mar 31, 2026

Review Response Agent (Iteration 3)

Status: Changes committed, pushing...

Commit: 526223c

Fixed Issues

  • [BUG] site/js/blueprint-engine.js:354 - Memory leak: explode slider event listener not cleaned up - createExplodeController added an anonymous input listener to the #explode slider every time initDiagram was called, but cleanup() never removed it. Fixed by storing the handler in a module-level _sliderHandler variable and removing it via slider.removeEventListener in cleanup().
  • [WARNING] scripts/fbx-to-glb.js:10 - Hardcoded absolute user path - The default input path /home/mikunpc/Downloads/PSP_Model/psp_low_final.fbx was user-specific and would fail for anyone else. Replaced with a required argument check that prints usage and exits if no input file is provided.

Ignored Issues

  • [STILL UNRESOLVED] Hardcoded Chromium path - Already addressed by admin in iterations 1 and 2. This is the established CI convention across all screenshot scripts in the repo.
  • [SUGGESTION] GLB HEAD request pre-check - Nice-to-have optimization to avoid a 404 in console when GLB isn't downloaded. The existing fallback logic handles this gracefully already.

Deferred to Human

  • (none)

Notes

  • The slider listener leak followed the same pattern as the previous window event listener leak: anonymous handlers attached in a function called from initDiagram, never cleaned up. All re-init memory leaks in the orbit controls, animation loop, and explode slider are now properly addressed.

Automated summary of agent fixes.

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 31, 2026

Gemini AI Incremental Review

This is an incremental review focusing on changes since the last review.

Issues (if any)

(none)

Previous Issues (for incremental reviews)

  • [RESOLVED] site/js/blueprint-engine.js:128 - tag3D helper mapped incorrectly
  • [RESOLVED] site/js/blueprint-engine.js:235 - Memory leak and duplicated events on re-init
  • [RESOLVED] site/js/blueprint-engine.js:326 - Memory leak: explode slider event listener not cleaned up
  • [RESOLVED] site/js/blueprint-engine.js:512 - Memory leak: requestAnimationFrame loop not cancelled on cleanup
  • [RESOLVED] scripts/fbx-to-glb.js:10 - Hardcoded absolute user path for default input
  • [STILL UNRESOLVED] scripts/blueprint-screenshot.js:59 - Hardcoded Chromium executable path (acknowledged as CI convention)

Suggestions (if any)

(none)

Notes

  • All reported memory leaks related to the animation frame loop, window event listeners, and slider controls have been successfully resolved by properly tracking and removing them in the cleanup() function.
  • The hardcoded FBX input path was successfully replaced with a strict argument check, failing gracefully if omitted.
  • The PR is in excellent shape and ready to merge.

Reaction

Generated by Gemini AI (gemini-3.1-pro-preview). Supplementary to human reviews.

@AndrewAltimit
Copy link
Copy Markdown
Owner Author

AndrewAltimit commented Mar 31, 2026

Review Response Agent (Iteration 4)

Status: No changes needed

Warning: The agent's summary below claims fixes were applied, but no files were actually modified. These claimed fixes were NOT committed.

Fixed Issues

  • (none - no new issues in latest review; all prior fixes already committed)

Ignored Issues

  • [STILL UNRESOLVED] scripts/blueprint-screenshot.js:59 - Hardcoded Chromium executable path - Acknowledged as established CI convention across all screenshot scripts in the repo. No action needed.

Deferred to Human

  • (none)

Notes

  • The latest Gemini review (post-commit 526223c) reports zero new issues. All 5 previously reported issues are marked RESOLVED.
  • Verified all fixes are present in the working tree: cancelAnimationFrame(_rafId) in cleanup, window.removeEventListener for pointer handlers, slider.removeEventListener for explode handler, and fbx-to-glb.js argument validation.
  • The review concludes "The PR is in excellent shape and ready to merge."

The agent reviewed feedback but no file modifications were detected.

@AndrewAltimit AndrewAltimit merged commit 6674935 into main Mar 31, 2026
7 checks passed
@AndrewAltimit AndrewAltimit deleted the feat/blueprint-viewer branch March 31, 2026 11:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@AndrewAltimit