The Building Coder

Migrating The Building Coder Samples to Revit 2014

I started migrating The Building Coder samples to Revit 2014. Funnily enough, on the exact same date as last year for the previous version.

The changes are very small this time around.

Furthermore, I am well prepared, since I recently intentionally eliminated all compiler warnings and deprecated calls compiling the code for Revit 2013.

First, however, a picture or three from my ski tour last weekend over Il Chapütschin (3386 m) and La Sella (3584 m) in the Swiss Engadin. Here I am on the first summit:

The panorama is grandiose:

We arrive back at the hut tired and happy:

Migrating The Building Coder Samples to Revit 2014

Back at the desk and steeped in the Revit API, Here is what I have done so far to migrate The Building Coder samples from Revit 2013 to Revit 2014:

• Update the Revit API assembly references
• Remove obsolete Collections namespace and RoomCreationData class
• TopographySurface namespace changed
• Some unit API changes
• Initial Revit 2014 version

Update the Revit API Assembly References

Every Revit add-in needs to reference the API assemblies.

They now live in the main Revit installation folder, together with Revit.exe.

In my case, this folder is "C:\Program Files\Autodesk\Revit Architecture 2014", and I am referencing the three assemblies RevitAPI, RevitAPIUI and UIFrameworkServices.

Just updating the references and recompiling generated 5 errors and 3 warnings.

Remove Obsolete Collections Namespace and RoomCreationData Class

Four of the five errors say "The type or namespace name 'Collections' does not exist in the namespace 'Autodesk.Revit' (are you missing an assembly reference?)".

To my surprise, I did indeed have several obsolete statements like this left over from previous versions:

using Autodesk.Revit.Collections;

They were actually not required at all by the Revit 2013 compilation, just left over from still older versions.

The fifth warning is similar, saying "The type or namespace name 'RoomCreationData' does not exist in the namespace 'Autodesk.Revit.Creation' (are you missing an assembly reference?)", and could also be resolved simply by removing this obsolete using statement:

using RoomCreationData
  = Autodesk.Revit.Creation.RoomCreationData;

Removing these erroneous using statements enables the compilation proper to execute and raises the number of problems reported to 3 errors and 108 warnings.

Just three errors! Looking good...

TopographySurface Namespace Changed

Now we hit some real errors caused by slight shifts and redefinitions in the API.

The first error is in CmdLandXml.cs:

  TopographySurface surface
    = doc.Create.NewTopographySurface( pts );

It says "The type or namespace name 'TopographySurface' could not be found (are you missing a using directive or an assembly reference?)".

The TopographySurface class apparently moved from one namespace to another. In Revit 2013, it lived in Autodesk.Revit.DB.

This is easily remedied by placing the cursor over the offending class name and pressing Ctrl + '.', which brings up a menu listing the fully qualified class name and offering to automatically correct the error for you:

Some Unit API Changes

The other two errors refer to units, one of the few areas seriously modified in the Revit 2014 API, and say:

• 'Autodesk.Revit.DB.Document' does not contain a definition for 'ProjectUnit' and no extension method 'ProjectUnit' accepting a first argument of type 'Autodesk.Revit.DB.Document' could be found (are you missing a using directive or an assembly reference?)
• 'Autodesk.Revit.DB.FormatOptions' does not contain a definition for 'Units' and no extension method 'Units' accepting a first argument of type 'Autodesk.Revit.DB.FormatOptions' could be found (are you missing a using directive or an assembly reference?)

They are caused by the following lines in ParameterUnitConverter.cs:

  FormatOptions fo = document.ProjectUnit
    .get_FormatOptions( ut );
 
  DisplayUnitType dut = fo.Units;

They are easily fixed by using the following new methods and properties:

  FormatOptions fo = document.GetUnits()
    .GetFormatOptions( ut );
 
  DisplayUnitType dut = fo.DisplayUnits;

We are left with zero errors and 111 warnings, which we will leave to deal with another day.

Initial Revit 2014 Version

So here is the result, the very first version 2014.0.100.2 of The Building Coder samples for Revit 2014.

To compare with the last version for Revit 2013, look at the version 2013.0.100.2 that I provided after eliminating all compiler warnings and deprecated calls.

Units and RevitLookup

Here is a typical question from a Revit API newbie that prompts me to reiterate some important basic beginner information on units and the RevitLookup tool for exploring the Revit database:

Question: How can I retrieve the length and mass units from a Revit document?

Answer: The internal Revit database length unit is always imperial feet.

That cannot be changed, so there is you answer for that.

Similarly, the internal database unit for weight is kg, as far as I know.

Revit Database Units

In fact, most internal Revit database units except length are SI units, and length is handled differently.

The user interface can display other units, set up just as the user prefers. They can also be modified programmatically, as demonstrated by the ProjectUnit SDK sample.

You can determine any internal database unit by setting the value of a given parameter using it on some Revit element to a specific number, e.g. 1.0, in the user interface.

You can then use RevitLookup to examine the parameter's resulting underlying database value.

The quotient between the user display and the underlying database values provides a factor that you can use to convert between user display and internal database units and enables you to determine what the internal database unit actually is.

This topic has been discussed exhaustively on The Building Coder blog. In fact, one of the very first posts ever is still perfectly valid. It deals with and covers all the fundamental facts of units.

We presented a unit conversion tool and updated it for Revit 2011 and 2013.

Many other aspects of this topic are collected in The Building Coder units category.

RevitLookup

I mentioned RevitLookup above. This is one of the most important tools, both for developers and end users, that you absolutely must be aware of.

It was formerly named RvtMgdDbg. This detailed description still calls it so.

Here are step-by-step installation instructions for Revit 2011 that pretty much still apply. There is even a video demonstrating the installation for Revit 2013.

RevitLookup is included in the Revit SDK available from the Revit Developer Center, which also includes all the other important material for getting started with the Revit API. Here is also an updated version with a corrected add-in manifest file to simplify the installation.

I hope that fully answers your question and helps you get started successfully.

Revit 2013 Unit Conversion Utility

Here is a Revit 2013 update of the Revit 2011 unit conversion utility, originally posted and described for Revit 2010, by Harry Mattison.

In his own words:

I was looking at the great unit conversion utility and created a new version upgraded to Revit 2013 that I thought you readers might enjoy.

I ran into one issue that required a code enhancement to catch an exception thrown by many parameters, such as HVAC_Temperature, HVAC_Slope, etc.

The rest of the code handles error conditions nicely, so I was surprised to see these uncaught exceptions.

