Revit ファミリAPI – その１

2週間ほど前に、「Revitファミリの作成の秘訣」というタイトルで、Revitファミリの作成の際の概念、特にパラメトリックなモデルを作成する上で大切な考え方や注意点を「骨格、筋肉、皮」にたとえてお話しました。今回は、その手順に従ってAPIで作成する方法のお話をしたいと思います。 

（なお、コードは、Revit ADN Open のサイトにポストしてあるRevit 2013/2014 API Labs にありますので、必要に応じて参考にしてください。）

概要

まず、ファミリAPIの定義ですが、私たちがファミリAPIと呼んでいるのは、Revit APIの一部で、UIでいうファミリ エディタの部分に相当します。ファミリ
エディタでは、窓や扉、柱といった、いわゆるコンポーネントファミリを作成することが可能です。壁や屋根といった要素は、システムファミリに属し、これらは、ファミリエディタでは編集できませんが、この点はAPIに関しても同じです。基本的に、ファミリAPIはファミリ エディタの部分を公開したAPIです。

ファミリAPIをもちいることにより、ファミリのライブラリの生成を自動化したり、あるいは、Revitプロジェクトの実行中に、他のライブラリやデータベースにアクセスして、適宜ファミリを作成したりすることが可能となります。また、既存のファミリから情報を抽出し、修正することも可能です。手順は基本的にはUIに類似しますが、いくつかの相違点と制限があります。これについては後ほど適宜触れることにします。

ファミリAPI特有のクラスとメソッド

ファミリのコンテキストで使用される特有のクラスとメソッドには以下があります。

FamilyManagerクラス：

• タイプの追加/削除/名前を変更、パラメータの追加/削除、値と数式の設定に使用します。

ファミリのコンテキストに固有なドキュメントのメソッド：

• IsFamilyDocument – 現在開いているドキュメントが、ファミリのドキュメントであるかどうかを識別します。
• OwnerFamily – このファミリドキュメントを所有するファミリを返します。
• FamilyManager – ファミリの種類やパラメータへのアクセスを提供するFamilyManagerオブジェクトを返します。
• FamilyCreate –　ファミリドキュメント内で新しいインスタンス要素を作成するFamilyItemCreateオブジェクトを返します。プロジェクトで作成するオブジェクトに類似します。
• EditFamily – プロジェクトドキュメントにロードされているファミリを編集します。

ベストプラクティスに準じたファミリAPIの使用例

それでは、ベストプラクティスに沿ったファミリAPIを、単純なL字型柱ファミリを例にとって見ていきましょう。ベストプラクティス、あるいは最適な手順としては、以下を常に意識する必要があることをお話しました：

• 計画
• 参照面
• パラメータ
• タイプ
• ジェオメトリ（幾何）

具体的には、以下の手順を踏むことになります：

1．計画

２．参照面の設定

３．パラメータの追加

４．タイプの追加

５．パラメトリックな動作のテスト – フレックス（Flex）

６．ジェオメトリの追加

7. 拘束（alignment）の追加

８．ステップ５～８を繰り返す

今回は、その前半にあたる１～５のお話をしたいと思います。

 

1．計画

UIと同様、まずは、作成しようとするファミリがどういった動きをするかを考える必要があります。正しいテンプレートを選択します。例えば、ここでは、「Metric Column.rft」を選択します。そして、テンプレートを理解します。テンプレートにはあらかじめ基本となる参照面や寸法線が名前付きで定義されています。

API でファミリを作成、編集する場合、まず与えられたドキュメントがファミリドキュメントであるかどうかを確認する必要があります。また、目的に応じたテンプレートやファミリのファイルを使用します。以下のコードでは、柱のファミリテンプレートであることを確認しています：

Function ValidateDocument(ByVal rvtDoc As Document) As Boolean

  ‘ 現在のドキュメントは、ファミリドキュメントであるかどうかをチェック

  If Not
rvtDoc.IsFamilyDocument Then

    TaskDialog.Show(

      “Family
API”, “このドキュメントはファミリドキュメントではありません。”)

    Return False

  End If

  ‘ 正しいテンプレートかどうかをチェック。このドキュメントのオーナーファミリを取得

  Dim ownerFamily As Family = rvtDoc.OwnerFamily

  If ownerFamily Is Nothing Then

    TaskDialog.Show(
      “Family
API”, “このドキュメントはオーナーファミリーを含みません。”)

    Return False

  End If

  ‘ このドキュメントのオーナーファミリのカテゴリをチェック。

  Dim
