The Building Coder

Extract Part Atoms

Last week, we discussed how to use the Revit API to read the values of family parameters.

Another quick way to access all non-empty parameter values in a family file and see some other interesting family data as well is to simply make a call to the Application.ExtractPartAtomFromFamilyFile method.

It is mentioned in the What's New section of the Revit 2010 API help file. Its purpose is to export family data to XML for integration with Autodesk Seek. It opens an existing family file on disk and creates an XML file with data used by Autodesk Seek for content search. It takes two string arguments, the family file path and the path of an XML file to be generated. If there is a TXT type catalogue next to the family file (a TXT file with the same name as the RFA file), it will read that as well and process its contents into part atoms. The usage is simple:

if( doc.IsFamilyDocument )
{
  string path = doc.PathName;
  if( 0 < path.Length )
  {
    app.ExtractPartAtomFromFamilyFile(
      path, path + ".xml" );
  }
}

I used the same simple column family generated by the Family API Lab 4 command which we used to examine the family parameter values, saved it to a file named 'column.rfa', and ran the code shown above to generate 'column.rfa.xml' with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:A="urn:schemas-autodesk-com:partatom">
  <title>column</title>
  <id></id>
  <updated>2009-11-11T08:12:08Z</updated>
  <A:taxonomy>
    <term>adsk:revit</term>
    <label>Autodesk Revit</label>
  </A:taxonomy>
  <A:taxonomy>
    <term>adsk:revit:grouping</term>
    <label>Autodesk Revit Grouping</label>
  </A:taxonomy>
  <category>
    <term>23.25.30.11.14.11</term>
    <scheme>std:oc1</scheme>
  </category>
  <category>
    <term>Columns</term>
    <scheme>adsk:revit:grouping</scheme>
  </category>
  <link rel="design-2d" type="application/rfa" href=".">
    <A:design-file>
      <A:title>column.rfa</A:title>
      <A:product>Revit</A:product>
      <A:product-version>2010 or later one</A:product-version>
      <A:updated>2009-11-11T08:12:08Z</A:updated>
    </A:design-file>
  </link>
  <A:family type="user">
    <A:variationCount>4</A:variationCount>
    <A:part type="user">
      <title>600x900</title>
      <Tw units="mm">150</Tw>
      <Td units="mm">225</Td>
      <Depth units="mm">900</Depth>
      <Width units="mm">600</Width>
    </A:part>
    <A:part type="user">
      <title>1000x300</title>
      <Tw units="mm">250</Tw>
      <Td units="mm">75</Td>
      <Depth units="mm">300</Depth>
      <Width units="mm">1000</Width>
    </A:part>
    <A:part type="user">
      <title>600x600</title>
      <Tw units="mm">150</Tw>
      <Td units="mm">150</Td>
      <Depth units="mm">600</Depth>
      <Width units="mm">600</Width>
    </A:part>
    <A:part type="user">
      <title>Glass</title>
      <Tw units="mm">150</Tw>
      <Td units="mm">150</Td>
      <Depth units="mm">600</Depth>
      <Width units="mm">600</Width>
    </A:part>
  </A:family>
</entry>

You can see the same four types with the same parameter values listed. The unnamed type is skipped, as well as empty parameter values. I also note that the ColumnFinish material parameter does not appear here.

Family Parameter Value

Pramod asked an interesting question on obtaining the values of family parameters in a family document which led me to explore this topic and discover a little more complexity than I was originally expecting:

Question: We are using the API of Revit Architecture 2010. We want to get all Parameters and their values from the Family document. We are referring to the AutoParameter example from the Revit SDK. With the help of this example, we are able to get parameters of Family, but didn't get any property or method for getting Value of those parameters. So please give any code example for getting values of the Family Parameters.

Answer: I dug around a bit to provide an answer for you, and was surprised at the result. I had not previously noticed the additional level of indirection required to access a family parameter value.

Before we start working on reading family parameter values, let me mention that the addParameters method in the Revit Family API labs provides a sample demonstrating how to create family parameters and set their values.

The family has two main aspects, the geometry and the parameter data. Some of the parameters can be used to drive the geometry, so the two areas are interlinked. The data is stored in parameters, and the family contains a set of predefined types which already have predefined values for certain parameters. The family parameter has a pointer to its definition which specifies the name and data type, just like a project parameter. However, it does not have a parameter value, because the values are specific to the family types. Instead, each family type has its own value for each of the family parameters.

One of the main objects in the family document is its family manager, which manages its family types and parameters. A family parameter looks a lot like a normal Revit parameter on a BIM element instance, and has many of the same properties such as the Definition property which defines the parameter name and data type. The big difference between a family and a non-family parameter is that the latter has a value and the former does not.

In a project document, a parameter has a pointer to the parameter definition which defines its name and data type and other properties, and the main data item of the individual parameter is its own personal parameter value. A family parameter has one additional level of complexity and indirection, since the family parameter values are defined individually for each of the family types.

When you retrieve a value for a parameter from a family type, you have to supply the family parameter instance to specify which parameter value to retrieve.

I created a new Building Coder sample command named CmdFamilyParamValue to demonstrate how to read the values of family parameters.

First of all, it ensures that we are running in a family document:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
if( !doc.IsFamilyDocument )
{
  message =
    "Please run this command in a family document.";
}
else

