The Building Coder

Verona Revit API Training

Yesterday was the last day of the advanced Revit Structure API training at Steel & Graphics srl in Verona, Italy, with Gianni, Stefano, Michele, Paolo, and we started diving into deeper topics.

But first, here are some of the initial things we discussed in the previous days:

• Making use of FamilyInstance.AddCoping to implement a Boolean operation between solids, for instance to cut a hole in a steel beam.
• Computing the volumes of all compound wall layers.
• Creating new column and beam types and inserting column and beam instances through the API.
• Improving the Revit SDK FrameBuilder sample to use language independent category comparison and make use of the Revit 2009 API filtering mechanism.

I already posted a description of the changes made to FrameBuilder to make the category comparison language independent. Notes on adding filtering may follow later. Here are some notes on the first of these issues:

AddCoping

Making use of AddCoping is pretty trivial. All we need to do is select two suitable beams, for instance a wide steel flange beam to cut a hole into, and a steel bar to define the hole, then feed these two instances into the AddCoping method. First of all, we implemented the following method to either extract a preselected element from the document selection set, or prompt the user to select a new one:

Element GetSelectedElement(
  Document doc,
  string description )
{
  Selection sel = doc.Selection;
  Element e = null;
  while( null == e )
  {
    ElementSetIterator i
      = sel.Elements.ForwardIterator();
 
    if( i.MoveNext() )
    {
      e = i.Current as Element;
      sel.Elements.Remove( e );
    }
    if( null == e )
    {
      sel.Elements.Clear();
 
      sel.StatusbarTip = "Please select "
        + description;
 
      if( !sel.PickOne() )
      {
        return null;
      }
    }
  }
  return e;
}

Then we can make use of that to select the two elements in the correct order and call the AddCoping method on the larger beam:

public IExternalCommand.Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  string s
    = "Please select a family instance for the ";
 
  IExternalCommand.Result rc
    = IExternalCommand.Result.Failed;
 
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  Element e1 = GetSelectedElement( doc,
    "beam to cut" );
 
  if( null != e1 )
  {
    Element e2 = GetSelectedElement( doc,
      "bar to drill hole" );
 
    if( null != e2 )
    {
      FamilyInstance beam = e1 as FamilyInstance;
      FamilyInstance bar = e2 as FamilyInstance;
 
      if( null == beam )
      {
        message = s + "beam";
      }
      else if( null == bar )
      {
        message = s + "bar";
      }
      else
      {
        beam.AddCoping( bar );
        rc = IExternalCommand.Result.Succeeded;
      }
    }
  }
  return rc;
}

The result of executing this is the flange beam with a nice little hole in it:

Unfortunately, this cannot be used as a generic Boolean operation, because if the bar is erased from the project, the hole immediately and automatically seals up again.

I hope to be able to jot down some notes on the other topics listed above on the way back home.

Category Comparison

Still giving Revit Structure API training in Verona, Italy, we ran into a problem in one of the Revit SDK samples today. The FrameBuilder sample works with structural beams and framing elements. It implements a FrameData class which defines an Initialize() method to set up internal lists of column, beam and brace symbols. These are sorted into different lists depending on their type, which is determined by comparing the category names. Unfortunately, the original SDK sample compares the category names with the language dependent strings "Structural Framing" and "Structural Columns". In the Italian version of Revit, these strings change to "Pilastri strutturali" and "Telaio strutturale", and the comparison will never succeed.

Here is the original, language dependent comparison code that we would like to replace by language independent code:

// add symbols to lists according to category name
string categoryName = symbol.Category.Name;
if ("Structural Framing" == categoryName)
{
  m_beambracesSymbolsMgr.AddSymbol(symbol);
}
else if ("Structural Columns" == categoryName)
{
  m_columnSymbolsMgr.AddSymbol(symbol);
}

To replace this by language independent code, we make use of the built-in category enumeration. We use the enumeration values OST_StructuralColumns and OST_StructuralFraming to obtain the corresponding document categories from the document settings and its categories collections, and store their element ids:

Document doc =
  m_commandData.Application.ActiveDocument;
 
Categories categories
  = doc.Settings.Categories;
 
