anatomy

構造

このスキルでは、図を作業台に置かれた小さな計測器のように描きます。脚の付いた重いベース、目盛り付きのルーラーを備えたレール、ブッシュに取り付けられたキャリッジ、ローレット加工されたノブ、コイルばね、針が動くダイヤルゲージ、そして小さな点のようなねじ。読者は見慣れた機械を思い浮かべるため、その仕組みを理解できます。図に示されるすべての数値は、各部品を動かすものと同じモデルから得られます。

このスキルには、完成した例が8つ含まれています。作業を始める前に、最も近い例を開いてください。フレームワークを使わない各例は、node examples/<name>/build.mjs でビルドできます。スクリプトの隣にスタンドアロンの HTML ページが生成されます。ライトテーマにするには、--light を追加してください。

• examples/dial-indicator/ は最小の例です。スタンドに載ったダイヤルゲージで、全体で約300行です。
• examples/desk-computer/ はフレームワークを使わないSVGです。キーボードを入力できるデスクトップコンピューターです。入力した行はケース前面と同じ平面に描かれたCRT画面に表示され、電源を切ると絵が線と点に縮みます。ソリッドは約85個、パスは約850個です。
• examples/arcade-cabinet/ は、側面パネルを外したアップライト型アーケード筐体です。約240個のソリッドと15本のケーブルからなるヒーローです。25セント硬貨がスロットに飛び込み、30°の斜面を転がる円盤が到達する速度でコインシュートを転がり落ち、コインスイッチのワイヤーを作動させてキャッシュボックスに落ちます。スイッチのパルスはケーブルに沿って区間ごとに基板まで伝わり、CRTは暖まり、セルフテストを実行して、傾いたモニターと同じ平面に描かれたアトラクトモードを表示します。スティックを傾けると、パネルの下にあるマイクロスイッチが閉じます。この例では、断面図の機構が見える状態を保つカメラの配置、任意の軸に沿ったプリズムとして描かれた凹型基板、ビルドで使用するものと同じモジュールからページ内で再構築される可動部品、そして確定済みの描画順序の予約スロットに描かれる動く硬貨とワイヤーを示しています。node build.mjs --audit でジオメトリを検証できます。
• examples/raptor-engine/ は、テストスタンドに吊り下げられたロケットエンジンです。丸い部品は kit/lathe.mjs から、パイプとハーネスは kit/tube.mjs から作られています。11個のアセンブリに分解され、スプリングはずらして配置され、フレームごとに奥行き順が再計算されます。各部品には実際の形状が記録されます。静止時、分解時、分解アニメーションを再生したすべてのフレームで node build.mjs --audit（kit/audit.mjs）を実行すると、何も別の物体を貫通しないこと、すべての端点が実際のマウントに接していること、曲がり部分が挟まったり折れたり別の線に重なったりしないこと、曲線プロファイルの傾きが揺れないこと、そしてすべての重なりが奥行き順に描画されていることを検証できます。WebGLのプルーム、衝撃波、飛沫、蒸気は、背面と前面のSVGの間に描画されます。密集した配管、滑らかなシェーディング、フェード処理の参考例です。
• examples/ripple-tank/ は、紙のスクリーンの上に高い脚で載った学校用の波紋タンクを、44°上から見た例です。2つのWebGLレイヤー（紙に当たるランプ光、影、集光模様と、水面の反射およびガラス）がアイソメトリック平面に位置合わせされ、純粋な分散・光学モデル（model.mjs）によって駆動されます。周波数の変化は、ディッパーから履歴テクスチャを通って伝わります。
• examples/test-rig/ は、実際のサイト（React/Next）にある本番品質の図です。スプリング式キャリッジに取り付けられたガラスボタン、レール上で押したり引いたりする指先プローブ、そして傾きを測るダイヤルゲージがあります。ソリッドは53個、パスは約470個です。
• examples/spot-plate/ は、同じサイトにある2つ目の本番品質の図です。スポットプレート上のガラス滴6組を、それぞれ1つの距離場から描画しています。そのため、merge の距離より近い滴のペアは、ひとつのガラス片につながります。複数の触針ブレードで merge を設定し、ブレードは間隔ごとに1枚あります。形状同士が変形してつながる例や、1つのコントロールで多数の部品を動かす例として参考になります。
• examples/turning-dial/ は、オプションの3Dモードです。小さなロボットハンドが操作する、実際の3D空間で回転するダイヤル式錠です。金属素材の可動パーツが約90個あり、2つ目の回転グループ、ヒンジ、持ち上がる3つのヒンジを持つ指、自由な剛体として外れるポッドがあります。WebGLのLED、その光だまり、火花は可動部品に追従します。その隣にある stress.mjs は、雑然とした作業場にある約380個の部品からなる密集したハンドで、パフォーマンス測定に使われます。

