lab-hardware-cad

ラボ用ハードウェア CAD

物理的な研究用ハードウェアをパラメトリックな Python ソースとして設計し、STEP を正式な成果物としてエクスポートし、製作に進む前に数値と視覚の両方で結果を検証します。

ラボ用ハードウェアの難しさは、ほとんどの場合、形状そのものではありません。公開規格やベンダーの図面で寸法が固定されている機器に、その部品を適合させる必要があることです。幅が 0.5 mm 大きいホルダーはプレートリーダーに取り付けられません。アスペクト比が間違った流路は接合時に潰れます。ボルトパターンが 25.0 mm ではなく 25.4 mm のマウントは、光学テーブルに届きません。このスキルは、こうした数値を正確に保ち、確認するためのものです。

使用する場面

チップ、モールド、マウント、アダプター、ホルダー、ラック、ブラケット、筐体、治具、固定具、アリーナ、迷路など、ラボ用の物理部品の設計、モデリング、製作を依頼された場合に使用します。既存の STEP ファイルを検査または変更する場合にも使用します。

有限要素解析、数値流体力学、分子構造、科学的なプロットには使用しないでください。それらには別のスキルを使用します。

セットアップ

uv venv --python 3.12 .venv-labcad
uv pip install --python .venv-labcad/bin/python "build123d==0.11.1" "matplotlib>=3.8"

build123d 0.11.1 には Python >=3.10,<3.15 が必要で、cadquery-ocp-novtk を介して OpenCascade カーネルを導入します。ホイールのサイズは大きいため、プロジェクトごとに一度インストールし、再利用してください。

同梱されているすべてのスクリプトで --help を使用できます。check.py standards は build123d をインストールしていなくても実行できます。

モデルファイルは解析されるのではなく、実行されます。 gen.py、check.py、snapshot.py は *_model.py をインポートして、その build() を呼び出します。これにより、現在の環境で任意の Python コードが実行されます。これはパラメトリック CAD の性質上避けられません。ソースが設計そのものだからです。このセッションで作成したモデルファイルか、信頼できる場所からユーザーが提供したモデルファイルのみを実行してください。モデルがインターネット、共有ドライブ、または信頼できない同僚から提供された場合は、実行前に内容を読み、そのことを伝えてください。

必須のワークフロー

次の手順を順番に実行してください。手順 5 と 6 は省略できません。また、手順 5 に合格しても手順 6 は省略できません。

1. デバイスファミリーに振り分ける

依頼を読み、分類して、ファミリーリファレンスを必ず 1 つだけ読み込みます。4 つすべてを読み込まないでください。内容が長いうえ、ファミリー間の慣習を混同することはよくあるエラーの原因です。

部品の種類	読み込むリファレンス
チップ、モールド、流路ネットワーク、フローセル、ガスケット、または流体ポートを備えたもの	references/microfluidics.md
光路内のマウント、ポスト、ブレッドボードアダプター、ケージシステム部品、フィルター、またはサンプルホルダー	references/optomechanics.md
プレート、キュベット、チューブ、スライド、またはディッシュ用のアダプター、インサート、ラック、またはホルダー	references/labware-adapters.md
動物実験用のアリーナ、迷路、頭部固定部品、スパウト、テザー、または押出材に取り付ける筐体	references/behavior-rigs.md

部品が実際に 2 つのファミリーにまたがる場合（光学テーブルにボルトで取り付けるマイクロ流体チップなど）は、重要なインターフェースを担当するファミリーを読み込み、2 つ目のファミリーからはインターフェースのセクションのみを読んでください。回答では、どのファミリーに振り分けたかを明記してください。

2. ジオメトリに取りかかる前に、インターフェースの寸法を確定する

各部品には、少なくとも1つの嵌合インターフェースがあります。コードを書く前に、各インターフェースについて次の項目を書き出してください。

• 寸法の出典：公開規格、ベンダー図面、またはユーザーによる測定値
• 公称値と公差
• 意図するクリアランスまたはしまりばめと、その理由

