slice_wrap_addon/README.md

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

*[Version française](README.fr.md)*

Turns a **holey, double-walled or noisy** mesh (scan, AI generation such as Pixal3D / Trellis) into a
**clean, closed and detailed surface**, ready to sculpt. No dependencies: numpy only (shipped with Blender).

Panel: **3D Viewport > Sidebar (N) > "Slice Wrap" tab**.

## Why not Blender's Voxel Remesh?
Voxel Remesh (and *Mesh to Volume* in Geometry Nodes) rebuilds a volume… but **leaks** as soon as the shell has a
hole: the inside is not filled and you get a double skin, moiré and misses.
Slice Wrap fills the volume **slice by slice along X, Y and Z**: a hole only leaks into the few slices it crosses,
and the other directions make up for it.

## Usage
Everything applies to the **selected (active) object**: there is no target to pick. The projection always goes
onto the source of the envelope. Without a selected mesh, the buttons are greyed out.

1. Select the (holey) source mesh in Object Mode.
2. Adjust the **Envelope** and **Wrap** sections if needed, then click **Slice Wrap** (one click):
   Envelope → Wrap Setup → Freeze, plus **Despike** if **Despike After** is checked.
3. The result `<source><suffix>` (by default `<source>_slicewrapped`) is ready to sculpt (light base + Multires
   levels). The source is hidden.

### Long computations: confirmation, progress, cancel
Slice Wrap, Envelope, Regenerate and Despike first show a message: the computation can take a while, Blender will
ignore clicks meanwhile (it has not crashed), Esc cancels. "Show this message next time" checkbox (also in
*Preferences > Add-ons > Slice Wrap > Confirm Long Operations*).
During the computation (as well as Freeze and Analyze): a **progress bar** with the current step and the elapsed
time, in the status bar at the bottom of the window and at the top of the panel. **Esc** cancels: nothing is
created or modified.
Limitation: a few internal Blender operations (Multires subdivision, Multires Reshape, Voxel Remesh) run in one
go. On a heavy mesh, the display stays frozen on that step for a few seconds, then progress resumes.

### Naming and placing the result
- **Suffix** (default `_slicewrapped`): name of the created mesh = source name + suffix.
- **Automatic numbering**: if the name already exists, `.001`, `.002`… like Blender — **no existing object is ever
  overwritten** (even with an empty suffix, the source stays intact).
- **Collection** (checkbox + name, default `SliceWrapCollection`): the result is placed in it; if the collection
  exists it is simply reused (its content is not touched), otherwise it is created and linked to the scene.
  Unchecked: the result goes into the collections of the source.
- **Regenerate** is the only button that recomputes an existing object: the active envelope, in place.

### "Steps" sub-panel (collapsed) — each step separately
| # | Button | What it does |
|---|--------|--------------|
| 1 | **Envelope** | On the active object (the source, never modified): voxels → hole closing → slice filling → closed surface (Voxel Remesh on an already full volume, no leak) → largest piece → Taubin smoothing. Creates `<source><suffix>` (numbered if the name exists). |
|   | ↻ **Regenerate** | Recomputes the active envelope from its source with the current settings (pseudo-modifier). Refused if the envelope is already wrapped. |
| 2 | **Wrap Setup** | Inflates the envelope along the normals (so that it lies entirely *above* the skin), adds **Multires** (N levels) then **Shrinkwrap**: *Project*, along the normals, **inwards only**, with a limit distance. |
| 3 | **Freeze** | Freezes the projection **into the Multires levels** (Multires Reshape) and removes the Shrinkwrap. With **Repair Missed Rays**, vertices whose projection missed — nothing hit (needles) or too far (hollow on an inner wall) — are detected exactly (before / after comparison) and rebuilt from their neighbours. |

Tip: to cut the base / shoulders before projecting, run **Envelope**, cut (Bisect), then **Wrap Setup** and
**Freeze**.

### "Despike" sub-panel — manual tool
Residual anti-spike filter: a vertex is only corrected if it is **isolated**, clearly further from the average of
its neighbours than they are from theirs; normal relief (ears, eyelids) is not smoothed.
- **Distance**: minimum deviation to count as a spike (0 = automatic: average edge length).
- **Strength** (0–1): fraction of the way towards the neighbours' average.
- **Iterations**: number of passes. **Isolation**: the spike must deviate N times more than its neighbours.
- **Vertex Group Filters**: list (+ / − / clear) of the vertex groups to process. The group **weight** modulates
  the strength (fade-out possible at the border). **Empty list = the whole surface.** If the list contains groups
  none of which exist, Despike refuses to run (so as never to process the whole surface by mistake).
  The groups of the base are propagated to the Multires levels.
- **Protect Detail**: attenuates Despike in proportion to the detail (shape analysis computed on the fly), so as
  never to flatten eyelids, nostrils or ears.

### "Analyze" sub-panel — optional, never modifies the geometry
Analyses the shape of the active object (Multires included): for each vertex, the spread of the normals over a
neighbourhood (covariance tensor) and the signed mean curvature. Result written on the base mesh:

| Data | Type | Content |
|------|------|---------|
| `sw_detail` | float attribute 0–1 | detail density (the surface "turns" a lot) — density map for a retopology |
| `sw_curvature` | float attribute −1…1 | > 0 convex (bump), < 0 concave (hollow) |
| `sw_anisotropy` | float attribute 0–1 | ~1: the surface turns in **one** direction (fold, ridge, finger); ~0: in all directions |
| `sw_shape` | integer attribute | tag: 0 Flat, 1 Bulge (dome), 2 Hollow (bowl), 3 Ridge, 4 Fold, 5 Saddle |
| `sw_flow` | vector attribute | direction of the fold / ridge = direction an edge loop should follow |
| `SW_Detail_Color`, `SW_Shape_Color` | colours | display (**Detail** / **Shapes** buttons, ✕ to go back) |
| `SW_Detail`, `SW_Bulge`, `SW_Hollow`, `SW_Ridge`, `SW_Fold`, `SW_Saddle` | vertex groups | Despike filters, masks, or density map for a remesher |

Tag colours: grey Flat · red Bulge · blue Hollow · yellow Ridge · cyan Fold · purple Saddle.
Colours carry the `_Color` suffix because vertex groups and attributes share the same namespace.

## Settings
- **Voxel: Relative / Absolute** — the resolution of the envelope.
  - *Relative* (default, **Voxel %** = 0.6 % of the largest dimension): scale-independent — the same setting gives
    the same result on a 23 cm head, a head normalised to 1 m or a hand imported at 3.7 m.
    Smaller = more faithful but heavier; too fine on a noisy source → the projection "sees" the grain.
  - *Absolute* (**Voxel Size** in units): same physical resolution on several objects of different sizes
    (e.g. head and hands of the same character, so that they join with an identical density), or to target a
    precise density. The equivalent value of the Relative mode is shown under the field.
- **Close Holes** (3): plugs holes up to ~2 × this value in voxels.
- **Slice Fill X/Y/Z**: slice filling axes (all three by default).
- **Remove Filaments** (1), **Smooth** (20 Taubin iterations).
- **Inflate** (0 = auto: 2 voxels) and **Limit** (0 = auto: 4 × inflate) for the Shrinkwrap.
- **Multires Levels** (2): density of the projection (×16 faces).
- **Repair Missed Rays** (on) and **Despike After** (off) for the one-click chain.
- Analyze: **Neighborhood** (8 edge rings), **Flat Below** (0.15), **Directional Above** (0.55).

## Tips
- Cutting the source **and** the envelope where they are not needed (base, shoulders) improves the projection.
- **Overhangs** (outer ear) remain the weak point of a projection along the normals: a few spikes may remain →
  Despike, or the Smooth brush.
- After Freeze, the object keeps a **light base** + Multires levels: sculpt, or bake the details.

## Installation
- **From the a2msystemes.org extension repository** (coming soon): updates will be offered directly in Blender.
  See https://a2msystemes.org/en/projects/slice_wrap.
- **Package**: `slice_wrap-<version>.zip` (*Releases* page of the Gitea repository, or `dist\` after building) →
  *Edit > Preferences > Get Extensions > ⌄ > Install from Disk…*
- **Build and publish**: `a2m` toolchain (repository `ange/apc-toolchain`) — `a2m validate --load`, `a2m build`
  (→ `dist\slice_wrap-<version>.zip`), `a2m release [patch|minor|major]` (version, CHANGELOG, tag, Gitea release
  with the zip and `publication.json`), `a2m release --dev` (test pre-release).
  Version history: [CHANGELOG.md](CHANGELOG.md).
- **Development**: copy / link this folder into
  `%APPDATA%\Blender Foundation\Blender\<version>\extensions\user_default\slice_wrap`.

## Files
- `__init__.py`: settings, operators, panels (main, Steps, Despike, Analyze), group list.
- `core.py`: algorithms (voxelisation, morphology, slice filling, Taubin, missed-ray repair, despike, shape
  analysis).
- `blender_manifest.toml`: extension manifest.

## Tests (Blender 5.2.1)
Raw Pixal3D head of 11.8 M faces → 70 k-face envelope (11 s) → Wrap Multires 2 → Freeze with repair (~93 k misses
repaired) — full chain in ~1.5–2 min. Despike filtered on an "Ears" group: 683 vertices corrected versus 4,749 on
the whole surface. Analyze (1.1 M evaluated vertices) in 9 s: Flat 86 %, Ridge 5 %, Bulge 3 %, Fold 3 %, Hollow 2 %,
Saddle 1 % — ear helix and lips as Ridge, eyelids and mouth corners as Fold.

## Ideas (not implemented)
- **Flow markers** drawn by the user (curves / Grease Pencil on the surface) with tags ("fold", "bulge",
  "eye loop"…), combined with the automatic Analyze tags.
- **Per-tag strategies** for a guided retopology: loops parallel to `sw_flow` on a Fold / Ridge, concentric rings
  around a Hollow (eye, mouth), a pole at the top of a Bulge, perpendicular rings on a cylinder (finger), density
  driven by `sw_detail`.