テストリグは、描画そのものの品質基準です。Raptorはシェーダー処理の基準です。WebGLエフェクトは、ワールド空間でちらつきがなく、シームレスにレンダリングされる点で、その品質に達している必要があります。

重要な考え方

オブジェクトそのものが説明になります。 箱や矢印、ラベルを描かないでください。仕組みそのものが概念を表す、実在しそうな精巧な物体を考案してください。これまでの図では、次のように対応させていました。

概念	オブジェクト
多数のキャンバスにサービスを提供する、共有 GPU コンテキスト 1 つ	ガントリープロッター：16 個の区画を巡る 1 つのプリントヘッド
何も変わっていないときに処理を省くキャッシュキー	ピンタンブラー錠：すべてのピンが合うとプラグが回り、何も再描画されない
テクセルあたりのバイト数が異なる 7 つのレンダーターゲット	7 段の引き出しがあるチェスト。それぞれの深さは格納するバイト数に比例
分離可能なぼかし（49 × 49 タップ対 49 + 49 タップ）	釘のベッド状のスタンプと、レール上の 2 本の櫛
押し下げながら傾くばね	ばね、プローブ、ダイヤルゲージを備えた試験装置
高さプロファイル	エッジに押し当てたプロファイル（輪郭）ゲージ
向きによって変わる光	回転台を囲むキーライトとフィルライトのある小さな写真スタジオ

どちらも実際に見られた、うまくいかない方法が 2 つあります。

• 抽象的すぎる。 重ねた板、宙に浮いたスラブ、ラベル付きの箱では、何を表しているのか伝わりません。
• 平坦で味気なさすぎる。 いくつか線を引いただけの大きなスラブには、立体感も部品もなく、発見するものがありません。

どちらも解決策は同じです。たくさんの小さく精密で目的のある部品から作られた、見覚えのある機械にします。

すべての制作物に、非常に細かなディテールを加えます。 アイデアや依頼の規模にかかわらず、すべての図に当てはまります。簡単な説明図でも、数枚のスラブだけで済ませず、密度の高い実在感のある機械にします。規模に応じて変えるのは、どこまで作り込むかです（ワークフローのステップ 1）。Figure では対象と機構を 4× で見直し、Hero または Epic では図全体を見直します。

• 実物をよく観察します。 実物と同じ構造にします。ねじ、継ぎ目、面取り、ブッシュ、銘板、コネクター付きケーブル、目盛り付きのスケール、さらに部品を固定する部品まで、すべて描き込みます。
• 2 つの見え方を意識します。 1× では、1 台の明快な機械として認識できます。4× では、どの領域にも見つける価値のある本物らしいディテールが残っています。何もない面や空白の隅は落ち着きではなく、未完成です。
• 目的のあるディテールにし、ノイズは加えません。 ディテールは機構に属する部品から生まれます。各部品は別の部品に取り付けられ、エッジで終わり、唐突に途切れず自然に薄れていきます。
• 最後に確認します。 仕上げる前に 4× に拡大し（Figure では対象と機構、Hero または Epic では図全体）、描き込みの足りない領域があれば、そこに実物らしい部品を追加します。

ワークフロー

この順序で進めます。ジオメトリを作る前に、概念と部品リストを書き出します。品質の大半は、この段階で決まります。

1. 始める前に規模を決めます。 ほかの作業に取りかかる前に規模を明示し、以下の区分で見積もりが必要な場合は、所要時間のおおよその目安をユーザーに伝えてください。
   • Figure：1つの機構、40～80個の部品、SVG、WebGLレイヤーは最大1つ。規模を明示し、確認を求めずに制作します。Figureは1時間もかからずに完成することが多いため、所要時間はユーザーに伝えません。以下の進捗確認では、最大1時間を見込んでください。
   • Hero：高密度のオブジェクト、複数のWebGLレイヤー、または1つの3D対象、80～150個の部品。目安は約2～4時間です。その旨を伝えてから制作します。ただし、ユーザーが手早いものを求めている場合は除きます。
   • Epic：乗り物、建物、工場など、動くシステムが多数あるもの、または複数の対象を3Dモードにするもの。6時間以上かかります。着手せず、見積もりを伝え、アイデアの核心を保ったHero版を提案し、完全版で追加される要素を列挙してください。ユーザーが選んだ場合に限りEpicを制作します。
   • 規模にかかわらず、最初の1時間以内にブラウザーで開ける動作するページを用意し、そこから作り込みます。開始時と各ステップでdateを実行してください。ステップに見積もり時間の2倍以上かかった場合は、現在の進捗と残作業をユーザーに伝えてください。
