Script Example Analysis in Altium Designer

スクリプトシステムの一般的な側面や、スクリプト内でのDelphiおよびX2オブジェクトモデルの使用についてさらに理解を深めるために、ここでは機能面から2つのサンプルプロジェクト ― ボード外形線コピーツールとネットリスト生成スクリプト ― を取り上げて解説します。

Board Outline CopierおよびNetlisterスクリプトは、Altium Designerのスクリプトシステムの機能を示すためにX2オブジェクトモデルを用いて開発されています。これらはサンプルスクリプト集に含まれている既存のスクリプトです。

• Board Outline Copierスクリプトは、PCBオブジェクトモデルを利用して、既存のPCBボード外形線をトラックやアークとして指定したレイヤーにコピーします。
  詳細は\Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCRをご覧ください。

• Netlist generatorスクリプトは、WorkSpace Managerオブジェクトモデルを利用して、従来のProtel（v1およびv2）形式のネットリストを生成します。
  詳細は\Scripts\Delphiscript Scripts\WSM\Protel Netlister\ScripterProtelNetlist.PRJSCRをご覧ください。

Board Outline Copierプロジェクト

Board Outline Copierの目的は、PCBドキュメント内の既存のボード外形線を同じドキュメント内の別のレイヤーにコピーすることです。

このプロジェクトでは、スクリプトフォームを使用し、ユーザーがダイアログを通じて外形線の幅を指定し、ドロップダウンメニューからターゲットレイヤーを選択できるようになっています。PCBオブジェクトモデルおよびPCB APIのインターフェースを利用して、ボード外形線のオブジェクトを抽出し、指定したレイヤーにコピーします。

► スクリプト動作例

スクリプトの主な構成要素は以下の通りです。

• グローバルなPCB_Board（IPCB_Board型）の変数。
• CopyBoardOutlineサブルーチン（AWidthおよびALayerパラメータを受け取る）。
• スクリプトフォームから幅とレイヤーの値を取得し、CopyBoardOutlineサブルーチンを実行するbOkClickイベントハンドラ。
• Board Outlineスクリプトフォーム（ダイアログ）を閉じるbCancelClickイベントハンドラ。

スクリプトの機能

このスクリプトでは、スクリプトフォームを使用し、OKやCancelボタンなど個々のコントロールのマウスクリックを検出するためのイベントハンドラが必要です。

OKボタンのイベントハンドラは、基本的に以下のようになります。

Sub bOKClick(Sender)
  Dim Width
  Dim Layer

  Call StringToCoordUnit(eWidth.Text,Width,PCB_Board.DisplayUnit)
  Layer = String2Layer(cbLayers.Items(cbLayers.ItemIndex))
End Sub

ここでは、フォームのマウスOnClickイベントハンドラ（bOKClick）がStringToCoordUnit関数を使って、外形線の幅（TEditボックスのeWidth文字列）を内部座標値で取得します。この関数は、現在のボード単位（PCB_Board.DisplayUnitプロパティ）をWidth変数に適用します。

同様に、選択されたレイヤー文字列（フォームTComboBoxのcbLayers項目）はString2Layer関数に渡され、Layer変数の列挙値が取得されます。このプロジェクトでは、フォームのTComboBoxにはインデックス付きのレイヤー文字列リスト（cbLayers.Items）があらかじめ設定されています。レイヤーリストについてはフォームのCopyBoardOutlineForm.dfmファイルをご参照ください。

イベントハンドラ（bOKClick）の最終ステップでは、CopyBoardOutlineサブルーチンをWidthおよびLayer変数をパラメータとして呼び出します。フォームのCancelボタン（bCancelClick）のハンドラは、単にフォームを閉じます。

IPCB_Boardインターフェース

OKボタンハンドラ（bOKClick）内で、現在のボードはIPCB_Boardインターフェースから、特別なPCBServer関数で返されるIPCB_ServerInterfaceを通じて取得されます。ここでGetCurrentPCB関数は、現在のボード参照をPCB_Board変数に設定します。

取得した現在のボード外形線（IPC_BoardOutline）は、スクリプト全体でIPCB_BoardインターフェースのBoardOutlineプロパティを使い、上記のPCB_Boardボード参照から取得します。