BuiltInCategory bipColumn
  = BuiltInCategory.OST_StructuralColumns;
 
BuiltInCategory bipFraming
  = BuiltInCategory.OST_StructuralFraming;
 
ElementId idColumn
  = categories.get_Item( bipColumn ).Id;
 
ElementId idFraming
  = categories.get_Item( bipFraming ).Id;

This can be done right at the beginning of the Intialize() method. Then we can replace the language dependent code listed above by:

// add symbols to lists according to category
ElementId categoryId = symbol.Category.Id;
if( idFraming.Equals( categoryId ) )
{
  m_beambracesSymbolsMgr.AddSymbol( symbol );
}
else if( idColumn.Equals( categoryId ) )
{
  m_columnSymbolsMgr.AddSymbol( symbol );
}

Note that in previous versions of Revit, 2008 and earlier, it was possible to compare the categories directly, i.e. use something like this:

Category cat = symbol.Category;
if( catFraming.Equals( cat ) )
{
  m_beambracesSymbolsMgr.AddSymbol( symbol );
}
else if( catColumn.Equals( cat ) )
{
  m_columnSymbolsMgr.AddSymbol( symbol );
}

This stopped working reliably in Revit 2009, so nowadays you need to compare the category element ids instead of directly comparing the categories.

Mechanical Duct Types

Question: When selecting duct type properties, under the mechanical heading, various fitting property values are specified. How can I find out what property a given fitting belongs to, i.e. is it an elbow, a transition or cross etc.? Obviously, the type of fitting is described in the family name, but is there a more definite way of knowing what kind of fitting it is through the API?

Answer: In Revit 2009, you can use the built-in parameter FAMILY_CONTENT_PART_TYPE. You can access it through the following series of properties:

FamilyInstance > Symbol > Family > Parameter > BuiltInParameter.FAMILY_CONTENT_PART_TYPE.

This parameter stores an integer value. The values for the different types are:

kUndefinedPartType = -1,
kNormal            = 0,
kDuctMounted       = 1,
kJunctionBox       = 2,
kAttachesTo        = 3,
kBreaksInto        = 4,
kElbow             = 5,
kTee               = 6,
kTransition        = 7,
kCross             = 8,
kCap               = 9,
kTapPerpendicular  = 10,
kTapAdjustable     = 11,
kOffset            = 12,
kUnion             = 13,
kPanelBoard        = 14,
kTransformer       = 15,
kSwitchBoard       = 16,
kOtherPanel        = 17,
kEquipmentSwitch   = 18,
kSwitch            = 19,
kValveBreaksInto   = 20,
kSpudPerpendicular = 21,
kSpudAdjustable    = 22,
kDamper            = 23,
kWye               = 24,
kLateralTee        = 25,
kLateralCross      = 26,
kPants             = 27,
kMultiPort         = 28,
kValveNormal       = 29,

Many thanks to Adam Nagy and Harry Mattison for providing this information.

Room and Wall Adjacent Area

I continued the discussion on the room and wall adjacency with Massimiliano Revelli of Informatica System srl, because he is actually interested in determining the wall area adjacent to the room, and not just the overlapping curve segment length.

The overlapping area is obviously easy to determine if the wall has a constant height, as I pointed out in the earlier post, but this is often not the case. For instance, let us look at the upper wall in this floor plan of a simple example demonstrating the difficulties, highlighted in red:

The 3D view of the highlighted wall looks like this:

The wall geometry and the solid it provides is not subdivided at the point where it intersects the interior wall, as we can see from the triangles displayed by the element viewer SDK sample:

To determine the exact adjacent area, we need to determine the inner face of the wall and determine which part of it overlaps the room boundary segments. We can make use of the solutions on how to determine the inner face of the wall and its area from previous discussions.

Here are three different suggestions on how to approach the problem:

• Implement an algorithm that calculates the area of the portion of a vertical triangle that overlaps a horizontal line segment.
• When determining the wall polygons, truncate them to return only those parts overlapping the horizontal room boundary segments.
• Use the room's ClosedShell property and calculate its intersection area with the wall faces.