2. まず事実を確認します。 説明する対象の実際の数値と動作を集めます。サイズ、数、しきい値、曲線などです。表示値、動き、キャプションはすべて正確でなければなりません。可能であれば、テスト用リグの例にあるrig.tsのような小さな純粋モジュールとしてモデルを記述し、すべてをそこから動かしてください。
3. オブジェクトを考案します。 機構が概念に一対一で対応する機械、工具、器具、または家具を選びます。何が動き、その動きが何を意味するのかを一文で説明します。参考画像を模倣してはいけません。取り入れるのは仕上げだけで、オブジェクトそのものは別のものにしてください。
4. 部品リスト。 部品を40個以上（Figureは40～80個、Heroは80～150個、Epicはそれ以上）用意し、グループ分けします。ベース（プレート、脚、溝、角のねじ、ラベルプレート、目盛り帯）、構造（支柱、レール、フレームバー、エンドストップ）、機構（キャリッジ、ブッシュ、ばね、プランジャー、針）、操作部（ローレットノブ、つまみねじ、クラウン）、そして対象そのものです。対象は光を当てる部品1つです。各部品は、別の部品の上に配置します。references/craft.mdには、部品の用語と作成レシピがあります。
5. 空間を設計します。 実物の約1 pxを1ワールド単位として使います。xとyは床面、zは上向きです。平面配置は、丸み付き長方形{x, y, w, d, r}と円で表します。カメラを選びます。既定の方位角は45°、長辺を見せる場合は35～60°、仰角は30°です。開いたものの内部を見る場合は、リップルタンクの44°のように、より高くします。次にfitProjection(points, width, height, { pad, azimuth })で収めます。
6. ジオメトリは一度だけ構築します。 キットを使って、すべての静的パスをジオメトリモジュールで事前計算します。slabOf、cylinder、extrude、planOutline、topTicks、knurl、coil、radialTicksなどを使います。ベル、フランジ、バルブ、アクチュエーターなど、どの軸でも丸い部品はkit/lathe.mjsから、パイプとケーブルはkit/tube.mjsから作ります。可動部品は静止位置で一度だけ作り、translateAlongで動かします。形状が変わる部品だけをフレームごとに再構築します。
7. 奥から手前へ、下から上へ描画します。 繰り返し部品はdepthOfで並べ替えます。別の部品を囲むものはすべて、後ろ半分と前半分に分けます。ロッドを囲むばねや、キャリッジを囲むフレームバーが該当します。可動部品は、物理的に配置されるスロットに描画します。references/craft.mdの「Painter's order」を参照してください。Figureにパイプ、ケーブル、丸い部品が加わったら、キーを目視で調整するのはやめます。各アイテムをA.recorder(P, { order, spring })に記録し、A.settle(R, P)でアイテム同士が重なる箇所の実際の奥行きを測定してキーを設定し、最後にA.auditOrExit(R, P)でビルドを締めくくります。パイプは描画前に配管します。両端に実際のポートを設け、構造に沿って脚を通し、交差は直線部分に置き、カラーでパイプに隙間を作ります（references/craft.mdのセクション8）。描画する形状は実物どおりに記録します。監査をすり抜けるための代用形状は不具合であり、監査で検出されます。グランドからスライドして出るロッドは、G.rodOutから作る1本のロッドとして記録し、A.slideを使います。
8. 枠に収めます。 Figureをカードに配置します。左上にFig n、右上に短いタイトル、左下に操作のヒント、右下にリアルタイムの表示値を置きます。凡例のキーと正確なキャプションはカードの下に配置し、描画内の文字は、小さな刻印ラベルを最大1つだけにします。
9. 動きを付けます。 指数関数的な追従や実際のばねを使い、落ち着いた時間ベースの動きにします。操作されていない間はアイドルツアーをループします。Figureはポインターとキーボードに応答し、画面外では停止し、視差効果を減らす設定では静止します。属性はrefsに書き込み、フレームごとに再レンダリングしないでください。references/motion.mdを参照してください。
10. 批評家の目で検証します。 制作者は拡大して欠陥を見つけるため、まず自分で拡大して確認します。作成したPNGはすべて確認してください。