I solved it by adding a try/catch statement around the existing call to AddParameter in frmUnitConversions.cs:

  if( null == _Parameter )
  {
    // Create a new parameter
 
    try
    {
      _Parameter
        = _DbDocument.FamilyManager.AddParameter(
          parameterTypeToCreate.ToString(),
          BuiltInParameterGroup.INVALID,
          parameterTypeToCreate,
          false );
    }
    catch( Exception ex )
    {
      TaskDialog.Show( "Error",
        "Cannot create parameter '"
        + parameterTypeToCreate.ToString()
        + "' with parameter type '"
        + parameterTypeToCreate
        + "' because of exception\n"
        + ex.Message.ToString() );
 
      return;
    }
  }

I think I figured out what is causing this and thought it would be interesting to share with your blog readers:

I am creating family parameters from a shared parameter file. Some parameters have types that are not supported in the version of Revit that I am currently using, which is Revit Architecture.

I created this function to detect the situation:

  public static bool canGetFormatOptions(
    Document doc,
    FamilyParameter familyParameter )
  {
    try
    {
      UnitType parameterUnitType
        = ConvertParameterTypeToUnitType(
          familyParameter.Definition.ParameterType );
 
      doc.ProjectUnit.get_FormatOptions(
        parameterUnitType );
 
      return true;
    }
    catch
    {
      return false;
    }
  }

I use it like this:

  if( !canGetFormatOptions(
    famDoc, familyParameter ) )
  {
    TaskDialog.Show( "Error",
      "Cannot set parameter value.\nUnit Type "
      + ConvertParameterTypeToUnitType(
        familyParameter.Definition.ParameterType )
      + " is not supported in Revit "
      + famDoc.Application.Product.ToString() );
  }

Take care.

The updated code is provided above.

Many thanks to Harry for this update with his enhancement and analysis!

Point Cloud Unit Conversion

Happy New Year of the Dragon!

Top: Happy New Year!

Bottom: Lucky Peace!

The Chinese dragon is the symbol of emperor and power.

Thanks to Joe Ye and nipic.com for the image and translation!

Besides programming Revit and climbing mountains, I also like climbing trees:

Returning to the Revit API, the topic of units is a recurring theme, and here it is again rearing its beautiful head in the context of point cloud data access:

Question: I am working on a point cloud engine implementation for Revit. In the IPointCloudAccess interface, the GetUnitsToFeetConversionFactor method seems to define the factor between the point cloud units and feet. It is not working properly for me, though. The only way I am able to use it so far is to convert all my points into feet myself and have this method return a constant factor of 1.0.

My point clouds always have a unit of measure, which is currently defined in meters, so an internal data item of 1 means 1 meter. If the Revit model's internal data also uses a fixed built-in length unit and not the unit preference to visible in the user interface, then the conversion between the point cloud data and the Revit model is fixed. Otherwise, if the Revit model's internal data is unitless (like AutoCAD DWG), the customer has to determine what unit is to be used to map the points into the model.

In the Revit user interface, I experimented with creating a circle and saving it. When it is selected, it displays the radius in the current user interface unit preference. If I change the unit preference, it displays a new value, showing that the actual radius did not change. This makes me believe that the internal data has a unit of measure. What is it? Is there a difference between the US English and German versions of Revit?

Answer: The explorations you describe toward the end of your query are leading in the absolutely right direction, and the solution is very simple, but not obvious.

Revit does indeed use a fixed internal database unit for all length measurements, and that unit is the imperial foot. There is thus no difference between the different versions and languages of Revit; they all use the same internal database unit. This fact is special enough to deserve a separate discussion of its own.

A test very similar to the one you describe can easily be expanded to reliably determine the conversion factor between any given user interface unit and the internal Revit database one, as explained in the discussion of unit conversion and preceding posts. You can also look at the entire collection of unit topics.

Here is a suggestion on how to implement the IPointCloudAccess interface GetUnitsToFeetConversionFactor method, assuming the point cloud data is given in millimetres:

  class PointCloudAccess : IPointCloudAccess
  {
    const double _mm_per_inch = 25.4;
    const double _mm_per_foot = 12 * _mm_per_inch;
    const double _mm_to_feet = 1.0 / _mm_per_foot;
 
    public double GetUnitsToFeetConversionFactor()
    {
      return _mm_to_feet;
    }
 
    // . . .
 
  }

Unit Conversion and Display String Formatting

AU went very well for me, and I think this was the one I liked most of all so far, to my own surprise. Now I am already at the next conference in Moscow, from where I continue to Tel Aviv tomorrow. December is always my monster travelling month, and I never get to prepare for Christmas or enjoy the dark and cosy celebration of Advent. But I really did have fun and enjoy AU in Las Vegas.

Sunday morning my colleague Marat Mirgaleev invited me to join him in his weekly volleyball game, which was a wonderful break from the conference presentation preparation. Marat is also a member of the ADN DevTech team and spelled Марат Миргалеев in Cyrillic. Another Autodesk colleague who also joined was Rustam Ibragimov, Рустам Ибрагимов. Here are Rustam, Marat, I and our all-time star, the volleyball herself:

Here we are now in the Autodesk Moscow office:

Fittingly enough, here is a question from Russia, by Victor Chekalin, or Виктор Чекалин in Cyrillic, on formatting a floating point number as a display string using the current project units. This issue has cropped up several times recently, and various solutions based on the same principle have been suggested, among others by Joe Offord of Enclos, who already shared insights on accessing curtain wall geometry, speeding up the interactive selection process, mirroring in a new family and changing the active view, and constructing a planar face transform.

All of the solutions to this problem I have seen revolve around stuffing in the value to format into an unused parameter picked up from some arbitrary database element and then calling the AsValueString method on it. The Parameter class provides this functionality, but unfortunately the API does not include any stand-alone access to it. Here is Victor's initial query:

