The Building Coder

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.

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.

Elevation and Section Views

Here are some questions handled by Joe Ye, on creation of and line work in elevation views and the cut plane definition of a section view.

Question: There are different specialised kinds of views derived from the Autodesk.Revit.Elements.View class, and I see several methods in the Revit API to create some of these, such as 3D, Plan, Section, Sheet and Drafting. However, I cannot find a method to create an Elevation View. How can I do that?

Answer: Unfortunately, the Revit API currently does not provide any method to create an elevation view. At the moment, you can use the NewViewSection method to create a vertical section view very similar to an elevation view. By using a large bounding box which does not intersect with the building model, it can display the same view as an elevation view:

Question: Once I have created an elevation view, how would I change the line work of certain elements in that view? In the user interface, Revit provides the Linework tool in the ribbon for this action. How can I achieve this through the API?

Answer: As regards modifying the line work displayed in an elevation view, you can use the CutLinePatternOverrideByElement method on the View object to set the line weight for specified elements. For more information about this method, please see the Revit API help file RevitAPI.chm file in SDK.

Question: How can I get the cut plane definition from a section view programmatically? I just need any point inside the cut plane and the normal vector of the plane to continue to do some other calculations.

Answer: The section view class provides the properties you need. The Origin property of a section view is a point in the world coordinate system or WCS located in the cut plane of the section view. The ViewDirection property of a section view returns a WCS vector indicating the direction towards the viewer. You can use the section view Origin as the cut plane origin, and the ViewDirection as its normal vector. Depending to your usage, you might need to reverse the direction of the ViewDirection.

Thank you very much Joe for these answers!

Detail Lines

We previously discussed various aspects of model lines, such as model line creation, the model line sketch plane, and the minimal length of a model line. Here is a question on the related topic of detail lines handled by my colleague Saikat Bhattacharya:

Question: How can I create a detail line on a drafting view? I tried to use the following statement:

doc.Create.NewDetailCurve( View, curve, y );

It is unclear to me what the "curve" and the "sketchPlane" stand for and how to use them. Please could you provide me with a small sample.

Answer: Detail curves are created for drawings such as a detail or drafting view. They are annotation elements and are visible only in the view in which they are drawn. They can currently only be created in plan views.

Except for this, detail curves are similar to model curves. ModelLine and DetailLine both belong to the Lines category. Thus, for a sample on creating detail curves, you can refer to and slightly adapt the Revit SDK sample ModelLines, which shows how to work with the sketch plane and geometry curve to create a new model line.

For more details on sketch planes and model curves, you can also refer to the developer guide "Revit 2010 API Developer Guide.pdf", especially chapter 14, Annotation Elements, and section 14.2, Detail Curve. Another helpful section is 15.3.1 on Creating a ModelCurve and the Code Region 15-2: Creating a new model curve, which illustrates how to create new geometry curves, a sketch plane, and model curves, a ModelLine and a ModelArc. You can use the same approach to create detail curves as well.

I implemented a new external command CmdDetailCurves in The Building Coder sample application by slightly modifying the sample code provided in the developer guide. Here is the code of the new command's Execute method:

  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
  View view = doc.ActiveView;
 
  // Create a geometry line
  XYZ startPoint = new XYZ( 0, 0, 0 );
  XYZ endPoint = new XYZ( 10, 10, 0 );
 
  Line geomLine = app.Create.NewLine(
    startPoint, endPoint, true );
 
  // Create a geometry arc
  XYZ end0 = new XYZ( 1, 0, 0 );
  XYZ end1 = new XYZ( 10, 10, 10 );
  XYZ pointOnCurve = new XYZ( 10, 0, 0 );
 
  Arc geomArc = app.Create.NewArc(
    end0, end1, pointOnCurve );
 
  // Create a geometry plane
  XYZ origin = new XYZ( 0, 0, 0 );
  XYZ normal = new XYZ( 1, 1, 0 );
 
  Plane geomPlane = app.Create.NewPlane(
    normal, origin );
 
  // Create a sketch plane in current document
  SketchPlane sketch = doc.Create.NewSketchPlane(
    geomPlane );
 
  // Create a DetailLine element using the 
  // created geometry line and sketch plane
  DetailLine line = doc.Create.NewDetailCurve(
    view, geomLine ) as DetailLine;
 
  // Create a DetailArc element using the 
  // created geometry arc and sketch plane
  DetailArc arc = doc.Create.NewDetailCurve(
    view, geomArc ) as DetailArc;
 
  return CmdResult.Succeeded;

As you see, the curve parameter above can be any geometric curve entity like Line, Arc, Ellipse or NurbSpline. All of these types are derived from the Curve class and can be used as parameters to create a detail curve.

Here are the resulting detail curves after running this command in a new project document:

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

Thank you Saikat for this helpful explanation!

Creating a Non-rectangular Slab