• scripts/capture.mjsでデスクトップ、スマートフォン（幅390）、ホバー、動きの複数の瞬間をキャプチャします。シーケンス、分解状態、--no-webglのフォールバックにはscripts/drive.mjsを使います。
• 監査結果をゼロにします。 パイプ、ケーブル、丸い部品がある場合、node build.mjs --auditの最後にaudit passedと表示され、失敗項目がすべて0でなければなりません。対象は、静止時、分解時、移動中のクリアランス、端子、未接続端、折れ、自己交差、混雑（細長い立体物との接触も含む）、代用形状、支持、ぐらつき、サドル、奥行き順です。噛み合わせはキーの補正ではなく、ジオメトリで修正します。
• 線のチェック結果をゼロにします。 監査では線のマークアップを検出できません。node scripts/lines.mjs page.html --out shots/lines.png（および-lightページ、さらにdrive.mjsの["lines"]アクションで各静止ポーズ）を実行すると、line ends: 0と表示されなければなりません。すべての継ぎ目、目盛り、リブ、刻み、ポインターの端が、ストローク、点、または輪郭に接している必要があります。リング付きPNGを確認してください。
• 両テーマで、すべての接合部を4倍に拡大して確認します（--lightもビルドします）。組み立て状態と分解状態の両方で確認してください。すべてのフランジ、T字管、エルボ、クランプ、バルブ、ベローズ、バンド、サドル、ボールジョイント、交差部、すべての曲面本体（トーンが階段状になっていないこと）、すべてのテクスチャの終端（縁で終わるか、徐々に薄くなること）、継ぎ目のある平らな箱面、チャンクの継ぎ目にあるテクスチャ付きホース、静止位置と全ストローク位置の各スライドロッド、テキストやシェーダーコンテンツを含む各ウィンドウを確認します。
• シェーダー： すべての遷移を["slow", 0.05]で遅くしたコンタクトシートを作成します。急な切り替わりや色の切り替わりがなく、エッジが0と判読できることを確認します。ライトテーマでは、各遷移を通じたフレームごとのインク量も記録します（ライトテーマに合わせて単調に変化する必要があります）。インクとストロークが接する箇所は、8～16倍に拡大して切り出してください（references/verify.mdの「Light-theme shaders」）。
• PNGをサンプルの隣に置いて、次の点を確認します。見た瞬間に本物のオブジェクトだとわかるか。小さな部品と立体感に富み、すべての線が何かに接しているか。1倍でも細部まで表現され、4倍に拡大しても見応えがあり、何もない面や空いた角がないか。すべて「はい」になるまで繰り返します。チェックリスト：references/verify.md。

セットアップ

キットは kit/ にあります。

ファイル	用途
kit/iso-kit.ts	カメラ、ソリッド、パーツライブラリ、SVG文字列レンダラー、カードとページのビルダー、CSS（ISO_CSS）を1つのファイルにまとめたコアです。TypeScript プロジェクトにコピーして使います。
kit/iso-kit.mjs	同じコアをプレーンな ESM にコンパイルしたもので、Node スクリプト向けです。直接インポートできます。
kit/iso.css	ISO_CSS を書き出したものです。1回インポートし、ラッパーまたは <body> に class="iso"（ライトテーマの場合は data-theme="light" も）を設定します。
kit/react/draw.tsx	サーバーセーフな React コンポーネントです。Solid、Line、Wire、Dots、FaceText、IsoFigure、Plate を利用できます。
kit/react/live.tsx	"use client" フックです。useReadout、useLoop、useEased、useInView、useStillness に加え、spring と follow を利用できます。
kit/lathe.mjs	任意の軸に沿った丸いパーツを作成します。frameAlong、lathe（プロファイルに滑らかな節点がある場合、自動的に滑らかなシェーディングが有効になります）、solidOf、disc、ringBand、sphereOf、saddleOf、bandsOf（1つの曲面を奥行き順に並べ替え可能な帯に分割します。帯は同じ面を共有し、sidesOf による輪郭線は1本です）、丸い表面上の可視円弧、リブ、ボルト円（ribsOf と dotsOf は fade を受け取り、ribsOf は seams も受け取ります）、グランドからスライドして出るロッド用の rodOut、配管経路用の fillet を利用できます。
kit/tube.mjs	tubePieces は3Dの配管やケーブルを奥行き順に並べ替え可能な断片に分割します（breaks、カラーやクランプ下の gaps、楕円形の端面キャップ、継ぎ目ごとに断面に沿う編組・コルゲーション・巻き付け用の rings に対応）。tubeSvg はそれを描画します。crossingsOf は経路がクランプを通過する位置を検出し、runsOf は描画された区間を返します。.tb-* の塗りつぶしは ISO_CSS に含まれています。
kit/audit.mjs	ジオメトリを検証します。recorder(P, { order, spring }) は、ヘルパーが描画する際にアイテム、形状（回転体、板、プリズム、ボックス、球、チューブ、ホストで切り取られたパッド）、経路を収集します。settle(R, P) は、静止時、離れた状態、再生された分解状態において、重なり合うすべてのペアにレイキャストを行って真の奥行きを判定し、描画順のキー（overlapsOf、orderKeys）を設定します。auditOrExit(R, P) は --audit フックで、すべてのチェック（細長いソリッドを線として扱う clearances、solidClearances、terminals、looseEnds、supports、folds、selfOverlaps、crowding、代用形状の coverage、wobble、seats、depthOrder）を実行し、問題があればゼロ以外の終了コードで終了します。A.slide は、グランドからスライドして出るロッドを記録します。references/kit.md のセクション 12 を参照してください。
kit/gl.mjs	描画内のシェーダー用 WebGL レイヤーです。GLSL_ISO（rayOf と pixelOf を含む GLSL のカメラ）、glCamera(P)、glLayer(...)、JS のエンベロープ smooth、burst、settle を提供します。3D図では、GLSL_TURN と glslPose(name) がワールド座標の点を移動するグループ内に配置し、coverOf で前面キャンバスをマスクします。
kit/turn.mjs、kit/turn-build.mjs、kit/turn-audit.mjs	オプションの3Dモードです。turn-build.mjs の turning(P, { recorder }) は、グループ（turn、slide、hinge、free）、ライブレイヤー、マテリアル付き凸パーツ、T.build を提供します。turn.mjs はランタイムで、TURN.mount、コントローラー、TURN.cover、TURN.poseUniforms、TURN_CSS を含みます。turn-audit.mjs には、あらゆる回転角とモーションクリップを対象にした軌道監査 orbitOrExit があります。references/3d.md を参照してください。
scripts/capture.mjs	WebGL を有効にしたヘッドレス Chrome で、スクリーンショット、クローズアップ、コンソールチェックを行います。node で実行します。
scripts/drive.mjs	WebGL に対応したスクリプト実行可能なヘッドレス Chrome です。移動、クリック、キー入力、スローモーション、条件成立までの待機、eval、ショット、ポップを検出するコンタクトシートに対応し、--no-webgl と --preload を利用できます。
scripts/lines.mjs	ヘッドレス Chrome でビルド済みページの線端をチェックします。すべてのテクスチャ線がストローク、ドット、または輪郭線で終わっている必要があります。失敗箇所を --out で囲んで示し、失敗があれば終了コード 1 で終了します。
scripts/inline-kit.mjs	kitScript()、glScript()、turnScript() は、キット、WebGL レイヤー、3D ランタイムを、スタンドアロンページにインライン化するためのソースとして返します。
scripts/turn-check.mjs、scripts/turn-bench.mjs	3D図を対象に、キットビルダーとの忠実度、Zバッファの描画順、ピクセルのポップ、24個の角度における線端、ブラウザーでのフレームタイミングをチェックします。また、Node でパーツの種類ごとの CPU 時間を計測します。
scripts/print.mjs、scripts/print-sheet.mjs	印刷用シートを作成します。ビルド済みページのポーズをベクター静止画として固定し、ポスター、図面、詳細図の3形式でA4またはLetterのPDFにレイアウトします。references/print.md を参照してください。
プロジェクトに合った方法を選んでください。