Here are slightly more detailed descriptions of each approach:

One approach to solve our current problem would be to implement an algorithm that projects the room boundary curve segments onto the wall face triangles and determines the area of the overlap.

Another approach might start a little bit earlier, modifying the utility methods in the module CmdWallProfile.cs, in the method GetWallProfilePolygons, for instance by modifying the GetProfile method to project its polygons onto the wall location curve, and then chop of the parts that lie outside the room boundary curve segment. The advantage of this is that our polygon area calculation algorithm could be left unchanged, since it already handles all kinds of polygons, and is not limited to triangles.

A third, completely different approach could make use of the Room object's ClosedShell property. ClosedShell returns a geometry element, which is a solid, which in this specific sample model is a quadrilateral with six faces and twelve edges. We can calculate the overlap of the closed shell faces with the wall faces, which will give us the adjacent surface.

The good thing about the latter approach is that part of the required analysis has already been implemented, in the SDK sample RoofsRooms. It includes a module GeomUtil.cs which implements a method AreSolidsCut. This method analyses whether any one room solid face is a subset of any roof solid face, in which case it returns true. In the RoofsRooms sample, this method is used to determine which roof element is covering which room. In our case, we would need to expand this method to not just return true if an overlap is found, but actually calculate the overlapping area. For the moment, this is left as an exercise to the reader. Submissions of working solutions are gladly accepted.

To implement a generic solution for calculating the area of two overlapping polygons, we need a 2D Boolean operation to calculate the intersection of two polygons. Unfortunately, the Revit API does not provide such a Boolean operation out of the box.

One might possibly be able to use the some of the functionality provided by various AutoCAD APIs such as AModeler or regions, by running AutoCAD in the background and calling a helper application. Of course, this requires AutoCAD to be installed on the same machine as your Revit application, which is not always desirable.

Another and possibly simpler option might be to make use of a free-standing Boolean operation library for polygons. There are a number of them out there, as you can see by googling for "polygon boolean" or by looking at the Wikipedia article on Boolean operations on polygons. I have downloaded the Generic Polygon Clipper (gpc) as well as the C# wrapper GpcWrapper for it, and that looks promising. Please let me know if you already have any experience making use of this or any other Boolean libraries within Revit.

Use F# Directly in Revit

Still struggling to load a native F# module directly as a Revit add-in? Ralf Huvendiek had a quick look at this issue and created all three different flavours of external commands implemented in F# that can be called directly as external Revit tools:

1. Defined in a namespace.
2. Defined in a module.
3. Defined in a module within a namespace.

The problem I had when calling F# via C# is caused by the line specifying 'module BuildingCoder', which generates the strange class names. But even those strange names can be entered and will work in the Revit.ini file.

The decorated name defined for the Execute method in the derived class by adding the interface prefix to it is also no problem. Apparently, the CLR ignores the name and uses some other method, maybe a position within a table, to determine what method to look up and call.

Here is Ralf's implementation of the three external command classes and their Execute methods; please watch out for the overly long lines in the F# source code ... you may have to copy and paste to an editor to see the full text:

Namespace

#light

namespace RevitAddin

open Autodesk.Revit

type RevitAddin() =
  interface Autodesk.Revit.IExternalCommand with
    member public this.Execute( cData, strMessage : string byref, aElements ) =
      strMessage <- "Hello world from RevitAddin.RevitAddin"
      Autodesk.Revit.IExternalCommand.Result.Failed

Module

#light

module RevitAddinModule

type RevitAddin() =
  interface Autodesk.Revit.IExternalCommand with
    member public this.Execute( cData, strMessage : string byref, aElements ) =
      strMessage <- "Hello world from RevitAddinModule.RevitAddin"
      Autodesk.Revit.IExternalCommand.Result.Failed

Module within Namespace

#light

namespace RevitAddin

module RevitAddinModule

type RevitAddin() =
  interface Autodesk.Revit.IExternalCommand with
    member public this.Execute( cData, strMessage : string byref, aElements ) =
      strMessage <- "Hello world from RevitAddin.RevitAddinModule.RevitAddin"
      Autodesk.Revit.IExternalCommand.Result.Failed

