The Building Coder

FindReferencesByDirection

This is part 9 of Scott Conover's AU 2009 class on analysing building geometry, dealing with the FindReferencesByDirection method and its use as an applications 'eyes'.

We mentioned the method briefly in our discussions on how to find a host or a foundation element, Harry Mattison recently presented a very compelling example using it to simulate a pool table in a Revit model, and Scott himself provided the real-world example for creating spot elevations on the top surface of a beam which we discussed yesterday. The Revit 2010 SDK Samples AvoidObstruction and RaytraceBounce also both demonstrate its use.

Here and now Scott presents more background information and several additional working examples proving how powerful and useful it can be for other real-world tasks.

FindReferencesByDirection

This new method introduced in Revit 2010 allows you to use Revit's picking tools to find elements and geometry. With this method, a ray is projected from a point in a specified direction. The geometry that is hit by the ray is returned by the method. Look at its description in the Revit API help. Here are some additional notes:

• The method intersects 3D geometry only and requires a 3D view as input. It is possible to use a 3D view which has been cut by a section box, or which has view-specific geometry and graphics options set, to find intersections which would not be found in the uncut and uncropped 3D model.
• This method finds both elements and geometric references which intersect the ray. Some element references returned will not have a corresponding geometric object which is also intersected (for example, rays passing through openings in walls will intersect the wall and the opening element). If you are interested only in true physical intersections you should discard all references whose GeometryObject is of type Element, leaving behind only intersections with faces.
• References will be found and returned only for elements that are in front of the ray. (This is a contradiction to the note in the 2010 documentation, which states that negative results are possible; they are not).
• This method will not return intersections in linked files.
• This method will not return intersections with elements which are not in the active design option.

Find Elements Near Elements

One major use for this tool is to find elements in close proximity to other elements. This allows you to use the tool as your application's 'eyes' and determine relationships between elements which don't have a built-in relationship already.

Example: Find Columns Embedded in Walls

In this example, we use the ray-tracing capability to find columns embedded in walls. As columns and walls don't maintain a relationship directly, this utility allows us to find potential candidates by tracing rays just outside the extents of the wall, and looking for intersections with columns. The implementation covers flat walls (where only two rays, one for either side, are necessary), as well as curved walls, where the rays are traced tangent to the walls at incremental distances, and only matches in close proximity are accepted.

Measure distances

The results of the FindReferencesByDirection are an array of Reference objects intersected by the ray. When the References are obtained from this method, the References' ProximityParameter will be set.

This is the distance between the origin of the ray and the intersection point. You can use this distance to exclude items too far from the origin for a particular geometric analysis. You can also use this distance to take on some interesting problems involving analyzing the in place geometry of the model.

Example: Measure Distance with FindReferencesByDirection

In this example, we measure the vertical distance from a skylight to a preselected floor. Yes, this could be obtained through geometric tools as well (Face.Project()), but with the ray-tracing tool, we don't have to examine the floor to find its top face(s), nor deal with sloped slabs or other problematic details. We just look at all the intersections with the floor, pick the closest one, and thus have found our distance and intersection point.

Ray bouncing analysis

The references returned by FindReferencesByDirection also include the intersection point on the geometry. Knowing the intersection point on the face, the face's material, and the ray direction allows you analyze reflection and refraction within the building. This is illustrated by the Revit SDK sample RayTraceBounce, which is used to track a ray bouncing off the walls of an enclosed space:

Please refer to Scott's AU class material for the full source code of his sample project defining the column intersection and distance measurement implementations.

We are nearing the end of this series. What an impressive amount of new content Scott packed into that one presentation! The next and last intalment of this series deals with material quantity extraction.

Spot Elevation Creation on Top of Beam

Here is another interesting solution to discuss in between the series on the Revit API geometry library from Scott Conover's Autodesk University presentation on analysing building geometry. This issue was also raised by Scott and deals with adding a spot elevation to a beam. It contains useful information both about spot elevation creation and using FindReferencesByDirection to find the top of a beam more easily than with get_Geometry.

Question: I am trying to add a spot dimension to the location curve of a beam. However, when I ask the beam location curve for a reference, it returns null. I found the same when I tried to obtain a reference for the location curve of a wall.

Answer: The assumption that a location curve can return a reference is completely incorrect. The location curve of a beam or wall does not represent a referenceable object.

A spot elevation should be created referencing a physical piece of geometry, for instance the top surface of the beam. You can still rely on the location curve to compute the nearest point of the spot elevation.

Below is the source code for a Revit 2010 VSTA macro that places three spot elevations on the top of a beam, at the midpoint and both ends. It defines three methods:

• FindView – Return a view in the document with the given name.
• FindTopMostReference – Return a reference to the topmost face of the given element.
• NewSpotElevation – the macro entry point, creating new spot elevations on the top surface of a beam.

The implementation of FindView is pretty standard:

private View FindView( Document doc, String name )
{
  TypeFilter filter = Create.Filter.NewTypeFilter(
    typeof( View ), true );
 
  ElementIterator iter = doc.get_Elements( filter );
  View ret = null;
 
  iter.Reset();
  while( iter.MoveNext() )
  {
    Element e = iter.Current as Element;
 
    if( e.Name == name )
    {
      ret = e as View;
      break;
    }
  }
  return ret;
}

FindTopMostReference is much more interesting. We define a viewDirection vector pointing straight down, and a point centerOfTopOfBox that is located exactly above the element whose top surface we are targeting. Using FindReferencesByDirection and filtering the resulting intersections to get the closest reference that belongs to the given element guarantees that the top surface is identified.

