移動後に KiCad の 3D モデルが表示されない？問題のある箇所だけを直す

1. 設計をコピーし、対象範囲を決める

KiCad を終了し、プロジェクト、カスタム フットプリント ライブラリ、モデルフォルダーをコピーします。この段階では元のフォルダーをそのまま残します。KiCad のバージョン、OS、新旧のルート、プロジェクトの場所、関係するパス変数の値、ほかのプロジェクトが同じモデルを使っているかどうかを記録します。

確認するコピー済みのプロジェクトフォルダーとライブラリフォルダーを列挙します。ライブラリの .kicad_mod ファイルと、配置済みフットプリントを含む .kicad_pcb ファイルの両方を対象にします。影響を受ける部品については、基板上のリファレンス番号、ライブラリのフットプリント、想定するモデル本体を記録します。これにより、すべてのフットプリントにモデルがあるはずだと思い込まず、後の確認対象を明確にできます。

2. 対象を限定して候補一覧を作る

POSIX シェルを使い、2 つのコピーを置いた作業フォルダーから次のコマンドを実行します。仮のディレクトリ名を実際の名前に置き換え、レポートには未使用のファイル名を選びます。このコマンドは対象の設計ファイルを読み取り、検索対象フォルダーの外にレポートを書き出します。

rg --no-config --hidden --no-ignore --json --multiline --glob '*.kicad_mod' --glob '*.kicad_pcb' '\(model\s+"' -- ./project-copy ./library-copy > ../kicad-model-matches.jsonl 2> ../kicad-model-scan-errors.txt

JSON の match レコードと、その path、line_number、lines、submatches フィールドを確認します。1 つのレコードに複数のトークンが含まれる場合があります。候補ごとにファイルを開き、モデル参照の全体を調べます。JSON は改行を含む場合もファイル名の区切りを保持するため、これらのレコードをコロンで分割してはいけません。これはテキスト検索であり、KiCad のパーサーやモデルパスの解決器ではありません。

隠しフォルダーと無視対象のフォルダーも検索に含まれ、同じ行にある model トークンや複数行にまたがる model トークンを見つけられます。ディレクトリのシンボリックリンクはたどりません。バイナリファイル、アーカイブ、ほかの拡張子は、ここで示した範囲の対象外です。ほかにもコピーしたライブラリのルートがある場合は明示的に追加し、検索エラーを確認します。終了コード 0 は一致あり、1 は一致なし、2 はエラーを表します。いずれも網羅的に確認できた証拠にはなりません。Linux 上で ripgrep 15.2.0 を使った限定的なテストでは、想定した合成データの候補が見つかり、入力ファイルのハッシュは変わりませんでした。本記事の検証では、KiCad GUI の操作、保存して開き直す操作、STEP 出力は実行していません。

3. 参照ごとに変更方法を選ぶ

共有するカスタム変数：${MY_3DMODELS}/Connectors/part.step のルート以下の部分が引き続き正しければ、新しいルートの下にファイルがあるかを確認します。それで対応できる場合は、Preferences → Configure Paths で MY_3DMODELS の値だけを変更します。新たに共有ルートを設定するときは、専用の変数名を使い、値にはフォルダーの絶対パスを直接指定します。外部で定義された変数が優先され、この画面では読み取り専用になるため、その変数を実際に定義している側で調整します。KIPRJMOD は、次に説明する例外です。

プロジェクト相対の参照：正常に機能する ${KIPRJMOD}/models/part.step 参照は維持し、models ディレクトリもプロジェクトと一緒に移します。KIPRJMOD はプロジェクトフォルダーに追従し、上書きできません。変数を付けない ../ パスは、影響を受ける各ビューで実際の解決コンテキストを確認する必要があります。既存の相対参照が適さない場合に限り、明示的なプロジェクトルートまたは共有ルートを選びます。

