docs: findings dal viewer (rigid groups vuoti, motion link 14 joint1=null, parent/child Motore X invertito)

BRIDGE_NOTES.md

@@ -71,3 +71,75 @@ $names = @('Motore asse X','Motore asse Y','Asse Penna ','asse Z pneumatico M5?'
 foreach($n in $names){ $j.joints | Where-Object name -eq $n | Select-Object name,type,child,axis,@{n='limits';e={ if($_.slideLimits){'slide '+$_.slideLimits.minimumValue+'..'+$_.slideLimits.maximumValue}elseif($_.rotationLimits){'rot '+$_.rotationLimits.minimumValue+'..'+$_.rotationLimits.maximumValue} }} | Format-List }
 $j.asBuiltJoints | Where-Object name -eq 'Motore A' | Select-Object name,type,child,axis | Format-List
 ```
+
+---
+
+## Findings dal viewer (2026-06-09)
+
+Lato consumer (`automation_kriz`) ho aggiunto una pagina di ispezione live a `/lab/graph` che carica `hierarchy.json` + `joints.json` direttamente dal server e ne mostra: l'albero completo con conteggi joint/rigid per nodo, i 5 driver con stato OK/rotto, la lista di tutti i 329 joint + 28 asBuilt con filtro per tipo, i 9 motion link (validi vs rotti) e i 20 rigid group. Serve per fare debug del JSON senza dover aprire Fusion. Dato che è una pagina autenticata e legge `/api/fusion/{joints,hierarchy}/` lato Django, basta sostituire i file in `/home/marco/automation_kriz/joints.json` + `hierarchy.json` e ricaricare.
+
+Ispezionando l'export attuale (`329 joints, 28 asBuiltJoints, 9 motionLinks, 20 rigidGroups`) ho trovato tre problemi che impediscono al viewer di propagare il movimento sull'asse X (e probabilmente anche Y e PEN dipendono dagli stessi pattern). Servono fix lato `ExportKinematicGraph.py`.
+
+### BUG 1 — `rigidGroups[].occurrences` è SEMPRE vuoto
+
+Tutti i 20 gruppi rigidi esportati hanno `occurrences: []`. Esempio dal file corrente:
+```json
+[
+  {"name": "Gruppo rigido 6", "occurrences": []},
+  {"name": "Gruppo rigido 17", "occurrences": []},
+  ...
+]
+```
+
+Nel `BRIDGE_NOTES` precedente è scritto che `Gruppo rigido 6` doveva contenere `end stop X PIastrina:1 | binario SX:1 | Cinghia T5:1`. Nell'export reale quelle occorrenze NON ci sono. Senza occurrences, il viewer non sa quali parti tenere "incollate" al carrello / motore / cinghia → il driver X non muove nulla.
+
+Possibili cause da verificare nell'add-in:
+- Si itera `rigidGroup.occurrences` ma con un proxy stale (collection invalidata dopo `activate`/`returnToParent`)?
+- Si guarda `nativeObject.occurrences` invece di farla risolvere via `assemblyContext`?
+- Si filtra accidentalmente per `occ.isLightBulbOn` o `isSuppressed`?
+
+Verifica veloce: in console Fusion durante export stampare `len(list(rg.occurrences))` per ogni `rg` in `rootComp.allRigidGroups` e confrontare con quello che finisce nel JSON.
+
+### BUG 2 — `Collegamento movimento 14` (driver X) ha `joint1: null`
+
+```json
+{"name": "Collegamento movimento 14", "joint1": null, "joint2": "Motore asse X", "ratio": null}
+```
+
+`Motore asse X` è un giunto `revolute` (il motore stepper gira), `joint2 = Motore asse X` significa "questo è il driver". Senza `joint1` (lo slider del carrello che dovrebbe seguire) il viewer non può propagare la rotazione del motore in traslazione del carrello.
+
+Stessa cosa per `Collegamento movimento 38` (`joint2 = "Asse Penna "`) e `Collegamento movimento 28` (`joint2 = "Rivoluzione 26"`).
+
+Nel BRIDGE_NOTES precedente è scritto "ignorabili, propagazione passa dai rigid groups" → ma siccome i rigid groups sono vuoti (BUG 1), questi motion link diventano cruciali. Bisogna almeno provare a recuperare `joint1` quando è `None`: il pattern API è `motionLink.entityOne` (proxy) vs `motionLink.entityOneNative` o usare `motionLink.bRepEdge.assemblyContext`. Se proprio l'API ritorna `None`, scrivere nel JSON il `componentToken` o l'`entityToken` come stringa hex così almeno il consumer può fare matching manuale.
+
+### BUG 3 — `Motore asse X` ha parent/child invertiti (convenzione)
+
+```json
+{
+  "name": "Motore asse X",
+  "type": "revolute",
+  "parent": "Puleggia_HTD5M_z15:1",
+  "child": "6627T281_Stepper Motor:1",
+  "axis": [-1, 0, 0]
+}
+```
+
+Fisicamente è il motore stepper che è fissato al telaio e fa girare la puleggia. Nel JSON è il contrario. Il viewer applica sempre la rotazione al `child` mantenendo fermo il `parent`, quindi vede il motore ruotare nel vuoto e la puleggia (che dovrebbe seguire) sta ferma.
+
+Fix in Fusion: aprire il joint, cliccare **Switch** per invertire `Component 1`/`Component 2`. Sospetto valga anche per gli altri driver — andrebbero controllati tutti e cinque con questo criterio:
+- `parent` = pezzo che resta solidale al telaio (o al precedente livello cinematico)
+- `child` = pezzo che si muove rispetto al parent
+
+### Patch temporanea lato viewer (in valutazione, non ancora applicata)
+
+Se i fix 1-3 lato Fusion richiedono tempo, lato viewer posso aggiungere:
+- una mappa `viewerOverrides.json` con `{ jointName: { swapParentChild: true } }` per simulare il fix BUG 3 senza modificare l'export
+- una mappa `viewerRigidGroups.json` con i contenuti che `Gruppo rigido N` dovrebbe avere, in attesa del fix BUG 1
+- una mappa `viewerMotionLinks.json` per ricostruire i `joint1` mancanti del BUG 2
+
+Sono workaround sporchi: preferisco fixare l'export quando possibile e tenere il viewer privo di patch ad-hoc. Fammi sapere se preferisci che proceda comunque con gli override per sbloccare le demo nel frattempo.
+
+### Per gli altri driver
+
+Stessa analisi va fatta per `Motore asse Y`, `Asse Penna ` e `asse Z pneumatico M5?`. Possibili problemi simmetrici: rigid groups vuoti, motion link `joint1=null`, parent/child invertiti. Quando rilancerai un export pulito segnalalo qui e rifaccio il giro su `/lab/graph`.
+