catColumn As
Category = _
    rvtDoc.Settings.Categories.Item(BuiltInCategory.OST_Columns)

    If Not
ownerFamily.FamilyCategory.Id.Equals(catColumn.Id) Then

      TaskDialog.Show(
        “Family
API”, “Metric
Column.rfを使用してください。”)

    End If

  Return True

End Function

２．参照面の設定

次に参照面を追加します。例えば、L字型の柱の断面形状を定義する場合、縦・横方向に追加します。そしてそれらに名前をつけます。ここでは、OffsetV、OffsetHといった名前にすることします。

以下が、縦の参照面OffsetVの作成例です。ここでは、FamilyCreate.NewReferencePlane（）メソッドを用いています。（コードをわかりやすくするために、ビューの取得には、ユーティリティを用いた形で書いていますが、すでにRevit APIの基本を修得されている方にとっては、エレメントフィルターを用いた基本的な操作であることはお分かりかと思います。）

Sub AddReferencePlane_VerticalOffset()

    ‘ 参照面の作成。NewReferencePlane
を使用。

    Dim pt1 As New XYZ(-0.5, -2.0, 0.0) ‘ 端点

    Dim pt2 As New XYZ(-0.5, 2.0, 0.0)  ‘ もう一方の端点

    Dim vec As
XYZ = XYZ.BasisZ         ‘ 最初のラインに垂直方向

    Dim
view As
View = _

      Utils.FindElement(rvtDoc, GetType(ViewPlan), “Lower Ref. Level”)

    Dim refPlane As ReferencePlane = _
      m_rvtDoc.FamilyCreate.NewReferencePlane(pt1,
pt2, vec, view)

    refPlane.Name = “OffsetV”

End Sub

参照面の作成にはもうひとつのメソッド、NewReferencePlane2()  があります。これは、3つの点を指定して、参照面を定義します。

Sub AddReferencePlane_VerticalOffset2()

    ‘ 参照面の作成。NewReferencePlane2を使用

    Dim
pt1 As New XYZ(-0.5, -2.0, 0.0) ‘ 第一端点

    Dim pt2 As New XYZ(-0.5, 2.0, 0.0)  ‘ 第二端点

    Dim pt3 As New XYZ(-0.5, -1.0, 1.0) ‘ 第三端点 

    Dim
view As
View = _

      Utils.FindElement(rvtDoc, GetType(ViewPlan), “Lower Ref. Level”)

    Dim refPlane As ReferencePlane = _
      m_rvtDoc.FamilyCreate.NewReferencePlane2(pt1,
pt2, pt3, view)

    refPlane.Name = “OffsetV”

End Sub

３．パラメータの追加

次にパラメータと寸法線を追加します。例えば、左側にある縦の参照面の寸法をパラメータTwとすることとします。

パラメータの追加には、FamilyManagerクラスのAddParameter()を使用します。以下が、Twの定義例です。

Dim m_familyMgr As FamilyManager = m_rvtDoc.FamilyManager

Sub AddParameter_Tw()

    ‘ パラメータ
“Tw”の追加

    Dim
isInstance As Boolean = False

    Dim
paramTw As
FamilyParameter = _
        m_familyMgr.AddParameter(
_
            “Tw”, _
            BuiltInParameterGroup.PG_GEOMETRY,
_　’ パラメータのグループ

            ParameterType.Length, _

　　　　　　　isInstance)

    ‘ 初期値を与える

    Dim tw As Double = Utils.mmToFeet(150.0) ‘ メトリック

    ‘Dim
tw As Double = 0.5  ‘ フィート

    m_familyMgr.Set(paramTw, tw)

    ‘ フォーミュラ（数式）を追加（オプション）

    m_familyMgr.SetFormula( _
        paramTw, “Width / 4.0“)

End Sub

パラメータColume Finish はここでは仕上げのマテリアルです。グループをマテリアルとします。また、今回は、タイプ パラメータではなく、インスタンス  パラメータとします。

Sub AddParameter_Material()

    ‘ “Column
Finish” パラメータの追加

    Dim param As FamilyParameter = _

        m_familyMgr.AddParameter( _

            “Column
Finish”, _

            BuiltInParameterGroup.PG_MATERIALS, _

            ParameterType.Material, _

            True)

    ‘ 後ほどソリッドへの追加を行います。

