# Blender → ECG Studio

Stan sprawdzony 17 października 2026, Blender 5.1.2. Dodatek jest w `blender/ecg_studio_io.py`. Nie jest automatycznie instalowany w preferencjach użytkownika.

## Instalacja i pierwszy eksport

1. W Blenderze otwórz **Edit → Preferences → Add-ons**. Z menu w prawym górnym rogu wybierz **Install from Disk…**, wskaż `ecg_studio_io.py` z folderu `blender` projektu i włącz **ECG Studio volume I/O**. W starszych wersjach przycisk może nazywać się **Install…**.
2. Otwórz jeden z plików startowych przez **File → Open**. Zacznij od `strip-starter.blend`, aby szybko sprawdzić cały przepływ.
3. Zaznacz siatkę tkanki, a dla serca wszystkie cztery siatki `ECG_LV`, `ECG_RV`, `ECG_LA`, `ECG_RA`. Punkty Empty zostaw w scenie.
4. Wybierz **File → Export → ECG Studio volume model (.json)**. Ustaw rozmiar komórki z tabeli poniżej i zapisz JSON.
5. Uruchom **Projekty → Medycyna i nauka → ECG Studio**. W aplikacji wybierz **Models & methods → Load model (.json)** i wskaż wyeksportowany plik. Import zastępuje bieżący model i zaczyna nową historię EKG.

| Plik startowy | Komórka eksportu | Sprawdzony wynik |
| --- | ---: | --- |
| `strip-starter.blend` | 2,5 mm | 1 536 węzłów, 24 ml tkanki |
| `sphere-starter.blend` | 5 mm | 3 448 węzłów, 380 ml tkanki |
| `atlas-starter.blend` | 2 mm | 38 826 węzłów, wszystkie aktywowane w silniku |

Serce ma 309 700 trójkątów i eksport około 35 MB. Jest dokładniejszą powierzchnią do edycji niż domyślny podgląd 48 000 trójkątów, więc wczytywanie i animacja mogą być wolniejsze. Sprawdzono też eksport przy 2,5 mm: 21 086 węzłów. Rozdzielczość zmienia graf przewodzenia; sam zgodny bilans objętości nie dowodzi zbieżności EKG.

## Co można zmieniać

Pracuj na kopii pliku. Przesuwaj wierzchołki w **Edit Mode**; nie zamykaj jamy krwi pełną bryłą. Siatka ma otaczać objętość mięśnia, razem z wewnętrzną powierzchnią ściany i brzegami otworów. Normalne zewnętrzne wskazują na zewnątrz, a wewnętrzne w stronę krwi.

Scena startowa używa milimetrów (`Unit Scale = 0.001`). Eksporter respektuje skalę sceny i transformacje obiektów. Aplikacja używa osi Y do góry, Blender osi Z; dodatek przelicza je automatycznie: Blender `(x,y,z)` → aplikacja `(x,z,-y)`. Nie obracaj modelu drugi raz „dla zgodności osi”.

Każdy obiekt mięśnia musi mieć właściwość **Custom Properties → ecg_region**: 1 LV, 2 RV, 3 LA, 4 RA. Pełne serce wymaga po jednym obiekcie każdego regionu. Pojedynczy obiekt jest traktowany jako tkanka dydaktyczna, bez fikcyjnych przedsionków, AV i pomiarów PR/QRS/QT.

Komory wymagają grup wierzchołków **ECG_ENDO** i **ECG_EPI** zawierających całe trójkąty powierzchni wewnętrznej i zewnętrznej. Serce wymaga też atrybutu **ecg_fiber** typu **Vector**, domena **Point**. Starter zawiera pole przeniesione z atlasu. Duże deformacje, remesh i zmiany topologii wymagają ponownej kontroli grup i kierunków włókien. Dodatek nie wyznacza automatycznie fizjologicznych włókien dla nowej anatomii.

Modyfikatory przed eksportem muszą być zastosowane na kopii. Samo zastosowanie nie gwarantuje zachowania grup i atrybutów. Nie scalaj stykających się wierzchołków startera serca: część kontaktów rozdzielono topologicznie, bez zmiany współrzędnych, aby zachować zamknięte powierzchnie.

## Punkty przewodzenia

Empty z właściwością `ecg_landmark` są mapowane na najbliższy węzeł odpowiedniej tkanki:

| Wartość | Region |
| --- | --- |
| `sa`, `av`, `bachmannRA` | RA |
| `bachmannLA` | LA |
| `leftBundle` | LV |
| `rightBundle` | RV |

Dla sfery/paska wystarczy `sa`. W scenie może być tylko jeden punkt o każdej wymaganej nazwie właściwości. Przesuwaj punkty razem z edytowaną anatomią; punkt dalej niż `max(10 mm, 3 × rozmiar komórki)` od regionu zostanie odrzucony. Własny anatomiczny dobór punktów wymaga weryfikacji.

## Kontrole i ograniczenia eksportu

Eksporter sprawdza zamknięcie i orientację krawędzi, objętość, nakładanie regionów w punktach próbkowania, spójność grafu każdego regionu, landmarki, atrybuty, rozmiar pliku i limity węzłów. Osiem próbek na komórkę określa masę tkanki; trzy promienie rozstrzygają wnętrze przy wklęsłych powierzchniach. Środki krawędzi muszą leżeć w tkance. To przybliżenie: nie jest pełnym dowodem braku samoprzecięć ani zgodności całego przebiegu każdej krawędzi z cienką ścianą.

Przekroczenie 15% różnicy objętości jest błędem eksportu, a nie granicą klinicznej akceptacji. Nie usuwa się automatycznie odłączonych fragmentów. Komunikat o rozłącznej tkance wymaga naprawy siatki lub drobniejszego próbkowania. Limit to 150 000 trójkątów na obiekt, 100 000 węzłów eksportu, 500 000 komórek kandydujących na region i 40 MB JSON.

Nowy starter serca powstał z granic oryginalnych czworościanów Rodero. Nie wykorzystuje błędnej rekonstrukcji z wrześniowego przekazania ani naprawy Boolean. Różnice mas mięśnia po eksporcie 2 mm wyniosły: LV 0,110%, RV 0,034%, LA 0,166%, RA 0,193%. Żadnego regionu nie przeskalowano.

**Eksport nie zachowuje identycznego EKG.** Nowy graf, powierzchniowe przybliżenie włókien i współrzędnych warstw zmieniają aktywację. Dla startera 2 mm QRS wyznaczony z aktywacji wyniósł około 62 ms, wobec 104 ms w domyślnym atlasie. Jest to istotne ograniczenie fizjologiczne, nie pozytywna walidacja. Domyślny `public/heart.json` pozostaje bez zmian. Zobacz [audyt](AUDYT_PL.md).

## Zapis ustawień i powrót do Blendera

**Save model + setup** w ECG Studio zapisuje geometrię, jawne landmarki, przewodzenie, położenia elektrod i bodźca, maskę malowania oraz siłę skurczu. Ponowny import odtwarza te ustawienia, ale zaczyna nowy zapis EKG. Zapisane próbki eksportuj osobno przez **Export CSV**. Układ paneli i kamery są zapisywane w przeglądarce, nie w JSON.

**File → Import → ECG Studio model (.json)** importuje zgodny model do nowej kolekcji Blendera. Dodatek przenosi geometrię i mapowania, nie pełną sesję rejestratora. Domyślny zdecymowany atlas aplikacji może zawierać kontakty niemanifoldowe: do edycji serca używaj przygotowanego `atlas-starter.blend`. Stary format powłoki z poprzedniej aplikacji nie jest modelem objętościowym i nie zostanie automatycznie uznany za zgodny.

## Odtworzenie sprawdzenia

Z katalogu projektu, w środowisku z NumPy/SciPy/trimesh i Node:

```sh
python scripts/prepare_blender_atlas.py /path/to/average.vtk /path/to/atlas-input.json
/Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup \
  --python scripts/check_blender.py -- /path/to/check-output /path/to/atlas-input.json
node scripts/check_blender_exports.mjs /path/to/check-output
```

Ostatni argument pierwszego wywołania Blendera przebudowuje `blender/atlas-starter.blend`; zachowaj wcześniej własne zmiany w kopii. Pomiń go, aby tylko sprawdzić dostarczone pliki. Test nie instaluje dodatku ani nie zapisuje preferencji Blendera. Pełne wyniki są w `docs/audit/blender-checks.json` i `docs/audit/blender-engine-checks.json`.