inkscape.isoCoucheGreyScale/README.md

Iso-couches par nuances de gris — extension Inkscape

Extension Inkscape 1.x qui transforme une image bitmap en planches à découper et à empiler, un calque par nuance de gris. L'image est lissée, quantifiée en quelques niveaux (16 par défaut), puis chaque aplat est bordé d'un contour fermé et souple, à la manière des courbes de niveau d'une carte. Le résultat se découpe en strates (une feuille par niveau) ou se réduit à un dessin au trait. De gauche à droite : l'image de départ, ses 16 niveaux remplis chacun de son gris (16 calques), et les mêmes 16 niveaux en remplissage blanc et trait noir.

Le lissage respecte les contours : sur un portrait, la peau et les cheveux sont aplanis mais les yeux, la bouche et le bord du visage restent nets, et les 16 niveaux suffisent à reconstruire le visage.

Sommaire

• Fonctionnalités
• Installation
• Utilisation
• Paramètres
• Structure du projet
• Développement

Fonctionnalités

• Entrée : une ou plusieurs images bitmap sélectionnées (PNG, JPEG…), incorporées ou liées, y compris dans un groupe sélectionné. Les couleurs sont lues comme des gris, la transparence comme du blanc.
• Lissage qui respecte les contours (filtre guidé) : les textures sont aplanies, les transitions marquées restent nettes, ce qui garde un visage reconnaissable. Un flou gaussien simple reste disponible pour les reliefs abstraits.
• Quantification à seuils réguliers, de 2 à 64 niveaux, après étirement de la plage de gris de l'image. Une répartition réglable rapproche les niveaux d'aires égales, pour les images dont presque toutes les valeurs tiennent dans quelques gris (cartes de profondeur).
• Carte de profondeur (facultative) : la profondeur de la scène est estimée à partir de la photo par un réseau de neurones (MiDaS small ou Depth Anything V2 Small), enrichie des contrastes fins de la photo (yeux, bouche) et mélangée aux gris dans la proportion voulue. Les planches suivent alors les volumes du sujet plutôt que ses lumières et ses ombres. Calcul sur la carte graphique quand c'est possible, résultat gardé en cache.
• Images 16 bits (cartes de profondeur produites ailleurs) lues sur toute leur plage.
• Contours tracés au sous-pixel sur l'image lissée (« marching squares »), puis simplifiés et convertis en courbes de Bézier : pas d'escalier de pixels.
• Toutes les formes sont fermées : là où un niveau touche le bord de l'image, son contour longe ce bord, en lignes droites.
• Un calque Inkscape par niveau, nommé « Planche n° 1 », « Planche n° 2 »… du fond vers l'avant, créé au-dessus de l'image : autant de nouveaux calques que de niveaux de gris. Plusieurs images sélectionnées partagent les mêmes calques.
• Planches à empiler : la planche n° 1 couvre toute l'image et chaque planche suivante, plus petite, se pose devant la précédente (la plus claire devant, ou la plus sombre devant), pour construire un relief en strates.
• Repère d'assemblage : chaque planche porte, en plus de son trait de découpe (rouge), le contour de la planche suivante (noir), au tracé exact de sa découpe, pour savoir où la coller.
• Variante « Son gris seul » : chaque calque contient l'aplat de son gris, bordé sur tous ses côtés ; les planches pavent l'image sans se recouvrir et ne portent pas de repère. Les contours sont exactement les frontières de l'image quantifiée.
• Formes écrites en coordonnées du document, sans transformation, même pour une image tournée, étirée ou placée dans un calque transformé.
• Remplissage au choix (gris du niveau, couleur unique, aucun) et trait facultatif.
• Interface traduite en français et en anglais, selon la langue d'Inkscape (anglais pour toute autre langue).
• Script de déploiement Windows.

Installation

Aucune dépendance à installer pour l'usage de base : l'extension utilise inkex, numpy et Pillow, tous fournis avec Inkscape. Seule la carte de profondeur demande une installation à part (-Depth, ci-dessous).

Windows

.\deploy.ps1              # copie dans %APPDATA%\inkscape\extensions\GrayIsoLayers
.\deploy.ps1 -Uninstall   # retire l'extension
.\deploy.ps1 -Force       # déploie même si Inkscape est ouvert
.\deploy.ps1 -Depth       # déploie, et installe de quoi calculer la profondeur

Inkscape doit être fermé pendant la copie, puis relancé.

Carte de profondeur