Question: I need to convert a numeric value to a corresponding display string honouring the current Revit ProjectUnit setting. I cannot find how to do it in the Revit help and began search the answer in your amazing site. I found the Unit Conversion tool and thought it would fulfil my need, but I was wrong :(

Looking at the Unit Converter code, I discovered that retrieving scale factor to internal units is not easy and you used some trick to get it: you change ProjectUnit, write "1" to family parameter, read value from this parameter, change ProjectUnit back. It works but is really hard and is not an official way.

Answer: Try something like this on some otherwise unused length parameter 'p':

  Dim value As String = "=2' + 4'/3"
  Dim t As New Transaction(doc, "Format Length")
  t.Start()
  p.SetValueString(value)
  value = p.AsValueString
  t.RollBack()
  Return value

In fact, Joe provided the following helper methods based on this idea implemented in VB:

• StringValueString – Converts a string to AsValueString equivalent.
• DblValueString – Converts a double to AsValueString equivalent.
• ValueStringDbl – Converts a ValueString to a double.

All three of these methods create and then roll back a temporary transaction to perform their task.

Here is the full implementation of the first of these, StringValueString:

  Public Shared Function StringValueString( _
    ByVal doc As Document, _
    ByVal value As String) As String
 
    ' Locate the arbitrary Length parameter
 
    Dim p As Parameter _
      = doc.ProjectInformation.Parameter( _
      "Parameter Name")
 
    If p Is Nothing Then
      TaskDialog.Show( _
        "Revit", _
        "Missing Project Parameter: Parameter Name")
      Return value
    End If
 
    Dim tr As New Transaction(doc)
    tr.Start("Format Length")
 
    Try
      p.SetValueString(value)
      value = p.AsValueString
    Catch ex As Exception
 
    End Try
 
    tr.RollBack()
 
    Return value
 
  End Function

For the second, DblValueString, simply replace the input argument by a floating-point value 'ByVal value As Double' and the two lines to perform the actual conversion by

    p.Set(value)
    sValueString = p.AsValueString

Finally, for the third, ValueStringDbl, the input argument 'value' is again a string and the conversion to the floating-point return value is performed by

    p.SetValueString(value)
    dValue = p.AsDouble

Response: Thanks for the answer.

I wrote some simple extension methods for the Revit API Parameter class to get value in project units and in meters value. Now it works with Length, Volume and Area (now I don't need any more). It would take much time to add support for all unit conversions.

Here is the entire implementation of my ParameterUnitConverter class. It defines the following methods and data:

• AsProjectUnitTypeDouble – Parameter extension method to retrieve double value parameter in ProjectUnits.
• AsMetersValue – Parameter extension method to retrieve double value of parameter in meters unit, i.e. length in meters, area in square meters and volume in cubic meters.
• ConvertParameterTypeToUnitType – static method to return the corresponding UnitType for a given ParameterType.
• _map_parameter_type_to_unit_type – a dictionary mapping ParameterType enumeration values to the corresponding UnitType ones.

Here is the complete implementation of this:

public static class ParameterUnitConverter
{
  private const double METERS_IN_FEET = 0.3048;
 
  public static double AsProjectUnitTypeDouble( 
    this Parameter param )
  {
    if( param.StorageType != StorageType.Double )
      throw new NotSupportedException( 
        "Parameter does not have double value" );
 
    double imperialValue = param.AsDouble();
 
    Document document = param.Element.Document;
 
    UnitType ut = ConvertParameterTypeToUnitType( 
      param.Definition.ParameterType );
 
    FormatOptions fo = document.ProjectUnit
      .get_FormatOptions( ut );
 
    DisplayUnitType dut = fo.Units;
 
    // Unit Converter
    // http://www.asknumbers.com
 
    switch( dut )
    {
      #region Length
 
      case DisplayUnitType.DUT_METERS:
        return imperialValue * METERS_IN_FEET; //feet
      case DisplayUnitType.DUT_CENTIMETERS:
        return imperialValue * METERS_IN_FEET * 100;
      case DisplayUnitType.DUT_DECIMAL_FEET:
        return imperialValue;
      case DisplayUnitType.DUT_DECIMAL_INCHES:
        return imperialValue * 12;
      case DisplayUnitType.DUT_FEET_FRACTIONAL_INCHES:
        NotSupported( dut );
        break;
      case DisplayUnitType.DUT_FRACTIONAL_INCHES:
        NotSupported( dut );
        break;
      case DisplayUnitType.DUT_METERS_CENTIMETERS:
        return imperialValue * METERS_IN_FEET; //feet
      case DisplayUnitType.DUT_MILLIMETERS:
        return imperialValue * METERS_IN_FEET * 1000;
 
      #endregion // Length
 
      #region Area
 
      case DisplayUnitType.DUT_SQUARE_FEET:
        return imperialValue;
      case DisplayUnitType.DUT_ACRES:
        return imperialValue * 1 / 43560.039;
      case DisplayUnitType.DUT_HECTARES:
        return imperialValue * 1 / 107639.104;
      case DisplayUnitType.DUT_SQUARE_CENTIMETERS:
        return imperialValue * Math.Pow( METERS_IN_FEET * 100, 2 );
      case DisplayUnitType.DUT_SQUARE_INCHES:
        return imperialValue * Math.Pow( 12, 2 );
      case DisplayUnitType.DUT_SQUARE_METERS:
        return imperialValue * Math.Pow( METERS_IN_FEET, 2 );
      case DisplayUnitType.DUT_SQUARE_MILLIMETERS:
        return imperialValue * Math.Pow( METERS_IN_FEET * 1000, 2 );
 
      #endregion // Area
 
      #region Volume
      case DisplayUnitType.DUT_CUBIC_FEET:
        return imperialValue;
      case DisplayUnitType.DUT_CUBIC_CENTIMETERS:
        return imperialValue * Math.Pow( METERS_IN_FEET * 100, 3 );
      case DisplayUnitType.DUT_CUBIC_INCHES:
        return imperialValue * Math.Pow( 12, 3 );
      case DisplayUnitType.DUT_CUBIC_METERS:
        return imperialValue * Math.Pow( METERS_IN_FEET, 3 );
      case DisplayUnitType.DUT_CUBIC_MILLIMETERS:
        return imperialValue * Math.Pow( METERS_IN_FEET * 1000, 3 );
      case DisplayUnitType.DUT_CUBIC_YARDS:
        return imperialValue * 1 / Math.Pow( 3, 3 );
      case DisplayUnitType.DUT_GALLONS_US:
        return imperialValue * 7.5;
      case DisplayUnitType.DUT_LITERS:
        return imperialValue * 28.31684;
 
      #endregion // Volume
 
      default:
        NotSupported( dut );
        break;
    }
 
    throw new NotSupportedException();
  }

  public static double AsMetersValue( 
    this Parameter param )
  {
    if( param.StorageType != StorageType.Double )
      throw new NotSupportedException( 
        "Parameter does not have double value" );
 
    double imperialValue = param.AsDouble();
 
    UnitType ut = ConvertParameterTypeToUnitType( 
      param.Definition.ParameterType );
 
    switch( ut )
    {
      case UnitType.UT_Length:
        return imperialValue * METERS_IN_FEET;
 
      case UnitType.UT_Area:
        return imperialValue * Math.Pow( 
          METERS_IN_FEET, 2 );
 
      case UnitType.UT_Volume:
        return imperialValue * Math.Pow( 
          METERS_IN_FEET, 3 );
    }
    throw new NotSupportedException();
  }
 
  public static UnitType 
    ConvertParameterTypeToUnitType( 
      ParameterType parameterType )
  {
    if( _map_parameter_type_to_unit_type.ContainsKey( 
      parameterType ) )
    {
      return _map_parameter_type_to_unit_type[
        parameterType];
    }
    else
    {
      // If we made it this far, there's 
      // no entry in the dictionary.
 
      throw new ArgumentException(
        "Cannot convert ParameterType '"
          + parameterType.ToString()
          + "' to a UnitType." );
    }
  }
 
  static Dictionary<ParameterType, UnitType>
    _map_parameter_type_to_unit_type
      = new Dictionary<ParameterType, UnitType>()
  {
    // This data could come from a file, 
    // or (better yet) from Revit itself...
 
    {ParameterType.Angle, UnitType.UT_Angle},
    {ParameterType.Area, UnitType.UT_Area},
    {ParameterType.AreaForce, UnitType.UT_AreaForce},
    {ParameterType.AreaForcePerLength, UnitType.UT_AreaForcePerLength},
    //map.Add(UnitType.UT_AreaForceScale, ParameterType.???);
    {ParameterType.ColorTemperature, UnitType.UT_Color_Temperature},
    {ParameterType.Currency, UnitType.UT_Currency},
    //map.Add(UnitType.UT_DecSheetLength, ParameterType.???);
    {ParameterType.ElectricalApparentPower, UnitType.UT_Electrical_Apparent_Power},
    {ParameterType.ElectricalCurrent, UnitType.UT_Electrical_Current},
    {ParameterType.ElectricalEfficacy, UnitType.UT_Electrical_Efficacy},
    {ParameterType.ElectricalFrequency, UnitType.UT_Electrical_Frequency},
    {ParameterType.ElectricalIlluminance, UnitType.UT_Electrical_Illuminance},
    {ParameterType.ElectricalLuminance, UnitType.UT_Electrical_Luminance},
    {ParameterType.ElectricalLuminousFlux, UnitType.UT_Electrical_Luminous_Flux},
    {ParameterType.ElectricalLuminousIntensity, UnitType.UT_Electrical_Luminous_Intensity},
    {ParameterType.ElectricalPotential, UnitType.UT_Electrical_Potential},
    {ParameterType.ElectricalPower, UnitType.UT_Electrical_Power},
    {ParameterType.ElectricalPowerDensity, UnitType.UT_Electrical_Power_Density},
    {ParameterType.ElectricalWattage, UnitType.UT_Electrical_Wattage},
    {ParameterType.Force, UnitType.UT_Force},
    {ParameterType.ForceLengthPerAngle, UnitType.UT_ForceLengthPerAngle},
    {ParameterType.ForcePerLength, UnitType.UT_ForcePerLength},
    //map.Add(UnitType.UT_ForceScale, ParameterType.???);
    {ParameterType.HVACAirflow, UnitType.UT_HVAC_Airflow},
    {ParameterType.HVACAirflowDensity, UnitType.UT_HVAC_Airflow_Density},
    {ParameterType.HVACAirflowDividedByCoolingLoad, UnitType.UT_HVAC_Airflow_Divided_By_Cooling_Load},
    {ParameterType.HVACAirflowDividedByVolume, UnitType.UT_HVAC_Airflow_Divided_By_Volume},
    {ParameterType.HVACAreaDividedByCoolingLoad, UnitType.UT_HVAC_Area_Divided_By_Cooling_Load},
    {ParameterType.HVACAreaDividedByHeatingLoad, UnitType.UT_HVAC_Area_Divided_By_Heating_Load},
    {ParameterType.HVACCoefficientOfHeatTransfer, UnitType.UT_HVAC_CoefficientOfHeatTransfer},
    {ParameterType.HVACCoolingLoad, UnitType.UT_HVAC_Cooling_Load},
    {ParameterType.HVACCoolingLoadDividedByArea, UnitType.UT_HVAC_Cooling_Load_Divided_By_Area},
    {ParameterType.HVACCoolingLoadDividedByVolume, UnitType.UT_HVAC_Cooling_Load_Divided_By_Volume},
    {ParameterType.HVACCrossSection, UnitType.UT_HVAC_CrossSection},
    {ParameterType.HVACDensity, UnitType.UT_HVAC_Density},
    {ParameterType.HVACDuctSize, UnitType.UT_HVAC_DuctSize},
    {ParameterType.HVACEnergy, UnitType.UT_HVAC_Energy},
    {ParameterType.HVACFactor, UnitType.UT_HVAC_Factor},
    {ParameterType.HVACFriction, UnitType.UT_HVAC_Friction},
    {ParameterType.HVACHeatGain, UnitType.UT_HVAC_HeatGain},
    {ParameterType.HVACHeatingLoad, UnitType.UT_HVAC_Heating_Load},
    {ParameterType.HVACHeatingLoadDividedByArea, UnitType.UT_HVAC_Heating_Load_Divided_By_Area},
    {ParameterType.HVACHeatingLoadDividedByVolume, UnitType.UT_HVAC_Heating_Load_Divided_By_Volume},
    {ParameterType.HVACPower, UnitType.UT_HVAC_Power},
    {ParameterType.HVACPowerDensity, UnitType.UT_HVAC_Power_Density},
    {ParameterType.HVACPressure, UnitType.UT_HVAC_Pressure},
    {ParameterType.HVACRoughness, UnitType.UT_HVAC_Roughness},
    {ParameterType.HVACSlope, UnitType.UT_HVAC_Slope},
    {ParameterType.HVACTemperature, UnitType.UT_HVAC_Temperature},
    {ParameterType.HVACVelocity, UnitType.UT_HVAC_Velocity},
    {ParameterType.HVACViscosity, UnitType.UT_HVAC_Viscosity},
    {ParameterType.Length, UnitType.UT_Length},
    {ParameterType.LinearForce, UnitType.UT_LinearForce},
    {ParameterType.LinearForceLengthPerAngle, UnitType.UT_LinearForceLengthPerAngle},
    {ParameterType.LinearForcePerLength, UnitType.UT_LinearForcePerLength},
    // map.Add(UnitType.UT_LinearForceScale, ParameterType.???);
    {ParameterType.LinearMoment, UnitType.UT_LinearMoment},
    // map.Add(UnitType.UT_LinearMomentScale, ParameterType.???);
    {ParameterType.Moment, UnitType.UT_Moment},
    ///map.Add(UnitType.UT_MomentScale, ParameterType.???);
    {ParameterType.Number, UnitType.UT_Number},
    {ParameterType.PipeSize, UnitType.UT_PipeSize},
    {ParameterType.PipingDensity, UnitType.UT_Piping_Density},
    {ParameterType.PipingFlow, UnitType.UT_Piping_Flow},
    {ParameterType.PipingFriction, UnitType.UT_Piping_Friction},
    {ParameterType.PipingPressure, UnitType.UT_Piping_Pressure},
    {ParameterType.PipingRoughness, UnitType.UT_Piping_Roughness},
    {ParameterType.PipingSlope, UnitType.UT_Piping_Slope},
    {ParameterType.PipingTemperature, UnitType.UT_Piping_Temperature},
    {ParameterType.PipingVelocity, UnitType.UT_Piping_Velocity},
    {ParameterType.PipingViscosity, UnitType.UT_Piping_Viscosity},
    {ParameterType.PipingVolume, UnitType.UT_Piping_Volume},
    //map.Add(UnitType.UT_SheetLength, ParameterType.???);
    //map.Add(UnitType.UT_SiteAngle, ParameterType.???);
    {ParameterType.Slope, UnitType.UT_Slope},
    {ParameterType.Stress, UnitType.UT_Stress},
    {ParameterType.TemperalExp, UnitType.UT_TemperalExp},
    {ParameterType.UnitWeight, UnitType.UT_UnitWeight},
    {ParameterType.Volume, UnitType.UT_Volume},
    {ParameterType.WireSize, UnitType.UT_WireSize},
  };
}

I used some functions from the Unit converter. Here is an external command sample to test it by iterating over and applying it to all floating point valued parameters on a selected element.

Hope you'll find this useful.

Many thanks to Joe and Victor for putting together and sharing these nice solutions!

I added the ParameterUnitConverter class to The Building Coder samples and defined a new external command CmdParameterUnitConverter based on Victor's code to test it. Here is version 2012.0.96.0 of The Building Coder samples including the new utility class and command.

This is the output generated by the command in the Visual Studio debug output window on selecting a wall element in the rac_basic_sample_project.rvt sample model:

Parameter name: Top Extension Distance
  Parameter value (imperial): 0
  Parameter unit value: 0
  Parameter AsValueString: 0.0

Parameter name: Length
  Parameter value (imperial): 45.5
  Parameter unit value: 13868.4
  Parameter AsValueString: 13868.4

Parameter name: Base Extension Distance
  Parameter value (imperial): 0
  Parameter unit value: 0
  Parameter AsValueString: 0.0

Parameter name: Top Offset
  Parameter value (imperial): 0
  Parameter unit value: 0
  Parameter AsValueString: 0.0

Parameter name: Volume
  Parameter value (imperial): 455.9586023831
  Parameter unit value: 12.911309795985
  Parameter AsValueString: 12.911 m³

Parameter name: Unconnected Height
  Parameter value (imperial): 18.0446194225722
  Parameter unit value: 5500
  Parameter AsValueString: 5500.0

Parameter name: Base Offset
  Parameter value (imperial): 0
  Parameter unit value: 0
  Parameter AsValueString: 0.0

Parameter name: Area
  Parameter value (imperial): 694.880910031848
  Parameter unit value: 64.5565489799251
  Parameter AsValueString: 64.557 m²

Here, the parameter value labelled 'imperial' is the internal Revit database unit, e.g. feet for length. Please note that not all internal database units are imperial. In fact, only length is measured in feet, and thus also area and volume. Other internal units are SI-based.

Internal Imperial Units

To start off this week, here is a pretty useless question that still seems to be of great interest to many people:

Question: Odd question perhaps, but why does Revit internally work in imperial units?

Answer: I do not find your question odd at all; many others wonder that as well, I am sure.

Briefly, I would hazard that the answer is simply that this is a religious question, or a question of taste, or historically evolved.

Does that satisfy your curiosity?

Here is a bit more background information in a little more depth:

1. Revit was first made in the US, and originally only for the US market. US architects work with imperial units.
2. At the time it was simplest to write Revit to use imperial units internally (feet for length) to match customer needs.
3. When Revit's market expanded, support was extended for metric units. But the existing database structures were preserved for backwards compatibility.
4. In addition, Revit started expanding in capability and had to cover additional new areas requiring other units such as force, mass, etc. For those new capabilities, metric units were chosen as being more universally understood and useful.
5. When Revit's API was introduced, the simplest method of introduction was to expose the database values directly. Thus feet for length, metric for everything else.

I hope this helps, useless as the information may be!

Many thanks to Giles and Scott for contributing to this!

Unit Conversion and New Blogs

Quite a while back, I published a unit conversion utility for Revit 2010. Let's take a fresh look at that, and also at a couple of new Revit blogs.

We discussed a couple of other issues related to units since then, such as the unit suffix and ProjectUnit SDK sample and a look at voltage units. The latter also includes an overview of some other unit related posts.

Anyway, Rod Howarth picked up on the unit converter utility and ported it to Revit 2011. He says:

I was reading your old post on a reader-contributed Unit Conversion Revit utility today, and I couldn't find an updated version (and I don't think it made it into the full SDK from what I could tell). So I decided to quickly convert it to Revit 2011, and send it through to you.

It's a handy utility, especially for us Aussies with our metric system. I've just gone through and done the basic conversions that are required for the new namespaces, and made a manifest file for it. It seemed to run fine for me though I am fairly busy so haven't done extensive testing. Here is UnitConversion2011.zip containing the complete source code and Visual Studio solution and including the binary executable files in the bin subfolder.

This is what it looks like running in Revit MEP 2011 and gives you an idea of the functionality provided:

Many thanks to Rod for converting and sharing this useful utility!

And yes, it didn't seem to make it into the SDK after all, did it?

For more details on the unit conversion tool, please refer back to the original post.

New Revit API Blog

Stephen Germano, Project Director, and his colleagues at the ibd Resource Group, have started up a new Revit API blog and say that they hope for a couple blog posts a week; check it out at

• ibdrg.typepad.com/ibd-resource-group or
• www.bimadvent.com/Blog.

New Polish Revit Blog

Andrzej Samsonowicz, Application Engineer in the Warsaw office of Autodesk, has successfully launched a new blog about Autodesk Revit in Polish:

• revit-pl.typepad.com/my-blog.

The new blog promotes BIM, provides tips and tricks, suggests best practices and workflows, answers common problems faced by Revit users, and presents the latest technologies for AEC users.

It is part of an effort from Autodesk in Poland and the International Community team to:

• Further develop the user community in Polish language.
• Support the connection of employees with customers in their particular market.
• Promote the creation of relevant content in Poland.

I would encourage you to take a look, read, subscribe, and engage if you are a Polish speaker (or use Google Translate :-).

Actually, you can get an English translation directly, courtesy of Scott Sheppard. I am pleasantly surprised how readable this machine translation is.

View Location on Sheet

I returned from a beautiful little mountain hike to the lake, pass and mountain of Piz Lunghin.

One very special aspect of this place is that it is Europe's one and only triple watershed, with rivers flowing all the way to the North Sea, Black Sea and Mediterranean. Another special aspect of my hike was spending the night outside on the mountain, with a wonderful clear sky and the almost full moon in sub-zero temperatures (Celsius).

Returning once again to the Revit API, the SDK sample AllViews collects all views in the model, asks the user to interactively select some of them, and places those on a sheet.

Even so, the exact definition and calculation of the view coordinates and location of the view on the sheet remains somewhat obscure. Here are some furhter helful results in this area. They do not answer every possible question in full completeness, so we still have some work to do exploring this area, but hopefully they will be useful already in this incomplete form.

We recently had one question from Thomas Fink of SOFiSTiK on this, and here is another recent question on that topic with some interesting research performed by my colleague Joe Ye. I am reproducing the rather long discussion in full, to show that the issue is not trivial and the solution is not yet completely perfect:

Question: Given a certain view placed on a sheet, I am trying to retrieve the location of the view on the sheet using:

  Location loc = Element.Location;

This is not giving me what I need, which is the UV or XYZ location of the view placed on the sheet.

Answer: You can use the Element BoundingBox property to retrieve the Max and Min points of a viewport in the sheet. From these, you can calculate the middle point of the Max and Min point. The middle point is the viewport's centre point in sheet.

Here is some code showing to determine the centre point of a view in a sheet view. To quickly test the solution, it currently uses a hardcoded element id 157165 for the viewport in the sheet view; please change that to suit your model and needs. In addition, please pass in the sheet object as an argument in the call to Element.get_BoundingBox. In this sample, we just set the sheet view to be the active view:

[TransactionAttribute( TransactionMode.Manual )]
[RegenerationAttribute( RegenerationOption.Manual )]
public class GetViewPosition : IExternalCommand
{
  public Result Execute( 
    ExternalCommandData commandData, 
    ref string messages, 
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    Document doc = app.ActiveUIDocument.Document;
 
    ElementId id = new ElementId( 157165 );
    Element elem = doc.get_Element( id );
 
    BoundingBoxXYZ bounding 
      = elem.get_BoundingBox( doc.ActiveView );
 
    string sMsg = "The Max and Min points are: \n";
 
    sMsg += bounding.Max.X.ToString() 
      + ", " + bounding.Max.Y.ToString() 
      + ", " + bounding.Max.Z.ToString() + "\n";
 
    sMsg += bounding.Min.X.ToString() 
      + ", " + bounding.Min.Y.ToString() 
      + ", " + bounding.Min.Z.ToString() + "\n";
 
    XYZ xyzPosition 
      = ( bounding.Max + bounding.Min ) / 2.0;
 
    sMsg += "view position in current sheet is:\n" 
      + xyzPosition.X.ToString() 
      + "," + xyzPosition.Y.ToString() 
      + "," + xyzPosition.Z.ToString();
 
    MessageBox.Show( sMsg );
 
    return Result.Succeeded;
  }
}

Response: I need to programmatically copy a legend view from one sheet to another. For this, I need to get the location of the view from the original sheet and reuse this location when adding new views to the other sheets.

For this purpose, I am using the following code:

  foreach( ViewSheet chosenSheet in SelectedSheets )
  {
    BoundingBoxXYZ xyzLocation 
      = selectedView.get_BoundingBox( 
        m_Doc.ActiveView );
 
    XYZ xyzPosition = ( xyzLocation.Max 
      + xyzLocation.Min ) / 2.0;
 
    int scale = correspondingView.Scale;
 
    chosenSheet.AddView( correspondingView, 
      new UV( xyzPosition.X, xyzPosition.Y ) );
  }

Here I am using the following variables:

• chosenSheet is the sheet where the legend will be copied.
• selectedView is the selected Viewport to be copied.
• correspondingView is the view to be copied.

Unfortunately, the views are not copied to the same location.

Answer: I created a simple project and added several view sheets. I picked the Level 1 viewport and tried to run this code, but this caused an error message saying 'Added view is already on another sheet and cannot be displayed on two sheets'.

Response: This is because you are trying to copy a "plan" view that is already placed on a sheet and place it on another sheet. Try running this code on a legend view placed on a sheet.

Answer: The point used to insert the view on the view sheet is mapping the (0,0,0) point of the source view. When you retrieve the centre point coordinates of the viewport, they do not match the (0,0,0) point of the source view. So you need to calculate the source view's original point coordinates in the view sheet from the viewpoint's centre point coordinates.

Response: I understand that I need to get the centre of the view in the ViewSheet in order to be able to calculate the shift. How can I obtain the coordinates of the centre of the view relative to the view sheet?

Answer: The View class has a very important property Outline. The Outline property will return the Max and Min point of the closest bounding box, which includes all elements in this view. The value in this Max and Min the result of the legend view's real Max and Min coordinates subdivided by the view scale. For more information about Outline property, please refer to the Revit SDK developer guide 'Revit 2011 API Developer Guide.pdf'.

Approximately, the outline Max point is mapping the same Max point of the viewport in view sheet. So we can calculate the source view's origin coordinates in the host view sheet using the following code:

  BoundingBoxXYZ xyzLocation 
    = SelectedView.get_BoundingBox( 
      m_Doc.ActiveView );
 
  // get the outline max and min 
 
  XYZ ptMaxOutline = new XYZ( 
    CorrespondingView.Outline.Max.U, 
    CorrespondingView.Outline.Max.V, 
    0 );
 
  // get the view's origin point's 
  // coordinates in current view sheet. 
 
  UV ptSourceViewOriginInSheet = new UV( 
    xyzLocation.Max.X - ptMaxOutline.X,
    xyzLocation.Max.Y - ptMaxOutline.Y ); 

Here is the complete code of the Execute method:

public Result Execute( 
  ExternalCommandData commandData, 
  ref string message, 
  ElementSet elements )
{
  try
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
 
    SelElementSet selection = uidoc.Selection.Elements;
    if( selection.Size == 0 )
    {
      MessageBox.Show( "Please Select a view to be copied.", 
        "View Coordinates", MessageBoxButtons.OK,
      MessageBoxIcon.Error );
      return Result.Failed;
    }
    else
    {
      // Get all Sheets 
      List AllSheets = GetAllSheets( doc );
 
      // Get all Views in the model. 
      // Find all views in the document by using category filter 
 
      ElementCategoryFilter filter 
        = new ElementCategoryFilter( 
          BuiltInCategory.OST_Views );
 
      FilteredElementCollector collector 
        = new FilteredElementCollector( doc );
 
      IList AllViews = collector.WherePasses( filter )
        .ToElements();
 
      foreach( Element SelectedView in selection )
      {
        if( SelectedView.Category.Name == "Viewports" )
        {
          String ViewName = SelectedView.get_Parameter( 
            "View Name" ).AsString();
 
          View CorrespondingView = null;
 
          for( int i = 0; i < AllViews.Count; i++ )
          {
            if( AllViews[i].Name == ViewName )
            {
              CorrespondingView = AllViews[i] as View;
              break;
            }
          }
 
          BoundingBoxXYZ xyzLocation 
            = SelectedView.get_BoundingBox( 
              doc.ActiveView );
 
          // get the outline max and min 
 
          XYZ ptMaxOutline = new XYZ( 
            CorrespondingView.Outline.Max.U, 
            CorrespondingView.Outline.Max.V, 0 );
 
          // get the view's origin point's coordinates 
          // in current view sheet. 
 
          UV ptSourceViewOriginInSheet = new UV( 
            xyzLocation.Max.X - ptMaxOutline.X,
            xyzLocation.Max.Y - ptMaxOutline.Y );
 
          // for each chosen to be exported 
          // get the views on it. 
 
          foreach( ViewSheet ChosenSheet in AllSheets )
          {
            ChosenSheet.AddView( CorrespondingView, 
              ptSourceViewOriginInSheet );
          }
        }
      }
      return Result.Succeeded;
    }
  }
  catch( Exception ex )
  {
    MessageBox.Show( ex.Message );
    return Result.Failed;
  }
} 