Here is a question raised and answered by my colleagues Katsuaki Takamizawa and Phil Xia on creating and editing a slab. Some related topics that we already discussed are related to the analysis of the geometry of existing slabs, e.g. the slab boundary and its side faces, explorations of the geometry of other elements, the eave cut property of roof slabs, and how to edit a floor profile. Now let's look at this generic slab issue:

Question: In the user interface, we can use the shape editing tools to modify slab surfaces and to create non-rectangular slabs. Is it possible to create slabs like these through the API as well?

Also, can we define slope angles on these non-rectangular slabs?

Answer: You can modify the slab surface with the slab editor, accessible through the SlabShapeEditor property on the Floor class. The SDK sample SlabShapeEditing shows how to use it.

There is no way to modify the slope of an existing slab, but it can be specified when a new slab is created with NewSlab method:

public Floor NewSlab(
  CurveArray profile,
  Level level,
  Line slopedArrow,
  double slope,
  bool isStructural
)

The parameters are:

• profile: an array of planar lines and arcs that represent the horizontal profile of the slab.
• level: the level on which the slab is to be placed.
• slopedArrow: a line to control the sloped angle of the slab. It should be in the same face as the profile.
• slope: defines the slope.
• isStructural: specifies whether the slab is structural.

Many thanks to Phil and Katsu-san for this overview!

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!

Electrical Settings and Lighting Fixtures

Here are two recent questions on electrical settings of distribution systems and family instances for lighting fixtures handled by Saikat Bhattacharya and Joe Ye, respectively.

By the way, this is a special occasion, namely the 200^th post to The Building Coder. I will resist the temptation to declare this as a birthday post like I did post number 100, because the first real annual birthday of The Building Coder is coming up quite soon now anyway, and we don't want to exaggerate, do we?

Reading and Writing the Electrical Settings of Distribution Systems

Question: Is there any way to use the Revit API to read and write the data under Electrical Settings, e.g. the Distribution System rows?

Answer: To do a quick check, I used the RvtMgdDbg tool and found out that the active document contains a DistributionSysType container which lists all the distribution systems available from the user interface. Here are the electrical settings displayed in the user interface:

Here, we have selected the DistributionSysType instance using RvtMgdDbg to show the same information as the user interface as accessed through the API:

Thus, the DistributionSysType class might be what you looking for.

Creating Hosted Family Instances for Lighting Fixtures

Question: I am loading a batch of lighting fixtures using .NET but I am having some issues. I programmatically set the host to be the ceiling by using parameters showing that the host is the ceiling when the fixture is loaded. However, the properties of the resulting fixture do not reflect this. Also, the fixture created cannot be copied. In sum, the properties of the fixtures are not the same as the properties of a fixture created manually and inserted by Revit itself. I used the following code to load the fixture:

FamilyInstance inst
  = doc.Create.NewFamilyInstance(
    location, symbol, ceil,
    StructuralType.NonStructural );

In this call, location is the location of the fixture. I set its Z coordinate to zero in order to inherit the host elevation, but this does not work. Symbol is the family symbol to be inserted, and ceil the selected host ceiling.

Answer: I reproduced the issue. Using your method, I found the created light fixture is located above the ceiling, although the Z elevation is the same. The host property is null, as is the parameter value of HOST_ID_PARAM. So I think the issue is caused by the level setting.

I changed the code to use another override of NewFamilyInstance, which takes the level as an argument:

Document.NewFamilyInstance(
  XYZ,
  FamilySymbol,
  Element,
  Level,
  StructuralType )

The lighting fixture now has a valid host property. Here is the updated code for the Execute method of the external command:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
Autodesk.Revit.Creation.Filter cf
  = app.Create.Filter;
 
// get a lighting fixture family symbol:
 
Filter f1 = cf.NewTypeFilter(
  typeof( FamilySymbol ) );
 
Filter f2 = cf.NewCategoryFilter(
  BuiltInCategory.OST_LightingFixtures );
 
Filter f = cf.NewLogicAndFilter( f1, f2 );
 
List<Element> symbols = new List<Element>();
doc.get_Elements( f, symbols );
 
FamilySymbol sym = null;
 
foreach( Element elem in symbols )
{
  sym = elem as FamilySymbol; // get the first one.
  break;
}
 
if( null == sym )
{
  message = "No lighting fixture symbol found.";
  return CmdResult.Failed;
}
 
// pick the ceiling:
 
doc.Selection.StatusbarTip
  = "Please select ceiling to host lighting fixture";
 
doc.Selection.PickOne();
 
Element ceiling = null;
 
foreach( Element elem in doc.Selection.Elements )
{
  ceiling = elem as Element;
  break;
}
 
// get the level 1:
 
ElementIterator it = doc.get_Elements(
  typeof( Level ) );
 
Level level = null;
 
while( it.MoveNext() )
{
  level = it.Current as Level;
 
  if( level.Name.Equals( "Level 1" ) )
    break;
}
 
if( null == level )
{
  message = "Level 1 not found.";
  return CmdResult.Failed;
}
 
// create the family instance:
 
XYZ p = app.Create.NewXYZ( -43, 28, 0 );
 