• スタンドアロン HTML、静的 SVG、ブログ記事、または React 以外のサイト。 examples/dial-indicator/build.mjs のような Node ビルドスクリプトを作成します。kit/iso-kit.mjs をインポートし、solidSvg、lineSvg、dotsSvg、wireSvg、faceTextSvg で文字列を組み立て、figureSvg と plateHtml でラップします。さらに、pageHtml({ script: kitScript() + live }) を使ってページを書き出します。シェーダーを使う場合は、kitScript() + glScript() + live とします。単独の .svg ファイルには、スタイルを埋め込む figureSvg({ standalone: "dark" | "light" }) を使います。
• React または Next.js。 kit/ をプロジェクトにコピーします（たとえば components/iso/）。ジオメトリはプレーンな .ts モジュールにまとめ、draw.tsx コンポーネントを使ってサーバーコンポーネント内で静的なアートを構築し、要素を props として、動きを付ける単一の "use client" ライブコンポーネントに渡します。references/react.md では、この分割方法と大きなページでの落とし穴を説明しています。

制作ルール（概要）

これらのルールが、丁寧に作り込まれた図と単なる図表を分けます。詳しい考え方と手順については、references/craft.md を参照してください。

• ワイヤーフレームではなく、立体にします。 すべての部品を紙の色で塗りつぶし、順番に描画することで、手前のものが奥のものを隠すようにします。透ける輪郭線や、隠れた部分を示す破線は使いません。
• キットの陰影を活かします。 extrude は向きに応じた4種類の側面の色調と、より明るい上面を返します。高さのあるものにはこれを使い、flat は床や厚さが1 unit未満のインレイにだけ使います。
• 色調の階層。 土台と脚には lo、構造には mid、主題には hi を使います。アクセントは1か所だけ lit にします（暗色では白、明色では黒）。これは読み手の視線を集める部分です。溝には faint、細かな目盛りには lo、主目盛りには mid、ゼロの印には hi を使います。色を使うのは、赤、緑、青のチャンネルのように、色そのものが主題の場合だけです。
• 細かく正確なディテールを使い、ノイズは加えません。 面取りは0.4～1.6、溝は縁から3～5内側に入れ、ネジはプレートの角にリング付きの直径0.4～0.55の点として配置します。ノブにはローレットを付け、定規の目盛りは4～5単位ごとに引いて5本ごとに長くし、ラベルプレートには3本の罫線を入れます。ディテールはすべて、いずれかの部品に属するものにします。
• 線の端は必ず何かに接続します。 すべての線の端は、面、別の線、または終端の点に接続します。コネクターは Wire とし、終端の点をオブジェクトに置きます。引き出し線、吹き出し、寸法矢印、宙に浮いたラベルは使いません。
• パイプやケーブルを何にも貫通させません。 静止時、分解時、分解表示のどのフレームでも、別のパイプ、ケーブル、立体を貫通させません。線自身の接続部分を除き、すべてのものから半径の約1.5倍の隙間を空け、線は対象の正面を横切らずに構造物の脇を通します。フランジ、バンド、ベローズ、クランプ、バルブが巻き付く部分ではパイプを途切れさせます。部品同士は面一、接線、または縁と面で接するようにし、埋め込みません。フランジの裏面はポートに接し（ポートが曲面の場合はサドルパッド上の G.saddleOf に接します）、枝管はボールティーから出し、分解時も含め、すべての端はフランジ、カップリング、コネクターシェル、または終端の点で終わらせます。
• 交差はすべて、正しい奥行き順で描きます。 画面上で重なる2つの要素は、手前のものが上に描画されるようにし、その順序は目視で調整せず、A.settle と監査で確認します。線が交差するのは、奥行きに十分な間隔がある直線上だけです。曲がり、端、クランプが別の線の輪郭に接すると、継ぎ目に見えてしまいます（棒、タイロッド、支柱、レールも線として扱います。パイプの最後の区間を画面上でこれらに沿わせてはいけません）。手前に向かう脚が曲がるとV字に挟まれて見えるため、そのようなポートからはエルボーボールを通して出します。また、経路を画面上で折り返しません。前後関係を決められない2つの要素は互いに干渉しているため、偏りで解決せず、切れ目を設けるか、接線で接触させます。
• 曲面は段差なく滑らかに陰影を付けます。 曲線のノットには滑らかさを指定し（[s, r, 1]）、lathe ではアウトラインも描く単調な曲線を使って陰影を付けます。継手より大きな曲面のある本体には smooth: { slope } を指定した解析的なプロファイルを与え、長い本体は G.bandsOf で区切り、球には G.sphereOf を使います。色調の帯は直線的な切り口で終わらせず、先細りにして消えるようにします。継ぎ目はアウトラインの下に配置します（inner）。
• テクスチャは実際の縁で終わらせるか、徐々に消します。 リブ、ボルト円、罫線、継ぎ目、溝を、平面でも曲面でも表面の途中で止めてはいけません。ribsOf と dotsOf には fade を指定できます（リブをフェード表示するには fadedSvg を使います）。リブの列は継ぎ目で終わらせ（ribsOf(…, { seams: true })）、箱の角をまたぐ継ぎ目や溶接線は角を回り込ませます（スラブの inner として k.sideSeam を使います）。1つの面上の線は端から端まで引き、通気口は閉じたスロットにし、目盛りは定規の縁から伸ばします。途中で止める必要のある1本の線は fadeLineSvg で徐々に消し、上を向いた特徴（リング上面の穴など）が並ぶ列は、全周に見えるようにします（all: true）。パイプ上のテクスチャ（編組、波形、巻き材）は断面に沿わせ、すべての分割部分の継ぎ目をまたいで通します（tubePieces(…, { rings })）。中心線に沿う破線のストロークにはしません。パイプの光沢と陰影は、端のキャップ上まで続け、すべての分割部分の継ぎ目をまたがせます。印刷文字を表す罫線、針の後端、ポインターの先端だけは、何もない面で止めてもかまいません。その場合は free と指定します。
• シェーダーが急に現れたり、途中で途切れたりしないようにします。 すべての一様な値には立ち上がりと減衰を持つエンベロープを適用し、位相の変化は物理量に連動したクロスフェードにします。すべての項は境界やキャンバスの端に達する前にゼロになり、エフェクトは図固有のカメラのワールド空間に配置します（以下を参照）。
• 面上のものは、その面に収めます。 機械が表示するテキストは、最も長い文字列でもウィンドウに収まるようにし、ウィンドウ内でクリッピングします。開口部から見える内容は、それ自身の平面だけでなく開口部でもクリッピングし、くぼみの側壁も描画します。
• 立体感。 ものに実際の厚みを持たせ、ほかのものの上に置き、土台の下や持ち上がったものの下には柔らかなハローを配置します。
• 構図。 図を中央に配置し、カードの約55～65％を占めるようにします。一連の図では縮尺を統一し、幅390 pxでも何を表しているか分かるようにします。

