The Building Coder

Parameter Filter Units

The Western European DevDays conference tour has begun, and I will be presenting and travelling all week, leaving very little time to spend blogging or responding to comments. I visited relatives in London the preceding weekend, and took some time to write and post this before the real crunch began.

Several previous posts deal with various aspects of unit handling in the Revit API:

• Units.
• Formatting unit strings.
• Unit types and format options.
• Unit conversion.
• Unit Suffix and the ProjectUnit SDK sample.
• DisplayUnitType and UnitSymbolType.

Here is a new related information nugget, a surprising little quirk when defining Revit API filters that just came to my attention last week. In brief, a Revit API parameter filter specifying a length or area will be evaluated using the current user interface units, and not the database units, as one would expect. This is an inconsistency that we expect to change in future releases. This means that to make proper use of filters for selecting elements depending on some unit-based parameter, an add-in using the 2010 API will have to convert the target value to the current user interface unit. This is unexpected. I would expect that when working purely within the API, all units should remain in the internal database units, with no exceptions, not for filters nor for anything else. In future, this conversion will hopefully be removed, so that add-ins can work consistently and exclusively in Revit database units.

Specifically, the Filter.NewParameterFilter method taking the three arguments BuiltInParameter, CriteriaFilterType, and double returns the selected elements based on the units displayed in the user interface instead of the internal database units.

Example: This can be reproduced using the ElementsFilter SDK sample. I tested it by running the ElementsFilter in a minimal model with two rooms:

ROOM_AREA  Area  double   6.840 m2   73.63 sqf
ROOM_AREA  Area  double  14.440 m2  155.43 sqf

Specifying a filter to select all rooms with a value of ROOM_AREA exceeding 14 returns only the second, larger room, i.e. it is evaluating the parameter in the user interface area unit 'square meters' rather than the database area unit 'square feet'.

DUT versus UST

After a wonderful weekend in the Swiss alps climbing the Diechterhorn, here is a follow-up explanation by Jeremy Sawicki of Autodesk on the difference between DisplayUnitType and UnitSymbolType in continuation of our last discussion on the unit suffix.

Question: What is the exact difference between DisplayUnitType and UnitSymbolType, please?

For instance, the default project unit settings on my system for a length are DUT_Millimetres and UST_None ... I wonder what exactly that means?

Also, can you suggest a way to obtain the display string representation shown in the user interface for either of these?

Answer: The simplest answer is based on the UI. In the Format dialog box, DisplayUnitType corresponds to the Units dropdown:

And UnitSymbolType corresponds to the Unit symbol dropdown:

In most cases, the DisplayUnitType determines the actual unit, for example feet vs. meters, with a different conversion factor applying to each DisplayUnitType. UnitSymbolType affects how the units are indicated on the screen, usually with a suffix. For example, square feet can use a suffix of either SF or ft² or no suffix at all. UnitSymbolType used to be called UnitSuffixType until we introduced a currency unit type, which uses prefixes in some cases, like $.

The above applies to most normal units which are displayed as a number followed by a suffix, but there are various special cases. For example, DisplayUnitType is also used to select certain kinds of units with special formatting, like Feet and fractional inches or Degrees minutes seconds.

I don't believe there is currently any API that can get the names of display unit types or unit symbol types.

Many thanks to Jeremy for this helpful clarification!

Unit Suffix and the ProjectUnit SDK Sample

We delved into various aspects of units in several previous posts:

• Basics on units.
• Formatting unit strings.
• Unit types and format options.
• Unit conversion.

And still the topic is not exhausted. Here is a new point to consider:

Question: Is there a way to retrieve the unit for a parameter? I can read a parameter's value and its Display Unit Type but not the unit's symbol, the display string suffix used to represent the unit in the user interface. For example, for a length parameter I would like to retrieve FT or m for the unit symbol, or SF for an area parameter. I can read the parameter value and unit suffix combined by using AsValueString, but what about retrieving the unit symbol separately. If it is possible to get the parameter unit symbol, could you send me a short code snippet about it?

If the Revit API does not provide parameter value unit, then what is the use of FormatOption.Unitsymbol? For example, UST_FT_SUP_2? Can you give me an application of UST symbols?

Also, one way I can think of putting a unit next to a parameter value in the user interface is to write a long switch statement and determine the name of the parameter and its DUT. For example, if the parameter name is Area and its DUT is DUT_SQUARE_FEET then unit is SF, etc. Am I right?

Answer: Let us dive into the unit handling and the classes and enumerations used for this a little bit deeper before returning to the question.

The unit suffix you mention is a user defined setting, so it is actually not directly defined by the parameter itself. The parameter is defined as having a certain unit type such as length or area, and it is completely up to the user to define how values of this type are represented in the user interface.

The UnitType enumeration lists 81 different available unit types, the simplest of which are UT_Length and UT_Area.

The unit types are further grouped by discipline into unit groups, represented by the UnitGroup enumeration with the following members:

• UG_Common
• UG_Electrical
• UG_HVAC
• UG_Piping
• UG_Structural

Length and area belong to the common group, whereas more specific unit types such as force or moment are classified as according to discipline, e.g., structural.