Response: Using this code, the location of the view on the sheet is still inaccurate. If I use this code to duplicate a view legend placed on a sheet in the same location, the legend view still appears to be shifted while duplicated on the same sheet, as shown in the following figures. Here is a view of the entire sheet:

Here is a more detailed picture of the offset between the original and copied views:

Answer: The reason for this might be that the Revit API returns the Viewport BoundingBox property value with an offset to its original outline property. The BoundingBox property is not completely accurate, so the result to calculate the legend view's origin in the sheet view cannot be so either. As far as I can tell, the offset of the Max point of the viewport's BoundingBox is enlarged 0.01 in both X and Y direction. We can take this scaling into account.

Here is some updated code with an adjustment added. You might need to further adjust the offset value according to different situations. The offset value of 0.01 is not obtained from source code, but from my empirical testing results:

foreach( Element SelectedView in selection )
{
  if( SelectedView.Category.Name == "Viewports" )
  {
    string ViewName = SelectedView.get_Parameter( 
      "View Name" ).AsString();
 
    View CorrespondingView = null;
 
    for( int i = 0; i < AllViews.Count; i++ )
    {
      if( AllViews[i].Name == ViewName )
      {
        CorrespondingView = AllViews[i] as View;
        break;
      }
    }
 
    BoundingBoxXYZ xyzLocation 
      = SelectedView.get_BoundingBox( 
        doc.ActiveView );
 
    // get the outline max and min,
    // offset in each direction of max point of 
    // bounding box than the outline box.
 
    double dMaxOffset = 0.01;  
    XYZ ptMaxOutline = new XYZ( 
      CorrespondingView.Outline.Max.U, 
      CorrespondingView.Outline.Max.V, 0 );
 
    UV ptSourceViewOriginInSheet = new UV( 
      xyzLocation.Max.X - dMaxOffset - ptMaxOutline.X, 
      xyzLocation.Max.Y - dMaxOffset - ptMaxOutline.Y );
 
    // for each chosen to be exported get the views on it
 
    foreach( ViewSheet ChosenSheet in AllSheets )
    {
      ChosenSheet.AddView( CorrespondingView, 
        ptSourceViewOriginInSheet );
    }
  }
}