描画内の WebGL

シェーダーは、線では描けないものにだけ使います。炎や排気、水や集光模様、本物のランプの光、グロー、蒸気などです。パーツは SVG のままにします。基本ルールは、位相間の色の変化がクロスフェードではなくカットのように見えた最初のシェーダー図に由来します。

• 3 つのレイヤー。 背面の SVG にエフェクトで覆われるものを配置し、キャンバスにエフェクトを描画します（pointer-events: none）。前面の SVG にはエフェクトを覆うものを配置します。パーツまたはエフェクトが両側にまたがる場合は分割します。
• ワールド空間で同じカメラを使います。 シェーダーの各点は onFloor、onWallX、onWallY から構築するか、ピクセルのレイ rayOf(vb) + t·towardViewer() を進めます。すべてをワールド単位に uK を掛けたサイズにします。平面上にあるものは、その平面の SVG の線と正確に位置が合います。
• 突然の変化をなくします。 すべてのユニフォームは、アタックとディケイを持つエンベロープに従わせます（イベントにはキットの burst、レベルには settle を使います）。位相の変化は、物理量に応じて色が連続的に変わるクロスフェードにし、フェードアウトでは暗くなるだけにします。
• 急な打ち切りをなくします。 すべての項は、if、境界、キャンバスの端、セルノイズの各セル境界に達する前にゼロになるようにします。
• 開口部越しに見せる場合は、二重にマスクします。 窓やくぼみの奥にあるコンテンツは、それ自体の平面と、面の平面にある開口部の両方でマスクし、乗算します（references/webgl.md、セクション 5）。
• ブレンド。 tonemap() とディザリングを使います。ダークテーマでは、光を加えるだけのキャンバスには乗算済み出力と mix-blend-mode: screen を使います。一方、暗くもする必要があるもの（リップルタンクの水など）は通常のブレンドのままにします。
• ライトテーマにも対応し、シェーダーは紙面用に設計します。 通常の乗算済みアルファを使い、スクリーンは使いません。紙に表示すべき色を書き込み、インクの色を逆算します。グローは、暗くしたダークテーマの色ではなく、彩度の高い本体、淡いコア、色付きの縁、最低アルファ値で表現します。そうしなかったため、Raptor の「赤インクの煙」のような結果になりました。
  • 光が当たる面には色味を加え、それを受ける空洞には物理的に暗い下地（すす、耐火材、水深など）を設けます。
  • 高温の本体には、フォールバックと共通の単一の黒体インクテーブルを使います。
  • インクは光が強くなるほど濃くなるようにし、各項を個別にではなく、完成したインクを一度だけフェードさせます。
  • インクは各ストロークの内側の縁で終わらせます。
  • フレームごとにインクを測定します。references/webgl.md のセクション 8 に、レシピとレビュー担当者が見つけた問題があります。
