Qiita Revit API アドベントカレンダー2024の13日目の記事です。
（前回の記事はこちら）
今回の内容
今回は、Revitアドインの基本中の基本である要素(Element)の抽出方法について整理したいと思います。
要素とは
本題に入る前に、Revitにおける「要素(Element)」について再確認しましょう。
Revitのモデル内に含まれる情報は、基本的にこの要素として表現されています。
モデル上に実際に配置されるインスタンスはもちろんのこと、その定義情報であるところのタイプやファミリなども要素の一種となります。
Revit APIでのプログラミング上では、要素はElementクラスという基本クラスに該当し、以下のような共通機能を提供しています。（以下は一例）
- ID(rvtファイル毎に一意の通し番号)
- UniqueId(rvtファイルに関わらず一意で割り振られるユニークなID)
- パラメタ
- カテゴリ
- 名前
- 位置及びレベル
- 所属ドキュメント
余談ですが、Revit2024よりIDに使用される数値（rvtファイル内での通し番号）のデータサイズが32bit整数値から64bit整数値に拡大されました。
バージョン間の移植時には注意が必要です。
後述する要素抽出方法（フィルタによるもの、ユーザの選択操作によるもの、等）では、基本的にこのElement型（またはElement型を導出することができるElementId型やそれらを導出できる情報）で結果を取得でき、必要に応じてダウンキャストを用いることで特定の型に変換できます。
Elementの抽出（取得）方法の分類
Revit APIを用いてElement型のオブジェクトを取得する方法は、大きく分けると以下のようなものがあります。
| 取得方法 | 利用API | 説明 |
|---|---|---|
| 1.フィルタによる抽出 | FilterdElementCollector | カテゴリやBoundingBoxなどの各種抽出条件を組み合わせて、ドキュメント内に存在するすべての要素から条件に合うものをリストで取得できる。 |
| 2.要素識別子の直接指定 | Document.GetElement | 要素を識別する情報（ElementId、ユニークID、参照）からElementを直接取得する。ElementIdを経由することで通し番号（整数値）やGuid、BuiltinParameterから取得することも可能。 |
| 3.パラメタからの取得 | Parameter.AsElementId | パラメタの種類がElementIdになっているもの（Parameter.StorageTypeがStorageType.ElementIdのもの）の場合に取得できる。 |
| 4.3Dモデル上の視線方向ヒットテスト | ReferenceIntersector | 3Dビューとフィルタ、Ray（半直線で表現する視線方向）などを指定することで、3D的に干渉する要素の参照を順次取得できる。（参照経由で要素の取得が可能） |
| 5.選択中要素 | Selection.GetElementIds | 呼び出し時点で選択中とされている要素のリストを取得できる。 |
| 6.ユーザによる選択 | Selection.PickObject Selection.PickObjects Selection.PickElementsByRectangle |
ユーザ入力待ちを発生させ、ユーザが選択操作を行った対象の要素または要素への参照を取得できる。 |
以下で、それぞれの取得方法について解説していきます。
1.フィルタによる抽出
指定したDocumentからElementを抽出する FilteredElementCollector クラスと、抽出条件を指定してフィルタリングを行う ElementFilter 派生クラスにより要素を列挙する方法です。
メソッドチェーンの形で複数のフィルタや遅延実行処理をつなげることも可能です。
FamilyInstance[] familyInstances = new FilteredElementCollector(doc)
.OfCategory(BuiltInCategory.OST_StructuralFraming) // カテゴリフィルタ
.OfClass(typeof(FamilyInstance)) // 型フィルタ
.WherePasses(new BoundingBoxContainsPointFilter(point)) // ElementFilterクラスの指定
.Where(fi => fi.Symbol.FamilyName == "ABCファミリ") // ラムダ式による絞り込み
.Cast<FamilyInstance>() // キャスト
.ToArray(); // 配列化（即時実行）
上記コード例に示す通り、LINQの遅延実行をメソッドチェーン内に含めることで、配列等のコンテナ領域確保処理を1回だけにとどめることが可能です。
フィルタの分類（高速・低速・結合）
Revitで用意されている要素フィルタは大きく３種類に分類されます。
- 論理フィルタ（ElementLogicalFilter派生クラス）
- 高速フィルタ（ElementQuickFilter派生クラス）
- 低速フィルタ（ElementSlowFilter派生クラス）
論理フィルタ
論理フィルタはANDフィルタ(LogicalAndFilter)とORフィルタ(LogicalOrFilter)の二種類です。
これらはその名の通り、コンストラクタで指定した2つのフィルタについてAND条件（両方の条件に合致している要素を抽出する）及びOR条件（いずれかの条件に合致している要素を抽出する）でのフィルタリングを行います。
var filter1 = new ElementClassFilter(typeof(FamilyInstance));
var filter2 = new ElementCategoryFilter(BuiltInCategory.OST_Doors);
var doorInstancesFilter = new LogicalAndFilter(filter1, filter2);
FilteredElementCollector collector = new FilteredElementCollector(doc);
IList<Element> doors = collector.WherePasses(doorInstancesFilter).ToElements();
但し、「絞り込み」という性質上、ANDフィルタを使用しなくても複数フィルタを指定した場合は必然的にAND条件になるため、一般的にはANDフィルタを利用する必要性はありません。
高速フィルタ
高速フィルタは各要素のデータをメモリ展開しなくても（索引情報だけで）フィルタの適合・不適合の判断が可能な内容についてのフィルタです。
高速フィルタで「足切り」を行っておくことで、詳細情報を参照する要素の数が限定され、抽出処理の高速化につながります。
| 高速フィルタクラス | 説明 |
|---|---|
| BoundingBoxContainsPointFilter | 指定点が要素のBoundingBoxに含まれるか？ |
| BoundingBoxIntersectsFilter | 指定したBoundingBoxが要素のBoundingBoxと干渉するか？ |
| BoundingBoxIsInsideFilter | 指定したBoundingBoxが要素のBoundingBoxに内包されるか？ |
| ElementCategoryFilter | 指定カテゴリか？(OfCategoryと同等) |
| ElementMulticategoryFilter | 指定されたカテゴリか？（複数指定） |
| ElementClassFilter | 指定された型か？(OfClassと同等) |
| ElementMulticlassFilter | 指定された型か？（複数指定） |
| ElementIdSetFilter | 指定されたIdか？（複数指定） |
| ExclusionFilter | 指定されたId以外か？（複数指定） |
| ElementOwnerViewFilter | 指定されたビューが所有する要素か？ |
| VisibleInViewFilter | 指定したビューで表示される要素か？ |
| ElementIsElementTypeFilter | ElementTypeか？ |
| FamilySymbolFilter | 指定したファミリシンボルか？ |
| ElementDesignOptionFilter | 指定されたDesign Optionか？ |
| ElementIsCurveDrivenFilter | LocationがLocationCurveで表現される要素か？ |
| ElementStructuralTypeFilter | 指定されたStructuralTypeか？ |
| ElementWorksetFilter | 指定されたWorkSetか？ |
| ExtensibleStorageFilter | 指定したGuidの拡張ストレージを持つ要素か？ |
低速フィルタ
低速フィルタは既定義のフィルタではあるものの、各要素の詳細情報を参照しないと適合の有無を判断できないような条件を判断するため、高速フィルタよりは処理時間を要するフィルタです。
可能な限り高速フィルタで絞り込んだ後で、これらの低速フィルタを利用するのが望ましいとされています。
| 低速フィルタクラス | 説明 |
|---|---|
| RoomFilter | 要素が部屋か？ |
| RoomTagFilter | 要素が部屋タグか？ |
| AreaFilter | 要素がエリアか？ |
| AreaTagFilter | 要素がエリアタグか？ |
| SpaceFilter | 要素がスペースか？ |
| SpaceTagFilter | 要素がスペースタグか？ |
| CurveElementFilter | 指定したCurveElementTypeに該当する要素か？ |
| ElementIntersectsElementFilter | 指定した要素と干渉している要素か？ |
| ElementIntersectsSolidFilter | 指定したSolidと干渉している要素か？ |
| ElementLevelFilter | 指定したレベルか？ |
| ElementParameterFilter | 指定したパラメタのFilterRuleに合致する要素か？ |
| ElementPhaseStatusFilter | 指定したPhase Statusに合致する要素か？ |
| FamilyInstanceFilter | 指定したファミリシンボルに合致するファミリインスタンスか？ |
| PrimaryDesignOptionMemberFilter | 要素がPrimary Design Optionか？ |
| FamilyStructuralMaterialTypeFilter | 指定したStructuralMaterialTypeに合致する要素か？ |
| StructuralInstanceUsageFilter | 指定したStructuralInstanceUsageに合致する要素か？ |
| StructuralMaterialTypeFilter | 指定したStructuralMaterialTypeに合致する要素か？ |
| StructuralWallUsageFilter | 指定したStructuralWallUsageに合致する要素か？ |
| SelectableInViewFilter | 指定されたビューから選択可能な要素か？ |
少し長くなったので今日はここまで。
次回は引き続き要素抽出方法の2～6について説明します。
このシリーズの予定
(1) RevitAPIについてのリンク集
(2) Revitでの幾何計算(1)
(3) Revitでの幾何計算(2)
(4) Revit APIで要素を抽出する(1) ★今回★
(4b) Revit APIで要素を抽出する(2)
(5) Revitアドインのエントリーポイント
(6) RevitでCADっぽい挙動（ラバー・一時図形・ラージカーソル）を実現してみる
(7) Revitアドイン開発 Debug Tips