Copyright 2026 Colin Ezra Wilder. Sous licence Apache, Version 2.0 (les fichiers LICENSE et NOTICE accompagnant cette compétence).
Pièces CAO via sous-processus CadQuery
CAO locale et scriptable : un script Python construit le solide, un sous-processus surveillé
l'exécute, cq_helpers valide l'exportation, un PNG à 6 vues prouve la forme. L'utilisateur
imprime les résultats sur des imprimantes FDM, donc chaque STL qui sort d'ici doit se trancher proprement.
Non-négociables
- Sous-processus unique uniquement. Le 14/07/2026, un processus serveur CAO de longue durée
a planté toute la machine par manque de mémoire alors que les modèles importés s'accumulaient entre
les appels (une relecture du 14/11/2026 a écarté l'échelle non uniforme d'abord soupçonnée ; voir
pièges). Un sous-processus qui plante perd une exécution ; une opération en cours qui plante
fait tomber la machine. Exécutez chaque construction via
scripts/run_watchdogged.ps1, et tous les autres scripts du venv aussi (sondes de dessin, vérifications de maillage), CadQuery ou non. Lorsquehooks/require_runner.pyest enregistré comme hook Claude Code (README), un appel direct au Python du venv est refusé avec la commande du lanceur à utiliser à la place : ce refus est le fonctionnement de la règle, pas une erreur à contourner. - Ne jamais modifier un fichier de pièce validé. Un script dont l'impression a été testée et
fonctionne est gelé. Les variantes obtiennent un NOUVEAU fichier (par ex.
adapter_hex_trim.pyà côté deadapter_hex.py) avec une docstring nommant exactement ce qui a changé et pourquoi. Chaque script porte une ligneSTATUS:(Conventions de script) afin que « validé » soit écrit, pas mémorisé. - Chaque exportation passe par
cq_helpers.export_checked.BRep.isValid()seul ne garantit pas un maillage propre ; les trancheuses rejettent les STL non étanches qui passent les vérifications de validité. Cette porte a déjà attrapé une mauvaise pièce expédiée. - Chaque pièce qui sera imprimée reçoit une vérification d'îlot dans son orientation
d'impression.
h.islands(solid, up="+z")(ou l'axe prévu vers le haut) trouve le matériau qui commence au-dessus du lit et ne rejoint les couches de la pièce que plus tard, reposant ainsi sur des supports tout du long. Un îlot HAUT est un problème de conception à corriger ou à soumettre à l'utilisateur avant tout plan d'impression, jamais « les supports géreront ça ». Le 09/10/2026, un pilier d'espace entre les roues d'une coque de robot en était un (36,8 mm de haut sur supports arborescents, 6,52 mince) et s'est cassé en cours de route lors d'une impression tricolore de 22 h, après que toutes les vérifications d'ajustement avaient réussi. Les vérifications d'ajustement demandent « est-ce que ça s'ajuste ? » ; celui-ci demande « peut-il être construit de bas en haut ? ».
Flux de travail
- Confirmez ce que l'invite laisse ouvert. Un cahier des charges complet (« 12 mm de haut, 9 DE, 4,3 trou ») n'a besoin d'aucune porte. Lorsqu'un choix important est ouvert (quels trous, à partir de quoi « 15 mm en saillie » est mesuré, ce qui s'y monte, quelle quincaillerie, quel dossier), énoncez votre lecture comme une courte proposition et demandez à l'utilisateur avant de construire. Les images de référence passent toujours cette porte (voir ci-dessous).
- Écrivez le script. Pièces livrables : le script se trouve à côté de ses sorties dans le dossier de la pièce (le script EST l'enregistrement de la pièce ; voir « Où vivent les pièces »). Sondes et expériences : un dossier de brouillon.
- Exécutez-le :
Valeurs par défaut : 300 s de timeout, 4 Go de limite, 500 ms de scrutation, interpréteur& "$env:USERPROFILE\.claude\skills\cad-parts\scripts\run_watchdogged.ps1" -Script "C:\chemin\vers\part.py" -Tail 40C:\cadquery-venv\Scripts\python.exe(remplacez par-Python <chemin>ou la variable d'environnementCADPARTS_PYTHON). La limite porte sur la mémoire allouée de l'ensemble de l'arborescence des processus, appliquée par le noyau via un objet de tâche Windows : une allocation au-delà est refusée (le script voitMemoryErrorou une erreur d'allocation OCCT) et le lanceur tue l'arborescence, code de sortie 137. L'importation de CadQuery seule alloue environ 0,7 Go, donc ne descendez jamais en dessous de ~1 Go. Augmentez les limites uniquement délibérément pour une tâche connue pour être lourde, jamais en première réponse à une mise à mort ; une mise à mort par watchdog indique généralement une erreur de géométrie (voir pièges), pas une limite trop basse.-Tail Nn'affiche que les N dernières lignes stdout ; le journal complet se trouve toujours dans<script>.out.txtà côté du script. Utilisez-le sur les scripts qui journalisent beaucoup pour que le journal complet n'atterrisse pas dans le contexte. La ligne de résumé indique le temps réel : choisissez-TimeoutSecà partir de cela, pas par estimation. Via un outil PowerShell, définissez le timeout de l'outil lui-même au-dessus de-TimeoutSec. Si l'outil tue le lanceur en premier, l'objet de tâche fait tomber la construction avec lui : l'exécution est perdue, jamais orpheline. - Lisez la sortie. Le lanceur affiche la sortie standard du script, toute erreur standard, le temps
réel, et la mémoire allouée maximale de l'arborescence. Exigez la sentinelle
DONE; une exécution sans elle ne s'est pas terminée. Code de sortie 137 = mise à mort par watchdog (la dernière ligne indique timeout ou limite) ; 3 = le watchdog n'a pas pu s'armer (ou l'interpréteur est manquant), donc le script n'a jamais été exécuté.<script>.out.txtest le journal d'exécution de la construction (les README le citent) ;<script>.err.txtn'existe que lorsque stderr avait du contenu. En cas de mise à mort par limite, triez avant de toucher à une limite (pièges : « Trier une mise à mort par limite »). - Vérifiez avant de rapporter. Lisez le PNG
render6et vérifiez la silhouette par rapport à l'intention. Rapportez les dimensions à partir de la boîte englobante/volume imprimés du script, pas de mémoire. Vérifiez chaque fonctionnalité en MESURANT le solide construit (describe, boîtes englobantes de faces, une tranche intersectée à travers la paroi) ; une assertion qui compare une constante d'entrée à elle-même ne prouve rien. Exécutez ensuiteh.islandsdans l'orientation dans laquelle la pièce sera imprimée (non négociable 4) et rapportez ce qu'elle signale avec la pièce. - Enregistrez. Mettez à jour le README du dossier (quel fichier imprimer), définissez la ligne STATUS, et notez tout ce qui a été appris et dont la prochaine session aura besoin (voir « Enregistrement »).
Où vivent les pièces et ce que contient un dossier de pièce
Racine des pièces : DEMANDER (si cela dit encore DEMANDER, demandez à l'utilisateur où les pièces doivent
vivre, par ex. C:\Users\<nom>\Documents\cad-parts, et proposez de l'écrire ici).
Chaque pièce obtient son propre dossier sous cette racine ; regroupez les pièces connexes dans
sous-dossiers (les pièces de châssis d'un robot ensemble, les impressions uniques ensemble). Si
l'emplacement d'une pièce n'est pas clair, demandez ; ne devinez pas.
Un dossier de pièce contient :
- Les script(s), STEP et rendus au niveau supérieur ; chaque STL dans un sous-dossier
stl/(exportez avecstl_dir="stl"). Dans un dossier de chaîne (voir « Modifications en chaîne »), le niveau supérieur contient UNE version vivante de la pièce : s'il y a un STL dansstl/pour la pièce de niveau supérieur, c'est celui à imprimer. Un STL cassé remis par quelqu'un reste au niveau supérieur, jamais dansstl/, carstl/signifie imprimable. README.md: ce qu'est la pièce, la lignée (« en cours d'utilisation : v12, le plus récent : essai v16 »), et une ligne explicite « celui à imprimer ». Rien ne passe dansarchived/sans l'accord de l'utilisateur. Pas encore de README : écrivez-en un. Les tailles frères plutôt que les versions (une entretoise de 11 mm et une de 14 mm) obtiennent une ligne d'impression chacune.archived/: versions remplacées, un dossier par version ou étape de chaîne, chacune avec son script, STEP, STL, rendus et journal d'exécution ensemble, etWHY-ARCHIVED.mdà la racine de l'archive. Les étapes de chaîne archivées ne se réexécutent pas sur place (leurs chemins sources supposent l'ancienne disposition) ; copiez-en une d'abord au niveau supérieur.- Marqueurs
DEAD-*.mdpour les fonctionnalités qui ne doivent jamais revenir (par ex.CRUSH-RIBS-DEAD-DO-NOT-REBUILD.md: nervures d'écrasement qui ont détruit deux moteurs). Lisez tout fichier DEAD dans le dossier avant de toucher à la pièce. - Un plan d'impression, s'il est écrit, lié à un nom de STL ; marquez-le comme obsolète lorsque la pièce évolue.
<script>.out.txt, le journal d'exécution de la construction.current.jsondans les dossiers de chaîne (sections suivantes).
Conventions de script
- Docstring du module : ce qu'est la pièce, pourquoi elle existe, comment l'exécuter, et une
ligne
STATUS:(faites-en une docstring brute,r""", lorsqu'elle contient des chemins Windows : CPython 3.14 avertit sur les échappements\c,\s) :STATUS: imprimé le 2026-09-08, ajusté, GELÉouSTATUS: essai, non imprimé. GELÉ est ce que le non négociable 2 entend par validé ; mettez à jour la ligne lorsqu'un résultat d'impression revient. - La docstring contient le delta de CETTE version et son raisonnement. La lignée et le fichier à imprimer appartiennent au README. Ne collez pas les notes de la version précédente (un script qui l'a fait a atteint 50 Ko).
- Les numéros de version avancent par dixièmes : chaque nouvelle construction d'une ligne de pièce versionnée
est +0,1,
v22->v22.1...v22.9->v23, ne sautez jamais en avant à moins que l'utilisateur ne le dise. Les fichiers écrivent le point comme un trait de soulignement (chassis_v22_1.py,.step,stl/..._v22_1.stl) car les scripts ultérieurs importent les versions antérieures comme modules (import chassis_v12 as V12) et un nom de module avec des points ne peut pas être importé ; les docstrings et README disent « v22.1 ». Les fichiers existants gardent leurs numéros. Les étapes de chaîne (step8,step11e) gardent leur propre schéma, et tout poinçon de version gravé sur une pièce reste le propre décompte de l'utilisateur. - TOUTES les dimensions en tant que constantes nommées en haut, en mm, un seul endroit à modifier.
import cq_helpers as h(installé dans site-packages du venv).- Dites QUELLE main chaque fois que vous écrivez gauche ou droite : la gauche du robot ou de la pièce elle-même (comme si vous l'étiez, faisant face à l'avant) ou la gauche du spectateur regardant son devant. Elles sont opposées ; une « gauche » nue dans une docstring, README ou message est un défaut. Écrivez la convention d'axe (quelle direction est l'avant, +x, le haut) en haut de tout projet multi-pièces et conservez-la.
- Affirmez
solid.isValid()et affirmez que la boîte englobante correspond aux dimensions prévues ; protégez également les formules avec des assertions (par ex. la profondeur d'alésage doit dépasser la saillie de l'arbre), afin qu'une mauvaise modification de paramètre échoue bruyamment au lieu d'imprimer des déchets. - La quincaillerie d'accouplement est modélisée en tant que solides et vérifiée avec
h.interference. Prenez les dimensions d'une fiche technique ou d'un pied à coulisse et marquez le commentaire de chaque constante mesurée ou supposée, avec l'origine du nombre. Valeurs par défaut de fixation lorsque rien de mieux n'est connu : tête cylindrique M3 5,5 x 3,0, jeu M3 D3,30, avant-trou auto-taraudeur M2 dans PLA D1,7 à 1,8. Autres fixations standard : filetage ISO 261 et jeu ISO 273, marqué supposé. print(..., flush=True)pour la progression ; terminez parprint("DONE", flush=True).- Exportation :
h.export_checked(solid, str(SORTIE / "nom_piece"), stl_dir="stl")puish.render6(solid, str(SORTIE / "nom_piece.png")). - Une pièce par fichier exporté ; les pièces sont imprimées individuellement.
Modifications en chaîne sur un STEP importé
De nombreuses pièces sont un delta sur un STEP parent importé (une plaque de base a atteint l'étape 10c via neuf de ces deltas). Règles :
- Nommez les étapes
step<N>, avec une lettre de suffixe pour une branche (step7c) ou un rebasage (step5r) ; la ligne SRC de la docstring nomme le fichier parent. Un rebasage obtient une note POURQUOI dans le dossier. - Le dossier de chaîne contient
current.jsonnommant le parent vivant. Écrivez-le avech.set_current(dossier, "piece.step", note="2026-09-22: ...")lorsque l'utilisateur nomme la pièce à imprimer, ou à partir du script d'étape juste après sonexport_checked. La ligne « celui à imprimer » du README etcurrent.jsondoivent correspondre. - Les dépendants importent le parent avec
plate = h.import_current(PLATE_DIR, pin="base_plate_step10c"), jamais par un nom de fichier codé en dur. Lorsque la chaîne se déplace, la construction épinglée ÉCHOUE en nommant les deux pièces ; réexécutez chaque vérification d'ajustement par rapport au nouveau parent, puis déplacez l'épingle. La vérification d'empreinte échoue également si le STEP a été remplacé sansset_current. (Pourquoi : les dépendants ont cessé de s'exécuter lorsque leur STEP parent a disparu, et l'un d'eux a réussi toutes les vérifications épinglé à un ancien parent alors qu'un plus récent était la pièce à imprimer.) - Prouvez le delta :
h.diffavant et après, et affirmez que tout en dehors de la boîte d'édition est inchangé. - Une NOUVELLE pièce dépendante (un support boulonné à une plaque) affirme au moins : assise (écart nul avec la face d'accouplement, pas de chevauchement), ses axes de trou sur ceux du parent, dégagement de tige dans les deux trous, accès de tête et d'outil dégagé (une colonne de clé hexagonale au-dessus de chaque tête), et toute fonctionnalité du parent qu'elle ne doit pas bloquer toujours libre. Lisez les trous du parent à partir de sa B-rep, en filtrant les faces de cylindre par direction d'axe, car un congé est aussi une face de cylindre.
- Variante uniquement paramétrique d'un script (la copie de 14 mm d'une entretoise de 11 mm) :
prouvez que « rien d'autre n'a changé » avec un diff textuel des deux scripts (seulement la
docstring, NOM et le paramètre diffèrent) plus
describe()par rapport au volume analytique. Aucune sonde de diff géométrique nécessaire. - Une échelle non uniforme transforme chaque face d'une B-rep importée en B-spline (pièges) : les décalages peuvent échouer après. Reconstruisez ou mettez à l'échelle le maillage.
API cq_helpers (site-packages du venv)
export_checked(shape, basepath, stl=True, step=True, stl_dir=None, mesh=None, agree_tol=0.015): accepte Workplane ou Shape ; exigeisValid(); écrit.step/.stl(le STL dans<dir de basepath>/<stl_dir>/lorsquestl_direst défini, toujours"stl"ici) ; trimesh étanche + porte de winding sur le STL avec réparation automatique (merge_vertices chiffres 5 puis 4, fill_holes, fix_normals, accepté uniquement si la dérive de volume < 0,5 %) ; puis le STL doit correspondre au STEP relu depuis le disque (ou avec shape lorsquestep=False) : boîte englobante dans max(0,05 mm, 0,5 % de la plus grande taille de la pièce) par côté, volume dansagree_tol. Retourne le maillage trimesh. Chaque vérification échouée lèveh.GateError(une sous-classe d'AssertionError, levée explicitement pour quepython -One puisse pas la sauter), ce qui arrête l'exécution. Imprime une ligneexport ok:par fichier écrit, chemin complet avec extension, et une ligneexport check:avec les nombres de correspondance. La réparation automatique ferme les fissures de tessellation capillaire sur une B-rep valide ; elle ne fermera PAS une face manquante (voir « Réparer un maillage remis par l'utilisateur »). Le STL est maillé sur une copie fraîche (la forme reste non maillée), donc un maillage épinglé sur la forme en premier est abandonné : épinglez-le avecmesh=(deflection, angular)(mm absolu, rad ; les pièces fournisseur avec des faces effilées nécessitaient(0,05, 0,2), pièges).render6(shape, png_path, color="#b25563", tol=0.3): 6 vues ombrées canoniques (avant/arrière/gauche/droite/haut/avant-3/4) en un seul PNG. Un rendu hors écran VTK avec tampon de profondeur (le tri du peintre de matplotlib imitait la transparence sur les assemblages, pièges), projection parallèle, chaque vue cadrée sur la pièce ; un Workplane rend chaque Shape sur sa pile ;tolest la déflexion linéaire de la tessellation en mm (0,6 pour les grands assemblages).- `render_compare(shape, ref_image_path, p