The entire operation is encapsulated in a transaction. This is used for the creation of a temporary view which can then be discarded afterwards. We thus avoid having to search for an existing 3D view. Remember that a 3D view is needed to use FindReferencesByDirection. The view is created within the transaction so we have a default 3D view to work with, and the transaction is then aborted so as not to keep the view around afterwards.

private Reference FindTopMostReference( Element e )
{
  Document doc = e.Document;
 
  doc.BeginTransaction();
 
  XYZ viewDirection = Create.NewXYZ( 0, 0, -1 );
 
  View3D view3D = doc.Create.NewView3D(
    viewDirection );
 
  BoundingBoxXYZ elemBoundingBox
    = e.get_BoundingBox( view3D );
 
  XYZ max = elemBoundingBox.Max;
 
  XYZ minAtMaxElevation = elemBoundingBox.Min;
 
  minAtMaxElevation.Z = max.Z;
 
  XYZ centerOfTopOfBox = minAtMaxElevation
    .Add( max ).Divide( 2 );
 
  centerOfTopOfBox.Z = centerOfTopOfBox.Z + 10;
 
  ReferenceArray references
    = doc.FindReferencesByDirection(
      centerOfTopOfBox, viewDirection, view3D );
 
  double closest = Double.PositiveInfinity;
 
  Reference ret = null;
 
  foreach( Reference r in references )
  {
    if( r.Element.Id.Value == e.Id.Value
      && r.ProximityParameter < closest )
    {
      ret = r;
      closest = r.ProximityParameter;
    }
  }
  doc.AbortTransaction();
 
  return ret;
}

Note how the reference is the face on the top of the element, whereas the target point is evaluated from the location curve parameter. This works even if the location alignment of the beam is along the bottom of the beam; the elevations are still at the top.

This method probably deserves being copied into your personal toolbox right away for reference and future reuse. It looks both generally useful and instructive to me.

Finally, here is the implementation of the NewSpotElevation macro mainline, which performs the following steps:

• Find the view named "West".
• Find the beam family instance with a specific hardcoded element id.
• Use FindTopMostReference to obtain a reference to its top surface.
• Retrieve its location curve.
• Open a transaction to apply changes to the model.
• Step along the location curve to create spot elevations along the top surface at the beginning, midpoint and end of the beam.
• Close the transaction to apply the changes to the model.

Note that this is an application-level macro. Application-level macros are required to manage all their own transactions, whereas document-level macros automatically open a transaction on the active document, just like external commands.

public void NewSpotElevation()
{
  Document doc = ActiveDocument;
 
  View westView = FindView( doc, "West" );
 
  // define the hard coded element id of beam:
 
  ElementId instanceId = Create.NewElementId();
 
  instanceId.Value = 230298;
 
  FamilyInstance familyInstance = doc.get_Element(
    ref instanceId ) as FamilyInstance;
 
  Reference topReference = FindTopMostReference(
    familyInstance );
 
  LocationCurve lCurve = familyInstance.Location
    as LocationCurve;
 
  doc.BeginTransaction();
 
  for( int beamIndex = 0; beamIndex < 3; ++beamIndex )
  {
    XYZ lCurvePnt = lCurve.Curve.Evaluate(
      0.5 * beamIndex, true );
 
    XYZ bendPnt = lCurvePnt.Add(
      Create.NewXYZ( 0, 1, 4 ) );
 
    XYZ endPnt = lCurvePnt.Add(
      Create.NewXYZ( 0, 2, 4 ) );
 
    // NewSpotElevation arguments:
    //
    // View view, Reference reference, 
    // XYZ origin, XYZ bend, XYZ end, XYZ refPt, 
    // bool hasLeader
 
    SpotDimension sd = doc.Create.NewSpotElevation(
      westView, topReference, lCurvePnt, bendPnt,
      endPnt, lCurvePnt, true );
  }
  doc.EndTransaction();
}

Scott provided a sample model ForSpotElevation.rvt containing a beam that runs N-S so that the West view shows the three different spot elevations, displaying them even more clearly by putting it at an angle.

Here is the west view of the target beam before running the macro:

Here are the resulting spot elevations created by the macro on the beam's top surface:

I converted Scott's VSTA macro source code to create a new Building Coder sample external command named CmdNewSpotElevation. Here is version 1.1.0.60 of the complete Building Coder source code and Visual Studio solution including the new command.

Many thanks to Scott for providing this useful and instructive solution!

Project Location

This is part 8 of Scott Conover's AU 2009 class on analysing building geometry, dealing with the project location and its effect on element transformations. We aready looked at the project location in the discussion on unrotate north. However, as Scott pointed out, the results presented there are somewhat misleading and are subsumed by the following discussion. The project location obviously also affects the azimuth of an element, i.e. the angle between the element and true north, and our previous discussion on that topic can also be replaced by this post.

Project location coordinates

Revit projects have another default coordinate system to take into account: the project location. The Document.ActiveProjectLocation provides access to the active ProjectPosition object, which contains:

EastWest – east/west offset (X offset).

NorthSouth – the north/south offset (Y offset).

Elevation – the difference in elevation (Z offset).

Angle – the angle from true north.

You can use these properties to construct a transform between the default Revit coordinates and the actual coordinates in the project:

// Obtain a rotation transform for the angle about true north
Transform rotationTransform = Transform.get_Rotation(
  XYZ.Zero, XYZ.BasisZ, project_north_angle );
 
// Obtain a translation vector for the offsets
XYZ translationVector = new XYZ(
  projectPosition.EastWest,
  projectPosition.NorthSouth,
  projectPosition.Elevation );
 
Transform translationTransform
  = Transform.get_Translation(
    translationVector );
 
// Combine the transforms into one.
Transform finalTransform
  = translationTransform.Multiply(
    rotationTransform );