In order to retrieve a parameter value from a family type, we need to provide a pointer to the family parameter instances that we are interested in, so we start off by creating a dictionary containing all the family parameters and mapping their names to the corresponding object instances:

FamilyManager mgr = doc.FamilyManager;
 
int n = mgr.Parameters.Size;
 
Debug.Print(
  "\nFamily {0} has {1} parameter{2}.",
  doc.Title, n, Util.PluralSuffix( n ) );
 
Dictionary<string, FamilyParameter> fps
  = new Dictionary<string, FamilyParameter>( n );
 
foreach( FamilyParameter fp in mgr.Parameters )
{
  string name = fp.Definition.Name;
  fps.Add( name, fp );
}
List<string> keys = new List<string>( fps.Keys );
keys.Sort();

I create a sorted list of the parameter names, so that the final result will be sorted and thus more readable.

Before we move on to the iteration over the family types and determining the family parameter values for each, here is a helper method to retrieve and format the family parameter value as a string. I noticed that a string-valued parameter value can only be retrieved using AsString, and AsValueString returns an empty string for it, so I implemented a switch statement and an optimal specialised access and display for each storage type:

static string FamilyParamValueString( 
  FamilyType t, 
  FamilyParameter fp, 
  Document doc )
{
  string value = t.AsValueString( fp );
  switch( fp.StorageType )
  {
    case StorageType.Double:
      value = Util.RealString(
        ( double ) t.AsDouble( fp ) )
        + " (double)";
      break;
 
    case StorageType.ElementId:
      ElementId id = t.AsElementId( fp );
      Element e = doc.get_Element( ref id );
      value = id.Value.ToString() + " ("
        + Util.ElementDescription( e ) + ")";
      break;
 
    case StorageType.Integer:
      value = t.AsInteger( fp ).ToString()
        + " (int)";
      break;
 
    case StorageType.String:
      value = "'" + t.AsString( fp )
        + "' (string)";
      break;
  }
  return value;
}

With the helper method in hand, we can iterate over the family types and display their family parameter values. We use HasValue to determine whether a type has a value for each parameter, retrieve its value, and display the result:

n = mgr.Types.Size;
 
Debug.Print(
  "Family {0} has {1} type{2}{3}",
  doc.Title,
  n,
  Util.PluralSuffix( n ),
  Util.DotOrColon( n ) );
 
foreach( FamilyType t in mgr.Types )
{
  string name = t.Name;
  Debug.Print( "  {0}:", name );
  foreach( string key in keys )
  {
    FamilyParameter fp = fps[key];
    if( t.HasValue( fp ) )
    {
      string value 
        = FamilyParamValueString( t, fp, doc );
 
      Debug.Print( "    {0} = {1}", key, value );
    }
  }
}

Here is the result of opening a new family document based on the Metric Column template, running the Family API lab 4 command to create a simple column family and some types, and then listing the family parameter values using CmdFamilyParamValues:

Family Family1 has 13 parameters.
Family Family1 has 5 types:
   :
    ColumnFinish = -1 ()
    Depth = 1.97 (double)
    Td = 0.49 (double)
    Tw = 0.49 (double)
    Width = 1.97 (double)
  1000x300:
    ColumnFinish = -1 ()
    Depth = 0.98 (double)
    Td = 0.25 (double)
    Tw = 0.82 (double)
    Width = 3.28 (double)
  600x900:
    ColumnFinish = -1 ()
    Depth = 2.95 (double)
    Td = 0.74 (double)
    Tw = 0.49 (double)
    Width = 1.97 (double)
  Glass:
    ColumnFinish = 574 (Materials <574 Glass>)
    Depth = 1.97 (double)
    Td = 0.49 (double)
    Tw = 0.49 (double)
    Width = 1.97 (double)
  600x600:
    ColumnFinish = -1 ()
    Depth = 1.97 (double)
    Td = 0.49 (double)
    Tw = 0.49 (double)
    Width = 1.97 (double)

Apparently, it includes one unnamed type as well as the four that our sample created intentionally.

I hope this clarifies the structure and usage of family parameters and possibly provides a useful additional little utility for your tool kit.

Here is version 1.1.0.53 of the complete Building Coder sample source code and Visual Studio solution including the new command.

Revit Family Creation API Labs

The handouts and presentation for my Autodesk University family API session are finally done, as well they should be, since they are due to be submitted by today. The last part I worked on was to add more documentation on the family API labs to the handout document. I think this overview will be of interest here as well. The family API labs were originally created and documented by Mikako Harada, the ADN AEC workgroup lead, so all of the material presented here is due to her. Talking about that prompts me to mention the webcasts where this material was first used:

ADN webcast registration statistics

Most of the material that I am presenting at AU was originally prepared for webcasts on the Revit Family API and MEP API and then posted to this blog as well. Mikako just sent around some statistics on the numbers of registrations for the various webcasts held by the Autodesk Developer Network this year. The overview of all webcasts and other training classes is available online from the Autodesk Developer Network API training schedule. All in all, we presented on 25 different topics and had a total of 1576 attendees registered. The absolute leader in the number of registrations was the Revit API webcast with 250, followed by the Inventor API with 100. The Revit family and MEP API webcasts were also pretty popular with 75 and 64 respectively, so the three Revit webcasts together attracted 389 out of 1576 registrations or about 25%. This just goes to show that the Revit API is an important and popular topic.