Thank you very much, Joe, for this thorough exploration!

Here is another quick question and answer that might be of use in this context:

Centre Point of View

Question: I need a way to get the XYZ of the centre of a view and the XYZ of the centre of a sheet. Can I achieve this using one of the Outline, CropBox or BoundingBox properties?

Answer: It depends on what exactly you mean by 'centre of view'. I can imagine that it might be any one of the following:

• The visible centre of a view: If we pan the view, the centre coordinates change. There is currently no API exposed to get the visible centre of a view, and we do have an open wish list item to obtain this information.
• The centre point of the crop box: We can retrieve the BoundingBoxXYZ of the view through the CropBox property. Then the centre can be determined by Max and Min of the crop box.
• The coordinate centre: the coordinate centre point is returned by the View.Origin property.

For an example of defining a completely different set of view coordinates, we also once looked at cropping a 3D view to a specific element.

Ribbon Icon Resolution

We are still on the Pantagruel, currently sailing from Norway to the west coast of Sweden. Here is a view from Preikestolen down into Lysefjord, where we went for a hike before leaving the Stavanger area:

Here are some of us on deck the first day:

That was before getting out onto the open sea and into higher winds, causing us to feel a lot less chirpy:

The weather has been pleasant all the time, but the wind is very weak now. Yesterday we caught a few mackerel which we had for dinner. For some reason I ended up playing butcher for the fish, in spite of being the only vegetarian on board. I did eat some of them, as well, anyway. We had a nice sunset last night:

The view towards the east was like a Rothko painting, a study in blue:

It was sunny all the time in Norway. Now, outside the northern coast of Denmark, we have a light cloud cover, but it is still dry. We had the motor on all through the night from Saturday to Sunday, then sailed all day long Sunday, and turned on the motor again Sunday evening when we passed the southern tip of Norway and headed across more open water towards Skagen on the northern tip of Denmark. We are almost there by now.

Later... almost there was a big exaggeration. The wind came up a bit on Monday, but from the east, which is the direction we were heading. We switched off the motor and sailed but had to cross against the wind, and it took us all day to cross the Skagerrak and arrive close to Skagen. Our skipper Micha dropped off us off on the west side of the Skagen peninsula for a beautiful walk along the beach up northwards on the west side beach of Skagen up to the point where the North Sea and the Baltic Sea meet. It is pretty fascinating. He headed out with a reduced crew to cross around the point and get into Skagen harbour from the east side. We did not arrive in Skagen harbour until nine o'clock at night, so the showers and shops were already shut.

Tuesday morning our aim was to leave as early as possible and get over to the islands north of Gothenburg in Sweden, but due to a pure easterly wind we ended up further south on the Danish island of Læsø, where I am sitting watching the sunset right now.

You can follow our exact route on the Pantagruel tracker.