The corresponding Revit.ini entries for loading the three external commands thus defined look like this:

[ExternalCommands]
ECCount=3

ECName1=F# 1
ECDescription1=F# in namespace
ECAssembly1=...\RevitAddin.dll
ECClassName1=RevitAddin.RevitAddin

ECName2=F# 2
ECDescription2=F# in module
ECAssembly2=...\RevitAddin.dll
ECClassName2=RevitAddinModule+RevitAddin

ECName3=F# 3
ECDescription3=F# in namespace and module
ECAssembly3=...\RevitAddin.dll
ECClassName3=RevitAddin.RevitAddinModule+RevitAddin

The three dots need to be replaced by the full path name of your assembly.

Here is the complete Visual Studio 2008 F# solution FsRevitAddin.zip

So nothing more to stop you from checking out this exciting new functional language and creating a Revit-based entry for Kean's F# programming contest.

Several people asked how I retrieved the full class name including namespace prefix from Reflector. In my installation, the full name of the declaring type is listed in the bottom panel when you select a class or method:

3DS Max, Maya and MotionBuilder Training

Rendering is another topic of interest to some Revit developers, so please note that the Media and Entertainment team are inviting all interested parties to a series of free online trainings to learn 3ds Max, Maya or MotionBuilder APIs in just one hour a day during the March, April and May time frame.

Lunedi Sera in Verona

Last night was very enjoyable ... I took a yoga class with Marco in the Scuola Massalungo, opposite the faculty of economy in the Zona Universitá, then had an enjoyable meal in the eminently recommendable Osteria al Duca in Via Arche Scaligere 2, where I met Mauro Neri and had my 'realest' Italian conversation so far, for a couple of hours ... perfect preparation for the first Revit API introduction in Italiano today.

Unit Types and Format Options

Here is a question from Matt Mason and some exhaustive research results by Saikat Bhattacharya of Autodesk on unit types and their format options.

To provide some context, UnitType is an enumeration listing all the unit types supported by Revit. The FormatOptions class is used to manage information for the ProjectUnit.FormatOptions property, which returns a FormatOptions instance containing the user's current project unit settings for each UnitType queried. Through the project units and the format options management, each unit type is associated with one FormatOptions instance, which provides the following properties and values:

• Group, a UnitGroup enumeration value,
• Name, a string,
• Units, a display unit type, represented by a DisplayUnitType enumeration value,
• Symbol, a UnitSymbolType enumeration value,
• Rounding, a double value.

In this context, Matt asks:

Question: When attempting to get the FormatOptions for a given UnitType, I am getting exceptions for certain UnitTypes:

• AreaForceScale
• DecSheetLength
• Electrical Apparent Power
• Electrical Current
• Electrical Frequency
• Electrical Luminance
• Electrical Potential
• Electrical Power
• Electrical Power Density
• ForceScale
• HVAC *
• Linear Force Scale
• Moment Scale
• Number
• Pipe Size
• Piping *
• SheetLength
• SiteAngle
• WireSize

Some of these might be related to the fact that I am running the Revit Architecture flavour, but it is not clear to me that all of these are based on Revit flavour issues. Are some of these legacy or otherwise invalid types?

Answer: Saikat created the following mapping of the list of unit types provided with the disciplines in RAC as well as RME. Most of the unit types listed below belong to the MEP flavour of Revit and thus do not throw an exception in RME:

• AreaForceScale - Structural
• DecSheetLength -
• Electrical Apparent Power - Electrical
• Electrical Current - Electrical
• Electrical Frequency - Electrical
• Electrical Luminance - Electrical
• Electrical Potential - Electrical
• Electrical Power - Electrical
• Electrical Power Density - Electrical
• ForceScale - Structural
• HVAC * - HVAC
• Linear Force Scale - Structural
• Moment Scale - Structural
• Number -
• Pipe Size - Piping
• Piping * - Piping
• SheetLength -
• SiteAngle -
• WireSize - Electrical

After contacting the engineering team for more details, he compiled a more comprehensive list including 80 unit types with their format option groups and names, and additional notes on some of them. Here is a spreadsheet ProjectUnit.csv with the complete mapping in a neutral comma delimited CSV format.