assets/standards.jsonまたはファミリーのリファレンスで数値を確認してください。**インターフェース寸法を記憶に頼って記述してはいけません。**数値が規格ファイルにもリファレンスにもない場合は、推測せず、ベンダー図面または測定値をユーザーに求めてください。推測によるインターフェース寸法は、このスキルで最もコストの高い失敗要因です。

標準化された部品を受け入れる必要があるフィーチャーは、その部品の最大実体状態、つまり公称値にプラス公差を加えた値を基準に寸法を決め、その後でクリアランスを加えます。公称値を基準に寸法を決めると、規格に適合する部品のうち、小さいものにしか適合しません。

python scripts/check.py standards --list
python scripts/check.py standards --show slas-microplate-footprint

同梱されている規格ID（文字列は完全一致。バリエーションを推測しないでください）：slas-microplate-footprint、slas-microplate-height、slas-microplate-flange、slas-well-positions-96、slas-well-positions-384、slas-well-positions-1536、cuvette-standard-10mm、optical-breadboard-metric、optical-breadboard-imperial、cage-system-30mm、sm1-lens-tube-thread。

部品がこのリスト内のどの規格とも嵌合しないことはよくありますし、問題ありません。インターフェースはないと明記し、すべてのインターフェース寸法の出典（ユーザー仕様、ベンダー図面、測定値）をレポートで未確認としてください。空欄を埋めるために無関係な規格を根拠として申告してはいけません。事実を偽って申告するより、「誰も確認していない」と正直に記載するほうがよいでしょう。

3. ジオメトリを選ぶ前に、製造プロセスを選ぶ

references/fabrication-limits.mdを読んでください。プロセスによって、最小肉厚、最小フィーチャー、実現可能な公差、および部品がオートクレーブ処理や使用する溶剤との接触に耐えられるかどうかが決まります。FDMでは±0.05 mmの公差を維持できません。SLA樹脂は、後硬化と試験を行わない限り、一般に細胞との接触には安全ではありません。モデルのドックストリングにプロセスと材料を記録してください。

4. パラメトリックモデルを作成する

<part>_model.py を作成します。ソースが正式な成果物です。エクスポートした STEP ファイルを手動で編集してはいけません。また、メッシュから再生成してはいけません。

要件：

• ユーザーが変更する可能性のある寸法はすべて、単位を名前に含めたモジュールレベルの名前付き定数にします：bore_d_mm、wall_t_mm、post_h_mm。本体で数値を直接記述できるのは 0、1、2 のみです。
• build() -> Part を公開します。これを gen.py が呼び出します。
• パラメーターを INTERFACE ブロック（規格で定められた寸法。規格 ID を注記）と DESIGN ブロック（自由に決められる寸法）に分けます。
• 計算される寸法はすべて関数内で導出し、モジュールレベルでは導出しません。これにより、--param によるオーバーライドが確実に反映されます。
• 部品が適合しなければならない寸法を返す interfaces() 関数を宣言します。各寸法には規格 ID と意図を含めます。これにより、ステップ 5 でインターフェースを機械的に検査できます。intent は、適合する部品を受け入れる必要がある場合（ポケット、穴、スロット。最大実体状態にクリアランスを加えた片側条件で検査）には "envelope"、この部品自体が適合しなければならない場合（対称な公差帯）には "match" とします。clearance は意図する合計クリアランスを mm 単位で指定し、0 以上でなければなりません。この部品の嵌合部を制約する寸法のみを宣言します。嵌合する機器の特性（テーブルの縁の枠、一般的なプレート厚など）は、この部品のインターフェースではありません。該当する規格が同梱されていない場合は [] を返します。
• 組み立てたソリッドから測定する合否ゲージを返す checks() 関数を宣言します。通過または収まる必要があるもの（ねじ軸、ビームの通路、ポケットに入る最大実体状態の嵌合部品）には clear 領域、残る必要があるもの（リッジ、段、ねじ座面）には material 領域を指定し、ユーザーが指定したサイズ制限ごとに bbox_* の境界を指定します。依頼に含まれるすべての幾何学的要件を、それぞれ 1 つのエントリーに対応付けます。これらの検査で、is_valid、バウンディングボックス、宣言された寸法だけでは検出できないエラーを捕捉します。gen.py は生成のたびに検査を実行し、1 つでも失敗すればビルドを失敗させます。スキーマと実例については references/build123d-patterns.md を参照してください。
• プロセス、材料、すべてのインターフェースの出典をモジュールの docstring に記載します。