How each unit is represented in the user interface is defined by the ProjectUnit and FormatOptions classes.

The description of the ProjectUnit class in the Revit API help file includes an example of accessing and listing this information.

The FormatOptions class contains the unit information of the current user settings in the project. It members include

• Group: the unit's type group.
• Name: the unit's type name.
• Rounding: the unit's type rounding and accuracy.
• Units: the unit type itself.
• Unitsymbol: the unit's type symbol.

We mentioned this class once in the past in the following blog post: http://thebuildingcoder.typepad.com/blog/2009/01/unit-types-and-format-options.html

A full example of managing the user-defined unit settings is provided by the SDK sample ProjectUnit. It demonstrates how to read and set units and format options. It defines an external command which displays a dialogue box listing all the units in the current project and displaying their format information, including the decimal separator and slope type.

This functionality includes

• List all units in current project and display each unit's format information.
• Display the current project units decimal symbol type of set it to comma or dot.
• Display the current project units slope type and set it to Rise or Angle.

The units listing uses the unit group classification by discipline, so a list all the available unit groups or disciplines is displayed and used to classify the units. When one unit group is selected in the list box, the corresponding project units and their name, format information, unit suffix type, and rounding is displayed.

• The name is the user interface display string such as Length or Area.
• The format information defines the display unit type such as DUT_KIP_FEET_PER_DEGREE_PER_FOOT, represented by the DisplayUnitType enumeration. This basically represents a numerical conversion factor from the Revit internal database units to the number you see in the user interface units.
• The unit suffix type specifies a string suffix appended to the value to communicate what units are being displayed. Possible values are defined by the UnitSymbolType enumeration, such as UST_NONE for length or UST_M_SUP_2 for area.
• The rounding or accuracy is a number like 1 or 0.2.

The unit's symbol that you mention in your question might correspond either to the format information or the unit suffix. There is a considerable overlap between these two enumerations.

The parameter definition has a ParameterType property, which returns the user visible interpretation of the parameter data. The Revit API help file provides a short code example of using this property. It returns a ParameterType enumeration value, and many of these values are associated with a unit type. The parameter definition also has a ParameterGroup property returning the group ID of the parameter definition, which is represented by the BuiltInParameterGroup enumeration. That can also give a hint on what units are appropriate.

To return to your original question, yes, there is a property on the parameter class itself for the DisplayUnitType as well as its definition. So you can simply use Parameter.DisplayUnitType to determine the DUT, just as you say. Yes, I do not see any access in the API to retrieve the display string of a DUT. These strings might be language dependent, and no API method has been provided to retrieve them for the localised product data. You will of course obtain the appropriate unit suffix by calling AsValueString.

For an application of the UnitSymbolType enumeration values, I can imagine that they might in fact be useful for what you are trying to achieve, since each enumeration name does actually describe the unit suffix. For instance:

• UST_M represents m.
• UST_M_CARET_2 represents m^2.
• UST_M_SUP_2 represents m².

So you could possibly reduce your switch statement to a shorter algorithm putting together your own unit suffix string based on interpreting the names of these enumeration values.

Alternatively, you could write a full switch statement such as you describe. It could be based on either the DUT or on the UST, since there is significant overlap between the two. This depends on what you actually want to display in the list. As you can see above, the default setting on my system for a length is DUT_Millimetres and UST_None, which are different, so depending on which of the two I base the unit symbol display on, I would get a different result.

Display Strings and Enumerations

Question: I need to get the string value displayed in the Revit user interface for some parameters whose values only contain an integer value, such as:

• Wall Function: the API returns an integer value, whereas the UI displays "Exterior".
• Wrapping at Inserts: again, the API returns an integer value, whereas the UI displays "Both".

Is there a general way to get a mapping between the integer values and the display strings for all such items in Revit?

Answer: For a parameter containing a double value representing a length or an area, you can retrieve the raw internal database value using the Parameter.AsDouble method, and the AsValueString method will return the string representation as displayed in the Revit user interface, honouring the current unit settings.

Unfortunately, for the enumerated parameter values you are interested in, the parameter value is just a normal integer value, and AsValueString can do nothing to convert it to the user interface display string. Please note that these display strings are localised, i.e. language dependent, so they cannot simply be hard-wired into the API. Revit does not provide any API method to retrieve the mapping from the internal integer values to the display strings programmatically. The mapping can be created manually by setting every option of the parameter in the user interface and then checking its integer value using RvtMgdDbg, which is obviously tedious and inefficient.

In the case of the wall function, this results in the following value mapping:

• 0 Interior
• 1 Exterior
• 2 Foundation
• 3 Retaining
• 4 Soffit
• 5 Core-shaft

The wall function is also represented by the WallFunction Enumeration in the API, which has the following values:

• Soffit
• Retaining
• Foundation
• Exterior
• Interior

Converting these enumeration values to integers does return the same numbers as those listed above. However, in this case, the Core-shaft entry is missing in the enumeration.

Whenever you run into an integer-valued parameter like this, it is worth while checking the Revit API help file to see whether a corresponding enumeration type is available. You may of course run into parameters for which this is not the case, or where some of the values displayed in the user interface are missing in the API, but in many cases this can save at least some of the manual effort described above.