After reviewing these results, Matt adds a note that the four 'special' unit types DecSheetLength, SheetLength, Number, and SiteAngle are 'fixed' and will throw an exception if you attempt to access them in any Revit Flavour. Saikat adds: As mentioned in the CSV file, there are more than the four special cases that Matt refers to as 'special'. The CSV file contains others which apply to all disciplines and also cannot be edited, which Matt refers to as 'fixed', and includes some notes on each of them.

Happy New Year in the East

I am always happy this time of year to hear from my far eastern colleagues about the biggest Chinese festival of the year, the Spring Festival and Chinese New Year. Here is calligraphy on this year's celebration that we received from Joe Ye:

Barbara Han and others provided the following explanation and rough translations:

Left

Field mouse jumps between the branches,
and makes the shadow of the moon wobble.

Right

Spring ...
An ox ploughing the field ...
Nice smell fills the valley.

These poems describes the winter mouse, meaning the last year, and the springtime ox, meaning this year.

Middle

The middle horizontal line says Happy New Year.

The middle character is 'Good luck' and is upside down. There is a meaning to this as well, about the good luck coming to you, and not going after it or holding on:

The middle character means good luck, good fortune, happiness, and so on, and its pronunciation is 'Fu'. Why is this character upside down? That is because the pronunciation of 'upside down' is 'Dao le' in Chinese, which is the same as another character meaning arriving, reaching, so when a guest enters your home and sees the poem, they might say 'oh, Fu Dao le', which sounds like 'good luck reaching your home', which are perfect words for you.

I hope you enjoy and appreciate this as much as I do. Happy New Year, good luck letting go, and good new beginnings every day and every moment!

AutoHotKey

Automate beyond the API ... Some parts of the Revit functionality are not yet accessible through the API, even though are repetitive tasks that are trivial to perform manually and a lot of work could be saved by automating them. One tool that many have found useful for this task and have published a number of working solutions for is AutoHotKey. Here is an AUGI discussion presenting a number of them, such as how to:

• Define F2 to open the View Range.
• Define F3 do perform Purge Unused.
• Define F5 to do a Save As to a filename that's been copied to the Windows clipboard first, and sets some additional options.
• Define F7 to set a solid's material to a new parameter called "Material".
• Define Win + 1 to Filter.
• Define Win + 2 to Finish Sketch.
• Define Win + 3 to Quit Sketch.
• Define Win + 1-4 to set various column heights.
• Automatically answer the message "This Central File has been copied".
• Remove the username from the INI file.

Walls and Doors on Two Levels

Here is a little note to answer a question from Berria on creating walls and doors on two separate levels. This is a slightly edited version of the original query:

Question: I need to create a house with two floors. I create a level and then a new wall and a door. It draws the two objects on different levels. When I build the first level, all is OK. An error occurs when I build the second, because the level to define the component position is always zero.

Answer: I cannot tell you off-hand what the problem is in your situation, but I can provide you with a code example that achieves your goal. Look at the external command Lab2_0_CreateLittleHouse in the Revit API introduction labs. To demonstrate that the code can be easily adapted to work on several levels, here is a modified version which creates only the walls and doors, omitting the other elements, and repeats the process on two levels. In order to place the second door, I do indeed modify the Z coordinate of its insertion point by setting 'midpoint.Z = levelMiddle.Elevation'. Before running this command, ensure that you have three levels in your model, and that the brain-dead code snippet which extracts them into the three variables really gets them in the right order:

WaitCursor waitCursor = new WaitCursor();
Application app = commandData.Application;
Document doc = app.ActiveDocument;
_createApp = app.Create;
_createDoc = doc.Create;
//
// determine the four corners of the rectangular house:
//
double width = 7 * LabConstants.MeterToFeet;
double depth = 4 * LabConstants.MeterToFeet;
List<XYZ> corners = new List<XYZ>( 4 );
corners.Add( new XYZ( 0, 0, 0 ) );
corners.Add( new XYZ( width, 0, 0 ) );
corners.Add( new XYZ( width, depth, 0 ) );
corners.Add( new XYZ( 0, depth, 0 ) );
 