South Facing Elements Using Project Location

In this example we adapt the south-facing walls and south-facing windows examples to deal with a project where true north is not aligned with the Revit coordinate system. The facing vectors are rotated by the angle from true north before the calculation is run, and the following walls are now determined to be south facing:

The following windows are now facing south:

Here is the method TransformByProjectLocation that we use to transform a direction vector by the rotation angle of the ActiveProjectLocation. It takes a given normalized direction as an input argument and returns the transformed location:

protected XYZ TransformByProjectLocation( 
  XYZ direction )
{
  // Obtain the active project location's position.
 
  ProjectPosition position
    = Document.ActiveProjectLocation.get_ProjectPosition(
      XYZ.Zero );
 
  // Construct a rotation transform from the position angle.
 
  Transform transform = Transform.get_Rotation(
    XYZ.Zero, XYZ.BasisZ, position.Angle );
 
  // Rotate the input direction by the transform
  XYZ rotatedDirection = transform.OfVector( direction );
 
  return rotatedDirection;
}

Please refer to Scott's AU class material for the full source code of his sample project.

We will continue this series with a look at the powerful FindReferencesByDirection method coming up next.

Extra Transaction Required

Here is another interesting issue to discuss in between the series of instalments of background information on the Revit API geometry library from Scott's Autodesk University presentation on analysing building geometry.

As we mentioned repeatedly in the past, Revit automatically opens a transaction when an external command is invoked, and closes or aborts it when the command terminates, depending on the command result returned by the Execute method. This affects the document IsModified property and clarifies why you need to open you own transactions for certain event handlers and modeless dialogues, forcing you to take on some transaction responsibility yourself. It is therefore always easier and more robust to use a modal dialogue instead of a modeless one, if that is possible.

Here is an example from a case handled by Joe Ye of a situation where we are forced to open our own transaction in spite of executing code within a normal modal external command context. This is because in this specific situation, certain actions of our command depend on previous actions having completed, and this does apparently not always happen automatically. By encapsulating the first step in its own transaction and closing that, the second step depending on it can execute correctly as well.

Question: I have created a new I beam in my Revit model. I then use the Revit API to apply the following modifications to it:

1. Change the beam's "Vertical Projection" property to "Center of Beam".
2. Change the beam's "Z Direction Justification" property to "Center".
3. Create two rectangular openings to hold the beam using the beam's start and end points as center points and defining rectangles around them.

Of the two openings, the first is created in the wrong position, while the second one, at the end of the beam, is created correctly. It seems as if the first opening is created before the "Z Direction Justification" is changed, and the second one afterwards.

Answer: This issue has to do with the model update. The changes to the Z direction justification and vertical projection properties modify the model. Apparently, these changes have not yet been completely applied to the model before the creation of the openings is launched. The complete changes are only guaranteed to be applied to the model after the external command has completely terminated and its automatic transaction has been closed.

In this case, it appears that the property modifications have not been applied when the first opening is created. The creation of the first opening affects the model in a way as to apply the property modifications as well, and therefore the second opening can make use of the updated properties, whereas the first one could not. This explains why the first opening ended up in the wrong position and the second was correct.

The solution for this is to add a transaction to encapsulate the process of changing the two parameter values. This makes sure the beam is updated. After modifying the properties and closing the transaction, the two openings can be added successfully.

Here is a sample code snippet demonstrating this:

using RvtElement = Autodesk.Revit.Element;
using CreationDocument = Autodesk.Revit.Creation.Document;

public IExternalCommand.Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
  View view = commandData.View;
 
  ElementSet elemSet = view.Elements;
 
  IEnumerator elementEnumerator 
    = elemSet.ForwardIterator();
 
  while( elementEnumerator.MoveNext() )
  {
    FamilyInstance fi = elementEnumerator.Current 
      as FamilyInstance;
 
    if( null != fi )
    {
      CurveArray curves = new CurveArray();
 
      app.ActiveDocument.BeginTransaction();
 
      // set the Vertical Projection
 
      Parameter p = fi.get_Parameter( 
        BuiltInParameter.BEAM_V_JUSTIFICATION );
 
      p.Set( 1 );
 
      p = fi.get_Parameter( BuiltInParameter
        .STRUCTURAL_ANALYTICAL_PROJECT_MEMBER_PLANE );
 
      if( p != null )
      {
        ElementId elemId = p.AsElementId();
 
        elemId.Value = -3;
 
        p.Set( ref elemId );
      }
 
      // Vertical Projection modification ends here
 
      app.ActiveDocument.EndTransaction();
 
      LocationCurve lc = fi.Location as LocationCurve;
 
      XYZ pointOnPlane = lc.Curve.get_EndPoint( 0 );
 
      XYZ hostY = fi.FacingOrientation;
      XYZ hostX = fi.HandOrientation;
      XYZ hostZ = hostX.Cross( hostY );
 
      curves = CreateRectangle( app, pointOnPlane, 
        hostX, hostZ, 0.5, 0.5 );
 
      Opening opening = doc.Create.NewOpening( fi, 
        curves, CreationDocument.eRefFace.CenterY );
 
      pointOnPlane = lc.Curve.get_EndPoint( 1 );
 
      curves = CreateRectangle( app, pointOnPlane, 
        hostX, hostZ, 0.5, 0.5 );
 
      opening = doc.Create.NewOpening( fi, 
        curves, CreationDocument.eRefFace.CenterY );
    }
  }
  return IExternalCommand.Result.Succeeded;
}

So the motto of this is that if you need to perform some model change immediately after some other model changing action, and the second change is closely related to the first, then it is safer to encapsulate the first change in a transaction to ensure that the second one correctly honours it.

