abchiaravalle/cad-studio-renders

CADスタジオレンダリング

CADアセンブリからプロダクトページに必要なアセット（フォトリアリスティックなスタジオショット、透明カットアウト、ターンテーブル動画、自己ホスト型3Dビューア）を生成します。全工程が1つのコマンドで完了し、すべてローカルで動作します。GPUがレンダリングを行い、AI画像生成は使用しないため、ピクセルは実際のジオメトリに基づきます。

python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --name "製品名"

${CLAUDE_SKILL_DIR} はこのスキルのフォルダ（Claude Codeが自動入力）です。他のエージェントでは、この SKILL.md が存在するフォルダを使用してください。以下のスクリプトパスはすべてそのフォルダからの相対パスです。

使用するタイミング

• 「このSTEPファイルをレンダリングして」「CADからプロダクトショット/パックショットを作って」「このパーツをフォトリアルにレンダリングして」
• 「この3Dモデルをウェブサイトに載せて」「回転可能にして」「製品のARビューを」
• 「製品の透明PNGを」「カタログ用のカットアウトを」「ターンテーブル動画を」
• 3Dアーティストが手仕上げ用の編集可能なBlenderシーンを欲している

このスキルが対象外: ゼロからのパーツモデリング（CADツールを使用）、テキストプロンプトからの画像生成、製品以外のシーン（インテリア、キャラクター）のレンダリング。

このスキルのインストール方法

• Claude Code（ターミナル）: claude plugin install cad-studio-renders --marketplace abchiaravalle/cad-studio-renders
• Claude Code（デスクトップアプリ）: Claudeに https://github.com/abchiaravalle/cad-studio-renders を ~/.claude/skills/cad-studio-renders にクローンするよう依頼（デスクトップアプリとターミナルは両方ともそのフォルダを参照します）。
• その他のエージェント: このフォルダを、そのエージェントが SKILL.md フォルダを読み込む場所に配置してください。

必要条件（事前確認）

blender --version       # 4.2以上。ない場合: https://www.blender.org/download/
uv --version            # CADファイルを読み込みます。ない場合: https://docs.astral.sh/uv/
ffmpeg -version         # --turntable 動画にのみ必要

Blenderがインストール済みだがPATHにない場合、BLENDER=/path/to/blender を設定してください。GPU（Apple Silicon、NVIDIA、AMD）を使用するとレンダリングが5〜20倍高速になります。CPUでも動作しますが低速です。初回実行時、CADライブラリ（約60MB）とスタジオHDRI（24MB、CC0）が ~/.cache/cad-studio-renders/ にダウンロードされます。

ワークフロー

1. レンダリング前にマテリアルをマッピングする。 CADファイルに実際の仕上げが含まれていることはほとんどありません。

   python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --map-only
   

   テーブルを確認してください。すべてのパーツにプリセットと理由が表示されます。（要確認） で終わる行は推測値です。間違っているものはルールファイル（次のセクション）で修正し、正しくなるまで --map-only を再実行してください。
2. プレビュー（約10秒）: --preview で1000pxのドラフトをレンダリングします。最終版に時間をかける前に確認してください。確認項目: 正しい向き、パーツが組み立てられている（浮いていない）、フレーミング、マテリアル。
3. 最終版: --preview を外します。デフォルトでは、背景上の2400pxのヒーローショット、同じショットの透明PNG、編集可能な .blend、Web埋め込みパッケージが生成されます。
4. 出力をフルサイズで確認する（最も密集した領域をズームイン）前に、引き渡さないでください。

マテリアルの修正: ルールファイル

{"rules": [
  {"match": "frame|base",    "preset": "powder_coat",  "color": "#2b2f33"},
  {"match": "^Cover",        "preset": "plastic_textured"},
  {"match": "motor",         "preset": "motor_housing"},
  {"match": "logo plate",    "preset": "anodised_color", "color": "#c8102e"},
  {"match": "spindle",       "preset": "steel_polished", "params": {"roughness": 0.05}},
  {"match": "safety guard",  "hide": true},
  {"match": "gantry",        "offset_mm": [0, 0, 80]}
]}