旧版の変数または埋め込みファイル：KICAD6 を KICAD10 に機械的に置き換えてはいけません。まず、明示的な旧設定の有無、文書化されたフォールバック、実際の参照先ファイルを確認します。正常に機能する参照は維持します。同様に、有効な kicad-embed:// 参照は保持し、そのファイルを所有する基板またはフットプリントの埋め込みファイル一覧で、対応する項目を確認します。これは外部ルートの置き換え対象ではありません。

解決できない外部パスまたは不足するモデルファイル：目的のファイルと、必要最小限の編集内容を記録します。新しいルートを設定しても、存在しないモデルが作られるわけではなく、.wrl 参照が実在する .step ファイルに変わるわけでもありません。置き換え先を選ぶ前に、実際のファイル名、拡張子、必要な出力形式を確認します。影響を受ける各参照について、設定のみの変更、保持、編集、不足ファイルの解決という判断を一覧に残します。

4. 必要な参照だけを編集する

外部パスが誤っていると確認できた場合は、コピーした設計で対象のモデル項目を変更するか、変更範囲を絞ったテキスト編集をレビューします。配下の対応関係を確認できた箇所に限り、旧ルートを置き換えます。別途修正する意図がない限り、ファイル名、拡張子、オフセット、スケール、回転は維持します。差分全体を調べ、無関係な変更や構文の破損がないかを確認します。

対応するライブラリのフットプリントと、影響を受ける基板上の各インスタンスを確認します。KiCad の Compare Footprint with Library ツールでは、両者の違いを確認できます。Update Footprints from Library は、より広範囲を同期する操作であり、独自に変更した基板上のフットプリントも変わる可能性があるため、その変更を意図している場合にだけ使います。パスの修復によって、独自のパッド、図形、その他の設計プロパティを意図せず置き換えてはいけません。

5. 再起動して 3 つの出力を確認する

パス設定を変えたら、KiCad を終了して再起動します。影響を受けるライブラリの各フットプリントを、通常は Alt+3 で開くフットプリント エディターのフル 3D ビューアーで表示します。Footprint Properties 内の小さなプレビューは編集中には便利ですが、このフルビューの確認には代えられません。続いて、コピーした基板を PCB 3D ビューアーで開き、影響を受ける配置、向き、モデル本体をチェックリストと照合します。

コンポーネントの出力を有効にし、意図するコンポーネントの選択と除外設定で、コピーした基板を STEP に出力します。VRML の .wrl モデルは STEP 出力に直接含まれません。Substitute similarly named models を有効にすると、適切な名前の対応する STEP モデルを出力に使えます。VRML のプレビューが表示されるだけで出力の準備が整ったと判断せず、必要な STEP モデルが実際に存在することを確認します。

出力した STEP を、実際にそのファイルを利用する機械系 CAD ツールで開き、想定するボディと位置を照合します。フットプリントビュー、基板ビュー、出力のどの確認に合格したかを記録します。あるビューアーで相対パスの問題が報告されたことは、その表示先を別途確認する理由にはなりますが、すべての環境に同じ不具合がある証拠にはなりません。

6. 旧ルートが不要になったことを確かめる

コピーした設計が確認を通過したら、旧外部モデルフォルダーを、このテストから一時的に利用できない状態にします。他のプロジェクトに影響しない場合にだけ、元に戻せる名前変更を使います。それ以外の場合は、隔離したテスト環境を使います。KiCad を終了してコピーしたプロジェクトを開き直し、候補検索を繰り返したうえで、3 つの出力確認もすべてやり直します。残った参照を選択した構成と照合します。有効な旧版の参照、プロジェクト相対の参照、埋め込み参照は、残っているというだけで不合格にはなりません。

モデルが消える、ファイルを開けない、差分が意図した変更を超えるといった問題があれば、旧フォルダーを元の場所に戻し、該当項目を解決してから先に進みます。元のバックアップは、次の設計レビューが終わるまで保持します。別のマシンへの移行や、ライブラリ、KiCad のバージョン変更後には、関係する確認を繰り返します。プラグインが管理するアセット、異なるパッケージ構成、KiCad 9–10 以外のバージョンについては、それぞれ対象範囲を評価する必要があります。