End Sub

次に寸法線を追加します。ここでも、Twを例にとった例を示します。ここでの作業では、FamilyCreate.NewDimension() をもちいて寸法線を作成しています。そして、pDimTw.Labelで、寸法線のラベルにパラメータTwを結び付けているところに注目してください。

Sub AddDimention_Tw()

    ‘ 寸法線を追加する平面ビューを取得

    Dim pViewPlan As View = _
        Utils.FindElement( _

            m_rvtDoc, GetType(ViewPlan), “Lower Ref. Level”)

    ‘ 寸法線を追加する2つの参照面を取得 

    Dim ref1 As
ReferencePlane = _
        Utils.FindElement( _

            m_rvtDoc, GetType(ReferencePlane), “Left”)

    Dim ref2 As
ReferencePlane = _
        Utils.FindElement( _

            m_rvtDoc, GetType(ReferencePlane), “OffsetV”)

    ‘ 参照面の配列の作成

    Dim pRefArray As New
ReferenceArray

    pRefArray.Append(ref1.Reference)

    pRefArray.Append(ref2.Reference)

    ‘ 寸法線の定義

    Dim p0 As
XYZ = ref1.FreeEnd

    Dim p1 As
XYZ = ref2.FreeEnd

    Dim pLine As Line = Line.CreateBound(p0, p1)

    ‘ 寸法線の作成

    Dim pDimTw As Dimension = _
        m_rvtDoc.FamilyCreate.NewDimension(
_

            pViewPlan, pLine, pRefArray)

    ‘ 寸法線にラベルをつける

    pDimTw.Label =
m_familyMgr.Parameter(“Tw”)

End Sub

4．タイプの追加

次に、２つ以上のタイプを追加します。

以下の関数は与えられた名前とパラメータの値で、1つのタイプを定義します。ファミリマネージャークラスのFamilyManager.
NewType()メソッドを用いてタイプを新規作成します。また、パラメータに値をセットするのもFamilyManagerのSet() 関数をもちいます。

Sub AddType( _

    ByVal name As String, _

    ByVal w As Double, _

    ByVal d As Double)

    ‘ 与えられた名前で新しいタイプの追加

    Dim
type1 As
FamilyType = m_familyMgr.NewType(name)

    ‘ ‘Width’
と
‘Depth’ パラメータの値を定義

    Dim paramW As FamilyParameter = m_familyMgr.Parameter(“Width”)

    Dim valW As Double = Utils.mmToFeet(w)

    If paramW IsNot Nothing Then

        m_familyMgr.Set(paramW,
valW)

    End If

    Dim paramD As FamilyParameter = m_familyMgr.Parameter(“Depth”)

    Dim valD As Double = Utils.mmToFeet(d)

    If paramD IsNot Nothing Then

        m_familyMgr.Set(paramD, valD)

    End If

End Sub

上で定義した関数を用いて3つのタイプを定義します。

Sub AddTypes()

      ‘ AddType(name,Width,Depth)

      AddType(“600×900”, 600.0, 900.0)

      AddType(“1000×300”, 1000.0, 300.0)

      AddType(“600×600”, 600.0, 600.0)

End Sub

5．パラメトリックな動作のテスト – フレックス（Flex）

ここで一度テストを行ってみてください。

ここまでの時点では、ジェオメトリがまだ、定義されていないので、本来なら、ファミリーをプロジェクトにロードしても、何も目に見える要素はなく、意味がないように思われるかもしれません。実はこの時点で、テストをしておくのはとても大切なことなのです。以前お話したように、ジェオメトリは「皮」に過ぎず、動作を定義するのはあくまで、骨格と筋肉 – 参照面とパラメータでコントロールされる寸法線なのです。パラメータや寸法を変更してみて、意図した動きをするかどうか確認する作業をフレックス（Flex）と呼んでいます。

上記のコードで作成されたタイプをUIで選択して、意図したように参照面の位置が変更されるかどうか確認してみてください。

さて、参照面がパラメータによって、意図する動きが加わったら、ここでようやくジェオメトリの追加です。

少々ブログのポストが長くなりましたので、今日のところは、これくらいにさせていただいて、次回に　「６．ジェオメトリの追加」からのお話をさせていただくこととします。

原田