"""SLAS microplate carrier for a custom stage insert.

Process: FDM, PETG, 0.2 mm layer.  Tolerance budget +/-0.3 mm.
Interfaces:
  - Plate pocket: ANSI/SLAS 1-2004 (R2012) footprint 127.76 x 85.48 mm, +/-0.25.
  - Stage bolts: user-measured, 40.0 mm centres (drawing in docs/stage.pdf).
"""
from build123d import *

# --- INTERFACE (fixed by standard; do not tune) ---
plate_l_mm = 127.76   # ANSI/SLAS 1-2004 nominal
plate_w_mm = 85.48    # ANSI/SLAS 1-2004 nominal
plate_tol_mm = 0.25   # ANSI/SLAS 1-2004; the pocket is sized to nominal + this
# --- DESIGN (free) ---
pocket_clearance_mm = 0.40   # per-side; FDM, see fabrication-limits.md
wall_t_mm = 3.0
floor_t_mm = 2.5
body_h_mm = 12.0


def pocket_mm() -> tuple[float, float]:
    """Pocket at the plate's maximum material condition plus clearance per side.

    A pocket sized from nominal jams on roughly half of conforming plates.
    """
    growth = plate_tol_mm + 2 * pocket_clearance_mm
    return plate_l_mm + growth, plate_w_mm + growth


def interfaces() -> list[dict]:
    """What this part must fit. `check.py interfaces` verifies every entry."""
    pocket_l, pocket_w = pocket_mm()
    return [
        {"feature": "plate pocket length", "standard": "slas-microplate-footprint",
         "dimension": "footprint_length", "value": pocket_l,
         "intent": "envelope", "clearance": 2 * pocket_clearance_mm},
        {"feature": "plate pocket width", "standard": "slas-microplate-footprint",
         "dimension": "footprint_width", "value": pocket_w,
         "intent": "envelope", "clearance": 2 * pocket_clearance_mm},
    ]


def checks() -> list[dict]:
    """Gauges measured from the built solid. Sized from the REQUIREMENT's numbers
    (plate MMC, the user's height limit), not from the pocket parameters, so a
    wrong parameter cannot shrink the gauge to match the wrong geometry."""
    depth = body_h_mm - floor_t_mm
    return [
        {"feature": "plate at MMC drops into the pocket",
         "clear": {"box": (plate_l_mm + plate_tol_mm, plate_w_mm + plate_tol_mm, depth),
                   "at": [(0.0, 0.0, floor_t_mm + depth / 2)]}},
        {"feature": "under 15 mm for the stage", "bbox_z": {"max": 15.0}},
    ]


def build() -> Part:
    pocket_l, pocket_w = pocket_mm()
    with BuildPart() as carrier:
        Box(pocket_l + 2 * wall_t_mm, pocket_w + 2 * wall_t_mm, body_h_mm,
            align=(Align.CENTER, Align.CENTER, Align.MIN))
        with Locations((0, 0, floor_t_mm)):
            Box(pocket_l, pocket_w, body_h_mm, mode=Mode.SUBTRACT,
                align=(Align.CENTER, Align.CENTER, Align.MIN))
    return carrier.part

ビルダー方式と代数方式の選択、interfaces() の契約、スケッチ、セレクター、フィレット、ねじインサート用の穴については、references/build123d-patterns.md を参照してください。

5. 生成してチェックを実行する

python scripts/gen.py carrier_model.py --outdir out/
python scripts/check.py facts out/carrier.step
python scripts/check.py interfaces out/carrier.manifest.json
python scripts/check.py geometry out/carrier.step --model carrier_model.py