Many thanks to Joe for handling this case!

Transformations

This is part 7 of Scott Conover's AU 2009 class on analysing building geometry, exploring coordinate transformations and the placement and orientation of family instances. For completeness sake, here are some back pointers to previous blog posts dealing with transforms and related issues:

• The Transform class.
• Polygon transformation.
• Instance coordinate transformation.
• Transforming an element.
• Scaling a curve.

So now I hand the word back to Scott:

Coordinate Transformations

Revit and the Revit API use coordinate transformations in a variety of ways. In most cases, transformations are represented in the API as Transform objects. A transform object represents a homogenous transformation combining elements of rotation, translation, and less commonly, scaling and reflection:

In this matrix, the 3 x 3 matrix represents the rotation applied via the transform, while the 1 x 3 matrix represents the translation. Scaling and mirror properties, if applied, show up as multipliers on the matrix members. Mathematically, a transformation of a point looks like this:

In the Transform class you have direct access to the members of the transformation matrix:

• The properties BasisX, BasisY, and BasisZ are the unit vectors of the rotated coordinate system.
• The Origin property is the translation vector.

Use the Transform.OfPoint() and Transform.OfVector() methods to apply the transformation to a given input point or vector. You can also use the Transformed indexed properties (on Curve, Profile, and Mesh) to transform geometry you extracted from Revit into an alternate coordinate system.

You obtain a transform from a variety of operations:

• From the Instance class: the transformation applied to the instance.
• From a Reference containing an Instance.
• From a Panel (curtain panel) element.
• From a 3D bounding box.
• From static properties on Transform: .Identity, .Reflection, .Rotation, .Translation.
• By multiplying two Transforms together: Transform.Multiply().
• By scaling a transform and possibly its origin: Transform.ScaleBasis() and Transform.ScaleBasisAndOrigin().
• By constructing one from scratch: Transform constructor.

Typically Transforms are right-handed coordinate systems, but mirror operations will produce left-handed coordinate systems. Note that Revit sometimes produces left-handed coordinate systems via flip operations on certain elements.

Transformation of Instances

The Instance class stores geometry data in the SymbolGeometry property using a local coordinate system. It also provides a Transform instance to convert the local coordinate system to a world coordinate space. To get the same geometry data as the Revit application from the Instance class, use the transform property to convert each geometry object retrieved from the SymbolGeometry property.

South facing windows

Similarly to the example selecting all south facing walls, we can use the transform of the Instance stored in a window FamilyInstance to find south facing windows:

The Y direction of the transform is the facing direction; however, the flipped status of the window affects the result. If a family instance is flipped in X, its FlippedHand property is true. If it is flipped in Y, its FlippedFacing property is true. If either one of these is set, and the other not, the result must be reversed. Here is the GetWindowDirection method implementing this:

protected XYZ GetWindowDirection( FamilyInstance window )
{
  Options options = new Options();
 
  // Extract the geometry of the window.
 
  Autodesk.Revit.Geometry.Element geomElem 
    = window.get_Geometry( options );
 
  foreach( GeometryObject geomObj in geomElem.Objects )
  {
    // We expect there to be one main Instance 
    // in each window.  Ignore the rest of the geometry.
 
    Instance instance = geomObj as Instance;
    if( instance != null )
    {
      // Obtain the Instance transform and the 
      // nominal facing direction (Y-direction).
 
      Transform t = instance.Transform;
 
      XYZ facingDirection = t.BasisY;
 
      // If the window is flipped in one direction, 
      // but not the other, the transform is left handed.  
      // The Y direction needs to be reversed to 
      // obtain the facing direction.
 
      if( ( window.FacingFlipped && !window.HandFlipped )
        || ( !window.FacingFlipped && window.HandFlipped ) )
      {
        facingDirection = -facingDirection;
      }
 
      // Because the need to perform this operation 
      // on instances is so common, the Revit API exposes 
      // this calculation directly as the FacingOrientation 
      // property as shown in GetWindowDirectionAlternate()
 
      return facingDirection;
    }
  }
  return XYZ.BasisZ;
}

Because the need to perform this operation on instances is so common, the Revit API exposes this calculation directly as the FacingOrientation property:

protected XYZ GetWindowDirectionAlternate( 
  FamilyInstance window )
{
  return window.FacingOrientation;
}

Nested instances

Note that instances may be nested inside other instances. Each instance has a Transform which represents the transformation from the coordinates of the symbol geometry to the coordinates of the instance. In order to get the coordinates of the geometry of one of these nested instances in the coordinates of the document, you will need to concatenate the transforms together using Transform.Multiply().

Next, we look at the Revit project location, which also affects the location and transformations of the elements in the project.

Insert Face-Hosted Sprinkler

In between the series of background information from Scott's Autodesk University presentation on analysing building geometry, let's have a look at another example that combines a little bit of geometric analysis with other issues. This example is from a case handled by Joe Ye and exploring how to insert a face-hosted sprinkler into the model. A family instance is used to represent the sprinkler, so we presumably need to make use of one of the overloads of the NewFamilyInstance method. The question is which one and how to supply the appropriate arguments. We have looked at a number of related issues in the past:

• Inserting a column.
• Inserting a beam.
• Creating a slanted column.
• Creating a curved beam.
• Creating hosted family instances for lighting fixtures.
• Creating nested families.

The first two show how to check whether the required family is loaded and optionally load it if not. The third discusses where to look in the developer guide for more information on the overloads of the NewFamilyInstance method. The fifth has a certain similarity to this case, but still requires a different solution. We can make use of all that information to tackle this current task as well, which requires yet a few more tricky details.

Question: I am having a problem inserting a face-hosted sprinkler symbol into my model. I've been able to insert other family instances without problem, but this one isn't working for me.