外形線をコピー・新規作成する前に初期化する必要があります。外形線はIPCB_BoardOutlineインターフェースで表されており、インターフェースの再構築／検証メソッドを使って初期化できます。

PCB_Board.BoardOutline.Invalidate
PCB_Board.BoardOutline.Rebuild
PCB_Board.BoardOutline.Validate

外形線のアークおよびトラックセグメント

IPCB_BoardOutlineインターフェース（ボード外形線を表す）は、IPCB_Groupインターフェースを継承しています。IPCB_Groupインターフェースは、子オブジェクトを格納できるグループオブジェクトを表します。IPCB_Groupインターフェースの例としては、ポリゴンやボード外形線が挙げられ、これらはアークやトラックを子オブジェクトとして格納できます。

ボード外形線オブジェクトは、ePolySegmentLineとePolySegmentArcの2種類のセグメント（それぞれトラックまたはアークオブジェクト）を格納します。セグメント数はPointCountプロパティ（IPCB_BoardOutlineインターフェース）で決まり、各外形頂点がI変数に抽出され、For-To-Nextループで処理されます。

取得したボード外形線の各セグメントは、If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then文でトラックとアークかどうかを判定します。トラックセグメント（ePolySegmentLine）でない場合、Else部分でそのセグメントがアークであるとみなします。

見つかった各セグメントについて、セグメントの種類に応じてPCBObjectFactory関数を使い新しいトラックまたはアークオブジェクトを作成します。

PCBObjectFactory関数

新しいPCBオブジェクトの作成には、IPCB_ServerInterfaceインターフェースから直接PCBObjectFactory関数を使用します。

'新しいトラックオブジェクトの作成
PCBServer.PCBObjectFactory(eTrackObject, eNoDimension, eCreate_Default)

'新しいアークオブジェクトの作成
PCBServer.PCBObjectFactory(eArcObject, eNoDimension, eCreate_Default)

PCBObjectFactory関数のパラメータで、オブジェクトタイプ（トラック、アーク、ビアなど）、寸法の種類（線形、放射状など）、オブジェクト作成モード（ローカルデフォルトまたはグローバル設定）を指定します。

各トラックまたはアークオブジェクトがPCBObjectFactory手続きで作成された後、そのプロパティは続くトラック／アーク文で初期化されます。

トラックおよびアークのプロパティは、それぞれのインターフェースIPCB_TrackおよびIPCB_Arcによって表されており、関連するプロパティはスクリプトによって実装されています。たとえば、新しいトラックの座標はソースの外形セグメントの頂点から取得され、Track.X1およびTrack.Y1がトラックの初期座標、X2およびY2プロパティが最終座標を表します。

Track.X1     = PCB_Board.BoardOutline.Segments(I).vx
Track.Y1     = PCB_Board.BoardOutline.Segments(I).vy
Track.X2     = PCB_Board.BoardOutline.Segments(J).vx
Track.Y2     = PCB_Board.BoardOutline.Segments(J).vy
Track.Layer  = ALayer
Track.Width  = AWidth

上記のコードスニペットからも分かるように、トラックのLayerおよびWidthプロパティは、ユーザーインターフェースダイアログから抽出された値（フォームのcbLayersおよびeWidth変数）によって単純に定義されています。

すべての定義が完了したら、新しいオブジェクトはPCB_Board.AddPCBObject(NewObject)ステートメントを使ってPCBドキュメントの指定レイヤーに追加されます。ここでNewObjectはTrackまたはArcです。

PreProcessとPostProcess

PCBオブジェクトを作成する際は、最初にIPCB_ServerInterfaceオブジェクトインターフェースのPreProcessメソッドを呼び出してPCBサーバーを準備する必要があります。オブジェクト作成後は、同じくIPCB_ServerInterfaceインターフェースのPostPocessメソッドを適用し、サーバーにオブジェクト追加が完了したことを通知します。

PreProcessおよびPostProcessメソッドは、PCBエディタのUndoシステムや他のサブシステムを最新の状態に保ち、同期させます。以下はPreProcessおよびPostProcessステートメントを含む代表的なコードスニペットです。

PCBServer.PreProcess
'PCBオブジェクトの作成
PCBServer.PostProcess