gen.pyは、作成したソリッドに対してモデルのchecks()ゲージも評価し、各項目のPASS／FAILを出力してマニフェストに記録し、失敗があればゼロ以外の終了コードを返します。これにより、宣言した形状に違反する部品が、気付かれないまま成果物になることはありません。check.py geometryを実行すると、正式な成果物であるエクスポート済みSTEPに対して同じゲージを再実行します。

out/は一時出力先として使う慣例であり、必須ではありません。ユーザーが特定の場所への納品を依頼した場合は、そこに生成する（--outdir .）か、完了前にSTEP、マニフェスト、DXFをその場所へコピーしてください。out/内にしか存在しない成果物は、納品されたことになりません。

gen.pyは、carrier.step（正式な成果物）、carrier.stl（メッシュプレビューおよび印刷用）、そしてソースハッシュ、解決済みパラメーター、宣言済みインターフェース、ライブラリのバージョン、測定したバウンディングボックス、体積、有効性を記録したcarrier.manifest.jsonを書き出します。マニフェストは来歴の記録です。成果物と一緒に保管してください。

check.py factsは、is_valid、バウンディングボックス、体積、表面積、重心、ソリッド数を報告します。is_valid: falseと報告された部品は形状が壊れています。先に進む前にソースを修正してください。

check.py interfacesは、モデルが宣言した各項目を標準データベースに照らして評価し、失敗時にはゼロ以外の終了コードを返します。**何を検証し、何を検証しないかを明確にしてください。**チェック対象は宣言された数値であり、寸法の転記ミス、誤った規格、MMCではなく公称寸法を使っている場合を検出します。しかし、作成した形状を測定することはありません。また、チェック対象と同じ定数から計算した値は、構造上、余裕がゼロでも合格します。形状が正しいことの根拠としてこれを挙げないでください。形状のチェックにはfactsとスナップショットを使用します。宣言リストが空でも合格します。同梱データベースに適合する相手部品がない場合、宣言するものはありません。その場合、インターフェースの寸法はレポートで未チェックとして明記されます。

内部形状――ポケット、穴、スロットなど――を確認する場合は、check.py fitではなくinterfacesを使ってください。内部形状は部品の外形バウンディングボックスには現れず、fitが測定するのはそのバウンディングボックスです。fitを使うのは、1つの数値を手動でチェックする場合（--value footprint_length=128.81）や、部品自体の外形がインターフェースである場合、たとえばプレートの外形に合わせて切り出すガスケットを確認する場合に限ってください。

アセンブリでは、部品同士が干渉していないことを確認します。

python scripts/check.py clearance out/carrier.step out/lid.step --min 0.3

6. スナップショットを撮り、実際に確認する

python scripts/snapshot.py out/carrier.step --out out/carrier.png

その後、PNGを確認してください。生成のたび、また変更のたびに、この手順を必ず実施してください。決定論的なチェックに合格していても、省略してよい理由にはなりません。is_validと正しいバウンディングボックスは、ポケットが誤った面に切られている、ボスが本体の外に配置されている、フィレットがフィーチャーを削ってしまっている、といった状態と両立します。こうしたミスは画像では明白でも、数値には現れません。

レンダリングの限界も把握してください。フレームに対して非常に小さいフィーチャー――40 mmの部品にある0.3 mmのモールドリッジや、プレートの座ぐり段差など――は、どのビューからも判断できない場合があります。画像で解像できないものを見たと報告してはいけません。確認しないよりも悪いことです。こうしたフィーチャーを確認するためのツールが用意されています。check.py boresはすべての円筒面（直径、軸、位置、範囲、掃引角度）を出力するため、モデルの意図と照らし合わせて穴加工を確認できます。また、check.py probeを使えばモデルを編集せずに、「この領域に障害物がないか／ここに材料があるか」という一度限りの確認ができます。測定値を明記し、画像から報告するのは、実際に画像で確認できることだけにしてください。