Family API Labs: Creating an Example Family

Returning to the Revit Family API Labs, they are a collection of exercises which introduce you step by step to the creation of a column family. The objective is to learn the basics of the family API. The labs start at zero and proceed through the absolute beginning steps up to slightly more advanced aspects. Here are the four steps of increasing complexity covered:

1. Define a rectangular profile column family.
2. Define an L-shaped profile column family.
3. Add formulae and materials.
4. Add visibility control.

The full Visual Studio solution and projects, source code, detailed documentation and instructions for each step are included separately for both C# and VB. Here is an overview of the main files and directories:

• rfa_labs.sln – common C# and VB Visual Studio solution file
• cs – C# source code directory
  • LabsCs.csproj
  • 1_ColumnRectangle.cs
  • 2_ColumnLshape.cs
  • 3_ColumnFormulaMaterial.cs
  • 4_ColumnVisibility.cs
  • Util.cs
• csdoc – C# documentation and detailed step-by-step instructions directory
  • Family Lab1 - Create Rectangular Column_CS.rtf
  • Family Lab2 - Create L-Shape Column_CS.rtf
  • Family Lab3 - Add Formula and Material_CS.rtf
  • Family Lab4 - Add Visibility Control_CS.rtf
• vb – VB source code directory
  • LabsVb.vbproj
  • 1_ColumnRectangle.vb
  • 2_ColumnLshape.vb
  • 3_ColumnFormulaMaterial.vb
  • 4_ColumnVisibility.vb
• vbdoc – VB documentation and detailed step-by-step instructions directory
  • Family Lab1 - Create Rectangular Column.rtf
  • Family Lab2 - Create L-Shape Column.rtf
  • Family Lab3 - Add Formula and Material.rtf
  • Family Lab4 - Add Visibility Control.rtf

The source code and instruction documents are part of the Family API webcast materials. For your convenience, I am including them here as well.

The following summary provides a high-level overview of the implementation. Detailed information and step-by-step instructions are provided in the source code comments and the dedicated csdoc and vbdoc documents.

Lab 1 – Create Rectangular Column

The first lab demonstrates how to implement the following four essential basic steps for creating a new family:

1. Check the family context and category.
2. Create a simple solid using extrusion.
3. Set alignments.
4. Add types.

It makes use of the following classes and methods:

doc.IsFamilyDocument
doc.OwnerFamily.FamilyCategory.Name
doc.FamilyCreate.NewExtrusion()
doc.FamilyCreate.NewAlignment()
familyMgr = doc.FamilyManager
familyMgr.NewType()
familyMgr.Parameter(); familyMgr.Set()

Here is an overview of the four steps listed above in slightly greater detail:

1. In the first lab, we create a simple rectangular column family defining three column types with different dimensions. Before proceeding with the definition of the geometry and types, we need to ensure that we are working in a family template file and the correct family category. The document provides a property IsFamilyDocument to check the former, and the owner family category gives us the category of the template file.
2. Creating the geometry is easily achieved by defining a rectangular profile in the XY plane and extruding it using the NewExtrusion method. When creating the geometry, we need to account for the Revit database units and convert all our length measurements to feet.
3. One method to drive the geometry parametrically is to specify alignments between certain parts of the geometry and reference planes. In this very simple case, the template file already provides six reference planes for the upper and lower levels and the right, left, front and back faces, and we have six corresponding faces on the column. We need to specify alignments between these reference planes and the corresponding faces of our solid extrusion. This is done by identifying the matching pairs of solid face and reference plane and calling NewAlignment for each. In this simple case, the solid faces can be identified by their normal vectors and the reference planes by their names. In a more complex case, such as the next example in lab 2, we may have to create the reference planes ourselves, and use more complex algorithms to identify the reference planes and the solid geometry faces to associate with each other.
4. Finally, we create a few sample types for the family. In this simple case again, the template file already defines the parameters that we require for this, namely Width and Depth. Lab 2 will demonstrate how to define our own new parameters. Since the parameters are given, all we need to do is access the FamilyManager object and use its AddType and get_Parameter methods to specify the types to create and their dimensions.

Further in-depth details on the process and source code snippets to achieve each of these four steps is given in the separate documents 'Family Lab1 - Create Rectangular Column.rtf' in the csdoc and vbdoc subdirectories for C# and VB, respectively.

Lab 2 – Create L-Shaped Column

The second lab builds on the first to define a column with a slightly more complex L-shaped cross section profile. Due to this, the predefined reference planes and parameters provided by the template file are not sufficient to drive all aspects of the geometry, so we have to create our own additional ones. To be precise, we need reference planes, parameters and dimensions to determine and measure the thickness of the two 'legs' of the L shape.

Also, in the L-shaped column solid, the normal vector alone is not enough to identify all of the individual solid faces, so that algorithm needs to be refined as well. In our case, we use the reference plane associated with each solid face to identify it.

Finally, the lab also demonstrates adding new dimensioning to the family definition. The following steps are added to the existing ones:

• Add reference planes.
• Add parameters.
• Add dimensions.