Returning once again to Revit programming, we talked about the Ribbon API and simulating a textbox label the other day.

Here is another interesting issue concerning the Revit ribbon and the icons used in it that took some research to figure out.

Question: I have been having problems correctly displaying icons and images in my Revit add-in. It was difficult to reproduce, but I can finally describe the differences that cause the problem.

It seems as if Revit is influenced by the resolution or DPI (dot per inch) information in the image file.

You can easily see this difference using the Ribbon SDK sample:

1. Copy the original Ribbon sample project with all its support files.
2. Rename Reset.png to something else, and replace it with __icon_16x16_org.png.
3. Rename RectangleWall.png to some other name, and replace it with __icon_16x16_resaved.png.
4. Start Revit and check icons.

The first image is the one causing a problem. The second one was reopened in Paint and simply resaved. Both images look like this, normally:

But in Revit, the resulting panel looks like this:

As you can see, the top image above is not showing correctly, while the lower one looks as expected.

Looking at the image attributes using Paint > Image > Attributes..., you can see that the resolution or DPI (dot per inch) settings differ. The one that does not work shows up like this:

If the file is resaved, it works fine, and the image attributes then look like this:

Apparently, once the image is saved in Paint, the DPI information is stripped out. The file becomes slightly smaller and the resolution changes from 72 to 96 dpi.

