slice_wrap_addon/README.fr.md

# Slice Wrap — add-on Blender (5.1 → 5.x)

*[English version](README.md)*

Transforme un maillage **troué, à doubles parois ou bruité** (scan, génération IA type Pixal3D / Trellis)
en une **surface propre, fermée et détaillée**, prête à sculpter. Aucune dépendance : numpy seulement
(fourni avec Blender).

Panneau : **Vue 3D > barre latérale (N) > onglet « Slice Wrap »**.

## Pourquoi pas le Voxel Remesh de Blender ?
Le Voxel Remesh (et *Mesh to Volume* en Geometry Nodes) reconstruit un volume… mais **fuit** dès que la
coque a un trou : l'intérieur n'est pas rempli et on obtient une double peau, du moiré, des ratés.
Slice Wrap remplit le volume **tranche par tranche selon X, Y et Z** : un trou ne fait fuir que les quelques
tranches qu'il traverse, les autres directions le compensent.

## Utilisation
Tout s'applique à **l'objet sélectionné** (actif) : il n'y a pas de cible à choisir. La projection se fait toujours
sur la source de l'enveloppe. Sans maillage sélectionné, les boutons sont grisés.

1. Sélectionnez le maillage source (troué) en mode Objet.
2. Réglez au besoin la section **Envelope** et **Wrap**, puis cliquez **Slice Wrap** (un clic) :
   Envelope → Wrap Setup → Freeze, et **Despike** en plus si **Despike After** est coché.
3. Le résultat `<source><suffixe>` (par défaut `<source>_slicewrapped`) est prêt à sculpter (base légère + niveaux
   Multires). La source est cachée.