The classes and methods used include:

doc.FamilyCreate.NewReferencePlane()
familyMgr.AddParameter()
doc.FamilyCreate.NewDimension()

Separate C# and VB versions of the detailed instructions, explanations, and source code snippets for this lab are provided by the document 'Family Lab2 - Create L-Shape Column_CS.rtf' in the csdoc and vbdoc subdirectories of the sample material.

Lab 3 – Add Formulae and Materials

In the third step, we further enhance the column family defined in the previous step by defining formulae for the L shape leg width parameters and by assigning a material to one of the family types.

• Add formulae.
• Add materials.

The classes and methods used include:

familyMgr.SetFormula()
pSolid.Parameter("Material")
familyMgr.AddParameter()
familyMgr.AssociateElementParameterToFamilyParameter()

The two parameters are defined as formulae so that the L shape leg width equals a quarter of the column width, and similarly for the depth. The key here is the family manager SetFormula method.

For the material, an instance parameter for the material group is added to the family and associated with the material parameter of the solid. Here, the key is the AssociateElementParameterToFamilyParameter method.

Again, separate C# and VB versions of the detailed instructions, explanations, and source code snippets for this lab are provided by the document 'Family Lab3 - Add Formula and Material_CS.rtf' in the csdoc and vbdoc subdirectories of the sample material.

Lab 4 – Add Visibility Control

Performance is a critical aspect of building family content, and significant performance improvements can be achieved by making use of the visibility settings accessible for each element in a family through the FamilyElementVisibility class, which can define which levels of detail and which types of views it appears in. That is the focus of this final lab, which implements the following:

• Implement a single line representation for the column in coarse view:
  • Single symbolic line representation in plan view.
  • Single model line representation in model view.
• Set the visibility control so that the single line representation is used in coarse view.

The classes and methods used include:

doc.FamilyCreate.NewSymbolicCurve()
doc.FamilyCreate.NewModelCurve()
FamilyElementVisibility(FamilyElementVisibilityType.ViewSpecific/Model)
FamilyElementVisibility.IsShownInFine, etc.
pLine.SetVisibility(pFamilyElementVisibility)

The detailed documentation and C# and VB code snippets for this lab are provided by the document 'Family Lab4 - Add Visibility Control_CS.rtf' in the csdoc and vbdoc subdirectories of the sample material.

AU 2009

These days I am pretty occupied with the preparation of my sessions for Autodesk University 2009:

• CP308-2 All Systems Go in the New Autodesk Revit MEP API
• CP9118-1 The New Autodesk Revit Family API: Everything is Relative

The Family API one is a virtual class which requires special preparation, since it is being recorded and broadcast worldwide for Virtual Autodesk University. As Rick Graham pointed out, virtual AU was created for those who are not able to make it to Las Vegas in person, and is free for subscription customers.

Here are links to the standard class catalogue and the virtual classes.

I would love to see you in person in the classroom session, or chat with you live during one of the virtual ones.

System Versus User Family Category

Here is a simple question and suggestion on classifying categories into built-in system versus user defined.

Question: Given an arbitrary element, how can I determine whether it belongs to a system family as opposed to a user-defined family? I thought I might look at its category, but how can I see whether that is system-defined? For example, I see that a duct has a category id of -2008000. Can I depend on the fact that this category id value is negative? Or is there any other way to determine this?

Answer: There is currently no API method to distinguish system categories from user defined ones short of creating your own hardcoded list. All built-in categories have negative values, but this includes system family types, family types, and subcategories of each, so that will not help you resolve this issue.

How could such a list be created?

Unfortunately, that would have to be done manually. This Family Category and Parameters dialogue lists all the family based categories:

If the category is a top level category and not in this list, then it is probably a system family category.

Getting Started with the Revit 2010 API

I am back again from a great vacation in Italy which I mostly spent outdoors camping, swimming, cooking, and drinking cappuchino. Yesterday was the Jeûne Fédéral holiday (French) in Neuchâtel. I used that to make a first pass through my overfull email inbox.

Meanwhile, here is a quick summary and overview of the material we have put together so far for getting started with the Revit 2010 API.

Question: Do you have any updated information similar to the getting started material for Revit 2009? I would like to hear about the news and differences between the Revit 2010 and 2009 APIs.

Answer: First of all, for completeness sake, here is the back pointer to the final wrap-up overview of the getting started material for the Revit 2009 API:

• Getting started with the Revit 2009 API

A large part of the material listed there applies to the Revit 2010 API as well.

Additional specific topics related to the Revit 2010 API are covered in subsequent posts:

• Revit 2010 API Introduction – recording and materials of the Revit 2010 API introcution webcast providing a general overview of the API as well as highlighting news and differences to the previous versions.
• The Revit Ribbon API – important for rewriting an external application to make use of the Revit 2010 ribbon.
• The Revit Family API – an overview of the family API including a pointer to the family API webcast recording and materials.
• The Form Creation API – highlights a subset of the family API.
• The Revit MEP API – an overview of the Revit MEP API and the recording and materials of the MEP webcast.

There is an entire blog category appropriately named '2010' which includes all of these and more:

• Revit 2010 API posts

As said, most of the additional resources listed in the discussion on getting started with the Revit 2009 API are also still valid and accessible.