I tried hosting the sprinkler on a ceiling object and on a face of the ceiling. When trying to host the sprinkler on the ceiling, I tried creating the instance both with and without the ceiling level. Every time it creates the sprinkler it places it at an elevation of zero even though my ceiling and insertion point is over 56'. I also tried moving the elevation of the sprinkler after insertion but this did nothing. Strangely, the XY location is correct.

I also tried to use a face of the ceiling to host the sprinkler. This failed completely with an exception. I tried using the face, the same insertion point, and a reference direction vector of (0, 0, -1) since I assume the sprinkler would point down the Z axis.

As an added note, I was unable to set the "Elevation" parameter of the Sprinkler after insertion. It says that the operation cannot be done due to the state of the element.

Answer: To address the last note first, you mentioned that you cannot change the elevation parameter. Yes, this is as designed, because this parameter is read-only and so cannot be modified.

Regarding the family instance creation, you need to use a specific overload of the NewFamilyInstance method to create new instance that is attached to the host face, namely:

FamilyInstance NewFamilyInstance(
  Face face,
  XYZ location,
  XYZ referenceDirection,
  FamilySymbol symbol
)

The face-hosted sprinkler requires a sketch plane, and all the other overloads of the NewFamilyInstance method cannot retrieve it together with the correct position and host element, so they end up creating an invalid instance without a correct sketch plane.

To place a sprinkler on the bottom of a ceiling element, we need to locate the ceiling's bottom face and create the sprinkler family instance on that face at a point located in it. In addition, the face that we place the sprinkler on must be associated with a reference, or the placement will not work correctly.

I used the sample code implemented by Joe to create a new Building Coder external command CmdNewSprinkler demonstrating this.

In order to determine an insertion point for the sprinkler on the bottom face of the ceiling, it makes use of the following PointOnFace helper method. It returns an arbitrary point on a planar face, namely the midpoint of the first mesh triangle encountered:

XYZ PointOnFace( PlanarFace face )
{
  XYZ p = new XYZ( 0, 0, 0 );
  Mesh mesh = face.Triangulate();
 
  for( int i = 0; i < mesh.NumTriangles; ++i )
  {
    MeshTriangle triangle = mesh.get_Triangle( i );
    p += triangle.get_Vertex( 0 );
    p += triangle.get_Vertex( 1 );
    p += triangle.get_Vertex( 2 );
    p *= 0.3333333333333333;
    break;
  }
  return p;
}

The Execute method of the CmdNewSprinkler command performs the following tasks:

• Check whether the required sprinkler family is loaded and load it if not.
• Retrieve an arbitrary symbol from the sprinkler family, in this case, the first one encountered.
• Prompt the user to select a ceiling element to host the sprinkler and ensure that a valid selection was made.
• Retrieve the ceiling geometry, its solid, and determine the bottom face.
• Use our PointOnFace helper method to determine an arbitrary insertion point on the ceiling bottom face.
• Call the NewFamilyInstance method.

The trickiest step is the solid retrieval and the determination of the bottom face. When retrieving the solid, we need to ensure that the options' ComputeReferences property is set, or the solid faces will not be associated with the required references.

In all previous Building Coder examples, we did not assign true to ComputeReferences, but left it in its default state of false, which presumably improves performance. It would be interesting to test this, actually, and benchmark the difference that this option setting might have. The setting is required in this case, because the NewFamilyInstance method needs the face reference to create the family instance and associate the sprinkler with the ceiling face.

To find the ceiling's bottom face, we assume that it is horizontal and flat, i.e. planar, so we can use its normal vector pointing straight down to identify it.

Here is the mainline code of the Execute method implementing this:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
// retrieve the sprinkler family symbol:
 
Filter filter = app.Create.Filter.NewFamilyFilter(
  _name );
 
List<RvtElement> families = new List<RvtElement>();
doc.get_Elements( filter, families );
Family family = null;
 
foreach( RvtElement e in families )
{
  family = e as Family;
  if( null != family )
    break;
}
 
if( null == family )
{
  if( !doc.LoadFamily( _filename, out family ) )
  {
    message = "Unable to load '" + _filename + "'.";
    return CmdResult.Failed;
  }
}
 
FamilySymbol sprinklerSymbol = null;
foreach( FamilySymbol fs in family.Symbols )
{
  sprinklerSymbol = fs;
  break;
}
 
Debug.Assert( null != sprinklerSymbol, 
  "expected at least one sprinkler symbol"
  + " to be defined in family" );
 
// pick the host ceiling:
 
RvtElement ceiling = Util.SelectSingleElement( 
  doc, "ceiling to host sprinkler" );
 
if( null == ceiling
  || !ceiling.Category.Id.Value.Equals( 
    (int) BuiltInCategory.OST_Ceilings ) )
{
  message = "No ceiling selected.";
  return CmdResult.Failed;
}
 
// retrieve the bottom face of the ceiling:
 
Options opt = app.Create.NewGeometryOptions();
opt.ComputeReferences = true;
GeoElement geo = ceiling.get_Geometry( opt );
 
PlanarFace ceilingBottom = null;
 
foreach( GeometryObject obj in geo.Objects )
{
  Solid solid = obj as Solid;
 
  if( null != solid )
  {
    foreach( Face face in solid.Faces )
    {
      PlanarFace pf = face as PlanarFace;
 
      if( null != pf )
      {
        XYZ normal = pf.Normal.Normalized;
 
        if( Util.IsVertical( normal ) 
          && 0.0 > normal.Z )
        {
          ceilingBottom = pf;
          break;
        }
      }
    }
  }
}
if( null != ceilingBottom )
{
  XYZ p = PointOnFace( ceilingBottom );
 
  // create the sprinkler family instance
 
  FamilyInstance fi = doc.Create.NewFamilyInstance( 
    ceilingBottom, p, XYZ.BasisX, sprinklerSymbol );
 
  return CmdResult.Succeeded;
}
return CmdResult.Failed;

