JST Connector Studio: manufacturer 3D mate editor

@@ -0,0 +1,153 @@+# JST Connector Studio (Adom app)++An interactive **Babylon 9.5** studio for JST wire-to-board connectors. Load a system and see the+**JST manufacturer housing + wire + ds2sf footprint** mate in a looping animation, beside the+**KiCad housing + footprint + silkscreen**. Rotate every part with **90-degree-snap gizmos**, set+mate axis / insertion / SMD-vs-THT / front-marker, toggle debug bounding boxes, and **export a+config that drives the wiki component-page GLB build**. AI-controllable (`window.JSTStudio` + `/api`).++![JST Connector Studio - Babylon 9.5 mate editor](docs/app-ui.png)++## Run it+```+adompkg install adom/jst-connector-cad   # installs the `jst-studio` command+jst-studio serve                         # http://localhost:8791+```+Open that URL in a Hydrogen webview panel. Built on **adom-3d-viewer-babylon9** (Babylon 9.5 + Inspector).++---++# JST connector CAD++Source JST connector CAD the **manufacturer-first** way and turn it into an **interactive,+animated, footprint-accurate** wiki component page. The 3D model is JST's own STEP. KiCad is+used only for the redistributable symbol and footprint, and as a side-by-side comparison foil.+Built and verified end-to-end on five 2-circuit systems (PH, XH, SH, GH, ZH).++This README is the full illustrated walkthrough: what the pipeline does, how each decision was+made, what gets published, how chip-fetcher and the KiCad references are used, and the viewer+gotchas that cost real time. The installable recipe is in [SKILL.md](SKILL.md).++> **Why manufacturer-first:** an engineer placing a JST part wants the *real* part. KiCad's+> generic 3D is fine for clearance, but the manufacturer STEP is the truth. So chip-fetcher+> always treats JST's STEP as the deliverable and KiCad as the comparison, never the reverse.++## The pipeline at a glance++```+JST email-gated STEP ─┐+KiCad sym + fp + 3D ──┤→ STEP→GLB (decompress) → orient → compose scene → animate → publish+                      │     (step2glb)            (per part)   (trimesh)   (gltf-transform)  (adompkg)+service-kicad ────────┘+```++Every stage is numerically self-checked (bbox asserts) and visually verified by screenshotting+the **live Babylon viewer** and reading it. matplotlib renders geometry but not textures or+text, so it cannot be trusted for labels, footprints, or orientation.++## 1. Get the manufacturer CAD (email-gated)++JST gates STEP downloads behind a License Agreement email form on `jst-mfg.com`, and the USA+`jst.com` Cloudflare-walls headless browsers. So chip-fetcher drives the user's **real** browser+(native-browser bridge), fills the form, and retrieves the emailed STEP through the Gmail API+(`adom-google`). Rules learned the hard way: one submit per file, dedupe before sending, route to+a filtered alias, and trash demo emails afterward. The full flow lives in chip-fetcher playbooks+`jst.md` and `jst-email-retrieval.md`.++For each 2-circuit system you fetch three real parts: the **board header**, the **wire housing**,+and the **crimp contacts**.++## 2. Look up the KiCad reference (symbol + footprint, and 3D if it exists)++`service-kicad` resolves the KiCad library footprint and symbol. The footprint is what makes the+3D scene honest: its pad coordinates are real millimetres.++![KiCad footprint reference for the PH header](docs/process-kicad-fp.png)++Not every JST part has a KiCad 3D model. ZH `B2B-ZR` returns 404 from `kicad-packages3d`, so its+page is single-column and says so (see the placard in section 7). KiCad still provides its+footprint and symbol, so the comparison is not lost.++## 3. STEP to GLB, and getting orientation right++`step2glb convert` turns each STEP into GLB. It emits **Draco-compressed** GLB that trimesh+cannot read, so it is decompressed first with `@gltf-transform`. Each model sits in its own+native frame, so orientation is read directly with `step2glb thumbnail --pose front|top|side`+(and `features`) rather than guessed from the bounding box (connectors are nearly cubic and fool+bbox heuristics). KiCad models are reliably Z-up with pins down; the JST THT boards here needed a+90 degree rotation about X.++![Reading the pin axis from ortho thumbnails](docs/process-orientation.png)++The part number encodes the mating axis: a `B` prefix (B2B, BM) is top entry (wire mates straight+down), an `S` prefix (SM, S2B) is side entry (wire mates horizontally).++## 4. Compose the scene (this is the part that matters)++Two columns: KiCad foil on the left (tan), JST manufacturer on the right (blue). Then four things+have to be exactly right, and each one was wrong at least once before it was right.++**Seat the body, not the bounding box.** The connector body bottom (where the cross-section+widens above the thin pins) sits on the PCB top. Seating by `bbox.min` sinks the housing into the+board. The body bottom is found by walking z-slices for the first wide slice.++**True-scale footprint pads, registered to the real pins.** The footprint is not a pasted image.+The `.kicad_mod` is parsed and copper pads are drawn at real millimetre coordinates, then+registered onto the connector's actual pin positions detected from the mesh. The build prints a+numeric check so a human can confirm alignment:++```+CHK board0 pins_through=True pin1=[1.95,-0.60] pin2=[3.95,-0.60] pad_pitch=2.0 pin_pitch=2.0+```++**Silkscreen and courtyard.** The silk outline (housing size) and courtyard (keep-out) are parsed+from the same `.kicad_mod` and drawn on the PCB with the same registration, so they sit correctly+around the part:++![Footprint pads + silkscreen + courtyard, board lifted](docs/result-silk.png)++**Float the PCB and show pins through.** The PCB is a thin 1.6 mm slab floating about 8 mm up,+with no riser (a riser hides the underside). THT pins pass through the slab and protrude out the+bottom. A tiny invisible anchor at z=0 forces the viewer (which grounds to the lowest geometry) to+put the floor low, so the camera can look under the PCB:++![Pins pass through the PCB to the other side](docs/process-pins-through.png)++## 5. Animate the mate++The board and wire are given named nodes, baked at their **seated** pose (so a non-animating+viewer still looks right), then animated with `@gltf-transform` translation channels: the board+descends so the pins pass through, then the wire inserts about 80 percent into the board body so+the contact slots engage. Lifts are kept small and the loop dwells on the fully-mated state, which+is the shot that matters. The Babylon viewer autoplays and loops embedded GLB animations.++![Final scene: correct labels, aligned pads, mated parts](docs/result-labels.png)++## 6. Viewer gotchas (verify, do not assume)++- **Screenshot your own 3D view in the live viewer and read it.** This is the single most+  important habit. matplotlib hides texture and text problems.+- **The viewer is an iframe** (`/viewer/3d/component/<slug>`). Reloading the parent page does not+  refresh the iframe's cached GLB. Bump the GLB filename and bust the iframe `src`.+- **Texture orientation:** the quad UV needs `[[0,1],[1,1],[1,0],[0,0]]` for upright, and Babylon+  flips U on the camera-facing face, so the image is pre-mirrored. Two-sided labels need separated+  single-winding quads backed opaque (coplanar faces z-fight, transparent PNGs bleed through).+- **KiCad models often sit 180 degrees about Z** versus the manufacturer part, so the KiCad board+  gets a 180 degree Z rotation to match.+- **Publish org-owned:** `adompkg publish --org adom`.++## 7. The five results++When KiCad has no 3D model, the column becomes a red placard so the absence is explained:++![ZH: KiCad-absent placard next to the JST mate](docs/result-zh.png)++Live, animated component pages built with this exact pipeline:++- [B2B-PH-K-S (PH 2.0 mm)](https://wiki.adom.inc/adom/b2b-ph-k-s)+- [B2B-XH-A (XH 2.5 mm)](https://wiki.adom.inc/adom/b2b-xh-a)+- [SM02B-SRSS-TB (SH 1.0 mm, side entry)](https://wiki.adom.inc/adom/sm02b-srss-tb)+- [BM02B-GHS-TBT (GH 1.25 mm SMT)](https://wiki.adom.inc/adom/bm02b-ghs-tbt)+- [B2B-ZR (ZH 1.5 mm, no KiCad 3D)](https://wiki.adom.inc/adom/b2b-zr)++See also: [chip-fetcher](https://wiki.adom.inc/adom/adom-chip-fetcher).