inkscape.BoxFingering/README.md

# Boîte à créneaux pour Inkscape

<table>
<tr>
<td width="50%" valign="top">
<img src="docs/apercu-boite.png" alt="Patron généré pour une boîte fermée de 100 × 80 × 50 mm : six pièces à créneaux rouges (avant, arrière, gauche, droite, fond, couvercle) disposées en grille" width="420">
</td>
<td valign="top">

Extension Inkscape 1.x qui génère le patron d'une boîte à découper au laser. Les faces s'assemblent par queues d'aronde droites (créneaux, _finger joints_) dont la largeur est paramétrable. Chaque pièce est un objet indépendant, déplaçable seul pour optimiser le placement sur la plaque.

</td>
</tr>
</table>

## Table des matières

- [Fonctionnalités](#fonctionnalités)
- [Installation](#installation)
- [Utilisation](#utilisation)
  - [En ligne de commande](#en-ligne-de-commande)
- [Paramètres](#paramètres)
- [Le kerf : compensation du trait laser](#le-kerf--compensation-du-trait-laser)
  - [Le problème](#le-problème)
  - [Ce que fait l'extension](#ce-que-fait-lextension)
  - [Mesurer son kerf](#mesurer-son-kerf)
  - [Régler l'ajustement](#régler-lajustement)
- [Structure du projet](#structure-du-projet)
- [Développement](#développement)

## Fonctionnalités

- Boîte **fermée** (6 pièces : avant, arrière, gauche, droite, fond, couvercle) ou **ouverte** (5 pièces, bord haut des côtés droit)
- Dimensions saisies **intérieures** ou **extérieures** (l'épaisseur est ajoutée automatiquement en mode intérieur)
- Largeur des créneaux paramétrable ; `0` = **3 × l'épaisseur** (défaut). La largeur est ajustée pour obtenir un nombre impair de créneaux par bord
- Compensation du **kerf** (défaut 0,1 mm), voir [section dédiée](#le-kerf--compensation-du-trait-laser)
- Chaque pièce = un chemin SVG fermé, nommé (Avant, Fond…), placé directement dans le calque courant : sélectionnable et déplaçable individuellement
- Pièces disposées en grille, espacement réglable, centrées sur la vue
- Couleur et épaisseur du trait réglables (défaut : rouge, 0,1 mm)
- Étiquettes optionnelles (texte bleu). Désactivées par défaut : le laser graverait le texte
- Message d'erreur si une dimension est trop petite (minimum 5 × l'épaisseur en dimension extérieure)

## Installation

Inkscape fermé, depuis le dossier du projet (PowerShell) :

```powershell
.\deploy.ps1              # installe dans %APPDATA%\inkscape\extensions\boxMaker
.\deploy.ps1 -Uninstall   # désinstalle
```

Le script copie `box_maker.inx`, `box_maker.py`, `box_core.py` et le dossier `images\` (schéma de l'onglet « Schéma »). Options : `-ExtensionsDir`, `-FolderName`, `-Force` (déploie même si Inkscape est ouvert). Redémarrer ensuite Inkscape.

Installation manuelle : copier ces mêmes fichiers et le dossier `images\` dans `%APPDATA%\inkscape\extensions\boxMaker\`.

## Utilisation

1. Menu **Extensions > AlexDesign > Boîte à créneaux…**
2. Régler les paramètres (illustrés dans l'onglet **Schéma**), cocher **Aperçu en direct** si besoin
3. **Appliquer**

### En ligne de commande

Avec le Python d'Inkscape (PowerShell) :

```powershell
$env:PYTHONPATH = "C:\Program Files\Inkscape\share\inkscape\extensions"
& "C:\Program Files\Inkscape\bin\python.exe" box_maker.py `
    --length=100 --width=80 --height=50 --thickness=3 `
    --kerf=0.1 --dim_type=interior --lid=false --labels=true `
    --stroke_color=4278190335 entree.svg > sortie.svg
```

Les options booléennes exigent une valeur (`--lid=true` / `--lid=false`). La couleur est un entier RGBA (`4278190335` = `0xff0000ff`, rouge).

## Paramètres

![Schéma des paramètres : dimensions de la boîte, épaisseur et dimensions intérieures ou extérieures, largeur des créneaux, compensation du kerf](docs/parametres.png)

| Onglet              | Paramètre                                    | Défaut        | Rôle                                                                     |
| ------------------- | -------------------------------------------- | ------------- | ------------------------------------------------------------------------ |
| Dimensions          | Longueur / Largeur / Hauteur (mm)            | 100 / 80 / 50 | Taille de la boîte (schéma 1)                                            |
| Dimensions          | Les dimensions sont                          | Extérieures   | Intérieures : l'épaisseur est ajoutée (schéma 2)                         |
| Dimensions          | Boîte fermée (avec couvercle)                | coché         | Décoché : 5 pièces, bord haut des côtés droit                            |
| Matière et créneaux | Épaisseur de la matière (mm)                 | 3             | Profondeur des créneaux et des encoches                                  |
| Matière et créneaux | Largeur des créneaux (mm, 0 = 3 × épaisseur) | 0             | Ajustée pour un nombre impair de créneaux par bord (schéma 3)            |
| Matière et créneaux | Compensation du trait laser, kerf (mm)       | 0,1           | Contour élargi de kerf / 2 (schéma 4, [détails](#le-kerf--compensation-du-trait-laser)) |
| Tracé               | Espacement entre les pièces (mm)             | 5             | Écart entre les pièces de la grille                                      |
| Tracé               | Épaisseur du trait (mm)                      | 0,1           | Largeur du trait de découpe                                              |
| Tracé               | Couleur du trait                             | rouge         | Couleur du trait de découpe                                              |
| Tracé               | Nommer les pièces (texte gravé !)            | décoché       | Ajoute le nom de chaque pièce en texte bleu                              |

## Le kerf : compensation du trait laser

### Le problème

Le faisceau laser n'a pas une largeur nulle : il vaporise une bande de matière, le **kerf** (typiquement 0,05 à 0,3 mm selon la machine, la lentille, la matière et son épaisseur). Cette bande est centrée sur le trait du dessin, donc chaque bord découpé recule de **kerf / 2** :

- une pièce de 100 mm sort à 100 − kerf ;
- un créneau de 9 mm sort à 9 − kerf ;
- une encoche de 9 mm sort à 9 + kerf.

Au montage, chaque créneau a donc un jeu d'un kerf complet dans son encoche : la boîte tient mal, voire pas du tout sans colle.

### Ce que fait l'extension

Chaque contour est décalé **vers l'extérieur de kerf / 2** avant d'être dessiné (`offset_orthogonal` dans `box_core.py`). Sur le dessin :

| Élément         | Cote dessinée | Cote après découpe |
| --------------- | ------------- | ------------------ |
| Pièce de 100 mm | 100 + kerf    | 100 mm             |
| Créneau de 9 mm | 9 + kerf      | 9 mm               |
| Encoche de 9 mm | 9 − kerf      | 9 mm               |

Après passage du laser, les pièces retrouvent leurs cotes nominales et les créneaux remplissent exactement les encoches. Conséquence visible dans Inkscape : les pièces mesurent kerf de plus que les dimensions saisies, c'est normal.

### Mesurer son kerf

1. Dessiner un carré de 20 mm, le découper avec les réglages habituels (puissance, vitesse, matière).
2. Mesurer le carré au pied à coulisse : kerf = 20 − cote mesurée.
   Pour plus de précision, découper une rangée de 10 carrés de 10 mm jointifs : kerf = (100 − longueur totale mesurée des 10 carrés) / 10.

### Régler l'ajustement

- **kerf = valeur mesurée** : ajustement exact, montage à frottement.
- **kerf plus grand** : plus serré (montage au maillet, sans colle). Attention au bois, qui gonfle avec l'humidité.
- **kerf plus petit** : du jeu (montage facile, collage).
- **kerf = 0** : pas de compensation, cotes du dessin = cotes nominales.

Le kerf dépend de la matière : refaire la mesure en changeant de matériau ou d'épaisseur.

## Structure du projet

```
.
├── box_maker.inx          # Interface de l'extension (paramètres, menu)
├── box_maker.py           # Extension inkex : conversion en SVG, placement dans le calque
├── box_core.py            # Géométrie pure Python (mm) : créneaux, kerf, mise en page
├── deploy.ps1             # Installation / désinstallation dans Inkscape
├── images/
│   └── parametres.png     # Schéma de l'onglet « Schéma » (déployé)
├── docs/                  # Illustrations du README (non déployées)
│   ├── apercu-boite.png   # Patron d'exemple
│   ├── parametres.png     # Schéma des paramètres (+ sources .svg)
│   └── schema_parametres.py  # Générateur des deux versions du schéma
└── tests/
    └── test_box_core.py   # Tests unitaires de la géométrie
```

## Développement

Environnement et tests (13 tests, géométrie pure, sans `inkex`) :

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install pytest
python -m pytest -q
```

### Schéma des paramètres

`docs/schema_parametres.py` dessine le schéma avec les fonctions de `box_core.py` (il reste fidèle au rendu réel) et l'exporte en PNG via `C:\Program Files\Inkscape\bin\inkscape.com` :

```powershell
python docs/schema_parametres.py            # les deux versions
python docs/schema_parametres.py readme     # docs/parametres.png, 1400 px
python docs/schema_parametres.py dialogue   # images/parametres.png, 900 px, textes agrandis
```

Relancer après toute modification de la géométrie ou des paramètres, puis `.\deploy.ps1`.

### Patron d'exemple

`docs/apercu-boite.png` est le résultat de l'extension sur un document vierge de 300 × 300 mm (boîte fermée 100 × 80 × 50 mm, épaisseur 3 mm, étiquettes activées, trait 0,4 mm), exporté par `inkscape.com --export-area-drawing --export-width=900`.