• 控えめに。 デバイス比は 1.5 を上限とし、エフェクトが有効で画面内にあるときだけ描画します。視差効果を減らす設定では静止フレームを 1 枚だけ表示し、WebGL がなくても SVG だけで意味が伝わるようにします。

シェーダーを書く前に references/webgl.md を読んでください。

3D：回転する図（ベータ版）

3DはWebGLと同様の選択肢です。奥行き方向に動くパーツがアイデアの中心となる場合に使います。回転するダイヤルやターンテーブル、曲がる指、外れて落下するパーツなどが該当します。図の残りの部分は静止したキットアートのままにします。

ベータ版です。エンジンはサンプルとテスト用の図1つで実証されていますが、まだ本番用の図では検証されていません。一度に回転させる対象は1つにし、その周囲の細かいものは静止させてください。小さな図なら60 fpsで動作します。負荷の高いマシンで、密度の高い380パーツの曲がる手を測定したところ、1440では約20 fps、スマートフォンのプロファイル（390 px、CPUを4倍にスロットリング）では13〜15 fpsでした。

• 動くパーツにはキット独自の画像を使います。 各フレームで、凸形状のキットプリミティブ（角柱、丸みのある形状、ドーム、平面を持つ球体、旋盤加工形状、チューブ）をキットのルールに従って再投影し、再シェーディングします。θだけ回転させる場合、キットは方位角a − θで描画します。
• 描画順序は分離平面によって決まります。 同じグループ内のペアにはグループ内で固定された平面を使い、異なるリンク上のペアにはそれらに共通する座標系内で固定された平面を使います。それ以外は各フレームで解決します。監査により、どの角度でも、どのクリップフレームでも循環がないことを証明します。
• 接触面は面一、接線、またはリムと平面の接触です。 ジョイントは子グループ上にある同軸のナックルディスクで、親リンクに接触します。そうでない場合、監査では子グループ全体が不安定と判定されます。動くグループ間にまたがるライブ線はありません。ケーブルは両側のクリップを通してジョイントを横切るか、ハブのスリップリングを通してターンテーブルに接続します。
• ライブチューブはほぼ水平な平面内、または継手の内部で曲げ、視線方向には決して向けません。 曲げにはR ≥ 2r / sin²(e − θmax)が必要です。θmaxには、そのチューブが通るすべてのヒンジのピッチ範囲を含めます。平らな場合の上限は8r、±12°のヒンジでは21rです。各ルートはマウント面からマウント面まで伸ばし、ポートをgapsに配置します。これにより、どの角度でも、どのポーズでも条件を満たします。
• マテリアルによってグラデーションを再マッピングします。 ゴールド、クローム、スチール、ガンメタル、ラバー、ブラス、カッパーにはそれぞれ明るい色と暗い色のセットがあり、色調は引き続き面の向きによって決まります。
• 自由グループは跳ねずに外れます。 同軸パーツは、テクスチャを回転させる固定画像です。
• シェーダーは動きに追従します。 controller.anchorまたはtoGroupでグループに固定し、coverOfで前面のキャンバスを遮蔽します。ワールドエフェクト（煙、落下する火花、作業台の上のオイル）はグループ空間に配置しないでください。
• --audit（turn audit passed）とscripts/turn-check.mjs（--fidelity、--order、--pops、--lines、--perf）で検証します。 --quick --only=…を使って反復できます。図を証明できるのはフル実行のみで、パーツ30個で15〜20分かかるため、バックグラウンドで実行してください。