6つのビューは正投影で、輪郭線はモデルの実際のエッジを隠線消去せずに描いたものです。そのため、材料の「向こう側」に見える円は、反対側にある穴であり、窓ではありません。部品が透明なのではありません。そこにない穴を報告しないよう、この点を踏まえて読み取ってください。

スナップショットを生成したと伝えるだけでなく、確認した内容を回答に記載してください。

7. ソースを修正する

いずれかのチェックに失敗した場合は、パラメーターまたはモデルコードを編集し、gen.py を再実行して、手順 5 と手順 6 の両方を再実行してください。STEP を直接修正してはいけません。

8. 製作前に報告する

references/validation.md を確認し、ユーザーに次の情報を伝えてください。製作工程と材料、インターフェース寸法すべてとその根拠および公差、選択したクリアランス、スナップショットで確認できた内容、合格しなかったチェック。

自動チェックで確認できなかったインターフェース（メーカーの図面、ユーザーによる測定、同梱データベースにない規格など）は、すべて明示してください。check.py interfaces が報告するのは、モデルで宣言され、既知の規格に照らして確認された内容だけです。何も報告されないからといって、問題がないことの確認にはなりません。確認できなかった寸法は、確認できなかったものとして明記する必要があります。

単位

build123d は内部で単位を扱わず、このスキルではすべてミリメートルと度を使用します。export_step は Unit.MM を指定して呼び出します。光学機器ではインチ規格のハードウェア（1/4-20 ネジ、1 インチグリッド、SM1 ねじなど）が広く使われます。定義箇所で単位変換を単一の名前付き定数にまとめ、式の中で異なる単位系を混在させないでください。1 インチは正確に 25.4 mm であり、25 mm のメートル法光学グリッドは、1 インチのインチ規格グリッドと互換ではありません。4 つの穴では誤差が 1.6 mm に達します。

公差と嵌め合い

公称寸法だけでは嵌め合いは決まりません。嵌め合う寸法にはすべて、references/fabrication-limits.md の製造公差に基づいて、意図的にクリアランスを設定する必要があります。一般的な初期値（片側あたり）は次のとおりです。

嵌め合い	FDM	SLA	CNC
自由に滑る（ポケット内のプレート）	0.40 mm	0.20 mm	0.10 mm
位置決めされ、取り外し可能	0.25 mm	0.10 mm	0.05 mm
圧入／締まり嵌め	-0.05 mm	-0.03 mm	-0.02 mm

これらは初回試作の出発点であり、保証値ではありません。報告時にはその旨を伝え、部品全体の製作に進む前に、重要なインターフェースのテストクーポンを印刷することを推奨してください。

科学的な注意事項

• 材料の適合性が最優先です。 幾何学的に完璧な部品でも、ポリマーが適切でなければ使用中に不具合が生じます。PLA はオートクレーブ処理で変形し、多くの溶剤はアクリルにクレージングを生じさせ、未硬化の SLA 樹脂には細胞毒性があります。細胞、組織、溶剤、または熱に接触するものに材料を推奨する前に、references/fabrication-limits.md を確認してください。
• 光学部品には幾何形状以外の要件があります。 自家蛍光、表面粗さ、迷光散乱は STEP ファイルでは確認できません。黒い樹脂だからといって、散乱が少ないとは限りません。
• メーカーによってラボウェアは異なります。 SLAS 規格で定められているのはプレートの外形寸法であり、ウェル形状、スカート形状、蓋の適合性は定められていません。また、消耗品のチューブもサプライヤーによって異なります。規格がある場合はそれに合わせて設計し、規格がない場合は測定値を必ず確認してください。
• 外接直方体のチェックに合格しても、部品として合格したことにはなりません。 fit は与えられた寸法をチェックします。欠けた形状は検出できず、スナップショットの代わりにもなりません。

参考資料