My colleague Augusto Goncalves points out that this is an apt place to mention that you can use the .NET Enum class to get some information about the enumeration values, for example like this:

// list enum values:
 
string[] enumValues = Enum.GetNames( 
  typeof( Autodesk.Revit.Enums.WallFunction ) );
 
StringBuilder values 
  = new StringBuilder( "Values are: " );
 
foreach( string s in enumValues )
{
  values.AppendFormat( "\n{0}", s );
}
 
System.Windows.Forms.MessageBox.Show( 
  values.ToString() );
 
// convert an enum value to string:
 
Autodesk.Revit.Enums.WallFunction aValue 
  = Autodesk.Revit.Enums.WallFunction.Interior;
 
string aValueName = Enum.GetName( 
  aValue.GetType(), aValue );
 
System.Windows.Forms.MessageBox.Show( 
  String.Format( "The value is: {0}", aValueName ) );

By the way, conversion to a string can also be achieved even more simply and directly by using aValue.ToString().

Unit Conversion

Here is a useful and instructive reader-contributed unit conversion utility which has been submitted for addition to the official Revit SDK samples.

We discussed the Revit unit handling in one of the very first posts to this blog. One main point discussed there is the fact that Revit internally uses a fixed set of internal database units which cannot be changed. For instance, all lengths are measured in feet. The post mentions the simple unit converter provided by the MidasLink sample, which makes use of hard-wired self-maintained conversion constants, and suggests a simple hands-on manual approach for determining any required conversion factor.

The unit conversion utility presented here demonstrates how this process can be automated to avoid the need for any hard-coded conversion factors at all.

Revit includes a comprehensive internal unit handling library. One use of this is to convert and display the internal Revit database units to whatever units the user prefers to see in the user interface. It would be nice to access this functionality from our external add-in applications as well, instead of maintaining our own conversion routines. We already discussed one idea for an approach to access the internal Revit functionality to format unit strings using the AsValueString and SetValueString methods on the Parameter class. Now we can present a unit conversion utility making use of this idea.

For completeness' sake, we also mention another area related to units that we touched on briefly, the exploration of unit types and format options by Matt and Saikat.

The aptly name UnitConversion utility presented here demonstrates accessing the internal Revit unit handling functionality to implement the inverse direction as well, and also provides a helpful user interface for determining and testing unit handling functionality and conversion factors.

The implementation follows the service-oriented architecture or SOA paradigm that we introduced yesterday for maximising the use of independent functions implementing mutually self-contained building blocks of functionality.

Here is a copy of the UnitConversion source code It is richly commented, and the comments include a wealth of additional information on details of the Revit unit handling methods that are not repeated in this text, so I recommend that you read through the source code and comments in addition to the following article describing the utility and its implementation:

Using the Revit API to Perform Unit Conversions for You

When using the Revit API and needing to store values into your document, Revit expects you to provide those values in the units of measure that Revit uses internally. This has been discussed previously in this article. The generally accepted solution has been for you to manually determine the multipliers you need for the Unit Types with which you are working and essentially write your own unit converter, wherein you hard-code the multipliers you need and scale your data by them accordingly.

But sometimes it can be difficult to determine what those internal units of measure are, and thus what the multipliers are that you need to use in order to get the values you send to Revit via the API to have the correct meaning in Revit.

Normally, when using the Revit graphical interface, you set your Project Units to the units of measure in which you are working, type in your data in those units, and Revit takes care of the rest. This functionality is actually available in the API as well, preventing you from needing to determine multipliers, but it's not very intuitive to find.

The key piece of the puzzle is to use the 'SetValueString' method instead of the 'Set' method on a parameter. SetValueString takes a string representation of your value in the current project units and converts it for you to internal units when setting the value into the parameter.

For example, Revit uses Decimal Feet as the internal unit of measure for Length. If your project units for Length are set to inches, and you store into a parameter using SetValueString the string value for 12, Revit will automatically convert 12 inches into 1 foot and really store the value of 1 for you into the parameter. Using SetValueString, you don't even have to know that Revit has an internal unit of measure, let alone what those units of measure are.

Further, SetValueString allows you to override the current units of measure for the project by including unit symbols in your string. If, for example, your project units for Length are set to centimetres and you send the string value: 18" (with the trailing double quotes), Revit will interpret that as eighteen inches and will store the value 1.5 (one and a half feet) into your parameter for you.

As another example, having your project units for Length set to meters and using SetValueString with the value: 2' 3" (including the single and double quotes) will store the value 2.25 into the parameter. Revit knows how to do all the string parsing for you, and will throw an exception if you try to send it something it cannot interpret.

A parallel reverse function called AsValueString also exists in the Revit API. This will convert a parameter's internal value back to the string representation for the current project units. When the project units are Feet and Fractional Inches and a Length parameter has an internal value of 3.5, calling AsValueString will return the string 3' 6".

Using this knowledge, it is possible to write methods which can be used to help solve the unit conversion problem much more easily. For example, we can write a function to return the scale factor (multiplier) that is needed for a specific set of units of measure. We can also write a single function to set a parameter's value given the value and the units of measure in which that value was defined.