FamilyInstance instLight
  = doc.Create.NewFamilyInstance(
    p, sym, ceiling, level,
    StructuralType.NonStructural );
 
return CmdResult.Succeeded;

Thank you very much Joe and Saikat for these answers!

Debug Geometric Form Creation

Here is a useful hint on debugging the generation of geometric shapes from Harry Mattison.

Question: I am trying to create multiple swept blends in a family document. The first call to FamilyCreate.NewSweptBlendForm() succeeds, but the second call is failing with the following exception:

Answer: For problems like this I suggest commenting out the code that creates the form so that the command creates only the lines being used to create the form. Then you can run the command, verify the geometry of the lines, and use the Revit UI to select them and push the Create Form button. If Create Form fails, then the bug probably has nothing to do with the API.

In this case, there are many overlapping line warnings:

I'd expect that you will get better results if the geometry forms closed loops without overlaps.

Finally, this will be easier to debug if the lines are created in the active document instead of a new document created in the external command that is not visible without saving and reopening the file. Thin Lines mode might also be helpful because the lines are quite short.

Thank you very much Harry for these valuable suggestions!

Scale a Curve

Now let us get back to really practical things again, after the practical notes on impractical things, and the more or less practical boot camp note.

Question: I have a CurveArray object containing data defined in inches. Now I need to scale it to feet in order to feed it into a Revit API method to create an extrusion. How can I perform this scaling operation? I would obviously prefer not having to rebuild the entire CurveArray. How does one apply a scale factor to an existing CurveArray?

I tried iterating over the Curve objects in the CurveArray but cannot figure out how to change the existing X, Y and Z coordinate values of the Curve objects.

There appears to be a Multiply function for the XYZ object, which doesn't actually act on the XYZ object itself, but instead acts on and returns a new copy of the original object. No such function appears to exist for the Curve, CurveArray or CurveArrArray objects.

Even if it did, acting on a copy wouldn't achieve the desired result. A 'Scale' method for the XYZ, Curve, CurveArray and CurveArrArray objects, which acts on the data in those objects directly, would be a great thing to have. It is especially important due to the fact that Revit requires the data be in one specific set of database units only, for example when submitting it to functions for doing things like creating an extrusion.

Answer: Unfortunately, this is not possible in the current API. You need to create a new curve. Here is an idea which may at least partly alleviate the problem:

Curve.get_Transformed() can be used to simplify the process of creating a new curve scaled as desired.

public void ScaleCurves()
{
  CurveArray cArray = PrepareCurveArray();
 
  Transform x = Transform.Identity;
  x = x.ScaleBasis( 1.0 / 12.0 );
 
  int numCurves = cArray.Size;
  for( int i = 0; i < numCurves; ++i )
  {
    Curve curve = cArray.get_Item( i );
 
    Curve newCurve = curve.get_Transformed( x );
 
    cArray.set_Item( i, newCurve );
  }
 
  WriteProfile( "After transformation", cArray );
}

You are still creating new curves, but not required to figure out how to scale each curve independently based on type.

Reply: That is definitely helpful code. I've been writing some extension methods to get around some of the limitations, essentially adding my own functions to the class definitions provided by the Revit API so my methods 'look' like they are part of the API itself. This new method for scaling curves is much cleaner than what I came up with, so I will definitely replace my extension method with this code.

On a very vaguely related note, here is a pointer to some Revit tools for both users and developers:

Revit Family Tools

Version 2.3.0.0 of the Revit Family Tools is available from the Revit Tools page with the following functionality useful for all flavours of Revit:

• Comparing shared parameter files.
• Merging shared parameter files.
• Deleting RFA backup files, optionally recursively.
• Copying CSV files created for Type Catalog usage to TXT files for easy change testing.
• Reporting the versions of Revit used to create family files, optionally recursively.

Practical Notes on Impractical Things

I just learned that the two introductory images presented in the article on the Revit form creation API came from Zach Kron, whose blog Buildz presents lots of interesting 'practical notes on making impractical things' in Revit.

Here is a pointer to a completely different kind of practical note on another blog:

Disable Auto Setback in Framing Template

Several developers have been struggling with some of the hard-coded Revit behaviour. Miroslav Schonauer just pointed out that he and Sarah Capes found a solution for one specific problem on an Autodesk Consulting project, which is documented in this article on how to disable auto setback in a framing template.

And to round off today's potpourri, here is another issue around the topic of form creation:

NewSweptBlend Failure

Question: I am trying to use the NewSweptBlend method, but it throws an exception saying “The attempted operation is not permitted in this type of family.” What can I do to solve this?

Answer: This indicates that swept blends are not supported in the category type of the family where you are attempting to create it.

If it is a 2D family type, you would get this exception, and maybe also on a few other types as well.

In your specific case, the code uses a Conceptual Mass template and tries to create a SweptBlend in it. If you want to work in a Conceptual Mass template, you must use the NewSweptBlendForm method instead. If you want to use NewSweptBlend, then use a non-mass template.