PCBドキュメントで表示されていないレイヤーにオブジェクトを追加する場合、そのレイヤーを強制的に表示させる必要があります。これはPCB_Board.LayerIsDisplayed(ALayer) = Trueステートメントで処理され、ALayerはユーザーが選択したレイヤーです。

ドキュメントのリフレッシュ

最後に、新しいボード外形を持つPCBドキュメントは、PCB:Zoomコマンドとその関連Action = Redrawパラメータによってリフレッシュされます。ズームコマンドのパラメータは、最初にResetParametersメソッドでパラメータバッファをクリアした後、AddStringParameter手続きで適用されます。

Netlisterプロジェクト

このNetlisterスクリプトプロジェクトの目的は、回路図を含むAltium Designerプロジェクトに対して、標準的なProtelネットリスト（バージョン1またはバージョン2形式）を生成することです。回路図プロジェクトのフラットネットリストは、2つのセクションに分かれます：

• コンポーネントのデジグネータと各コンポーネントに関連する情報
• ネット名と各ネット名に関連する情報、およびピン接続（コンポーネントのピン）

► スクリプト動作例

APIのWorkSpace Manager Object Modelは、プロジェクトおよびその構成要素（ドキュメント、コンポーネントとそのピン、ネット）を表すインターフェースを提供します。WorkSpace Managerは、プロジェクトおよび関連ドキュメントを扱うクライアントモジュールと密接に連携したシステムサーバーです。コンパイル、マルチシート設計サポート、接続性ナビゲーションツール、マルチチャネルサポート、複数の実装ドキュメントなどを提供します。WorkSpace Managerインターフェースを取得するには、GetWorkspace関数を呼び出し、IWorkspaceインターフェースを取得します。

Netlisterスクリプトで注目すべきインターフェースは、IWorkSpace、IProject、IDocument、IComponent、INetインターフェースです。

一部のインターフェース、特に設計オブジェクトインターフェースは、同等のSchematic Objectインターフェースに対応していることに注意してください。これは、プロジェクト内の論理ドキュメントが接続情報を持つ回路図ドキュメントであるためです。実際、Schematic ObjectモデルをWorkSpace Managerの代わりに使用することも可能ですが、WorkSpace Managerはプロジェクトのコンパイルやドキュメントの抽出、回路図オブジェクトからのデータ取得などの機能も提供します。

Netlisterスクリプトの主な構成要素は以下の通りです：

• グローバルなTargetFileName文字列変数（ネットリストのファイル名）
• ネットリストデータが格納されるグローバルNetlistTStringListコレクションオブジェクト
• WriteComponent_Version1およびWriteComponent_Version2手続き
• WriteNet_Version1およびWriteNet_Version2手続き
• ピンの電気的プロパティを文字列に変換するConvertElectricToString関数 データ生成やファイル名、パス、ディレクトリ管理を行うGenerateNetlist手続き

スクリプトの機能

パラメータなしの2つの手続きGenerateProtelV1FormatNetlistおよびGenerateProtelV2FormatNetlistは、Select Item to Runダイアログに表示され、Protel V1形式またはProtel V2形式のネットリスト生成を選択できます。これらの手続きは、ネットリスト形式の選択（0または1）をパラメータとしてGenerateNetlist手続きを呼び出します。

Procedure GenerateProtelV1FormatNetlist;
Var
 Version : Integer;
Begin
 // Protel 1 Netlist format, pass 0
 GenerateNetlist(0);
End;

Procedure GenerateProtelV2FormatNetlist;
Var
 Version : Integer;
Begin
 // Protel 2 Netlist format, pass 1
 GenerateNetlist(1);
End;

GenerateNetList

GenerateNetList手続きは、ワークスペースインターフェースを取得し、現在のプロジェクト（IWorkspace.DM_FocusedProject）のプロジェクトインターフェースを抽出できるようにします。

ネット情報を抽出する前にプロジェクトをコンパイルする必要があります。コンパイル処理によってプロジェクトの接続情報が構築されるためです。プロジェクトインターフェースのDM_Compileメソッド（IProject.DM_Compile）を以下のコードスニペットのように適用します。なお、Altium Designerの最近のバージョンではプロジェクトが自動的にコンパイルされるため、このステップは省略可能です。

WS := GetWorkspace;
 If WS = Nil Then Exit;

Prj := WS.DM_FocusedProject;
 If Prj = Nil Then Exit;