This has been accomplished in the UnitConversion sample, whose source code accompanies this article. The code leverages the new Family Editor API, so will only work in Revit 2010.

Here is a sample image to show the functionality provided:

We can see near the top of this form that for CFM or cubic feet per minute units, the scale factor (multiplier) we need to store our value into Revit is 0.01666666666666. You can copy that value to the clipboard from this form. So if we want to store 1000 CFM into Revit, we have to store the value 16.666666666.

For the mathematically inclined, this scale factor equates to 1/60, which tells us the internal units Revit uses for air flow are Cubic-Feet-per-Second. Interestingly, this unit is not available as a choice for Project Units in the Revit user interface, in spite of being used internally. That is one reason why it can be difficult to determine what scale factor should be used.

We can also see near the bottom of the form that when we store a value of 1.0 CFM, the internal value will be 0.01666666. This is actually how the scale factor can be determined for a given unit of measure: set a display value of 1.0 for those units of measure and see what is stored internally. This procedure for determining the required conversion factor corresponds exactly to Jeremy's manual approach: "To determine a unit conversion factor, set the parameter value to 1 in the user interface, then determine the value returned by the API; this will give you the exact conversion factor between the two."

Further, we can actually have Revit convert that value to a very different set of units of measure. In this case, we can have it convert 1.0 CFM to cubic meters per hour, which, as we can see near the bottom of the form, equates to 1.699010795520. That conversion is done using the AsValueString approach.

If you explore the sample code you will probably gain some more insights into how Revit works with parameters and units of measure. It's worth noting that this code was written following an n-tier, service-oriented architecture approach, as the comments in the code mention.

Because this architectural approach was used, it should not be difficult for you to extract the UnitFunctions class and perhaps put it into its own, separate assembly (DLL) for reuse in other projects.

However, at the very least you may find this sample application useful for providing accurate scale factors that can be copy-and-pasted directly from the form, if you still wish to embed hardcoded conversion factors into your code.

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.

Think Big in Revit

A couple of cases dealing with issues concerning small dimensions in Revit were recently raised by Toste Wallmark of Tecton Limited and Henrik Bengtsson of Lindab:

• Minimal length required when calling NewLineBound.
• Minimal possible family component dimension.
• Minimum scaling factor for annotation family symbol.

Minimal Length in NewLineBound

Question: I have discovered that NewLineBound throws System.ArgumentException "Value does not fall within the expected range" when the values are close or very close. Is that an expected behaviour in this case? How close can the line endpoints be for NewLineBound?

Answer: I wrote an external command with the following implementation of its Execute method and was able to verify your assertion with it:

double length = 1; // foot
try
{
  Application app = commandData.Application;
  XYZ p = new XYZ();
  XYZ q = new XYZ();
  Line line;
  while( 0 < length )
  {
    length = 0.5 * length;
    p.X = q.X = q.Y = length;
 
    Debug.Print( 
      "Creating model line of length {0}...", 
      length );
 
    line = app.Create.NewLineBound( p, q );
  }
  return CmdResult.Succeeded;
}
catch( Exception e )
{
  Debug.Print( 
    "Creating model line of length {0} "
    + "threw exception '{1}'", 
    length, e.Message );
 
  message = e.Message;
  return CmdResult.Failed;
}

This is the result of running this command in a new Revit model:

Creating model line of length 0.5...
Creating model line of length 0.25...
Creating model line of length 0.125...
Creating model line of length 0.0625...
Creating model line of length 0.03125...
Creating model line of length 0.015625...
Creating model line of length 0.0078125...
Creating model line of length 0.00390625...
Creating model line of length 0.001953125...

A first chance exception of type 
'System.ArgumentException' occurred in RevitAPI.dll

Creating model line of length 0.001953125 threw 
exception 'Value does not fall within the expected range.'

So apparently, you should not try to create any model lines with a length below about 0.004 feet, i.e. ca. 0.05 inches or 0.12 millimetres.

This makes pretty good sense to me in the context of an architectural model.

Minimal Family Component Dimension

Question: When building families, the smallest parametric dimension that can be created is about 0.7 mm. Why? This is causing a great deal of problems for us. We are designing profiles whose thicknesses range from 0.4 mm to 3.0 mm. Is there any workaround to lower the minimal allowable dimension limit?

To be exact, our thin metal profiles are produced in different thicknesses. The range is between 0.4 mm and 3.0 mm. When I am designing my product, I want the geometries to be exactly as the physical product.

In the same way, if someone is designing a hot rolled beam like an IPE270, it would really have been a problem if it was created 200 mm high or 300 mm instead of 270 mm. This is the same type of issue. The difference is big for us if you talk about 0.4 mm to 0.5 mm compared to 270 and 300.

With the current limitations in Revit, when I am designing our profile which is 0.7 mm, I have to artificially make it 0.8 mm instead. I will need to create a dummy parameter for the real thickness which is simple text, and then an extra parameter that controls the thickness of the profile. These cannot be the same and that slows me down, as well as having the problem that the profiles are designed with an inaccurate thickness. People will get confused.