Level levelBottom = null;
Level levelMiddle = null;
Level levelTop = null;
List<Element> levels = new List<Element>();
 
Filter filterType
  = _createApp.Filter.NewTypeFilter(
    typeof( Level ) );
 
doc.get_Elements( filterType, levels );
foreach( Element e in levels )
{
  if( null == levelBottom )
  {
    levelBottom = e as Level;
  }
  else if( null == levelMiddle )
  {
    levelMiddle = e as Level;
  }
  else if( null == levelTop )
  {
    levelTop = e as Level;
  }
  else
  {
    break;
  }
}
 
BuiltInParameter topLevelParam
  = BuiltInParameter.WALL_HEIGHT_TYPE;
 
Line line;
Wall wall;
Parameter param;
 
ElementId topId = levelMiddle.Id;
List<Wall> walls = new List<Wall>( 8 );
for( int i = 0; i < 4; ++i )
{
  line = _createApp.NewLineBound(
    corners[i], corners[3 == i ? 0 : i + 1] );
 
  wall = _createDoc.NewWall(
    line, levelBottom, false );
 
  param = wall.get_Parameter( topLevelParam );
  param.Set( ref topId );
  walls.Add( wall );
}
 
topId = levelTop.Id;
for( int i = 0; i < 4; ++i )
{
  line = _createApp.NewLineBound(
    corners[i], corners[3 == i ? 0 : i + 1] );
 
  wall = _createDoc.NewWall(
    line, levelMiddle, false );
 
  param = wall.get_Parameter( topLevelParam );
  param.Set( ref topId );
  walls.Add( wall );
}
 
List<Element> doorSymbols
  = LabUtils.GetAllFamilySymbols(
    app, BuiltInCategory.OST_Doors );
 
Debug.Assert(
  0 < doorSymbols.Count,
  "expected at least one door symbol"
  + " to be loaded into project" );
 
FamilySymbol door
  = doorSymbols[0] as FamilySymbol;
 
XYZ midpoint = LabUtils.Midpoint(
  corners[0], corners[1] );
 
FamilyInstance inst0
  = _createDoc.NewFamilyInstance(
    midpoint, door, walls[0], levelBottom,
    StructuralType.NonStructural );
 
midpoint.Z = levelMiddle.Elevation;
 
FamilyInstance inst1
  = _createDoc.NewFamilyInstance(
    midpoint, door, walls[4], levelMiddle,
    StructuralType.NonStructural );

return CmdResult.Succeeded;

Here is the result of running the command:

I hope this helps resolve your problem. And please do not use the upper door!

Element Caching

Here is a question from Julien Duprat of Vertice:

Question: I would like to know the best practises for data caching. This topic is mentioned in your tutorial on "Ten Steps for enhancing your Revit add-in". Specifically, I wonder:

• How to put the elements in a static List<Element> of cached elements?
• How to refresh this list?

Answer: We do not have any official recommendations from the API or development team, so it is more a question of finding out what works best.

The one thing to be aware of is that it is currently not possible to keep track of the exact state of the Revit database, because we are still lacking any element level events. We can request notification when certain events occur at an application or document level, such as application start-up or shutdown and document creation, open, save, and close. There is no notification about adding, deleting or modifying individual elements, though.

Another point is that this issue is much less important in Revit 2009 than it was in 2008. In 2008, we did not yet have the element filtering API. That meant that it was extremely expensive to retrieve a specific set of elements from the database, because the application basically had to iterate over the entire database and filter out the elements it needed itself. To avoid repeating this lengthy iteration several times, it was important to identify all required elements up front and perform the entire iteration for all required elements only once and in one single go. In 2009, with element filtering, this is not longer the case. We now have full support from the Revit API for a highly efficient and optimised selective access, and an application can repeatedly query the database for different sets of specific elements with hardly any overhead. Therefore, the need for caching elements is drastically reduced.

The first part of your question is very easy: to add an element to a generic list, simply call the Add method.

As explained, the second part is more difficult. I would suggest that you update the list every time you need to make use of it.