To test the new command, we create a simple model with four walls and a ceiling:

Running the command and selecting the ceiling element inserts the desired sprinkler:

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

Many thanks to Joe for handling this case and creating the initial implementation!

Face Edges

This is part 6 of Scott Conover's AU 2009 class on analysing building geometry.

Edge and Face Parameterization

Edges are boundary curves for a given face.

Iterate the edges of a Face using the EdgeLoops property. Each loop represents one closed boundary on the face. Edges are always parameterized from 0 to 1.

An edge is usually defined by computing intersection of two faces. But Revit doesn't recompute this intersection when it draws graphics. So the edge stores a list of points – end points for a straight edge and a tessellated list for a curved edge. The points are parametric coordinates on the two faces. These points are available through the TessellateOnFace method.

Sections produce 'cut edges'. These are artificial edges – not representing a part of the model-level geometry, and thus do not provide a Reference.

Edge Direction

Direction is normally clockwise on the first face (first representing an arbitrary face which Revit has identified for a particular edge). But because two different faces meet at one particular edge, and the edge has the same parametric direction regardless of which face you are concerned with, sometimes you need to figure out the direction of the edge on a particular face.

The figure below illustrated how this works. For Face 0, the edges are all parameterized clockwise. For Face 1, the edge shared with Face 0 is not re-parameterized; thus with respect to Face 1 the edge has a reversed direction, and some edges intersect where both edges' parameters are 0 (or 1):

The PanelEdgeLengthAngle Revit SDK Sample

The Revit SDK sample PanelEdgeLengthAngle shows how to recognize edges that are reversed for a given face. It uses the tangent vector at the edge endpoints to calculate the angle between adjacent edges, and detect whether or not to flip the tangent vector at each intersection to calculate the proper angle:

The next instalment of this series will look at transformations.

Retrieving Project Parameters

In between the series of background information from Scott's Autodesk University presentation on analysing building geometry, let's have a quick look at a completely different question, on retrieving all shared parameters from a Revit project. Other posts related to shared parameters are listed at the end of our discussion of RDBLink Export.

The following solution comes from a case handled by Saikat Bhattacharya.

Question: How can I programmatically retrieve the set of project parameters added to a given Revit project?

Answer: Shared parameters are bound to certain categories. You can access all the bound parameter definitions from the BindingMap returned from the Document.ParameterBindings property. Each project parameter shown in the Settings > Project Parameters dialogue represents an entry in this mapping. To see more on how this works, you can refer to the VB.NET BrowseBindings SDK sample residing in the SDK samples folder. It illustrates the usage of the ParameterBindings property by retrieving the ParameterBindingsMap and looping through all entries in the map to display all parameter definitions and bindings in a tree view.

Here are the project parameters as displayed in the user interface:

This is the display generated for the same project through the Revit API by the BrowseBindings SDK sample:

Many thanks to Saikat for handling this case!

Faces

This is part 5 of Scott Conover's AU 2009 class on analysing building geometry.

Faces in the Revit API can be described as mathematical functions of two input parameters 'u' and 'v', where the location of the face at any given point in XYZ space is a function of the parameters. The U and V directions are automatically determined based on the shape of the given face. Lines of constant U or V can be represented as gridlines on the face:

You can use the UV parameters to evaluate a variety of properties of the face at any given location:

• Whether the parameter is within the boundaries of the face, using Face.IsInside.
• The XYZ location of the given face at the specified UV parameter value. This is returned from Face.Evaluate. If you are also calling ComputeDerivatives, this is also the .Origin property of the Transform returned by that method.
• The tangent vector of the given face in the U direction. This is the BasisX property of the Transform returned by Face.ComputeDerivatives.
• The tangent vector of the given face in the V direction. This is the BasisY property of the Transform returned by Face.ComputeDerivatives.
• The normal vector of the given face. This is the BasisZ property of the Transform returned by Face.ComputeDerivatives.

All of the vectors returned are non-normalized.

Face types

Revit uses a variety of curve types to represent face geometry in a document, including the following with their corresponding Revit API representation classes:

• Plane – PlanarFace
• Cylinder – CylindricalFace
• Cone – ConicalFace
• Revolved face – RevolvedFace
• Ruled surface – RuledFace
• Hermite face – HermiteFace

Here is the definition and some notes on each of these:

• Plane: A plane defined by the origin and unit vectors in U and V.
• Cylinder: A face defined by extruding a circle along an axis. The Radius property provides the 'radius vectors' – the unit vectors of the circle multiplied by the radius value.
• Cone: A face defined by rotation of a line about an axis. The Radius property provides the 'radius vectors' – the unit vectors of the circle multiplied by the radius value.
• Revolved face: A face defined by rotation of an arbitrary curve about an axis. The Radius property provides the unit vectors of the plane of rotation, there is no 'radius' involved.
• Ruled surface: A face defined by sweeping a line between two profile curves, or one profile curve and one point. Both curve(s) and point(s) can be obtained as properties.
• Hermite face: A face defined by Hermite interpolation between points.

Mathematical representation

Mathematical representations of all of the Revit face types are given in Appendix B of Scott's handout document, and we include them here as well for easy online access. This section describes the face types encountered in Revit geometry, their properties, and their mathematical representations.

PlanarFace

A plane defined by origin and unit vectors in U and V. Its parametric equation is

P(u,v) = P₀ + u n_u + v n_v