Some things in the building process are quite thin and small and that has nothing to do with tolerances really. The tolerances are much smaller than this, but there is no need to express that. There is a very big difference between a profile that is 0.5 mm and 0.7 mm. The load bearing capacity will be twice as big and that is important if someone analyses the drawing in detail. Users will wonder why it is 0.8 instead of 0.7, especially since 0.8 mm might be available from some producers.

Answer: Revit in general is not intended to work with very thin elements of ca. 1 mm. We may have something like that to support surfaces for massing functionality, but it is not possible throughout the product.

The reason is that Revit is tuned up to address building scale modelling. Small details are incompatible with such scale, primary because they interfere with tolerances and it requires much more memory to combine in the same model very small and very large geometrical entities, with side effect of increased processing times.

One approach to such cases is to model the external shape of the object, such as a column, and use interior layers for thin materials.

Currently no such concept is applied to column, but only to wall, ceiling, floor, and roof, unless a column is joined geometry with a wall, in which case the column takes on the layer structure of the wall.

Meanwhile, detail components could be added to such columns in views in which they are cut. Certainly this can be done through the user interface, not sure if it is possible via the API as well.

Minimum Annotation Family Symbol Scaling Factor

Question: Annotation families cannot scale down in size when placed in views with 1:100 or smaller-sized items, e.g. 1:200, 1:500, etc. After setting a parameter of the annotation family which makes it too small, Revit says 'Can't make type xxx", with error in Generic Annotation.

The error seems to happen when the line is shorter than 1 mm.

Is there any way to use the API to circumvent this, e.g. to scale down the annotation to an even smaller size in the view?

Answer: Unfortunately, there is no known way to achieve this. Revit is not designed to function with elements of that size.

Inserting a Beam

This is the final Verona installment, discussing the last remaining topic raised in the Revit API training in Verona the week before last, on creating new beam types and inserting beam instances through the API.

Similar to the exploration concerning columns, we explored the following topics:

• Retrieving all matching family elements in current document in order to check whether the family we are interested in is loaded.
• Exploring the results of using a FamilyFilter.
• Loading a new family, if not already present.
• Creating a new family symbol, i.e. duplicating a beam type and setting its name and dimensions.
• Inserting a new beam instance into the model.

The interesting new aspects addressed with beams compared to columns are:

• The family type parameters and the naming convention used are completely different.
• Inserting a beam instance requires using a different version of NewFamilyInstance.

We implemented a new external command CmdNewBeamTypeInstance to demonstrate the steps listed above. It is very similar to the command CmdNewColumnTypeInstance for the columns. First, we set up some constants to define the family we are interested in, its library path, the structural type and a unit conversion:

const string family_name
  = "M_Concrete-Rectangular Beam";
 
const string extension
  = ".rfa";
 
const string directory
  = "C:/Documents and Settings/All Users"
  + "/Application Data/Autodesk/RAC 2009"
  + "/Metric Library/Structural/Framing"
  + "/Concrete/";
 
const string path
  = directory + family_name + extension;
 
StructuralType stBeam
  = StructuralType.Beam;

Creating a new Beam Type

Most of the implementation of the Execute method is the same as for CmdNewColumnTypeInstance. We check whether the family we are interested in is already loaded, making use of a family filter to get all family elements in the current document. We again note that the family filter returns both the symbols contained within the family and the family itself. The family element itself is stored in the variable 'f', and its symbols are simply listed. In real life, we would probably eliminate the symbols by creating a Boolean 'and' filter and filtering for the Family class as well as the family name. If the family was not already loaded, then 'f' remains null, and we load it with the LoadFamily method. It would also be sufficient to load one single symbol from the family, since we just need one single symbol 's' in order to call its Duplicate method. Any one will do, so we simply select the first one. When duplicating it, we simultaneously define the new symbol name. We list all its parameters, set the new type's dimensions, and demonstrate that we can change its name at a later stage as well if desired:

s.get_Parameter( "b" ).Set(
  Util.MmToFoot( 500 ) );
 
s.get_Parameter( "h" ).Set(
  Util.MmToFoot( 1000 ) );

s.Name = "Nuovo simbolo due";

The names of the dimension parameters we are interested in for the beam are named 'b' and 'h'. The column class that we examined used a completely different naming convention, with full names and upper-case initial letters, e.g. 'Width' and 'Depth'. This just goes to show that families are user defined and every family can use different conventions.

The new beam and column types appear like this in the Revit project browser:

To follow the standard Revit type naming conventions, we would normally include the new type dimensions in its name, like the existing types do.

Creating FamilyInstance Objects

We did some experiments in order to place an instance of our new symbol in the model. First we verified that it is possible to insert a beam, which normally uses a location line, by specifying only a location point:

XYZ p = XYZ.Zero;
doc.Create.NewFamilyInstance( p, s, nonStructural );

We can also place it with just a point and a direction:

XYZ p = XYZ.Zero;
XYZ q = app.Create.NewXYZ( 30, 20, 20 ); // feet

FamilyInstance fi = doc.Create.NewFamilyInstance(
  p, s, q, null, nonStructural );

In both of these cases, the instance has no location line defined for it, causing it to behave rather strangely and basically be unusable, e.g. it cannot be selected.

It is also possible to place it on a level, but lacking a location line, this version is also not really useful:

List<Element> levels = new List<Element>();
doc.get_Elements( typeof( Level ), levels );
Debug.Assert( 0 < levels.Count,
  "expected at least one level in model" );
 
Level level = levels[0] as Level;
 
fi = doc.Create.NewFamilyInstance(
  line, s, level, nonStructural );

These various attempts led us to realise that we really do need to define a location line for the beam. We also verified that we must specify a structural type. Specifying a non-structural type means that no beam is created, and results in a null family instance. So this is the final working version for inserting a valid instance of a beam with sloped location line:

XYZ p = XYZ.Zero;
XYZ q = app.Create.NewXYZ( 30, 20, 20 ); // feet

Line line = app.Create.NewLineBound( p, q );

FamilyInstance fi = doc.Create.NewFamilyInstance(
  line, s, null, stBeam );

Here is an image showing the result of running the two new commands CmdNewBeamTypeInstance and CmdNewColumnTypeInstance, which insert one instance each of the of the new beam and column types:

By the way, if you have any questions regarding the use of NewFamilyInstance and especially the choice of the correct overload to use for specific situations, the first place to look is in the Revit 2009 API Developer Guide section 11.3.4 on Creating FamilyInstance Objects. That document contains the most complete and up-to-date description of the topic. That section was also provided temporarily as a stand-alone SDK document named Guide to placing Family Instances with the API.doc This document provides a roadmap on how to create different categories of family instances using the API. Typically these instances are created using one of the eight overloads of the Autodesk.Revit.Creation.Document method NewFamilyInstance. The choice of which overload to use depends not only on the category of the instance, but also other characteristics of the placement, such as whether it should be hosted, placed relative to a reference level, or placed directly on a particular face. The details are included in a table. Instances of some family types are better created through methods other than NewFamilyInstance and are listed in a second table.

Here is version 1.0.0.24 of the complete Visual Studio solution with the new CmdNewBeamTypeInstance command implementation.

Inserting a Column

Here I continue the discussion of another of the topics that were raised in the Revit API training in Verona last week, on creating new column types and inserting column instances through the API.

We explored the following topics:

• Retrieving all family elements in current document in order to check whether the family we are interested in is loaded.
• Exploring the results of using a FamilyFilter.
• Loading a new family, if not already present.
• Creating a new family symbol, i.e. duplicating a type and setting its name and dimensions.
• Inserting a new column instance into the model.

We implemented a new external command CmdNewColumnTypeInstance to demonstrate these steps. First, we set up some constants to define the family we are interested in, our library path, the structural type and a unit conversion:

const string family_name
  = "M_Rectangular Column";
 
const string extension
  = ".rfa";
 
const string directory
  = "C:/Documents and Settings/All Users"
  + "/Application Data/Autodesk/RAC 2009"
  + "/Metric Library/Columns/";
 
const string path
  = directory + family_name + extension;
 
StructuralType nonStructural
  = StructuralType.NonStructural;
 
const double _foot_to_mm
  = 25.4 * 12;

Here is the implementation of the Execute method which achieves the steps listed above:

In order to check whether the family we are interested in is already loaded, we make use of a family filter to get all family elements in the current document. If so, we store it in the variable 'f'.

The family filter returns both the symbols contained within the family and the family itself. In real life, we would probably eliminate the symbols by creating a Boolean 'and' filter and filtering for the Family class as well as the family name.

CmdResult rc
  = CmdResult.Failed;
 
Application app = commandData.Application;
Document doc = app.ActiveDocument;

List<Element> symbols = new List<Element>();
 
Filter filter = app.Create.Filter.NewFamilyFilter(
  family_name );
 
doc.get_Elements( filter, symbols );

Family f = null;
foreach( Element e in symbols )
{
  if( e is Family )
  {
    f = e as Family;
  }
  else if( e is FamilySymbol )
  {
    FamilySymbol s = e as FamilySymbol;
    Debug.Print(
      "Family name={0}, symbol name={1}",
      s.Family.Name, s.Name );
  }
}

If the family was not already loaded, then 'f' remains null, and we load it with the LoadFamily method. It would also be sufficient to load one single symbol from the family:

if( null == f )
{
  if( !doc.LoadFamily( path, ref f ) )
  {
    message = "Unable to load '" + path + "'.";
  }
}

If the loading does not succeed, 'f' is still null and we cannot proceed. Otherwise, we pick one of them for duplication and store it in the variable 's'. Any one will do, so we simply select the first one.

if( null != f )
{
  Debug.Print( "Family name={0}", f.Name );

  FamilySymbol s = null;
  foreach( FamilySymbol s2 in f.Symbols )
  {
    s = s2;
    break;
  }
  Debug.Assert( null != s,
    "expected at least one symbol"
    + " to be defined in family" );

We duplicate it using the Duplicate method, simultaneously defining the new symbol name. To find out what parameters are available for setting the new type's dimensions, we first list all of them. We set the new type's dimensions and demonstrate that we can change its name at a later stage as well if desired. By trial and error, we definitely proved that when using a localised name to set the parameter value, the specified name is case sensitive.

  Symbol s1 = s.Duplicate( "Nuovo simbolo" );
  s = s1 as FamilySymbol;

  foreach( Parameter param in s.Parameters )
  {
    Debug.Print(
      "Parameter name={0}, value={1}",
      param.Definition.Name,
      param.AsValueString() );
  }

  s.get_Parameter( "Width" ).Set(
    500 / _foot_to_mm );
 
  s.get_Parameter( "Depth" ).Set(
    1000 / _foot_to_mm );

  s.Name = "Nuovo simbolo due";

Finally, we insert an instance of our new symbol. We also tested inserting it using a non-vertical reference direction, but that is ignored for columns, because columns are inherently vertical:

  XYZ p = XYZ.Zero;
  doc.Create.NewFamilyInstance(
    p, s, nonStructural );

  rc = CmdResult.Succeeded;
}
return rc;

