[Feature] Supporto esercizi di spinta orizzontale: asse corretto e semantica automatica delle fasi + semantic biomechanical layer Personal Annotator

[andreazedda]

Origine feedback

• Data: 2026-03-06 16:14
• Utente: mattia.rivieccio
• Tipo: Desiderio / Nuova funzione
• Urgenza: Media
• Pagina: /datasets/upload/

Sintesi utente

Per gli esercizi di spinta orizzontale:

1. va visualizzato ANG2 come asse corretto;
2. la fase di riposo si trova nella DST e non nella UST;
3. di conseguenza il pannello interpreta al contrario fase eccentrica e concentrica;
4. il sistema dovrebbe attribuire automaticamente valori e colori corretti una volta selezionata la categoria esercizio corretta.

Estensione Personal Annotator

Devo modificare la piattaforma Personal Annotator / Gym Annotator for PT introducendo un layer di interpretazione biomeccanica sopra le annotazioni del segnale, senza alterare la logica base di annotazione già esistente.

Architettura corretta

• Signal annotation layer: invariato. (picchi, valli, up_stable_time, down_stable_time). Non va ridefinito.
• Biomechanical interpretation layer: Nuovo layer separato, mappa gli output analitici (ascending, descending, stable_up, stable_down) verso etichette biomeccaniche configurabili come (concentrica, eccentrica, riposo, lockout, reset, preparazione, release, etc).

Vincolo

Il sistema deve mantenere distinta la natura tecnica del segnale da quella biomeccanica/umana. Nessuna modifica alla base annotativa.

Obiettivo concreto

Il trainer deve poter configurare la semantica:

• ascending_meaning = concentric
• descending_meaning = eccentric
• stable_up_meaning = rest_top
• stable_down_meaning = preparation_bottom
  oppure altre combinazioni per esercizi diversi.

Default richiesto

Se nulla viene configurato, restano i mapping storici dello squat, senza regressione.

Acceptance criteria

• Le annotazioni tecniche restano invariate.
• Il sistema introduce un layer separato di interpretazione biomeccanica.
• ascending e descending possono essere etichettati biomeccanicamente in modo configurabile.
• stable_up e stable_down possono essere etichettati biomeccanicamente in modo configurabile.
• In assenza di configurazione, resta il comportamento storico.
• UI e analisi leggono la stessa configurazione.
• Nessuna regressione sulla pipeline attuale.

Implementazione suggerita

• Minimo impatto: estendere modello dati con campi opzionali:
  • ascending_meaning
  • descending_meaning
  • stable_up_meaning
  • stable_down_meaning
• File chiave:
  • backend: aggiungi i nuovi metadati nell'entità di annotazione/sessione
  • frontend: aggiorna la logica di mapping label/colore/legend/help per usare la nuova configurazione
• Struttura dati proposta:

# Nuova struttura
class BiomechanicalSemantic:
    ascending_meaning: str
    descending_meaning: str
    stable_up_meaning: str
    stable_down_meaning: str

• Aggancio: Carica i metadati se presenti, altrimenti applica il mapping storico.

Punti di confusione attuali

• La UI a volte mostra label biomeccanica hardcoded per dynamica del segnale, confondendo "up_stable_time" con "rest" o "lockout" senza separazione.

NO refactor algoritmi base, NO tassonomie, NO hardcode per una categoria sola.

Estensione futura

• Possibile preset da exercise_type, ma solo come suggerimento non come default.

---

Evidenze nel codice originale (personalpageAZ)

• L'utente può già classificare l'esercizio e salvare un asse di riferimento.
• Categoria e metadato reference_axis sono usati in sessione.
• In annotazione il reference_axis viene riletto e applicato al grafico.
• In analisi, l'asse iniziale parte da querystring e defaulta a ANG1 senza usare reference_axis.
• La semantica di STABLE_UP viene interpretata come standing/top, con variante API su bottom, non derivata dalla categoria.
• La pipeline preset distingue squat vs balanced, non spinta orizzontale.

Root cause

• Il dominio biomeccanico è stato modellato solo parzialmente.

Soluzione preferita

Introdurre un layer di semantic interpretation, separato e configurabile.

Alternative considerate

A. Forzare asse ANG2.
B. Toggle inverti fasi manuale.
C. Implementazione semantic layer separato.

Decisione consigliata

Adottare la soluzione C per robustezza e estendibilità.

Acceptance criteria (personalpageAZ + personal_annotator)

1. Se l'esercizio appartiene a spinta orizzontale, la pagina analisi apre su ANG2.
2. Label e colori sono coerenti biomecanicamente, con configurazione separata.
3. Significato pause/top/bottom derivato da semantica esplicita.
4. La logica è applicata in annotazione, analisi e decision support.
5. Il nuovo semantic layer estende la annotazione tecnica senza modificarla.
6. Nessuna regressione: se la semantica manca, resta il vecchio mapping.

Piano tecnico

1. Introdurre tabella/mappa exercise_type -> semantics (futura). Ora solo struttura dati separata.
2. Usare reference_axis/default_axis come fallback.
3. Separare in UI "phase_1_s/phase_2_s" dalla etichetta umana.
4. Propagare semantica a help, chart, legend, badge.
5. Test per spinta orizzontale e squat controllato.

Rischi

• Confusione tra segnale e biomeccanica.
• Regole non chiare, mapping hardcoded.
• Regressione sul caso squat.

Domande aperte

1. Override manuale di asse/semantica per esperti.
2. Nuova categoria per spinta orizzontale o derivazione.
3. Applicare logica anche a tirata orizzontale?
4. Copertura anche annotazione/decision support?

Output richiesto

• Indica punto minimo di estensione codice.
• Suggerisci quali file toccare con impatto minimo.
• Proponi struttura dati semplice per semantic layer.
• Mostra come agganciarlo senza rompere caso squat.
• Evidenzia possibili punti dove oggi c’è confusione tra segnale e biomeccanica.
• Evita refactor non necessari.