まずreferences/3d.mdを読んでください。

印刷用シート（A4）

ユーザーが図を紙に印刷したい場合（配布資料、ポスター、PDF、A4 または Letter サイズのシート）は、描き直すのではなく、完成した図から印刷します。ビルドの隣に sheet.mjs を作成します。撮影するポーズは drive.mjs のアクションとして、パーツはライブ SVG に対する CSS セレクターとして、文言はすべてモデルに忠実なものとして記述します。その後、node scripts/print.mjs sheet.mjs --format all --png を実行し、すべてのページを確認します。

• poster（既定）：1 ページ。大きな名前、質問、大きな数字、番号付きピンを付けた図、各パーツの説明をそれぞれ 1 行で掲載します。
• drawing：1 ページ。パーツリスト、仕様、拡大図、動作中のパーツを点灯させた手順の帯を含む技術図面です。
• detailed：2～4 ページ。機械に合わせた縮尺で作成します。概要ページにはピンと円形の拡大図を配置します。「仕組み」ページでは、各手順を大きく表示した点灯状態の静止画として掲載します（1 ページにつき 6 枚。最後の枠には理由を記載します）。複雑な図では、パーツ群を最大 4 つ大きく拡大した「アセンブリ」ページを追加します（仕様の assemblies）。シンプルな図は 2 ページのままとし、ページ数は maxPages で制限します。

ユーザーが形式を選んでいない場合は、3 種類すべてを提示します。ページに PDF がある図を表示する場合は、プレートの本文内に kit/pdf-button.mjs の pdfButton(href) を使ってカードにリンクを追加します（examples/push-button/build.mjs を参照）。先に印刷し、その後ページを再ビルドします。参照例は examples/raptor-engine/sheet.mjs と examples/arcade-cabinet/sheet.mjs です。まず references/print.md を読んでください。

参考資料

必要に応じて、以下を読んでください。

• references/craft.md：パーツのコード付き用語、トーンテーブル、描画順のパターン、円形パーツ、パイプとハーネス、分解図、顔面のスクリーン、図が却下されたアンチパターンなど、見た目について詳しく説明しています。設計の前に読んでください。
• references/kit.md：API、シグネチャ、使用例。
• references/motion.md：ライブ動作（ループ、スプリング、ツアー、ポインター、キーボード、アクセシビリティ、動きを抑える設定）に加え、単発イベント、分解図、奥行き順の並べ替えとアーム設定のエンベロープを、バニラ JS と React で説明しています。
• references/react.md：React／Next.js のサーバー／クライアント分割、要素の props、大きなペイロードによるキー警告の落とし穴。
• references/verify.md：capture.mjs と drive.mjs のコマンド、レビュー用チェックリスト（シェーダーを含む）、よくある不具合。
• references/webgl.md：図にシェーダーを組み込む場合について説明しています。シェーダーを使う価値があるケース、レイヤースタック、カメラの契約、アイソメカメラでのレイマーチング、最小ページを含む完全な API、失敗から学んだ不具合を含む制作ルール、ライトテーマ（紙面上のインク、現象ごとのレシピ、レビュアーが指摘した不具合）、検証方法を扱います。
• references/walkthrough.md：テストリグの設計を、コンセプトからコードまで手順を追って説明しています。
• references/3d.md：オプションの 3D モードについて説明しています。グループとポーズ、ライブレイヤー、凸型パーツとそのルール、マテリアル、フリーグループ、ヒンジチェーン、描画順、ターンテーブル周辺の静的な装飾、ターンに追従するシェーダー、オービット監査、ブラウザチェック、パフォーマンス、制限を扱います。
• references/print.md：完成した図から印刷用の A4 または Letter サイズのシートを作成する方法を説明しています。3 種類の形式、sheet.mjs の仕様（ポーズ、セレクターで指定するパーツ、フォーカス、非表示、切り抜き、WebGL 用ラスター）、PDF の確認方法を扱います。
• references/publish.md：ユーザーから依頼された場合に限り、scripts/publish.mjs を使って完成した図をコミュニティギャラリーで共有する方法を説明しています。代わりにプッシュされることはありません。