The next step we took was to explore the similar concepts for beams and braces, but the discussion of those steps will have to wait until some later time.

Here is version 1.0.0.23 of the complete Visual Studio solution with this new command implementation.

Compound Wall Layer Volumes

Here I continue the discussion of one of the topics that were raised in the Revit API training in Verona last week.

We can combine the two discussion strands analysing wall areas and compound wall layers to calculate the volumes of each individual layer in a compound wall.

In our initial idea for implementing this, we thought of making use of the wall area that we calculated ourselves from the appropriate face of the wall's solid geometry. Whatever method we use to determine the area, there will be some imprecision in the calculation, since the wall profile area will be calculated either for the inner or outer face of the wall, which will not exactly match the area of some of the interior layers, depending on how the wall layers connect in the corners and wall intersections.

Later, we discovered that a simpler and sometimes exact approach is given by using the value of the built-in parameter HOST_AREA_COMPUTED instead. In a compound wall with multiple layers, we can simply multiply this value with the thickness of each of the component layers to obtain the volume of each layer. We implemented a test to compare the sum of all the component layer volumes with the total wall volume obtained from the HOST_VOLUME_COMPUTED parameter. Depending on the type of wall connection, the two results are sometimes exactly equal.

Since the Revit database unit for length is feet, all our raw values will be in feet for length, square feet for area, and cubic feet for volume. We convert the data to metric before displaying it.

To store the cumulated volumes for each wall layer as well as the wall total, we make use of a dictionary mapping a key to a double number representing the volume. The key is defined by concatenating the wall type name and the layer function, using the string " : " as a separator.

Since we want to cumulate the volumes for all selected walls, we implemented a derived class MapLayerToVolume with a Cumulate method. If we used the generic Dictionary class directly, we would have to use the ContainsKey as well as the Add method to check whether the key is present before adding to its volume:

class MapLayerToVolume
  : Dictionary<string, double>
{
  public void Cumulate(
    string key,
    double value )
  {
    if( !ContainsKey( key ) )
    {
      this[key] = 0.0;
    }
    this[key] += value;
  }
}

We define constants for the two parameters we are interested in and a little helper method to retrieve their values from a given wall:

const BuiltInParameter _bipArea
  = BuiltInParameter.HOST_AREA_COMPUTED;
 
const BuiltInParameter _bipVolume
  = BuiltInParameter.HOST_VOLUME_COMPUTED;
 
double GetWallParameter(
  Wall wall,
  BuiltInParameter bip )
{
  Parameter p = wall.get_Parameter( bip );
 
  Debug.Assert( null != p,
    "expected wall to have "
    + "HOST_AREA_COMPUTED and "
    + "HOST_VOLUME_COMPUTED parameters" );
 
  return p.AsDouble();
}

The method GetWallLayerVolumes uses this helper method to determine and cumulate the compound wall layer volumes for a given wall:

void GetWallLayerVolumes(
  Wall wall,
  ref MapLayerToVolume totalVolumes )
{
  WallType wt = wall.WallType;
 
  CompoundStructure structure
    = wt.CompoundStructure;
 
  CompoundStructureLayerArray layers
    = structure.Layers;
 
  int i, n = layers.Size;
  double area = GetWallParameter( wall, _bipArea );
  double volume = GetWallParameter( wall, _bipVolume );
  double thickness = wt.Width;
 
  string desc = Util.ElementDescription( wall );
 
  Debug.WriteLine( string.Format(
    "{0} with thickness {1}"
    + " and volume {2}"
    + " has {3} layer{4}{5}",
    desc,
    Util.MmString( thickness ),
    Util.RealString( volume ),
    n, Util.PluralSuffix( n ),
    Util.DotOrColon( n ) ) );
 
  //
  // volume for entire wall:
  //
  string key = wall.WallType.Name;
  totalVolumes.Cumulate( key, volume );
 
  //
  // volume for compound wall layers:
  //
  if( 0 < n )
  {
    i = 0;
    double total = 0.0;
    double layerVolume;
    foreach( CompoundStructureLayer
      layer in layers )
    {
      key = wall.WallType.Name + " : "
        + layer.Function;
 
      layerVolume = area * layer.Thickness;
 
      totalVolumes.Cumulate( key, layerVolume );
      total += layerVolume;
 
      Debug.WriteLine( string.Format(
        "  Layer {0}: function {1}, "
        + "thickness {2}, volume {3}",
        ++i, layer.Function,
        Util.MmString( layer.Thickness ),
        Util.RealString( layerVolume ) ) );
    }
 
    Debug.Print( "Wall volume = {0},"
      + " total layer volume = {1}",
      Util.RealString( volume ),
      Util.RealString( total ) );
 
    if( !Util.IsEqual( volume, total ) )
    {
      Debug.Print( "Wall host volume parameter"
        + " value differs from sum of all layer"
        + " volumes: {0}",
        volume - total );
    }
}

It iterates over each layer in the compound structure of the wall and determines its volume by multiplying the wall area with the layer thickness. It checks whether the total wall volume obtained from the HOST_VOLUME_COMPUTED parameter is equal to the sum of all the individual layer volumes and reports the difference if this is not the case.

The mainline of the command selects the walls to process, applies GetWallLayerVolumes to each one in turn, and presents the results. The user can preselect some specific walls, otherwise all walls in the project will be processed:

Application app = commandData.Application;
Document doc = app.ActiveDocument;

List<Element> walls = new List<Element>();
if( !Util.GetSelectedElementsOrAll(
  walls, doc, typeof( Wall ) ) )
{
  Selection sel = doc.Selection;
  message = ( 0 < sel.Elements.Size )
    ? "Please select some wall elements."
    : "No wall elements found.";
  return CmdResult.Failed;
}
 
MapLayerToVolume totalVolumes
  = new MapLayerToVolume();
 
foreach( Wall wall in walls )
{
  GetWallLayerVolumes( wall, ref totalVolumes );
}
 
string msg
  = "Compound wall layer volumes formatted as '"
  + "wall type : layer function :";
  + " volume in cubic meters':\n";
 
List<string> keys = new List<string>(
  totalVolumes.Keys );
 
keys.Sort();
 
foreach( string key in keys )
{
  msg += "\n" + key + " : "
    + Util.RealString(
      Util.CubicFootToCubicMeter(
      totalVolumes[key] ) );
}
 
Util.InfoMsg( msg );
 
return CmdResult.Cancelled;

The command returns CmdResult.Cancelled, because no changes have been made to the Revit database. If we return Succeeded, the document is unnecessarily marked as dirty.

Before displaying the volumes, they are converted from the raw internal cubic feet units to cubic meters using a new utility function CubicFootToCubicMeter:

const double _convertFootToMm = 12 * 25.4;
 
const double _convertFootToMeter
  = _convertFootToMm * 0.001;
 
const double _convertCubicFootToCubicMeter
  = _convertFootToMeter
  * _convertFootToMeter
  * _convertFootToMeter;
 
static public double CubicFootToCubicMeter(
  double volume )
{
  return volume * _convertCubicFootToCubicMeter;
}

Here is the debug output produced by running this analysis in a simple project with just a few walls:

Walls <130328 Exterior - Block on Mtl. Stud> with thickness 460 mm and volume 679.68 has 7 layers:
  Layer 1: function Finish1, thickness 200 mm, volume 295.51
  Layer 2: function ThermalOrAir, thickness 76 mm, volume 112.29
  Layer 3: function MembraneLayer, thickness 0 mm, volume 0
  Layer 4: function Substrate, thickness 19 mm, volume 28.07
  Layer 5: function Structure, thickness 152 mm, volume 224.59
  Layer 6: function MembraneLayer, thickness 0 mm, volume 0
  Layer 7: function Finish2, thickness 13 mm, volume 19.21
Wall volume = 679.68, total layer volume = 679.68

Walls <130357 Exterior - Block on Mtl. Stud> with thickness 460 mm and volume 489.94 has 7 layers:
  Layer 1: function Finish1, thickness 200 mm, volume 213.02
  Layer 2: function ThermalOrAir, thickness 76 mm, volume 80.95
  Layer 3: function MembraneLayer, thickness 0 mm, volume 0
  Layer 4: function Substrate, thickness 19 mm, volume 20.24
  Layer 5: function Structure, thickness 152 mm, volume 161.89
  Layer 6: function MembraneLayer, thickness 0 mm, volume 0
  Layer 7: function Finish2, thickness 13 mm, volume 13.85
Wall volume = 489.94, total layer volume = 489.94

Walls <130424 Generic - 200mm> with thickness 200 mm and volume 791.05 has 1 layer:
  Layer 1: function Structure, thickness 200 mm, volume 791.05
Wall volume = 791.05, total layer volume = 791.05

Compound wall layer volumes formatted as 'wall type : layer function : volume in cubic meters':

Exterior - Block on Mtl. Stud : 33.12
Exterior - Block on Mtl. Stud : Finish1 : 14.4
Exterior - Block on Mtl. Stud : Finish2 : 0.94
Exterior - Block on Mtl. Stud : MembraneLayer : 0
Exterior - Block on Mtl. Stud : Structure : 10.94
Exterior - Block on Mtl. Stud : Substrate : 1.37
Exterior - Block on Mtl. Stud : ThermalOrAir : 5.47
Generic - 200mm : 22.4
Generic - 200mm : Structure : 22.4

To see the full text, you will have to copy and paste to a text editor.

The final result is displayed in a dialogue box:

Here is an updated version 1.0.0.21 of the complete Visual Studio solution with this new command implementation.