CylindricalFace

A face defined by extruding a circle along an axis. The Revit API provides the following properties:

• The origin of the face.
• The axis of extrusion.
• The 'radius vectors' in X and Y. These vectors are the circle's unit vectors multiplied by the radius of the circle. Note that the unit vectors may represent either a right handed or left handed control frame.

The parametric equation for this face is:

P(u,v) = P₀ + r_x cos(u) + r_y sin(u) + v n_axis

ConicalFace

A face defined by rotation of a line about an axis. The Revit API provides the following properties:

• The origin of the face.
• The axis of the cone.
• The 'radius vectors' in X and Y. These vectors are the unit vectors multiplied by the radius of the circle formed by the revolution. Note that the unit vectors may represent either a right handed or left handed control frame.
• The half angle of the face.

The parametric equation for this face is:

P(u,v) = P₀ + v [sin(α) (r_x cos(u) + r_y sin(u)) + cos(α) n_axis]

RevolvedFace

A face defined by rotation of an arbitrary curve about an axis. The Revit API provides the following properties:

• The origin of the face.
• The axis of the face.
• The profile curve.
• The unit vectors for the rotated curve (incorrectly called 'Radius').

The parametric equation for this face is:

P(u,v) = P₀ + C(v) [r_x cos(u) + r_y sin(u) + n_axis]

RuledFace

A ruled surface is created by sweeping a line between two profile curves or between a curve and a point. The Revit API provides the curve(s) and point(s) as properties.

If both curves are valid, the parametric equation for this surface is:

P(u,v) = C₁(u) + v (C₂(u) - C₁(u) )

If one of the curves is replaced with a point, the equations simplify to one of:

P(u,v) = P₁ + v (C₂(u) - P₁ )
P(u,v) = C₁(u) + v (P₂ - C₁(u) )

A ruled face with no curves and two points is degenerate and will not be returned.

HermiteFace

A cubic Hermite spline face. The Revit API provides:

• Arrays of the u and v parameters for the spline interpolation points.
• An array of the 3D points at each node (the array is organized in increasing u, then increasing v).
• An array of the tangent vectors at each node.
• An array of the twist vectors at each node.

The parametric representation of this surface between nodes (u1, v1) and (u2, v2) is:

P(u,v) = U^T [M_H] [B} [M_H]^T V

Here, U = [u³ u² u 1]^T, V = [v³ v² v 1]^T, and M_H is the Hermite matrix:

[MH] =

2 -2 1 1     -3 3 -2 -1     0 0 1 0     1 0 0 0

B is the coefficient matrix obtained from the face properties at the interpolation points:

[B] =

Pu1v1 Pu1v2 P'v(u1v1) P'v(u1v2)     Pu2v1 Pu2v2 P'v(u2v1) P'v(u2v2)     P'u(u1v1) P'u(u1v2) P'uv(u1v1) P'uv(u1v2)     P'u(u2v1) P'u(u2v2) P'uv(u2v1) P'uv(u2v2)

Face analysis and processing

Several Face member methods provide tools suitable for use in geometric analysis:

• Intersect: computes the intersection between the face and a curve.
• Project: projects a point on the input face, and returns information on the projection point, the distance to the face, and the nearest edge to the projection point.
• Triangulate: returns a triangular mesh approximating the face. Similar to Curve.Tessellate, this mesh's points are accurate within the input tolerance used by Revit (slightly larger than 1/16').

The Intersect method can be used in to identify:

• The intersection point(s) between the two objects.
• The edge nearest the intersection point, if there is an edge close to this location.
• Curves totally coincident with a face.
• Curves and faces which do not intersect.

The next instalment of this series will look at face edges and their directions and parametrisation.

Rectangular Duct Corners

In between the series of background information from Scott's Autodesk University presentation on analysing building geometry, let's have a quick look at a practical application.

This is an MEP-specific issue on how to determine the corners of a rectangular duct. One approach to determine this information is to perform the following steps:

• Analyse the duct geometry.
• Extract its solid.
• Iterate over the faces.
• Select the face containing the rectangular connector.
• Determine its four corners.

We explored the geometry of various elements in detail in the past, e.g. slab boundary, slab side faces, wall elevation profile, 2D polygon areas and outer loop, 3D polygon areas, and cylindrical columns. We have also had a look at MEP connectors and used the information contained in them, e.g. for the modeless pressure drop tool. This analysis now shows how these two sources of information, geometry and connectors, can be usefully combined.

The following solution comes from a case handled by Joe Ye and an implementation by Aaron and Vico in the Revit development team.

Question: I need to determine the four corners at the end of a rectangular duct. Given a connector at the end of the duct, I have been using the connector coordinate system transform and width and height properties to determine the corners like this:

  XYZ p = connector.CoordinateSystem.OfPoint( 
    new XYZ( connector.Width / 2, 
      connector.Height / 2, 0 ) );

This only seems to work if the duct is oriented such that the airflow is in the XY plane.

If the duct's airflow is along the Z axis so the duct is going up or down, I can calculate the corner like this:

  XYZ p = connector.CoordinateSystem.OfPoint( 
    new XYZ( connector.Height / 2, 
      connector.Width / 2, 0 ) );

I seem to be missing something, because it seems like I shouldn't have to determine the duct's orientation. Is there a more general solution to determining the corners of a rectangular duct? Also, if the duct has been rotated, neither of these methods works.

Answer: There is no direct access to the four corners, but they can easily be determined from the duct geometry in combination with the connector location:

• Retrieve the duct geometry solid.
• Retrieve the duct centre line and find the two rectangular end faces which are perpendicular to it.
• Alternatively, find the planar rectangular face containing the connector.
• Retrieve its four vertices to obtain the desired corner points.