### Calculs longs : confirmation, progression, annulation
Slice Wrap, Envelope, Regenerate et Despike affichent d'abord un message : le calcul peut être long, Blender
ignorera les clics pendant ce temps (il n'est pas planté), Échap annule. Case « Show this message next time »
(aussi dans *Preferences > Add-ons > Slice Wrap > Confirm Long Operations*).
Pendant le calcul (ainsi que Freeze et Analyze) : **barre de progression** avec l'étape en cours et le temps écoulé,
dans la barre d'état en bas de la fenêtre et en haut du panneau. **Échap** annule : rien n'est créé ni modifié.
Limite : quelques opérations internes de Blender (subdivision Multires, Multires Reshape, Voxel Remesh) sont d'un
seul tenant. Sur un maillage lourd, l'affichage reste figé quelques secondes sur cette étape, puis la progression
reprend.

### Nom et rangement du résultat
- **Suffix** (défaut `_slicewrapped`) : nom du maillage créé = nom de la source + suffixe.
- **Numérotation automatique** : si le nom existe déjà, `.001`, `.002`… comme Blender — **aucun objet existant
  n'est jamais écrasé** (même avec un suffixe vide, la source reste intacte).
- **Collection** (case + nom, défaut `SliceWrapCollection`) : le résultat y est rangé ; si la collection existe,
  elle est simplement réutilisée (son contenu n'est pas touché), sinon elle est créée et liée à la scène.
  Case décochée : le résultat va dans les collections de la source.
- **Regenerate** est le seul bouton qui recalcule un objet existant : l'enveloppe active, sur place.

### Sous-panneau « Steps » (replié) — chaque étape séparément
| # | Bouton | Ce qu'il fait |
|---|--------|---------------|
| 1 | **Envelope** | Sur l'objet actif (la source, jamais modifiée) : voxels → fermeture des trous → remplissage par tranches → surface fermée (Voxel Remesh sur volume déjà plein, sans fuite) → plus grande pièce → lissage de Taubin. Crée `<source><suffixe>` (numéroté si le nom existe). |
|   | ↻ **Regenerate** | Recalcule l'enveloppe active depuis sa source avec les réglages actuels (pseudo-modificateur). Refusé si l'enveloppe est déjà wrappée. |
| 2 | **Wrap Setup** | Gonfle l'enveloppe le long des normales (pour qu'elle soit entièrement *au-dessus* de la peau), ajoute **Multires** (N niveaux) puis **Shrinkwrap** : *Project*, le long des normales, **vers l'intérieur seulement**, avec une distance limite. |
| 3 | **Freeze** | Fige la projection **dans les niveaux du Multires** (Multires Reshape) et retire le Shrinkwrap. Avec **Repair Missed Rays**, les sommets dont la projection a raté — rien touché (aiguilles) ou trop loin (creux sur une paroi interne) — sont détectés exactement (comparaison avant / après) et reconstruits depuis leurs voisins. |

Astuce : pour couper le socle / les épaules avant la projection, faites **Envelope**, coupez (Bisect), puis
**Wrap Setup** et **Freeze**.

### Sous-panneau « Despike » — outil manuel
Filtre anti-pointes résiduel : un sommet n'est corrigé que s'il est **isolé**, nettement plus loin de la moyenne
de ses voisins que ceux-ci ne le sont des leurs ; le relief normal (oreilles, paupières) n'est pas lissé.
- **Distance** : écart minimal pour être une pointe (0 = automatique : longueur moyenne d'arête).
- **Strength** (0–1) : part du chemin vers la moyenne des voisins.
- **Iterations** : nombre de passes. **Isolation** : la pointe doit dévier N fois plus que ses voisins.
- **Vertex Group Filters** : liste (+ / − / vider) des groupes de sommets à traiter. Le **poids** du groupe module
  la force (fondu possible en bordure). **Liste vide = toute la surface.** Si la liste contient des groupes
  dont aucun n'existe, le Despike refuse de s'exécuter (pour ne jamais traiter toute la surface par erreur).
  Les groupes de la base sont propagés aux niveaux du Multires.
- **Protect Detail** : atténue le Despike en proportion du détail (analyse de forme recalculée à la volée), pour
  ne jamais aplatir paupières, narines ou oreilles.

### Sous-panneau « Analyze » — optionnel, ne modifie jamais la géométrie
Analyse la forme de l'objet actif (Multires compris) : pour chaque sommet, la répartition des normales sur un
voisinage (tenseur de covariance) et la courbure moyenne signée. Résultat écrit sur le maillage de base :

| Donnée | Type | Contenu |
|--------|------|---------|
| `sw_detail` | attribut float 0–1 | densité de détail (la surface « tourne » beaucoup) — carte de densité pour une retopo |
| `sw_curvature` | attribut float −1…1 | > 0 convexe (bosse), < 0 concave (creux) |
| `sw_anisotropy` | attribut float 0–1 | ~1 : la surface tourne dans **une** direction (pli, crête, doigt) ; ~0 : dans toutes |
| `sw_shape` | attribut entier | tag : 0 Flat, 1 Bulge (dôme), 2 Hollow (cuvette), 3 Ridge (crête), 4 Fold (pli), 5 Saddle (selle) |
| `sw_flow` | attribut vecteur | direction du pli / de la crête = direction que doit suivre une boucle d'arêtes |
| `SW_Detail_Color`, `SW_Shape_Color` | couleurs | affichage (boutons **Detail** / **Shapes**, ✕ pour revenir) |
| `SW_Detail`, `SW_Bulge`, `SW_Hollow`, `SW_Ridge`, `SW_Fold`, `SW_Saddle` | groupes de sommets | filtres Despike, masques, ou carte de densité d'un remailleur |

Couleurs des tags : gris Flat · rouge Bulge · bleu Hollow · jaune Ridge · cyan Fold · violet Saddle.
Les couleurs portent le suffixe `_Color` car groupes de sommets et attributs partagent le même espace de noms.

## Réglages
- **Voxel : Relative / Absolute** — la finesse de l'enveloppe.
  - *Relative* (défaut, **Voxel %** = 0,6 % de la plus grande dimension) : indépendant de l'échelle — le même
    réglage donne le même résultat sur une tête de 23 cm, une tête normalisée à 1 m ou une main importée à 3,7 m.
    Plus petit = plus fidèle mais plus lourd ; trop fin sur une source bruitée → la projection « voit » le grain.
  - *Absolute* (**Voxel Size** en unités) : même finesse physique sur plusieurs objets de tailles différentes
    (ex. tête et mains d'un même personnage, pour qu'elles se raccordent avec une densité identique), ou pour
    viser une densité précise. La valeur équivalente du mode Relative est affichée sous le champ.
- **Close Holes** (3) : bouche les trous jusqu'à ~2 × cette valeur en voxels.
- **Slice Fill X/Y/Z** : axes de remplissage par tranches (les trois par défaut).
- **Remove Filaments** (1), **Smooth** (20 itérations de Taubin).
- **Inflate** (0 = auto : 2 voxels) et **Limit** (0 = auto : 4 × gonflement) pour le Shrinkwrap.
- **Multires Levels** (2) : densité de la projection (×16 faces).
- **Repair Missed Rays** (activé) et **Despike After** (désactivé) pour la chaîne en un clic.
- Analyze : **Neighborhood** (8 anneaux d'arêtes), **Flat Below** (0,15), **Directional Above** (0,55).

## Conseils
- Couper la source **et** l'enveloppe là où elles ne servent pas (socle, épaules) améliore la projection.
- Les **surplombs** (pavillon de l'oreille) restent le point faible d'une projection le long des normales :
  quelques pointes peuvent subsister → Despike, ou pinceau Smooth.
- Après Freeze, l'objet garde une **base légère** + niveaux Multires : sculptez, ou bakez les détails.

## Installation
- **Depuis le dépôt d'extensions d'a2msystemes.org** (à venir) : les mises à jour seront proposées directement dans
  Blender. Voir https://a2msystemes.org/projets/slice_wrap.
- **Paquet** : `slice_wrap-<version>.zip` (page *Releases* du dépôt Gitea, ou `dist\` après construction) →
  *Edit > Preferences > Get Extensions > ⌄ > Install from Disk…*
- **Construire et publier** : chaîne d'outils `a2m` (repo `ange/apc-toolchain`) — `a2m validate --load`,
  `a2m build` (→ `dist\slice_wrap-<version>.zip`), `a2m release [patch|minor|major]` (version, CHANGELOG, tag,
  release Gitea avec le zip et `publication.json`), `a2m release --dev` (pré-release de test).
  Historique des versions : [CHANGELOG.fr.md](CHANGELOG.fr.md).
- **Développement** : copier / lier ce dossier dans
  `%APPDATA%\Blender Foundation\Blender\<version>\extensions\user_default\slice_wrap`.

## Fichiers
- `__init__.py` : réglages, opérateurs, panneaux (principal, Steps, Despike, Analyze), liste des groupes.
- `core.py` : algorithmes (voxelisation, morphologie, remplissage par tranches, Taubin, réparation des ratés, despike,
  analyse de forme).
- `blender_manifest.toml` : manifeste d'extension.

## Tests (Blender 5.2.1)
Tête Pixal3D brute de 11,8 M faces → enveloppe 70 k faces (11 s) → Wrap Multires 2 → Freeze avec réparation
(~93 k ratés réparés) — chaîne complète en ~1,5–2 min. Despike filtré sur un groupe « Oreilles » : 683 sommets
corrigés contre 4 749 sur toute la surface. Analyze (1,1 M sommets évalués) en 9 s : Flat 86 %, Ridge 5 %,
Bulge 3 %, Fold 3 %, Hollow 2 %, Saddle 1 % — hélice des oreilles et lèvres en Ridge, paupières et commissures en Fold.

## Pistes (non implémentées)
- **Marqueurs de flow** dessinés par l'utilisateur (courbes / Grease Pencil sur la surface) avec des tags
  (« pli », « gonflement », « boucle œil »…), combinés aux tags automatiques d'Analyze.
- **Stratégies par tag** pour une retopologie guidée : boucles parallèles à `sw_flow` sur un Fold / Ridge, anneaux
  concentriques autour d'un Hollow (œil, bouche), pôle au sommet d'un Bulge, anneaux perpendiculaires sur un
  cylindre (doigt), densité pilotée par `sw_detail`.