Claude CodeでOpenSCADのモデルを作る — PNG書き出しで形状を確かめる反復
OpenSCADはコードで3Dモデルを書けます。CLIでPNGを書き出し、Claude Codeに画像を読ませて形を直させる検証ループと、視点・権限・CLAUDE.mdの設定をまとめます。
OpenSCADはモデルをGUIで描かず、コードで書く3D CADです。Claude Codeと相性が良いのは、成果物がテキストのファイルだからです。ただし、コードが文法として通っても、できた形が意図どおりとは限りません。穴が壁を貫いていない、蓋が浮いている、といったずれは、見なければ分かりません。
そこで、OpenSCADのコマンドラインでPNGを書き出し、その画像をClaude Codeに読ませます。形の確認までを自分の反復に組み込ませると、「書く、描く、見る、直す」がセッションの中で閉じます。この記事では、そのための書き出しオプション、複数視点のスクリプト、権限とCLAUDE.mdの書き方を順に扱います。
OpenSCADのCLIでPNGを書き出す
OpenSCADは、-oオプションで出力ファイルを指定すると、GUIを起動せずに.scadファイルを実行して書き出します。形式は拡張子で決まり、公式マニュアルの一覧にはstl、off、wrl、amf、3mf、csg、dxf、svg、pdf、png、echoなどが挙がっています。PNGの書き出しは2013.05以降の機能です。
最小の形は次のとおりです。
openscad -o out/iso.png --imgsize=800,600 bracket.scad--imgsizeは画像の幅と高さです。カメラは何も指定しなければ既定の位置になるため、形が画面に収まる保証はありません。後で触れる--viewallと--autocenterを組み合わせて、物体に合わせたカメラにします。
プレビューと完全レンダリングの違い
コマンドラインでPNGを出すとき、既定の描画はGUIのF5と同じプレビューモードで、OpenCSGを使います。ジオメトリを完全に評価してから描かせたいときは--renderを付けます。状況によってはCGALによるフルレンダリングが望ましい場面があります。
差し引き(difference())を重ねたモデルの最終確認には、--renderの画像を使う運用が考えられます。反復の途中は速いプレビュー、仕上げだけ完全レンダリング、という分け方です。完全評価の分だけ時間がかかるため、毎回の反復で回すかどうかは、手元のモデルの重さで決めます。
3Dレンダリングのバックエンドは、開発版(nightly)のヘルプに--backendが載っています。CGALが「old/slow」で既定、Manifoldが「new/fast」と書かれています。2021.01版のヘルプ一覧には--backendがありません。手元の版で使えるかは、openscad --helpで確かめます。
画像の見た目を決めるオプション
PNGの見た目を決めるオプションは次のとおりです。
| オプション | 役割 | 検証ループでの使いどころ |
|---|---|---|
--camera | 役割カメラ位置の指定 | 検証ループでの使いどころ視点を固定して毎回同じ角度で比べる |
--autocenter | 役割物体の中心を見るよう調整 | 検証ループでの使いどころ原点から外れた形でも画面中央に置く |
--viewall | 役割物体全体が収まるよう調整 | 検証ループでの使いどころ寸法を変えても見切れない |
--imgsize | 役割幅と高さの指定 | 検証ループでの使いどころ大きすぎる画像を避ける |
--projection | 役割正射影(o)か透視(p) | 検証ループでの使いどころ寸法比較は正射影、見た目の確認は透視 |
--view | 役割axes・scalesなど | 検証ループでの使いどころ軸と目盛りを描かせて大きさの手掛かりにする |
--colorscheme | 役割配色の指定 | 検証ループでの使いどころ面の境界が見分けやすい配色を選ぶ |
--cameraには2つの書式があります。1つはGUIの視点表示と同じ「gimbal」型で、translate_x,y,z,rot_x,y,z,distの7値です。もう1つは視点位置と注視点を与える「vector」型で、eye_x,y,z,center_x,y,zの6値です。--projectionはGUIと同様に正射影か透視かを選びます。
--viewは、2021.01版のヘルプでaxes、crosshairs、edges、scales、wireframeが並び、nightlyのヘルプではwireframeを除いた4つが並んでいます。軸と目盛りを描かせると、Claudeが画像から大きさの見当を付けやすくなります。寸法そのものは数値で確かめるので、目盛りはあくまで補助です。
--colorschemeは、Cornfield(既定)、Metallic、Sunset、Starnight、BeforeDawn、Nature、DeepOcean、Solarized、Tomorrow、Tomorrow Night、Monotoneなどから選べます。どれが読み取りやすいかは形と好みによります。複雑な形でうまく読めないときに切り替える程度で足ります。
複数の視点を一括で書き出すスクリプト
1枚の斜め視点だけでは、穴の貫通や裏側の欠けが見えません。上面、正面、側面、斜めの4枚を毎回書き出すスクリプトにして、Claudeにはそのスクリプトだけを呼ばせます。コマンドを毎回組み立てさせるより、視点が固定されて比較しやすくなります。
#!/bin/sh
# scripts/render.sh 使い方: scripts/render.sh bracket.scad
set -eu
SCAD="${1:?model.scad を指定してください}"
OPENSCAD="${OPENSCAD:-openscad}"
OUT="out"
mkdir -p "$OUT"
for v in iso:55,0,25 top:0,0,0 front:90,0,0 side:90,0,90; do
name="${v%%:*}"
rot="${v#*:}"
"$OPENSCAD" -o "$OUT/$name.png" --imgsize=800,600 \
--camera="0,0,0,$rot,500" --autocenter --viewall \
--view=axes,scales "$SCAD"
done視点の角度は例です。gimbal型の回転角が、手元のモデルで想定した「正面」や「側面」になるかは、最初の1回だけ画像で確かめます。向きが違っていたら、スクリプトのrotの値を入れ替えます。ここを最初に固めておくと、以降の反復で「どの面を見ているのか」をClaudeが取り違えません。
環境変数OPENSCADを設けたのは、macOSでバイナリの場所が違うためです。公式マニュアルによると、macOSではバイナリがアプリフォルダ内にあります。
OPENSCAD=/Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD \
scripts/render.sh bracket.scadシンボリックリンクでopenscadを呼べるようにする方法もあります。/usr/local/bin/openscadへのリンクを張る例があります。Windowsでは、コマンドラインからopenscad.comを呼びます。openscadと打つとこのラッパーが呼ばれ、openscad.exeのコンソール出力の問題を避ける作りです。
Claude Codeに画像を読ませて直させる
書き出したPNGは、Claude Codeにファイルパスを渡すだけで読ませられます。公式のワークフロー解説は、画像を渡す方法として、ウィンドウへのドラッグ、Ctrl+Vでの貼り付け、画像パスの指示を挙げています。スクリプトがout/に決まった名前で書き出すなら、パスを指示する方法がいちばん自動化に向きます。
頼み方の例を挙げます。
bracket.scad の穴の数と位置を直してください。
scripts/render.sh bracket.scad を実行し、out/top.png と out/iso.png を
読んで、次の点を確かめてください。
- 底板に穴が3つ、等間隔で並んでいるか
- 立ち上がりの壁が底板の長辺に沿っているか
合っていなければ .scad を直して、もう一度書き出してください。ポイントは、見てほしい観点を文章で渡すことです。「確認して」とだけ頼むと、画像から何を読めば良いかが決まらず、見た目の感想で終わりがちです。チェックリストにしておけば、反復のたびに同じ観点で合否が出ます。
画像では確かめにくいことは数値で見る
画像から読み取れるのは形の傾向です。壁の厚さが2.5mmか3mmか、といった寸法の確認は、画像に頼らないほうが確実です。確認の対象ごとに、手段を分けます。
| 確かめたいこと | 向いている手段 | 補足 |
|---|---|---|
| 穴・凸部の有無や位置関係 | 向いている手段複数視点のPNG | 補足正射影にすると比較しやすい |
| 全体の大きさ | 向いている手段--summary=bounding-box | 補足結果は--summary-fileでJSONに出せる |
| パラメータの値そのもの | 向いている手段echo()を.echoに書き出す | 補足拡張子.echoで出力 |
| 警告が出ていないか | 向いている手段--hardwarnings | 補足最初の警告で停止する |
| 印刷用の最終形状 | 向いている手段STLの書き出し | 補足CLIの既定はASCII STL |
--summaryは、all、cache、time、camera、geometry、bounding-box、areaから選べるオプションです。--summary-fileは、サマリーをJSONで指定ファイルに書き、-を指定すると標準出力に出します。モデルの外形寸法を数値で確かめたいときは、この出力をClaudeに読ませます。
echo()の出力は、拡張子を.echoにした出力ファイルへ集められます。2015.03-2以降は、GUIのコンソールに出る内容と同じものがファイルに入ります。.scadの末尾に主要な寸法をecho()しておき、-o check.echoで書き出せば、寸法の確認がテキストで済みます。ただしこの方法では、同時にモデル本体を出力できません。
-oは複数回指定でき、1回の実行で別形式を同時に書き出せます。STLとPNGを同時に出す、という使い方です。3Dプリンター向けのSTLについては、CLIの既定がASCII形式なので、スクリプトでは--export-format asciistlと明示する選択肢があります。将来の既定がバイナリに変わる予定があるためです。
検証ループをClaude Codeの設定に落とす
毎回口頭で手順を説明するのは手間です。CLAUDE.mdとpermissionsに書いて、セッションの初めから同じ前提で動かします。
CLAUDE.mdに書く規約
CLAUDE.mdはClaudeが読む文脈で、強制力のある設定ではありません。だからこそ、コマンドと確認観点を具体的に書きます。次は.scadを扱うリポジトリ向けの断片です。
## OpenSCAD 規約
- .scad を変更したら必ず `scripts/render.sh <file>` を実行する
- out/top.png と out/iso.png を読み、依頼された観点を1つずつ確認する
- 寸法は画像でなく `--summary=bounding-box` と echo() の出力で確認する
- パラメータはファイル先頭の変数にまとめ、数値を直書きしない
- モジュール名は部品の名前にする(例: `bracket_base`, `hole_row`)
- 確認が済むまで STL は書き出さない「数値を先頭の変数にまとめる」は、OpenSCADの-Dオプションと相性が良い規約です。-D var=valで変数を実行時に上書きできるため、同じ.scadから寸法違いのPNGやSTLを作れます。文字列を渡すときのクォートはシェルによって異なるので、マニュアルの例に合わせます。
permissionsで承認の手間を減らす
反復のたびに承認を求められると、ループが止まります。繰り返し実行するコマンドだけを、許可ルールに入れます。ルールの書き方は、許可したいコマンドをそのまま書き、変わる部分を*にします。
{
"permissions": {
"allow": [
"Bash(scripts/render.sh *)",
"Bash(openscad *)"
]
}
}末尾に空白付きの*を置いたルールは、引数のない素のコマンドにも一致します。一方、Bash(openscad *)は、バイナリをopenscadという名前で呼んだ場合の書き方です。macOSでアプリ内のバイナリを絶対パスで呼ぶなら、そのパスで書きます。権限ルールの全体像は/permissionsコマンドの解説にまとめています。
Bash(openscad *)は、任意の引数を許すルールです。-oで書き込み先を自由に指定できるため、範囲を絞りたいなら、書き出し先を固定したスクリプト1本だけを許可する形のほうが安全です。
反復の組み立てと、つまずきやすい点
ここまでの部品を並べると、1回の反復は次の流れになります。
- Claudeが.scadを書く、または直す
scripts/render.shで4視点のPNGを書き出す- 観点のチェックリストに沿って画像を読む
- 寸法は
--summaryやechoの出力で確かめる - 合っていなければ1に戻る。合っていれば、
--renderの画像とSTLを最終出力にする
コンパイラの出力を読ませて直す流れは、他の言語でも同じ型です。たとえばRustなら、cargo checkとclippyを回す反復がそれに当たります。OpenSCADでは、コンパイラの代わりに「描いた画像」が検査の出力になる点が違います。
つまずきやすい点を挙げます。
- macOSで起動に失敗する: 一部のmacOSでは、リンク経由の起動時にQtプラットフォームプラグイン
cocoaが見つからないというエラーが出ます。バイナリを直接呼ぶラッパースクリプトを作る対処があります - 複雑なモデルでPNGが遅い:
--renderは完全評価の分だけ時間がかかります。反復の途中はプレビューのまま回し、--csglimitでCSG要素の数に上限を付ける手もあります - 画像が大きすぎて読めない:
--imgsizeを大きくしすぎると、Claude Code側で画像の寸法上限に当たることがあります。上限の仕組みはImage was too largeの解説にあります。反復用には800×600程度から始めます - -Dで文字列を渡せない: 二重引用符のエスケープはシェルごとに違います。シェルを介さずプロセスを起動する場合は、引数ごとに分けて渡せます
- 視点が想定と違う: 最初に1枚ずつ見て、正面や側面の向きをスクリプトに固定します
PNGを成果物そのものとして作るなら、スキルで画像を描かせる方法もあります。canvas-designスキルでポスターを作る手順では、デザインの確認を画像で回す別の型を扱っています。OpenSCADでは、形状を数値と画像の両方で追えます。
画像・数値・警告の3系統で検証を分担する
検証の手段は、画像、数値、警告の3系統に分けると役割が重なりません。画像は「形がそれらしいか」を見る目、--summaryとechoは「寸法が合っているか」を測る定規、--hardwarningsは「文法上の取りこぼしがないか」を見る関所です。Claudeに画像を読ませる工程は、この3つのうち最初の1つを自動化したものにあたります。
画像の確認は、複数の視点と固定されたチェックリストが揃って初めて機能します。視点が毎回変わると、前回との差を見分けられません。観点が曖昧だと、合格の基準が揺れます。反復の本体はスクリプトとチェックリストの側にあり、Claudeはそれを回す役です。この分担にしておけば、モデルの形が複雑になっても、確認の手順は変わりません。