Ergo-Mediapipe-XSens

Guida per installare l’ambiente e usare gli script principali: protocollo-analisi.py, RULACalculator_XSens.py e RULACalculator_Mediapipe.py. Tutto il codice è Python puro, senza CLI avanzate: i parametri si settano in testa ai file.

Prerequisiti e installazione

• Python 3.10 o 3.11 a 64 bit (consigliato 3.10 per Mediapipe). Su Windows usa py -3.10 -m venv ergo-env e attiva l’ambiente (ergo-env\Scripts\activate).
• Dipendenze comuni: pip install -U pip wheel e poi pip install numpy opencv-python mediapipe matplotlib openpyxl.
• XSens: installa anche i requisiti della cartella XSens_Code (solo matplotlib): pip install -r XSens_Code/requirements.txt.
• Per usare SolvePnP con camera reale, genera camera_params.npz con CodiceMediapipe_3D/calib_chessboard_from_video.py (serve un video con scacchiera) e aggiorna il path in CodiceMediapipe_3D/process_video_plot.py.
• Se preferisci il modello Pose offline .task, mettilo in pose_landmarker_models/ (es. pose_landmarker_heavy.task) e adatta process_video_plot.py di conseguenza; di default usa il modello integrato Mediapipe Pose.

Struttura cartelle consigliata

Dati/
  SoggettoXX/TaskY/RipetizioneZ/           # video e (opzionale) mvnx
CodiceMediapipe_3D/                        # process_video_plot.py e calibrazione
pose_landmarker_models/pose_landmarker_heavy.task (opzionale)
XSens_Code/                                # loader XSens
protocollo-analisi.py
RULACalculator_Mediapipe.py
RULACalculator_XSens.py
camera_params.npz (opzionale, se usi SolvePnP)

Uso rapido (pipeline completa)

1. Imposta ROOT_FOLDER in protocollo-analisi.py sulla ripetizione da analizzare, regola MAX_FRAMES, FPS_CAP e VISUALIZE.
2. Esegui python protocollo-analisi.py. Per ogni video:
   • Se esiste già un file _cut (o _cut_60fps ecc.) lo riusa, altrimenti compare la UI per selezionare start (s) ed end (e) e salva <nome>_cut.ext accanto al video.
   • Se gli FPS superano FPS_CAP, ricampiona a <nome>_cut_<FPS_CAP>fps.ext.
   • Calcola RULA con Mediapipe; se nella cartella ci sono .mvnx, calcola anche RULA XSens.
3. Output: log a console e rula_output.xlsx dentro ROOT_FOLDER (uno sheet per file).

protocollo-analisi.py (cosa toccare)

• ROOT_FOLDER: cartella della ripetizione (Dati/Soggetto01/Task1/Ripetizione01/...). Il codice scandisce ricorsivamente video (.mp4/.mov/.avi/.mkv) e .mvnx.
• MAX_FRAMES: limite globale per video e MVNX (None o intero).
• FPS_CAP: ricampiona se il video ha fps maggiori.
• VISUALIZE: apre l’animazione 3D (Mediapipe e XSens); chiudi la finestra per proseguire.
• La funzione select_frame_range mostra i comandi nella UI (play/pause, s/e, frecce, invio per confermare).

RULACalculator_Mediapipe.py

• Parametri principali in testa: CODE_DIR (cartella con process_video_plot.py), VIDEO_PATH, FRAMES, STEP, MODEL_COMPLEXITY (0/1/2), USE_PNP (SolvePnP), VISUALIZE.
• Vettori nel plot: attiva/disattiva i flag SHOW_* e, se vuoi, modifica i colori in VECTOR_COLORS.
• Keypoint e vettori:
  • Mapping Mediapipe → joint ergonomici in MP_IDX e funzione joints_from_points (qui puoi cambiare i landmark usati per spalla/gomito/polso/anche/ginocchia/caviglie).
  • Vettori e assi corporei in _body_axes_vectors; i vettori mostrati nel plot sono scelti in _vector_map_for_plot.
  • Il calcolo degli angoli RULA è in compute_ergo_mediapipe; se cambi i vettori modifica qui le proiezioni.
• Modello Mediapipe: cambia MODEL_COMPLEXITY oppure personalizza la Pose in CodiceMediapipe_3D/process_video_plot.py (confidenze, enable_segmentation, ecc.).
• Esecuzione singola: python RULACalculator_Mediapipe.py (usa i parametri di default o passa override a run_mediapipe da altri script).

RULACalculator_XSens.py

• Parametri: XSENS_CODE_DIR, MVNX_PATH, FRAMES, VISUALIZE, NECK_DEBUG_FRAMES (stampa metriche collo sui primi N frame).
• Vettori nel plot: flag SHOW_* (assi sagittale/trasverso/frontale, segmenti collo-braccia-gambe).
• Mapping XSens: dizionario XSENS_JOINT_SEG (segmento XSens → joint ergonomico) usa gli ID definiti in XSens_Code/mvn.py (SEGMENT_PELVIS, SEGMENT_RIGHT_FOREARM, ecc.). Cambia qui per usare segmenti diversi (es. usare SEGMENT_RIGHT_HAND come polso).
• Vettori e assi per il calcolo: _body_axes_vectors e compute_ergo_xsens; i dati per la visualizzazione sono costruiti in compute_ergo_xsens e raccolti in axes_series.
• Esecuzione singola: python RULACalculator_XSens.py (calcola RULA e, se VISUALIZE=True, mostra lo scheletro XSens con vettori scelti).

Keypoint Mediapipe (33 landmark, ordine ufficiale)

0 nose; 1 left eye (inner); 2 left eye; 3 left eye (outer); 4 right eye (inner); 5 right eye; 6 right eye (outer); 7 left ear; 8 right ear; 9 mouth (left); 10 mouth (right); 11 left shoulder; 12 right shoulder; 13 left elbow; 14 right elbow; 15 left wrist; 16 right wrist; 17 left pinky; 18 right pinky; 19 left index; 20 right index; 21 left thumb; 22 right thumb; 23 left hip; 24 right hip; 25 left knee; 26 right knee; 27 left ankle; 28 right ankle; 29 left heel; 30 right heel; 31 left foot index; 32 right foot index.

Dove cambiare keypoint e vettori

• Mediapipe: RULACalculator_Mediapipe.py → MP_IDX (scelta landmark), joints_from_points (costruzione del dizionario), _body_axes_vectors e compute_ergo_mediapipe (definizione e uso dei vettori), _vector_map_for_plot (quali vettori disegnare).
• XSens: RULACalculator_XSens.py → XSENS_JOINT_SEG (segmenti usati), joints_from_xsens (come derivare mano da polso), _body_axes_vectors e compute_ergo_xsens (vettori/angoli). Gli ID segmento/giunto di riferimento sono in XSens_Code/mvn.py.

Note utili

• VISUALIZE=True blocca l’esecuzione finché non chiudi la finestra Matplotlib.
• Se Mediapipe perde i keypoint, prova a ridurre MODEL_COMPLEXITY o aumentare la qualità del video; per debug rapido puoi stampare i frame mancanti in process_video_plot.extract_landmarks.
• Per evitare errori Qt di Matplotlib senza icone, entrambe le versioni del calcolatore creano icone minime con _ensure_mpl_icons().