The Revit MEP API

By the time you read this, I will be away happily on a one-week vacation in Italy. I hope you and the blog manage yourselves and behave well until I return. I scheduled some items to be published in my absence, though.

In previous posts, we already had a look at the new MEP-specific API features in Revit 2010 and the classes involved in defining and representing MEP connectors in particular. On August 27^th 2009, we held the first webcast dedicated entirely to Revit MEP programming. This post provides an abbreviated overview of the complete Revit MEP and the webcast contents with links to available related materials, including the following topics:

• The Revit MEP API
• MEP model analysis
• Hierarchical systems and connectors
• Electrical systems
• HVAC and plumbing systems
• Sample applications
• Materials and further reading

The Revit MEP API

Revit MEP is a flavour of Revit for work in the mechanical, electrical and plumbing domains. HVAC, i.e. heating, ventilation and air conditioning, is considered part of the mechanical domain. Efficient work in these areas requires strong model analysis tools in addition to read and write access to the components and data used to model the electrical, HVAC and piping systems in Revit MEP. Some of the required MEP specific functionality includes access to the MEP project information, Green Building XML, spaces and zones, the electrical, duct and pipe systems, their components, properties and parameters, methods for element creation and modification, and system traversal and analysis.

Most of the Revit API is generic and applies to all three flavours of the Revit product, i.e. Architecture, MEP and Structure. All three flavours of Revit also include the same .NET assembly named RevitAPI.dll providing API access to third-party applications. However, some specific additional features exist for each of the flavours as well, for instance some room-related functionality in Revit Architecture and access to the analytical and MEP models in Revit Structure and MEP respectively. If API functionality not supported by the currently running flavour is accessed, the call will simply do nothing or return null.

In Revit 2008, no MEP-specific functionality was provided by the API. It was still possible to analyse and manipulate an HVAC system using the generic Revit API methods, for instance by accessing ducts as generic Revit elements and reading and writing their properties using the generic parameter access. We used this to create a sample application for HVAC air terminal analysis and sizing, presented at Autodesk University 2007. Revit 2009 introduced the first MEP-specific API support, including classes for electrical and mechanical equipment, lighting device and fixture, connector, electrical system, space and zone, the MEP model property on family instances, and the ability to create and modify MEP elements. In Revit 2010, the MEP-specific API was a focal point of the API development and greatly enhanced, especially the support for HVAC and piping systems.

MEP Model Analysis

Access to the MEP Project Info is provided through the gbXMLParamElem element and its properties, which is accessed through the ProjectInfo.gbXMLSettings property. The available data includes PostalCode, ProjectLocation, BuildingService, BuildingConstruction, GroundPlane, ShadingSurfaces, and ProjectPhase.

Green Building XML or gbXML export is initiated by a call to the Document.Export method:

Document.Export( string folder, string name, GBXMLExportOptions );

Using spaces instead of rooms, and zones to group spaces, enables a subdivision of the architectural rooms into subspaces required for MEP analysis. The AddSpaceAndZone SDK sample demonstrates the programmatic creation and management of spaces and zones. The FamilyInstance class already had a Room property to determine in which room an instance is located, and now an analogous Space property has been added for MEP usage.

Several model inspection utility methods added in Revit 2010 are especially useful in the MEP domain. One group helps determine the relationships between and contents of volumes, rooms and spaces:

• Room.IsPointInRoom determines if a 3D point is in the volume of a room.
• Space.IsPointInSpace determines if a 3D point is in the volume of a space.
• GetRoomAtPoint and GetSpaceAtPoint return the room or space containing a given 3D point.

The new ray intersection method can be used to determine proximity of elements:

• FindReferencesByDirection returns an array of elements, faces, and references found when moving through the model from a specified point in a specified direction.

One use of FindReferencesByDirection is demonstrated by the RayTraceBounce SDK sample.

Hierarchical Systems and Connectors

Many of the building blocks of an MEP system are represented in Revit by family instances. The generic family instance definition in the Revit API has been enhanced to provide access to additional MEP-specific properties and data, and provide classes to represent systems and connections between system components.

The objects dealt with in the MEP domain are organised into hierarchical structures. The top level node in these structures is an MEP system, represented by the MEPSystem class. This is the base class for the derived classes ElectricalSystem, MechanicalSystem and PipingSystem. The system has properties to access the base equipment or panel, the terminal elements, and the connector manager. The derived classes have many additional domain specific properties.

The Revit 2009 API introduced the MEPModel and Connector classes as fundamentals for programmatically representing and accessing the MEP model. It is accessed through the FamilyInstance.MEPModel property, and one of its main purposes is to provide access to the connector manager.

We have logical and physical connections between MEP components. Logical connections are used in the electrical domain, where wires and cables are not necessarily modelled individually. Physical connections are used in the mechanical and plumbing domains, where the connectors define and transmit sizing and flow information from one part to the next.

A connector is part of an MEP element such as a duct, pipe, fitting, or piece of equipment. The Connector class is used to represent connectors in the project environment. Individual stand-alone connector elements need to be created inside a family to define the component and are represented there by the DuctConnector, PipeConnector and ElectricalConnector classes.

The connector defines geometry, e.g. its oval, round or rectangular shape, and dimensions such as width, height and radius. It also maintains a coordinate system and system data such as domain, system type, flow, direction.