ファイル	内容
references/microfluidics.md	チャネル断面とアスペクト比、モールドとチップの極性、製造工程ごとの最小形状、ポートおよびチューブのインターフェース、接合面、デッドボリューム
references/optomechanics.md	ブレッドボードのグリッドとネジのクリアランス、ポストとペデスタルの高さ、30 mm ケージ形状、SM レンズチューブのねじ、ビーム高
references/labware-adapters.md	ANSI/SLAS 1-4 マイクロプレートの寸法、キュベット、チューブ、スライド、ディッシュ、デッキおよびステージの制約
references/behavior-rigs.md	アリーナと迷路の形状、頭部固定インターフェース、注水口とポート、T スロット押出材、洗浄と耐久性
references/fabrication-limits.md	製造公差、最小壁厚と最小形状、クリアランスとねじインサート、材料、オートクレーブ処理、溶剤、生体適合性
references/validation.md	製作前チェックリストと、各項目で検出できる不具合
references/build123d-patterns.md	build123d 0.11.1 API クックブック：ビルダーと代数方式、スケッチ、セレクター、ジョイント、エクスポート

スクリプト

コマンド	目的
gen.py <model.py> --outdir DIR	build() を実行し、STEP と STL をエクスポートして、プロベナンスマニフェストを書き込みます
gen.py <model.py> --dxf [--dxf-z MM]	レーザー切断用の 2D DXF プロファイルもスライスします（デフォルトの平面：高さの中間）
check.py facts <step>	有効性、バウンディングボックス、体積、面積、重心、ソリッド数を確認します
check.py interfaces <manifest|model.py>	宣言されたすべてのインターフェース番号を規格と照合し、不合格の場合はゼロ以外の終了コードを返します
check.py geometry <model.py|step --model M>	構築したソリッドに対して、モデルの checks() ゲージを評価します。宣言値ではなく実測値を使用します
check.py probe <step> --cyl D|--box X,Y,Z --at ...	アドホックなゲージを 1 つ実行します。この領域に材料がないか、材料で満たされているかを判定します
check.py bores <step>	すべての円筒面を調査します。直径、軸、位置、範囲、スイープを確認します
check.py fit --standard ID --value DIM=MM	1 つの寸法を手動で確認するか、外形がインターフェースとなる部品を確認します
check.py clearance <a> <b> --min MM	2 つのソリッド間の最小距離を計算し、干渉を検出します
check.py standards [--list|--show ID]	同梱された規格データを参照します（標準ライブラリのみ）
snapshot.py <step> --out PNG	目視確認用に、6 方向の正投影図とアイソメトリック図をレンダリングします

すべてのコマンドは機械可読な出力用の --json を受け付け、進行状況を stderr に書き込みます。 check.py standards と、マニフェストを指定した check.py interfaces は、build123d をインストールしなくても実行できます。

エージェントの操作手順

1. 環境を確認します。 機器またはプラットフォームのモデル、API バージョン、認証情報、シミュレーターの利用可否を確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 実際のサンプルを使う前に、プロトコルをシミュレーションするか、水またはダミーのラボウェアを使って実行します。
4. 上記の手順と参考情報を使って、タスク全体を実行します。
5. 結果を検証します。 容量、デッキの配置、ラボウェアの定義を確認し、プロトコルの実行前に人間の承認を得ます。
6. 報告します。 実行内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

このような場合	対応
シミュレーションでプロトコルが失敗する	シミュレーションで修正します。検証されていないプロトコルをハードウェア上で実行してはいけません。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに質問するか、実行前に仮定を明示します。

インテグリティのルール

• 結果、パラメーター、識別子、引用、統計を捏造してはいけません。実行または検証できないことは、明確に伝えてください。
• ユーザーの明示的な確認なしに、物理的な操作、注文、課金を行ってはいけません。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があります。インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する場合、共有 GPU やクラウドのクォータを消費する場合、個人データまたは患者データにアクセスする場合、あるいは取り消せない操作を行う場合は、事前に確認してください。

関連スキル

• fictiv：公開 API がないため、ユーザーのブラウザーで Fictiv のオンデマンド製造ウェブアプリ（app.fictiv.com）を操作します。