Le Python fourni avec Inkscape ne peut pas charger onnxruntime (c'est une construction MinGW, sans pip). .\deploy.ps1 -Depth installe donc, dans %LOCALAPPDATA%\GrayIsoLayers :

• venv\ : un environnement Python avec onnxruntime-directml, numpy et pillow, créé à partir du Python 3 de la machine (python du PATH, sinon le lanceur py ; -Python <chemin> pour en imposer un autre) ;
• models\ : les deux modèles, téléchargés une fois (64 Mo et 94 Mo) ;
• cache\ : les 30 dernières cartes calculées.

L'extension lance le calcul dans cet environnement. Sans lui, elle le signale et travaille sur les gris seuls. .\deploy.ps1 -Uninstall supprime aussi ce dossier. La variable d'environnement GRAY_ISO_LAYERS_PYTHON désigne un autre Python que celui de venv\.

Temps mesurés sur le portrait d'essai, lancement du Python compris (Core i7-3770 et RTX 4080 SUPER ; à titre indicatif) :

Modèle	Calcul	Premier passage	Passages suivants
MiDaS small (256 points)	processeur	1 s environ	cache, sans délai
Depth Anything V2 Small (518 points)	carte graphique (DirectML)	2 s environ	cache, sans délai
Depth Anything V2 Small	processeur	3 s environ	cache, sans délai

MiDaS small est toujours calculé sur le processeur : sous DirectML il rend une carte fausse, et son calcul est plus court que l'initialisation de la carte graphique.

Manuelle

Copier dans un sous-dossier du répertoire des extensions utilisateur (%APPDATA%\inkscape\extensions sous Windows, ~/.config/inkscape/extensions sous Linux, ~/Library/Application Support/org.inkscape.Inkscape/config/inkscape/extensions sous macOS) :

• gray_iso_layers.inx, gray_iso_layers.py, gray_iso_layers_core.py, gray_iso_layers_depth.py, depth_estimate.py ;
• images/parameters_en.png ;
• le dossier locale/.

Utilisation

1. Importer une image (Fichier > Importer) et la sélectionner.
2. Lancer Extensions > AlexDesign > Iso-couches par nuances de gris… (Gray Iso-Layers).
3. Régler le nombre de niveaux et le lissage, puis Appliquer.

Le résultat est une série de calques « Planche n° 1 », « Planche n° 2 »… ajoutés juste au-dessus du calque de l'image, un par niveau de gris. La planche n° 1 est au fond, la dernière devant. Par défaut, les planches s'empilent : la planche n° 1, la plus sombre, couvre toute l'image et les suivantes se posent devant elle. Chaque calque contient deux chemins : la « Découpe » de la planche (trait rouge) et le « Repère de la planche n° … » suivante (trait noir, sans remplissage). Avec le contenu « Son gris seul », chaque planche est l'aplat de son gris et il n'y a pas de repère. Un niveau dont toutes les formes sont plus petites que le plus petit îlot conservé garde son calque, vide.

Conseils

• Découpe laser : choisir « Aucun remplissage » ; il ne reste que les traits de découpe (rouge) et de marquage (noir), à affecter chacun à son réglage dans le logiciel de la machine. Découper un calque par feuille.
• Dessin au trait, comme une carte topographique : remplissage « Couleur unique » blanche (ou « Aucun remplissage »), trait noir, repère décoché.
• Contours trop chargés, petits îlots : augmenter le lissage ou le plus petit îlot conservé.
• Contours anguleux : augmenter le lissage ou la simplification.
• Détails perdus, visage méconnaissable : réduire le lissage (0,5 à 1 %), laisser « Préserver les contours » coché, augmenter la résolution de calcul.
• Relief fidèle aux volumes : onglet « Profondeur », part de la carte de profondeur à 100 % et modèle « Fin », qui détoure nettement mieux les cheveux et le visage que le modèle « Rapide ». Les planches suivent les volumes (le nez devant, le fond derrière) et le réglage « Détails fins » y grave les yeux, la bouche et les sourcils, que la profondeur seule ne contient pas. Visage trop lisse : monter les détails fins (jusqu'à 150 %). Trop de petites formes dans les cheveux ou la barbe : les baisser, ou augmenter le lissage.
• Planches vides, sujet tassé sur quelques planches (fréquent avec une carte de profondeur) : augmenter la répartition des niveaux. À 100 %, toutes les planches ont la même surface, fond compris ; une valeur intermédiaire garde plus de planches pour le sujet.
• Carte de profondeur produite ailleurs : l'importer et la sélectionner comme n'importe quelle image (8 ou 16 bits), part de profondeur à 0.
• Portrait : un fond uni donne le meilleur résultat ; un fond en dégradé produit des anneaux, puisque chaque nuance du dégradé devient un aplat.
• Image liée introuvable : l'incorporer (clic droit > Incorporer l'image).
• Une image de bruit flou (nuages, relief) donne les motifs les plus proches d'une carte de courbes de niveau.

Paramètres

Onglet Niveaux

Paramètre	Défaut	Rôle
Nombre de niveaux de gris	16	Nombre d'aplats, donc de calques produits (2 à 64).
Répartition des niveaux (% d'aires égales)	0	0 : seuils régulièrement espacés. 100 : chaque planche couvre la même surface.
Contenu de chaque planche	Empilées, la plus claire devant	« Empilées, la plus claire devant » : planche n° 1 = la plus sombre, toute l'image. « Empilées, la plus sombre devant » : planche n° 1 = la plus claire, toute l'image. « Son gris seul » : planches côte à côte, sans recouvrement, planche n° 1 = le gris le plus sombre.
Reporter sur chaque planche le contour de la suivante	oui	Repère d'assemblage tracé dans la couleur de marquage (planches empilées uniquement).
Lissage (% du grand côté de l'image)	1	Lissage appliqué avant la découpe : plus il est fort, plus les contours sont ronds et simples.
Préserver les contours lors du lissage	oui	Aplanit la peau et les textures mais garde nettes les transitions marquées (portraits, photos). Décoché : flou gaussien simple, mieux adapté aux reliefs abstraits.
Résolution de calcul (points sur le grand côté)	800	Taille à laquelle l'image est rééchantillonnée pour le calcul.
Plus petit îlot ou trou conservé (% de la surface de l'image)	0,02	Les formes plus petites sont écartées.
Simplification (points de calcul)	0,4	Écart maximal toléré lors de la suppression de nœuds ; 0 les conserve tous.
Lisser les contours avec des courbes de Bézier	oui	Sinon, les contours sont des polygones.

Onglet Profondeur

Paramètre	Défaut	Rôle
Part de la carte de profondeur (%)	0	0 : gris de l'image seuls. 100 : profondeur estimée seule. Entre les deux, mélange. Demande deploy.ps1 -Depth.
Modèle de profondeur	Rapide (MiDaS small)	« Rapide » : MiDaS small, carte lisse. « Fin » : Depth Anything V2 Small, contours plus précis.
Détails fins de la photo (%)	100	Grave dans la profondeur les contrastes fins de la photo (yeux, bouche, sourcils). Un fond uni n'apporte rien et reste au fond. 0 : profondeur lisse seule.

Onglet Style

Paramètre	Défaut	Rôle
Remplissage	Gris de chaque niveau	Gris du niveau, couleur unique ou aucun remplissage.
Couleur de remplissage	blanc	Utilisée par le mode « Couleur unique ».
Épaisseur du trait (0 = sans trait)	0,2	Dans l'unité choisie ; commune à la découpe et au marquage.
Unité	mm	Unité de l'épaisseur du trait.
Couleur du trait de découpe	rouge	Contour de la planche.
Couleur du trait de marquage	noir	Repère de la planche suivante.
Conserver l'image d'origine	oui	Sinon l'image est supprimée.

Structure du projet

gray_iso_layers.inx        Boîte de dialogue (textes source en anglais)
gray_iso_layers.py         Couche inkex : lecture de l'image, écriture du SVG
gray_iso_layers_core.py    Noyau de calcul, sans inkex (numpy seul)
gray_iso_layers_depth.py   Carte de profondeur : lancement du calcul, cache
depth_estimate.py          Calcul de la profondeur (onnxruntime), hors Inkscape
i18n.py                    Extraction / mise à jour / compilation des traductions
po/                        Catalogues grayisolayers.pot, en.po, fr.po
locale/                    Catalogues compilés (.mo), déployés
images/parameters_en.png   Schéma de l'onglet « Help »
docs/schema_parametres.py  Générateur du schéma (fr pour le README, en pour le dialogue)
docs/parametres.png        Schéma du README
docs/exemple.png           Illustrations du README (relief, portrait)
docs/exemple-portrait.png
doc/patern.jpg             Motif qui a servi de modèle
doc/personne.jpg           Portrait d'essai
test_gray_iso_layers.py    Tests pytest
deploy.ps1                 Déploiement / désinstallation Windows

API du noyau (gray_iso_layers_core.py). Un champ est un tableau numpy 2D de gris (0 noir, 1 blanc) ; un anneau est un tableau (n, 2) de points, en échantillons du champ.

Fonction	Rôle
gaussian_blur(field, sigma)	Flou gaussien séparable, bords prolongés.
box_blur(field, radius)	Moyenne sur une fenêtre carrée.
edge_preserving_blur(field, radius, contrast)	Lissage qui respecte les contours (filtre guidé).
smooth(field, blur, preserve_edges)	Lissage avant découpe, puis étirement sur 0..1.
normalize(field)	Étire le champ sur 0..1.
spread_levels(field, amount)	Répartit les valeurs pour que les niveaux tendent vers des aires égales.
guided_filter(guide, source, radius, eps)	Lisse source en lui donnant les contours de guide (carte de profondeur recalée sur la photo).
add_detail(depth, gray, amount, sigma)	Grave dans la profondeur les contrastes fins des gris (yeux, bouche).
blend_fields(gray, depth, mix)	Mélange des gris et de la profondeur.
thresholds(levels)	Seuils réguliers séparant les niveaux.
contour_rings(field, threshold, above=True)	Contours fermés de la région au-dessus (ou au-dessous) du seuil.
ring_area(ring)	Aire d'un anneau.
simplify_ring(ring, tolerance) / simplify_chain(chain, tolerance)	Simplification de Douglas-Peucker d'un anneau fermé, d'une ligne ouverte.
contour_lines(field, threshold, tolerance, min_area)	Ligne de niveau d'un seuil : boucles fermées et lignes ouvertes aboutissant au bord.
region_rings(field, lines, inside)	Contour fermé d'une région bornée par des lignes de niveau, refermé le long du bord de l'image.
iso_boards(field, levels, blur, min_area, tolerance, shapes, preserve_edges, equalize)	Une planche par niveau : liste de (niveau, gris, anneaux, repère), le repère étant la ligne de niveau qui borde la planche suivante.
iso_layers(…)	Comme iso_boards, sans les repères.
image_ring(width, height)	Rectangle de l'image.
scale_rings(rings, scale_x, scale_y, offset_x, offset_y)	Passage au repère de destination.
lines_to_d(lines, smooth, box, precision, matrix) / scale_lines(…)	Écriture et mise à l'échelle d'une ligne de niveau (boucles fermées et lignes ouvertes).
rings_to_d(rings, smooth, box, precision, matrix)	Données d d'un chemin SVG, bords de l'image gardés droits, transformation affine facultative.
parse_color(value) / gray_to_hex(gray)	Couleurs.

Développement

pip install pytest numpy pillow
python -m pytest -q

Sans inkex : 51 tests passent, 17 sont ignorés. Avec inkex :

pip install lxml tinycss2 cssselect2 cssselect
$env:PYTHONPATH = 'C:\Program Files\Inkscape\share\inkscape\extensions'
python -m pytest -q        # 67 tests passent, 1 est ignoré

Le test ignoré est le calcul réel d'une carte de profondeur, qui demande onnxruntime et le modèle. Il se lance dans l'environnement de -Depth :

& "$env:LOCALAPPDATA\GrayIsoLayers\venv\Scripts\python.exe" -m pip install pytest
& "$env:LOCALAPPDATA\GrayIsoLayers\venv\Scripts\python.exe" -m pytest -q -k depth

Les tests couvrent le noyau (lissage qui respecte les contours, répartition des niveaux, filtre guidé, détails fins gravés dans la profondeur, contours d'un cône et d'une rampe, fermeture le long des bords, cas selle, simplification, aplats conformes à l'image quantifiée, frontières communes aux aplats voisins, feuilles à empiler, îlots écartés, écriture des chemins), la carte de profondeur avec un calcul simulé (cache, environnement transmis, causes d'échec), l'extension de bout en bout (image 16 bits, mélange de la profondeur et repli sur les gris, un calque par niveau, repères d'assemblage, image incorporée, liée ou tournée, groupe sélectionné, styles, messages d'erreur) et la cohérence des traductions et du .inx.

Traductions

Les textes source sont en anglais, dans le .inx et dans les _("...") du .py. Après toute modification :

python i18n.py        # extrait, met à jour po/*.po, compile locale/

Compléter les msgstr vides de po/fr.po, puis relancer la commande. Pour ajouter une langue, l'ajouter à LANGUAGES dans i18n.py.

Schéma des paramètres

python docs/schema_parametres.py

Produit docs/parametres.png (français, README) et images/parameters_en.png (anglais, onglet « Help »), tracés avec les fonctions du noyau. L'export PNG passe par inkscape.com.