Electrical Systems

Electrical systems are organised hierarchically in Revit MEP. The root elements are panels. Each panel is connected to a number of systems, also known as circuits. Each system or circuit consists of a number of circuit elements, some of which may be further panels, and so on, recursively. Cables and wires need not be modelled individually, and the connections between the electrical system components are defined by logical connectors rather than physical ones. The Revit 2009 API introduced the classes ElectricalEquipment, LightingDevice, LightingFixture, ElectricalSystem, specialisations of the base MEPModel and MEPSystem classes, to represent electrical components and systems. These elements all have a connector manager, whose Connectors property returns logical as well as physical type connectors:

ElectricalSystem sys;
ConnectorSet connectors = sys.ConnectorManager.Connectors;

This makes it very simple to analyse and traverse the electrical system hierarchies similarly to the approach demonstrated by the TraverseSystem SDK sample for duct and piping ones.

HVAC and Plumbing Systems

New support for HVAC and plumbing was provided with Revit 2010, which introduced the Autodesk.Revit.MEP namespace containing a wealth of new classes and functionality, as well as moving existing MEP-related classes to the MEP namespace. The main components in HVAC and piping hierarchy are the top level systems, ducts, pipes, fittings and connectors:

• Systems to manage the top level system properties.
• Ducts and pipes to define the main flow elements.
• Fittings to implement bends and branches in the system.
• Connectors to hook up the ducts, pipes and fittings.

The classes MechanicalSystem and PipingSystem introduced in Revit 2010 provide the following top-level system functionality:

• Access to equipment, connectors and system type.
• Access to system properties such as flow and static pressure.
• Analysis of system contents through the DuctNetwork or PipeNetwork property.

The elements contained within a system are not automatically returned in the flow direction. The TraverseSystem SDK sample demonstrates how to query the connector managers to implement traversal in direction of flow for a given system.

Ducts and pipes are represented by the classes Duct, FlexDuct, Pipe and FlexPipe, derived from the MEP curve type. They provide the following functionality:

• Read access to duct properties, types, and geometry.
• Change duct or pipe type.
• Move or layout duct or pipe.

The layout functionality can be driven by two points, one point and a connector, or two connectors.

Fittings are represented by family instances, which are created with dedicated methods on the Autodesk.Revit.Creation.Document class for inserting Elbow, Tee, Cross, Takeoff, Transition, and Union elements. The fitting properties, shape and dimensions can be accessed through the FamilyInstance.MEPModel property.

Connectors limited to the electrical realm were introduced in Revit 2009. In Revit 2010, we have connectors for the mechanical and piping domains as well. The connector is an item that is a part of another element such as a duct, pipe, fitting, or equipment. The basic features of connectors and the different classed used to represent them in the family and project contexts were mentioned above. The additional HVAC-specific connector features include properties to read the flow, coefficient and demand. They also provide access to physical properties like Origin, Angle, Height, Width and Radius.

We have read and write access to so-called assigned connector properties. These are connector properties that can be overridden by the user and are dependent on the overall network condition, including characteristics like Flow, Flow Config, Coefficient, Loss etc. These depend on the system being well connected, the configuration of the family within the system, and how the family is constructed.

Connector size and location can be modified. Connectors can be disconnected to insert a new fitting into a network or connect two ducts into a transition.

• The family connector elements define Flow, Flow Configuration, Coefficients, and Loss Method.
• Read duct, pipe, and fitting connector properties such as Flow, Coefficient, and Demand.
• Access physical connector properties e.g. Origin, Angle, Height, Width, Radius.
• Change connector size and location.
• Connect and disconnect.

The creation document provides a number of methods for the creation of HVAC and plumbing elements within the project environment, including new mechanical or piping systems, new duct and pipe elements, and new fittings. In the context of a family, the different types of duct, pipe and electrical connectors are represented by specific elements that can be created by the FamilyItemFactory class, accessed through the Document.FamilyCreate property.

Sample Applications

The MEP-specific sample applications include both those provided in the standard Revit SDK as well as a non-SDK one created for this presentation on the RME API.

The introduction of an MEP specific API with Revit 2009 was accompanied by two SDK samples:

• AddSpaceAndZone demonstrates handling the new space and zone elements.
• PowerCircuit demonstrates manipulation of electrical power circuits.

The Revit 2010 SDK includes the following new MEP-specific SDK sample applications:

• AutoRoute: Route a set of ducts and fittings between a source, the air supply equipment, and the sink, two air outlet terminals.
• AvoidObstruction: Detect and resolve obstructions between ducts, pipes, and beams.
• TraverseSystem: Traverse a well-connected mechanical or piping system in the direction of flow.
• CreateAirHandler: Create an air handler and add connectors.

The first three demonstrate RME API features in the project context, the fourth uses the family API.

Finally, we provide a non-SDK sample application named ‘mep’. It implements some HVAC oriented commands making use of the generic Revit API to analyse and manipulate duct elements for automatic air terminal sizing, and others which implement an electrical sample for analysis and display of an electrical system in a tree view reproducing the Revit system browser structure or showing the full connection hierarchy tree:

• HVAC air terminal analysis and sizing.
• Electrical system connectivity analysis and hierarchical display.