Is this an expected behaviour of the image specification? Do I need to take the DPI image attributes into consideration when creating my Revit add-in user interface? What settings do I have to use?

Answer: From the technical point of view, the underlying Windows Presentation Foundation technology WPF used in the ribbon postulates 96 dpi as the default resolution setting. If an image has a different resolution such as 72 dots per inch, it will be displayed bigger under 96 dpi. I would say that this is expected behaviour.

To have the ribbon display icons the same way you originally see them, you have to use 96 dpi resolution images.

Many thanks to Matt Mason for raising and pursuing this issue and to Mikako Harada and Dominic Zhang for researching and nailing it down so clearly!

Slope is Slope, Not Radians

I am still in Thailand, flying home tonight. Still, I had time to go through some email today, and picked up lots of interesting tidbits. Let me start with this one:

Question: When I use the sample code from the Revit API help file RevitAPI.chm to create a NewFootPrintRoof, the slope is set to 0.5 radians. This results in a slope of 26.57 degrees for the newly created roof. This value is incorrect, however, since 0.5 radian equals about 28.65 degrees.

Using the Revit Lookup tool, I can see that the value has indeed been set to 26.57, which is also what we get to see in the UI, and the internal value in radians is 0.5. What is wrong here, and where does this inconsistency come from?

Answer: The value is not in radians. It is really a 'slope', i.e. the relation between the horizontal and vertical components of the corresponding vector, e.g. 0.5 means half a foot = 6” / 12 up per foot sideways”, 0.75 means three quarters of a foot = 9” / 12”, etc., and

atan (0.5) ≈ 26.57°

Thanks to Saikat and Scott for raising and clarifying this issue!

In other words, and from another case, if you set a parameter of type slope to a value of 1, the value returned by AsValueString will be 45 degrees (and not 57.217 = 180 / π, for instance).

This definition of slope is mentioned in the description of the FootPrintRoof.SlopeAngle property.

Voltage Units

The last day before DevCamp!

I am happy to note that the articles on grabbing a webcam image and displaying it on a Revit element face were so popular ... I will be demonstrating that and other samples using the Idling event and modeless dialogues at DevCamp.

Meanwhile, here is an interesting little item that my colleagues Jorgen Dahl and Martin Schmid (who by the way published a book on AutoCAD MEP 2010) dug up, another nugget of information on the topic of Revit database units, an area that we looked at repeatedly in the past:

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

Martin is an expert in the MEP domain, so one area of interest to him is the following:

Question: What is the internal unit used by Revit for voltage? In the API, the ElectricalSystem.Voltage property returns a value that is about 10.76391 times the expected value in Volts, i.e., I get 1291.669 instead of 120 V. The same applies to the TrueLoad property. So I assume Revit is using some non-standard unit for voltage?

Answer: Electrical potential can be defined using the following more fundamental units:

(Length² * Mass) / (Time³ * Current).

In Revit, this formula makes use of the following units:

• Length: feet
• Mass: kg
• Time: s
• Current: A

The unit Volt is defined in the same way, of course, but uses the SI unit meters instead of feet, as specified by the International System of Units SI.

As a result, to convert the Revit internal database voltage unit to Volts, you have to multiply it with 0.3048^2.

It would be nice to upgrade the internal Revit database unit to use meters as well, but the problem is that there are a lot of data fields on elements in Revit that don’t know if they are just a number or a length. We are working on it, though.

Every unit in Revit knows what base units it is built of, and data is stored in that format. The base units used internally by Revit are currently:

enum BaseUnit
{
  BU_Length = 0,         // length, feet (ft)
  BU_Angle,              // angle, radian (rad)
  BU_Mass,               // mass, kilogram (kg)
  BU_Time,               // time, second (s)
  BU_Electric_Current,   // electric current, ampere (A)
  BU_Temperature,        // temperature, kelvin (K)
  BU_Luminous_Intensity, // luminous intensity, candela (cd)
  BU_Solid_Angle,        // solid angle, steradian (sr)
};

Many thanks to Jorgen and Martin for this useful background information!

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 1.2 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.