// 設計の接続情報を取得するためにプロジェクトをコンパイル
 Prj.DM_Compile;

コンポーネントおよびネット情報は、後でフォーマット済みネットリストテキストファイルを生成するために使用されるTStringList型のNetlistオブジェクトに格納されます。TStringListオブジェクトは、スクリプトで使用可能なDelphiクラスです。

その後、現在のプロジェクトパスとファイル名、ネットリストフォーマットバージョンを定義するパラメータを渡してGenerate手続きが呼び出されます。

Generate

Generate手続きは、生成されるネットリストファイルの出力先パス（渡されたDocumentPathパラメータから）を取得し、ネットリストファイル名（TargetFileName）を決定し、プロジェクトのフラット化状態（IProject.DM_DocumentFlattened）を確認します。

プロジェクト内のすべての回路図ドキュメントについて、各ドキュメントのネットおよびコンポーネントをWriteNetsおよびWriteComponents手続きでチェックし、最終的にNetlistオブジェクトに抽出します。

ネットおよびコンポーネントの書き出し

ネットリストはコンポーネントセクションとネットセクションで構成されるため、コンポーネントデータとネットデータを個別に書き出す2つの手続きが必要です。

ノード数が2つを超えるネットのみがネットリストに書き出され、それ以下のものは破棄されます。各ネットについては、ネット名はNetのDM_CalculatedNetNameメソッドに基づいており、これはコンパイル済みプロジェクトの接続情報からネット名を抽出します。

以下は、バージョン1のネットリスト形式における「Components」セクションと「Nets」セクションの2つのコードスニペットです。コンポーネントおよびネットのデータは NetList オブジェクト（TStringList 型）に格納されます。生成されるネットリストは、コンポーネント情報セクションとネット情報セクションの2つで構成されています。

コンポーネントセクション

WriteComponent プロシージャでは、プロジェクトから見つかった各コンポーネントが実際のコンポーネントかどうかを確認し、その後、物理デジグネータ、フットプリント、パートタイプの値を抽出します。これらの情報はネットリストオブジェクトコンテナ（NetList.Add）に追加され、ネットリスト自体が構築されます。

If Component <> Nil Then
Begin
 NetList.Add('[');
 NetList.Add(Component.DM_PhysicalDesignator);
 NetList.Add(Component.DM_FootPrint);
 NetList.Add(Component.DM_PartType);
 NetList.Add('');
 NetList.Add('');
 NetList.Add('');
 NetList.Add(']');
End;

ネットセクション

Netsプロシージャでは、ネットに2つ以上のピン（INet.DM_PinCount）がある場合、NetNameとデジグネータが抽出されます。ネットおよびピン情報と書式設定用の文字が Netlist コンテナに追加され、ネットリストが構築されます。以下のスニペットは、バージョン1ネットリストのネット書き込みプロシージャです。

If Net.DM_PinCount >= 2 Then
Begin
NetList.Add('(');
NetList.Add(Net.DM_CalculatedNetName);
For i := 0 To Net.DM_PinCount – 1 Do
Begin
   Pin := Net.DM_Pins(i);
   PinDsgn := Pin.DM_PhysicalPartDesignator;
   PinNo := Pin.DM_PinNumber;
   NetList.Add(PinDsgn + '-' + PinNo);
End;
NetList.Add(')');
End;

より詳細なネットリスト形式であるProtel v2では、ネットピンの電気的特性（In、Out、Passive、HiZ など）が含まれている点に注意してください。

バージョン2形式（WriteNet_Version2）のネット書き込みプロシージャでは、各ネットピンの電気的特性（INet.DM_Electical）を調べ、呼び出された ConvertElectricToString プロシージャによって変換されます（本質的には文字列変換のルックアップテーブルです）。これらはローカルの文字列変数（ElectricalString）に追加され、最終的にNetlistコンテナオブジェクトに追加されます。

ネットリストファイルの作成

最後に、Netlist コンテナオブジェクトにプロジェクトのコンポーネントおよびネット情報が選択した形式で完全に格納されたら、Generate プロシージャが Netlist データをファイル（TStringList.SaveToFile）に書き込みます。ファイルのパスと名前は TargetFileName 文字列変数で定義され、Generate プロシージャで決定されます。