Materials and Further Reading

A more extensive document discussing the Revit MEP API and the related samples in deeper detail as well as other useful material is provided with the recording of Revit MEP Programming Webcast held on August 27th 2009, available through the ADN or Autodesk Developer Network API training schedule (also accessible via www.autodesk.com/apitraining), filter for 'Revit MEP API', and click on the download link. This material is accessible to all developers, regardless of ADN membership.

Duplicate Family Solids

Here is a question handled by Joe Ye on multiple occurrences of solids in a pipe family definition.

Question: We were surprised to discover that the solids inside a pipe family are duplicated. This is an issue for us, because we want to determine the relationship between the family symbol and the corresponding geometrical solid. We would like to add symbol properties such as a subcategory to the solid. During the export, we don't know which sub category is used for presentation on the screen. We retrieve all the solids, but their subcategory is not defined, so we cannot determine whether or not to export the data.

Answer: There are three solids in the family definition, and they represent three different parts of the pipe. One is for the pipe fitting insulation, another is for the pipe fitting lining, and the third for the pipe itself.

If the parameter values Lining Thickness and Insulation Thickness are zero, all three solids are identical. Otherwise, their sizes are different. Here is an example displaying non-zero Lining Thickness and Insulation Thickness parameter values:

According to which solid you need to export, you can compare the sizes and export only the one that you require.

For example, if you only want to export the insulation size, then you can search for the largest solid and export that. If you want to export the lining solid, export the smallest solid.

If the Lining Thickness and Insulation Thickness are both zero, then exporting any one of them will work.

By the way, for a pipe fitting, there are only two such solids.

Many thanks to Joe for this explanation!

Remove all Geometry from a Family

Here is a question from Joel Karr of Environmental Systems Design, Inc that nicely complements the issue of identifying model elements in a project file with the subsequent correction added.

Question: Is it possible to delete all geometry from a Revit RFA family file? I would like to keep all parameters but delete all geometry.

Answer: To achieve what you desire, we first need to identify all elements contributing geometry to the model, similarly to the model element selection issues mentioned above.

This is simpler in a family file than in a project file, since there are normally less elements and almost all elements having geometry are the ones we are interested in.

I implemented a sample application RemoveRfaGeom to test this, with the following mainline code for its Execute method:

public IExternalCommand.Result Execute( 
  ExternalCommandData commandData, 
  ref string message, 
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  ElementIterator it = doc.Elements;
  Options opt = app.Create.NewGeometryOptions();
  List<Element> a = new List<Element>();
 
  while( it.MoveNext() )
  {
    Element e = it.Current as Element;
 
    if( null != e.get_Geometry( opt ) )
    {
      a.Add( e );
    }
  }
 
  int n = a.Count;
  Debug.Print( 
    "{0} element{1} have non-null geometry{2}", 
    n, 
    ( 1 == n ? "" : "s" ),
    ( 0 == n ? "." : ":" ) );
 
  ElementSet els = new ElementSet();
 
  foreach( Element e in a )
  {
    string cat = (null == e.Category)
      ? "<null>"
      : e.Category.Name;
 
    Debug.Print(
      "Category={0}; Name={1}; Id={2}; Type={3}",
      cat,
      e.Name,
      e.Id.Value.ToString(),
      e.GetType().Name );
 
    if( null == e.Category )
    {
      els.Insert( e );
    }
  }
 
  ElementIdSet ids = doc.Delete( els );
 
  n = (null == ids) ? 0 : ids.Size;
 
  Debug.Print( "{0} element{1} deleted.",
    n,
    ( 1 == n ? "" : "s" ) );
 
  return IExternalCommand.Result.Succeeded;
}

It performs the following steps, assuming that the active document is indeed a family document:

• Iterate over all family document elements.
• Identify and list all elements with non-null geometry.
• Create a set of all elements with geometry whose category is null.
• Delete the latter set and display the number of deleted elements.

Running this in the metric library rectangular column family file 'M_Rectangular Column.rfa' produces the following output:

2 elements have non-null geometry:
Category=; Name=Extrusion; Id=105; Type=Extrusion
Category=Cameras; Name=View 1; Id=427; Type=Element
13 elements deleted.

As you can see from this, there are some elements having geometry that you presumably do not want to eliminate, such as the camera, so you will need to remove those from the set before deletion. In this case, I simply noted that the camera has a non-null category, whereas the category of the extrusion I want to remove is null, so I just check the null category property to select the extrusion.

Secondly, deleting an element causes other dependent elements to be deleted also, so even though we just pass in one single extrusion element to the Delete method, a whole group of other elements are eliminated as well. We already discussed and made use of this effect to determine the association between a tag and the tagged element and between a host and its hosted elements.

Here is the complete Visual Studio solution RemoveRfaGeom implementing the new command.

New Sweep and References

Here is a question posted by Mike Cotreau of Langan Engineering & Environmental Services on how to create a new sweep using a reference array, which provided a welcome opportunity to explain a little about the use of references in the Revit API:

Question: I want to use the NewSweep method to create a 3D curb line that follows along a path of 3D points. The NewSweep method can be invoked in two ways, one uses a ReferenceArray and the second uses a CurveArray. There is an example provided in the VSTA Family Sample code that illustrates the CurveArray version and I have used that code to layout an entire curbline without issues. Unfortunately, I need to use the first version that allows for a sweep to follow a 3D path using the ReferenceArray version. I keep getting an error saying the object is not referenced, and I am clueless as to why. I am using VB.NET and here is the code I modified from the sample code:

 
Dim arrarr As CurveArrArray = m_revit.Create.NewCurveArrArray()
Dim arr As CurveArray = m_revit.Create.NewCurveArray()
'****** This creates the section for the curb ********
Dim normal As XYZ = XYZ.BasisZ
Dim sketchPlane As SketchPlane = CreateSketchPlane(normal, XYZ.Zero)
Dim pnt1 As XYZ = m_revit.Create.NewXYZ(0, 0, 0)
Dim pnt2 As XYZ = m_revit.Create.NewXYZ(0, 0.5, 0)
Dim pnt3 As XYZ = m_revit.Create.NewXYZ(0.5, 0.5, 0)
Dim pnt4 As XYZ = m_revit.Create.NewXYZ(0.5, -1, 0)
Dim pnt5 As XYZ = m_revit.Create.NewXYZ(0, -1, 0)
arr.Append(m_revit.Create.NewLineBound(pnt1, pnt2))
arr.Append(m_revit.Create.NewLineBound(pnt2, pnt3))
arr.Append(m_revit.Create.NewLineBound(pnt3, pnt4))
arr.Append(m_revit.Create.NewLineBound(pnt4, pnt5))
arr.Append(m_revit.Create.NewLineBound(pnt5, pnt1))
arrarr.Append(arr)
Dim profile As SweepProfile = m_revit.Create.NewCurveLoopsProfile(arrarr)
Dim curves As CurveArray = m_revit.Create.NewCurveArray()
Dim refArray As ReferenceArray = m_revit.Create.NewReferenceArray
Dim pt1 As XYZ = m_revit.Create.NewXYZ(-265.9978, -358.3954, 0)
Dim pt2 As XYZ = m_revit.Create.NewXYZ(-265.9374, -340.4006, 0)
Dim curve As Curve = m_revit.Create.NewLineBound(pt1, pt2)
curves.Append(curve)
refArray.Append(curve.Reference)
'Create the Sweep
Dim sweep1 As Sweep = m_creationFamily.NewSweep(True, refArray, profile, 0, ProfilePlaneLocation.Start)
' move to proper place 
Dim transPoint1 As XYZ = m_revit.Create.NewXYZ(11, 0, 0)
m_familyDocument.Move(sweep1, transPoint1)

An exception is thrown on the NewSweep method. I have also tried building the Reference array using code like this without any luck:

refArray.Append(curve.get_EndPointReference(0))
refArray.Append(curve.get_EndPointReference(1))

Any help you can provide that allows me to sweep along a 3D path would be GREATLY appreciated.

Answer: NewSweep is used in the family document to create a new sweep. The overloads you refer to for creating a new sweep form are:

• NewSweep( Boolean, ReferenceArray, SweepProfile, Int32, ProfilePlaneLocation ), using an array of selected references as a 3D path.
• NewSweep( Boolean, CurveArray, SketchPlane, SweepProfile, Int32, ProfilePlaneLocation ), using a path of curve elements.

The three last arguments are the same for both overloads, so these are presumably not cause of the problem:

• SweepProfile profile,
• int profileLocationCurveIndex, and
• ProfilePlaneLocation profilePlaneLocation.

The API documentation specifies the reference array passed in to define the path in the first overload as follows:

• ReferenceArray path: The path of the sweep. The path should be reference of curve or edge obtained from existing geometry.

The cause of your problem is almost certainly the fact that the curve that you are trying to obtain references from is not part of any existing geometry, since you created it on the fly.

To understand the difference and the importance of this, here are some private hypothetical musings of mine on what references actually mean within Revit. I have never seen any hard documentation of this, but I am gradually getting the following idea:

References

All of objects living in the Revit API Geometry namespace are transient in-memory objects. The non-transient Revit BIM model resides in the database. To query the geometry of BIM objects, transient geometry is generated on the fly from their parametric representations. If a new BIM object B is to be generated and stored in the database, such as your sweep, and it needs to reference existing BIM geometry in any way, for instance some edge of an existing object A, then a reference can be generated to provide a hook from the new object B definition through the transient geometry back to the underlying BIM object A. Later on, when the BIM is saved, the transient geometry has all disappeared, but the reference ensures that B knows that it depends on the geometry and location of A in some way. If A is moved or modified, B can adapt.

In your sample, you are creating a new line between two fixed points pt1 and pt2. This is all transient geometry, and not referring back to any BIM object, so there is no way that the resulting curve can contain or provide a valid reference to anything.

The question is why you are trying to use the overload requiring a reference array at all? If your input data is fixed, you should use the curve array option instead.

By the way, for completeness sake, prompted by your query, I had a look at the VSTA family samples. They are provided in the Revit SDK VSTA Samples sub-folder, in the family file Revit_VSTA_Family_Samples.rfa. I see the code you based yours on, in the subroutine CreateSweep() of the GenericModelCreation project. This project is also provided as one of the standard SDK samples as well, albeit only in a C# version.

I hope this answers your question. Good luck!