I added a new external command CmdRectDuctCorners to The Building Coder sample application to demonstrate how these steps can be implemented.

This implementation also demonstrates making use of the .NET diagnostics Trace class to create a log file to write the data to, rather than using our customary approach of writing to the Visual Studio debug console window. Using the Trace class and writing to a file is useful for driving automated tests and comparing the results with an expected template output file, for instance.

We make use of the following helper methods:

• GetFirstRectangularConnector – return the first rectangular connector of the given duct element.
• FaceContainsConnector – return true if the given face of a solid contains the given connector.
• AnalyseDuct – analyse the given duct element: determine its first rectangular connector, retrieve its solid, find the face containing the connector, and list its four vertices.

Here is the implementation of GetFirstRectangularConnector:

static bool GetFirstRectangularConnector( 
  Duct duct, 
  out Connector c1 )
{
  c1 = null;
 
  ConnectorSet connectors 
    = duct.ConnectorManager.Connectors;
 
  if( 0 < connectors.Size )
  {
    foreach( Connector c in connectors )
    {
      if( ConnectorProfileType.RectProfile 
        == c.Shape )
      {
        c1 = c;
        break;
      }
      else
      {
        Trace.WriteLine( "Connector shape: " 
          + c.Shape );
      }
    }
  }
  return null != c1;
}

FaceContainsConnector is short and sweet. It uses Face.Project to determine the closest point on the face to the connector origin. If it exists and the distance returned by the method is small, the connector is contained in the face:

static bool FaceContainsConnector(
  Face face,
  Connector c )
{
  XYZ p = c.Origin;
 
  IntersectionResult result = face.Project( p );
 
  return null != result
    && Math.Abs( result.Distance ) < 1e-9;
}

The mainline of the command does the following:

• Check that we really are running in Revit MEP. If that is not the case, we will not have access to the duct element's connector manager.
• Set up the log file for the Trace mechanism. Its path and filename is determined from the location and name of the executing assembly with a suffix of the current date and an extension ".log".
• Set up an error handler and manage exceptions, including final cleanup to ensure the trace mechanism is properly closed.
• Iterate over the selected elements, check that each one really is a duct, and pass it into the analysis method.
• Return Failed regardless of whether the analysis was successful or not, so that the database is not unnecessarily marked as dirty even though nothing was modified.

Application app = commandData.Application;
 
if( ProductType.MEP != app.Product )
{
  message = "Please run this command in Revit MEP.";
  return CmdResult.Failed;
}
 
Document doc = app.ActiveDocument;
SelElementSet sel = doc.Selection.Elements;
 
if( 0 == sel.Size )
{
  message = "Please select some rectangular ducts.";
  return CmdResult.Failed;
}
 
// set up log file:
 
string log = Assembly.GetExecutingAssembly().Location 
  + "." + DateTime.Now.ToString( "yyyyMMdd" ) 
  + ".log";
 
if( File.Exists( log ) )
{
  File.Delete( log );
}
 
TraceListener listener 
  = new TextWriterTraceListener( log );
 
Trace.Listeners.Add( listener );
 
try
{
  Trace.WriteLine( "Begin" );
 
  // loop over all selected ducts:
 
  foreach( Duct duct in sel )
  {
    if( null == duct )
    {
      Trace.TraceError( "The selection is not a duct!" );
    }
    else
    {
      // process each duct:
 
      Trace.WriteLine( "========================" );
      Trace.WriteLine( "Duct: Id = " + duct.Id.Value );
 
      AnalyseDuct( duct );
    }
  }
}
catch( Exception ex )
{
  Trace.WriteLine( ex.ToString() );
}
finally
{
  Trace.Flush();
  listener.Close();
  Trace.Close();
  Trace.Listeners.Remove( listener );
}
return CmdResult.Failed;

Finally, here is the AnalyseDuct method that does the real work:

• Retrieve the duct's first rectangular connector.
• Retrieve the duct geometry.
• Extract the solid.
• Iterate over its faces.
• Find the face containing the connector.
• List its four vertices to the log file.

static bool AnalyseDuct( Duct duct )
{
  bool rc = false;
 
  Connector c1;
  if( !GetFirstRectangularConnector( duct, out c1 ) )
  {
    Trace.TraceError( "The duct is not rectangular!" );
  }
  else
  {
    Options opt = new Options();
    opt.DetailLevel = Options.DetailLevels.Fine;
    GeoElement geoElement = duct.get_Geometry( opt );
 
    foreach( GeometryObject obj in geoElement.Objects )
    {
      Solid solid = obj as Solid;
      if( solid != null )
      {
        bool foundFace = false;
        foreach( Face face in solid.Faces )
        {
          foundFace = FaceContainsConnector( face, c1 );
          if( foundFace )
          {
            Trace.WriteLine( "==> Four face corners:" );
 
            EdgeArray a = face.EdgeLoops.get_Item( 0 );
 
            foreach( Edge e in a )
            {
              XYZ p = e.Evaluate( 0.0 );
 
              Trace.WriteLine( "Point = " 
                + Util.PointString( p ) );
            }
            rc = true;
            break;
          }
        }
        if( !foundFace )
        {
          Trace.WriteLine( "[Error] Face not found" );
        }
      }
    }
  }
  return rc;
}

This is the resulting log file output after running this command with a simple rectangular duct selected:

Begin
========================
Duct: Id = 431526
==> Four face corners:
Point = (-18.27,4.66,8.53)
Point = (-18.27,4.66,9.51)
Point = (-18.27,3.67,9.51)
Point = (-18.27,3.67,8.53)

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

Many thanks to Joe for handling this case and to Aaron and Vico for the initial implementation!