match は、パーツ名、インスタンス名、アセンブリパスに対してテストされる大文字小文字を区別しない正規表現です。最初に一致したルールが優先されます。params はプリセットの値を上書きします（粗さ、金属度、コート、異方性、ベベル、バンプなど）。offset_mm は爆発図でのそのパーツの位置を設定します。プリセットは assets/presets/materials.json にあります。新しいプリセットはそこに追加してください。

ルールがない場合、自動マッパーは次の順序で使用します: パーツ名のキーワード（ファスナー、ベアリング、リニアレール、ボールねじ、モーター、ゴム、ガラス...）、次にCAD色（彩度の高い色は塗装に、同じ色を共有するパーツは同じ仕上げに）、次にサイズ。

重要なオプション

フラグ	機能
--shots hero,front,side,top,iso,back,square,hero_low,detail	カメラアングル（assets/presets/shots.json）
--lighting studio_soft / high_key / dramatic / hdri_only	照明設定（assets/presets/lighting.json）
--backdrop 0.42 または --backdrop "#1d1f22"	背景のグレーまたは色
--size 4000 --aspect 16:9	出力サイズとアスペクト比
--samples 768	サンプル数が多いほど、光沢のある詳細がきれいに、レンダリング時間が長くなります
--exposure 0.3, --light-scale 1.2, --env-scale 0.8	明るさ
--hdri photo_studio_01 または --hdri my.exr, --hdri-rotation 40	反射環境
--dof 0 / --dof 2	背景ぼかしオフ / 弱め
--bevel-scale 0	エッジの丸めをオフ（丸めがCADをリアルに見せる要素です）
`--detail-target "spindle	chuck"と--shots detail`
--no-transparent, --no-backdrop, --no-embed, --no-blend	特定の成果物をスキップ
--clay	グレーのクレイパス（照明/形状確認、デザインレビュー用）
--passes	マルチレイヤーEXR: 深度、法線、アンビエントオクルージョン、ミスト、クリプトマット（オブジェクト＋マテリアルID）
--exploded 0.4	爆発図（パーツを中心から押し出し、offset_mm ルールが優先）
--turntable [--turntable-transparent]	360° MP4 + WebM（アルファオプション）+ PNGフレーム
--up y	自動検出が間違っている場合、アップ軸を強制

生成されるもの

<モデル名>_studio/
  hero.png                    16ビット、スタジオ背景上
  hero_transparent.png        16ビットRGBA、ソフトな接触影を保持（--shadow none で削除）
  hero_clay.png, hero_exploded.png, hero_passes.exr       （指定時）
  <スラグ>_turntable.mp4 / .webm, turntable_frames/          （指定時）
  <スラグ>_scene.blend          ライト、カメラ、マテリアル、背景、テクスチャをバンドル
  materials_map.json          すべてのパーツ -> プリセット + 理由（--rules で編集して再実行可能）
  manifest.json               設定、タイミング、サイズとハッシュ付きファイルリスト
  embed/                      自己ホスト型3Dビューアパッケージ（以下参照）

.blend は手仕上げ用に構築されています。 コレクション: Product（パーツごとに1つのエンプティ。個別に移動やアニメーションが可能）と Studio（背景、ライト、カメラ）。各カメラはタイムラインマーカーにバインドされているため、タイムラインをスクラブするとショットが切り替わります。マテリアルはプレーンなPrincipled BSDFノードツリーです。エッジの丸めはベベルシェーダーノードで行われるため、ジオメトリは正確なままです。

埋め込みパッケージ

embed/ は完全に静的で、外部リクエストを一切行いません。Google <model-viewer>（Apache-2.0）とDracoデコーダをバンドルしています。フォルダを任意の場所にアップロードし、snippet.html を貼り付けるか、embed.html をiframeで埋め込んでください。含まれるもの:

• assets/<スラグ>.glb: Draco圧縮、レンダリングに合わせたマテリアル
• assets/<スラグ>.usdz: Quick LookによるiPhone/iPad AR
• ポスター画像
• スタジオHDRI（反射用）
• index.html: コピーボタンとレンダリングダウンロード付きデモページ

WordPress、Shopify、Webflowなどに関するホスティングの注意点は embed/README.md にあります。

落とし穴（開発中にそれぞれ遭遇した問題）

• モデルが横向きまたは上下逆さま。 SolidWorks、Inventor、Creo、FusionはデフォルトでY-up。その他はほとんどがZ-up。コンバーターはSTEPヘッダーを読み取って推測し、推測値を出力します（up axis: Y (written by Solidworks)）。間違っている場合は、--up z（または y、-y、x...）を渡してください。
• パーツが離れてしまう／「意図せず爆発図になる」。 原因はアセンブリ変換が2回適用されたことです。シーンビルダーは、グループ化パーツがジオメトリを移動させないことをチェックし、移動する場合は中断するようになりました。シーンコードを編集する場合は、そのチェックを維持してください。
• フラットで偽物のように見える金属。 通常はマテリアルではなく照明が原因です。環境がないと金属が反射するものがありません。エリアライトと併用してもHDRIをオンのままにしておいてください（--env-scale を0にしない）。
• 最初のレンダリングが白飛びする。 ライトのパワーはモデルのサイズに合わせてスケーリングされます。lighting.json でカスタムライトを追加する場合、パワーは（モデル半径（メートル））の2乗あたりです。低い値から始めて --preview を使用してください。
• マテリアルの推測が間違っている。 難解なパーツ名（P-0042、ASSY_7_REV2、翻字された非英語名）はキーワードマッチングを無効にし、色/サイズにフォールバックします。それが （要確認） フラグの目的です。それらのパーツにはルールを作成してください。
• OCP 8 がリーダーを壊した（TDF_LabelSequence が移動）。CADリーダーは cadquery-ocp-novtk<8 を固定しています。再テストなしで固定を解除しないでください。
• Webモデルがレンダリングと異なって見える。 glTFはプロシージャルバンプ、ベベル、粗さノイズを保持できないため、Webモデルはベース値のみを取得します。これは仕様です。ポスター画像は実際のレンダリングです。
• 巨大なアセンブリ（500万トライアングル超）: プレビューには --quality web を使用してください。最終レンダリングは動作しますが、RAMが必要です（Blenderで200万トライアングルあたり約1GB）。

引き渡し前の確認

1. ヒーローPNGを100％で開き、最も密集した領域を検査する: 黒い面がない、曲線にファセットがない、ノイズ（白い斑点）がない。
2. 透明PNGを暗い背景と明るい背景の上で開く: エッジがきれい、影は製品の下のみ。
3. embed/ をローカルで提供し（python3 -m http.server -d embed 8000）、開いてモデルが読み込まれ、回転し、コンソールエラーがないことを確認する。ARが重要な場合はスマートフォンで確認する。
4. materials_map.json にまだ 要確認 の行がある場合は、引き渡し時にその旨を伝える。

ファイル

• scripts/studio.py: エントリーポイント（上のCLI）
• scripts/cad_to_glb.py: STEP/IGES/BREPをアセンブリ名とCAD色付きのglTFに変換（uvスクリプト）
• scripts/automap.py: パーツからマテリアルへの決定（純粋Python、単独実行可能）
• scripts/blender_studio.py: シーン、マテリアル、ライト、カメラ、レンダリング、.blend、Web出力
• scripts/package_embed.py: 自己ホスト型ビューアパッケージ
• assets/presets/*.json: マテリアル、照明設定、カメラショット
• examples/make_demo_model.py: デモ用のベンチバイスを構築（オリジナルジオメトリ、CC0）