The Building Coder

Copy and Paste API Applications and Modeless Assertion

Here is a detailed description of one of the most exciting Revit 2014 API features that you should have heard about by now and promises numerous uses, prompted by a question from a developer on duplicating views from one document to another. Another couple of uses of it cropped up in the past, so it seems like an overview is called for:

• Duplicating a view from one document to another
• Solving the non-unique unique id problem
• Managing materials in adsklib or template files
• Transferring groups between projects
• Revit API use in modeless form throws an exception

Duplicating a View from one Document to Another

Question: I need to perform the following action programmatically:

Insert Tab > Insert from File > Insert view from file > Select File > Select view in this file.

Is there some way to achieve this via API in Revit?

Answer: Yes, you are in luck, this is covered by the new Revit 2014 API.

And even more luckily, the development team selected very good and suitable API samples, so the exact workflow you describe is covered by the new Revit 2014 DuplicateViews SDK sample illustrating the new copy and paste API.

Look at the second bullet item in the overview of Revit 2014 API news, mentioning the new copy and paste API.

Here is the description from the What's New section of the Revit API help file RevitAPI.chm, reproduced here:

Copy & paste elements

The new methods:

ElementTransformUtils.CopyElements(Document, ICollection<ElementId>, Document, Transform)

ElementTransformUtils.CopyElements(View, ICollection<ElementId>, View, Transform)

Transform ElementTransformUtils.GetTransformFromViewToView(View, View)

support copy and paste of arbitrary elements. The first overload supports copy within documents, or from document to document. The second overload also support copying within one document or between two documents, but specifically supports copy and paste of view-specific elements.

The DuplicateViews SDK Sample

DuplicateViews copies and pastes drafting views and schedules from one document to another
, demonstrating use of the CopyPasteOptions, ElementTransformUtils, FilteredElementCollector, IDuplicateTypeNamesHandler and IFailuresPreprocessor classes. The drafting view contents are also copied.

The DuplicateAcrossDocumentsCommand.cs module implements an external command to copy schedules and drafting views across documents and makes use of a number of useful utility classes defined in DuplicateViewUtils.cs.

In detail, DuplicateViews copies all drafting views, image views, and schedules from the currently active document into another document that is currently in memory. All drafting elements in the non-schedule views are also copied, as is all schedule formatting and filtering. It uses API tools to hide any duplicate types warnings that typically arise when doing this from the user interface.

To test this, open any two project documents in Revit. Set the active document to be the document from which you wish to copy views. Launch Add-ins > CopyPaste > Duplicate across documents and enjoy. A popup message will appear listing the number of schedules, drafting views and drafting elements copied by the command.

If you prefer to watch someone else run this sample rather than trying it yourself, it is also demonstrated live in the Revit 2014 DevDays presentation recording.

Solving the Non-unique Unique Id Problem

A couple of times, people mentioned issues caused by copied files, resulting in copied unique ids on certain elements, e.g. thus:

Question: Do you have any recommendation on how to handle unique ids in copied files?

We cannot tell people 'do not copy the files', because they sometimes put in a large effort to create a file that is used as a basic starting point for multiple projects.

Answer: Yes, you are in luck again. The copy and paste API should solve this.

Documents that are copied obviously contain exact copies the ids of their elements. This also can happen when using a document as a template to create another document.

Elements created by copying them through the copy and paste API obviously are assigned new unique ids. That should solve the issue.

Of course, there is no way to change the unique id of an element that already exists.

Managing Materials in Adsklib or Template Files

Question: I would like to know if it is possible to access data stored in adsklib files through API functions. The desired functionality would be to load materials, appearance, physical and thermal assets from an external adsklib file to the current active project document.

The aim is to implement a custom materials library with our application using an adsklib file instead of a project template, as described in the Autodesk wiki on managing material libraries, so only the required materials are included and not all, to decrease the project template size and speed up the material browser.

Is this possible? If so, how?

Answer: Nope, sorry, as far as I know, there is no API support for this.

From my naive grass roots perspective, the adsklib idea was born quite a few years back and has since been displaced by visions of cloud and mobile.

The file formats have died, and long live the new format, ubiquitous JSON or whatever.

You say you "have been looking into this subject for some time already" ... maybe it is time to start looking into something new? I see two possibilities for moving forward, besides the solution that you mention of including all materials in the template file:

1. Store the materials in several separate adsklib files, and only load the ones you really need.
2. Use the new Revit 2014 copy and paste API functionality to copy and paste only the required materials from your or some other project.

Response: Thank you for thinking of other solutions.

Option 1 probably still requires API access to the adsklib file to programmatically transfer the material assets from the adsklib into the project.

I had a quick look at the copy and paste functionality and think this would be a good solution. We could use a separate project or template file as our material library instead of the adsklib one and copy/paste the required materials into the current project.

Transferring Groups Between Projects

I have been working with the Revit API to create a Revit application that can transfer a group type from one project file to another. I am working on a very large project, so we have to separate it into several project files due to performance. We are using groups to ensure that rooms having the same characteristics always are the same and can be updated quickly. But the model separation creates a problem to ensure that all group types in all project files are updated. We tried to use the link functionality instead of groups, but when there are many instances of a link Revit become very slow. We also considered using family nesting to solve the problem, but we want to be able to include system families as well, so that solution won't work.

We have one project file where we create the Groups, use 'Save Group' to create a project file, then 'Load Group' or 'Reload Group' to get it in to the actual project file (we have 21 project files). So what I want is to create a Revit application that optimizes this workflow by transferring groups from one project file to another. But working with the API has raised a couple of questions:

• Why are the user interface functions 'Load Group', 'Save Group', 'Reload group' not accessible from the API? Are there any plans to make them accessible?
• If I want to transfer a group type from one project file to another, is the only way to do this to create every group member in the receiving project file using the API functions for every member, e.g. Wall.Create and then group the members?
• Is there a way to transfer system families from one project file to another using the API? The user interface function transfer project standards is not available, are there any plans to make it available?
• It seems like Revit is more appropriate for small projects, there are some plans to make Revit better for larger projects? For instance by sharing families (system and loadable) and groups across project files?

Answer: I am surprised that you say that Revit is more appropriate for small projects. I was under the impression that the opposite is true.

You may be surprised to hear that the answer to all your questions is yes.

You will be glad to hear that a number of improvements in Revit 2014 are specifically targeted at supporting still larger projects, and many of these improvements specifically target the family management and loading performance.

Regarding all of your other questions, I have one single big suggestion to make to you: please take a look at Revit 2014, and especially at the new copy and paste API functionality it provides. I think that may meet your needs exactly and efficiently.

Response: I took a look at the Revit 2014 API and I must say that the copyElement method is just what I need ;-)

It is a much safer way to transfer groups from one project file to another.

Revit API use in Modeless Form Throws an Exception

Finally, on a completely different topic, several people making illegal use of the Revit API from an invalid context in Revit 2013, e.g. in a modeless form, are now running into a problem. David Rock describes it in his comment on accessing the Revit main window handle:

Question: In Revit 2014 I'm having trouble showing a modeless form and calling a transaction whilst inside the form. It is producing an error stating that "starting a transaction from an external application running outside of API context is not allowed".

Answer: Yes, it looks as if you are calling the Revit API directly from your modeless dialogue running in another thread.

As you should know, actually, that was never supported.

Now, in Revit 2014, an exception is raised when you make such an attempt.

You are lucky that it worked so far without corrupting anything.

The solution is described in depth here on the blog: simply google for "modeless site:thebuildingcoder.typepad.com", or look at the discussions in the Idling category.

In short, make use of the Idling event, or implement an external event, which is a simplified wrapper around that, and base you application on the ModelessForm_ExternalEvent and ModelessForm_IdlingEvent SDK samples.

Do not call the Revit API directly, ever.

Setting up your ViewOrientation3D

Here is a contribution from Mario Guttman of CASE, who already made various contributions here in the past. He says:

I have been purging my 2013 code of deprecated functions in preparation for my 2014 upgrade. One group of statements I have needed to replace are the view creations. They were previously using the Document.Create.NewView3D method and needed converting to the View3D.CreateIsometric with a separate ViewOrientation3D object defining the view direction.

Typically, in these kind of cases, I just search your blog for the answer. In this case I found a few references, for example your March 04, 2013 item on What's New in the Revit 2013 API – View API – View Creation. This, together with the wikihelp entry on the View3D class, describe the new syntax, but they don't really explain how you would create the values.

After searching the inner reaches of my brain for some ancient math skills I figured out the following:

Assuming that your user interface has produced two angular values (in degrees):

  /// <summary>
  /// The angle in the XY plane (azimuth),
  /// typically 0 to 360.
  /// </summary>
  double angleHorizD;
 
  /// <summary>
  /// The vertical tilt (altitude),
  /// typically -90 to 90.
  /// </summary>
  double angleVertD;

Then this utility function returns a unit vector in the specified direction:

  /// <summary>
  /// Return a unit vector in the specified direction.
  /// </summary>
  /// <param name="angleHorizD">Angle in XY plane 
  /// in degrees</param>
  /// <param name="angleVertD">Vertical tilt between 
  /// -90 and +90 degrees</param>
  /// <returns>Unit vector in the specified 
  /// direction.</returns>
  private XYZ VectorFromHorizVertAngles(
    double angleHorizD,
    double angleVertD )
  {
    // Convert degreess to radians.
 
    double degToRadian = Math.PI * 2 / 360;
    double angleHorizR = angleHorizD * degToRadian;
    double angleVertR = angleVertD * degToRadian;
 
    // Return unit vector in 3D
 
    double a = Math.Cos( angleVertR );
    double b = Math.Cos( angleHorizR );
    double c = Math.Sin( angleHorizR );
    double d = Math.Sin( angleVertR );
 
    return new XYZ( a * b, a * c, d );
  }

From this it is easy to create the ViewOrientation3D object as follows:

  XYZ eye = new XYZ.Zero;
 
  XYZ forward = VectorFromHorizVertAngles(
    angleHorizD, angleVertD );
 
  XYZ up = VectorFromHorizVertAngles(
    angleHorizD, angleVertD + 90 );
 
  ViewOrientation3D viewOrientation3D
    = new ViewOrientation3D( eye, up, forward );

Although it is already explained in one of your other posts, just for completeness, here is the final step is to apply the orientation to the view:

  ViewFamilyType viewFamilyType3D
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ViewFamilyType ) )
      .Cast<ViewFamilyType>()
      .FirstOrDefault<ViewFamilyType>(
        x => ViewFamily.ThreeDimensional
          == x.ViewFamily );
 
  View3D view3d = View3D.CreateIsometric(
    doc, viewFamilyType3D.Id );
 
  view3d.SetOrientation( viewOrientation3D );

I hope you find this useful.

Personally, I do indeed.

Many thanks to Mario for sharing!

Curve Following Face and Bounding Box Implementation

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I looked at using the ExtrusionAnalyzer to create a plan view boundary profile for the furniture and equipment family instances and implemented a utility method SortCurvesContiguous to sort and re-orient the curves it returns into a closed contiguous loop.

An alternative and more effective method is to use the Edge AsCurveFollowingFace call instead of AsCurve, as we shall see below.

In any case, we want to check the results, e.g. to ensure that we really have obtained the valid closed boundary loops we expect.

The easiest way to do so is to visualise them graphically. To visualise something, you mostly need to know how big it is first. You often need to scale it to fit into your visualisation space, e.g. a fixed-size window, i.e. transform from its given initial size and location to the target coordinate space. A useful way to determine the size of a boundary loop is to calculate the bounding box of its collection of vertices.

That leads to the following topics of today's post, including one additional unrelated issue that just came in:

• Using AsCurveFollowingFace
• XYZ point bounding box calculation
• 2D integer-based point bounding box calculation
• Overview of sweep sample code and issue resolutions

Use Curve Following Face

I already had one stab at using a built-in Revit API method instead of implementing my own SortCurvesContiguous solution: Rudolf Honke suggested testing the ExporterIFCUtils ValidateCurveLoops method instead, but that did not work.

Now Bettina Zimmermann provided another idea:

I don’t understand why you write your own code for direction sorting of the curves when Revit can provide it for you: Edge.AsCurveFollowingFace. Scott Conover's Geometry API document describes it a bit but not very detailed.

I have written some code using Revit API to find the curves sorted in the right direction for using GeometryCreationUtilities.CreateExtrusionGeometry, so I found out it is possible using this call.

I tested that, simply replacing the call to Edge.AsCurve by AsCurveFollowingFace:

  Plane plane = new Plane( XYZ.BasisX,
    XYZ.BasisY, XYZ.Zero );
 
  ExtrusionAnalyzer extrusionAnalyzer = null;
 
  try
  {
    extrusionAnalyzer = ExtrusionAnalyzer.Create(
      solid, plane, XYZ.BasisZ );
  }
  catch( Autodesk.Revit.Exceptions
    .InvalidOperationException )
  {
    ++nExtrusionAnalysisFailures;
    return nAdded;
  }
 
  Face face = extrusionAnalyzer
    .GetExtrusionBase();
 
  foreach( EdgeArray a in face.EdgeLoops )
  {
    int nEdges = a.Size;
 
    List<Curve> curves
      = new List<Curve>( nEdges );
 
    XYZ p0 = null; // loop start point
    XYZ p; // edge start point
    XYZ q = null; // edge end point
 
    foreach( Edge e in a )
    {
      // This requires post-processing using
      // SortCurvesContiguous:
 
      Curve curve = e.AsCurve();
 
      if( _debug_output )
      {
        p = curve.get_EndPoint( 0 );
        q = curve.get_EndPoint( 1 );
        Debug.Print( "{0} --> {1}",
          Util.PointString( p ),
          Util.PointString( q ) );
      }
 
      // This returns the curves already
      // correctly oriented:
 
      curve = e.AsCurveFollowingFace(
        face );
 
      if( _debug_output )
      {
        p = curve.get_EndPoint( 0 );
        q = curve.get_EndPoint( 1 );
        Debug.Print( "{0} --> {1} following face",
          Util.PointString( p ),
          Util.PointString( q ) );
      }
 
      curves.Add( curve );
    }
 
    CurveUtils.SortCurvesContiguous(
      creapp, curves, _debug_output );
 
    q = null;
 
    JtLoop loop = new JtLoop( nEdges );
 
    foreach( Curve curve in curves )
    {
      // Todo: handle non-linear curve.
      // Especially: if two long lines have a 
      // short arc in between them, skip the arc
      // and extend both lines.
 
      p = curve.get_EndPoint( 0 );
 
      loop.Add( new Point2dInt( p ) );
 
      Debug.Assert( null == q
        || q.IsAlmostEqualTo( p, 1e-05 ),
        string.Format(
          "expected last endpoint to equal current start point, not distance {0}",
          (null == q ? 0 : p.DistanceTo( q ))  ) );
 
      q = curve.get_EndPoint( 1 );
 
      if( _debug_output )
      {
        Debug.Print( "{0} --> {1}",
          Util.PointString( p ),
          Util.PointString( q ) );
      }
 
      if( null == p0 )
      {
        p0 = p; // save loop start point
      }
    }
    Debug.Assert( q.IsAlmostEqualTo( p0, 1e-05 ),
      string.Format(
        "expected last endpoint to equal current start point, not distance {0}",
        p0.DistanceTo( q ) ) );
 
    loops.Add( loop );
 
    ++nAdded;
  }

I also added new code to the SortCurvesContiguous method to report correctly sorted and oriented curves. A typical snippet of output looks like this now:

(2.18,8.4,0) --> (2.18,5.78,0)
(2.18,8.4,0) --> (2.18,5.78,0) following face
(2.18,5.78,0) --> (7.31,5.78,0)
(2.18,5.78,0) --> (7.31,5.78,0) following face
(7.31,5.78,0) --> (7.31,8.4,0)
(7.31,5.78,0) --> (7.31,8.4,0) following face
(7.31,8.4,0) --> (6.75,8.4,0)
(7.31,8.4,0) --> (6.75,8.4,0) following face
(6.75,8.4,0) --> (6.75,8.46,0)
(6.75,8.4,0) --> (6.75,8.46,0) following face
(6.75,8.46,0) --> (6.41,8.46,0)
(6.75,8.46,0) --> (6.41,8.46,0) following face
(6.41,8.46,0) --> (6.41,8.4,0)
(6.41,8.46,0) --> (6.41,8.4,0) following face
(6.41,8.4,0) --> (3.08,8.4,0)
(6.41,8.4,0) --> (3.08,8.4,0) following face
(3.08,8.46,0) --> (3.08,8.4,0)
(3.08,8.4,0) --> (3.08,8.46,0) following face
(2.74,8.46,0) --> (3.08,8.46,0)
(3.08,8.46,0) --> (2.74,8.46,0) following face
(2.74,8.4,0) --> (2.74,8.46,0)
(2.74,8.46,0) --> (2.74,8.4,0) following face
(2.74,8.4,0) --> (2.18,8.4,0)
(2.74,8.4,0) --> (2.18,8.4,0) following face
0 endPoint (2.18,5.78,0)
1 start point match, no need to swap
1 endPoint (7.31,5.78,0)
2 start point match, no need to swap
2 endPoint (7.31,8.4,0)
3 start point match, no need to swap
3 endPoint (6.75,8.4,0)
4 start point match, no need to swap
4 endPoint (6.75,8.46,0)
5 start point match, no need to swap
5 endPoint (6.41,8.46,0)
6 start point match, no need to swap
6 endPoint (6.41,8.4,0)
7 start point match, no need to swap
7 endPoint (3.08,8.4,0)
8 start point match, no need to swap
8 endPoint (3.08,8.46,0)
9 start point match, no need to swap
9 endPoint (2.74,8.46,0)
10 start point match, no need to swap
10 endPoint (2.74,8.4,0)
11 start point match, no need to swap
11 endPoint (2.18,8.4,0)
(2.18,8.4,0) --> (2.18,5.78,0)
(2.18,5.78,0) --> (7.31,5.78,0)
(7.31,5.78,0) --> (7.31,8.4,0)
(7.31,8.4,0) --> (6.75,8.4,0)
(6.75,8.4,0) --> (6.75,8.46,0)
(6.75,8.46,0) --> (6.41,8.46,0)
(6.41,8.46,0) --> (6.41,8.4,0)
(6.41,8.4,0) --> (3.08,8.4,0)
(3.08,8.4,0) --> (3.08,8.46,0)
(3.08,8.46,0) --> (2.74,8.46,0)
(2.74,8.46,0) --> (2.74,8.4,0)
(2.74,8.4,0) --> (2.18,8.4,0)
FamilyInstance Furniture Desk <212646 1525 x 762mm> has 1 loop:
  0: (664,2561), (664,1761), (2227,1761), (2227,2561),
    (2056,2561), (2056,2580), (1954,2580), (1954,2561),
    (937,2561), (937,2580), (836,2580), (836,2561)

As you can see, AsCurveFollowingFace does indeed return all the curves correctly oriented and sorted, and SortCurvesContiguous has nothing at all left to do.

Thank you very much Bettina for this valuable suggestion!

Also thanks to Scott Conover for his valuable Geometry API document from the Autodesk University 2011 class, which I already mentioned numerous times in the past but was not previously published in PDF format and therefore not included in web searches until now.

Bounding Box Determination for XYZ Points

As explained above, I would like to check the validity of the boundary loop listed above. The easiest way to do so is by displaying it visually. To do so, I need to transform it from its native coordinate space to my display space, for instance Windows device or HTML5 Canvas coordinates. This normally requires scaling and translation, and in turn knowledge of the size and location of the native coordinate space. The latter can be easily determined by calculating a bounding box.

I therefore set out to implement a bounding box determination for XYZ points.

I could use the existing Revit API BoundingBoxXyz class, because it does provide both read and write access to its Min and Max properties. However, it includes a number of additional features that are of no interest to me at this point, so I prefer to create my own lightweight class for this.

My first idea was to use a generic Tuple class, e.g.

  class JtBoundingBoxXyz : Tuple<XYZ, XYZ>

However, the components of such a tuple are read-only and cannot be changed after instantiation, so I cannot easily update the min and max values as I add new points using this approach.

My next idea was to implement my own class and manage Revit XYZ max and min member variables within it. However, the components of an XYZ are read-only and cannot be changed except by re-instantiation, so extending the bounding box to include new points would have sub-optimal performance in this case as well.

The simplest solution appears to be managing six individual doubles instead, and instantiating XYZ return values when needed, like this:

/// <summary>
/// A bounding box for a collection of XYZ instances.
/// The components of a tuple are read-only and cannot 
/// be changed after instantiation, so I cannot use 
/// that easily.
/// The components of an XYZ are read-only and cannot 
/// be changed except by re-instantiation, so I cannot 
/// use that easily either.
/// </summary>
class JtBoundingBoxXyz // : Tuple<XYZ, XYZ>
{
  /// <summary>
  /// Minimum and maximum X, Y and Z values.
  /// </summary>
  double xmin, ymin, zmin, xmax, ymax, zmax;
 
  /// <summary>
  /// Initialise to infinite values.
  /// </summary>
  public JtBoundingBoxXyz()
  {
    xmin = ymin = zmin = double.MaxValue;
    xmax = ymax = zmax = double.MinValue;
  }
 
  /// <summary>
  /// Return current lower left corner.
  /// </summary>
  public XYZ Min
  {
    get { return new XYZ( xmin, ymin, zmin ); }
  }
 
  /// <summary>
  /// Return current upper right corner.
  /// </summary>
  public XYZ Max
  {
    get { return new XYZ( xmax, ymax, zmax ); }
  }
 
  public XYZ MidPoint
  {
    get { return 0.5 * ( Min + Max ); }
  }
 
  /// <summary>
  /// Expand bounding box to contain 
  /// the given new point.
  /// </summary>
  public void ExpandToContain( XYZ p )
  {
    if( p.X < xmin ) { xmin = p.X; }
    if( p.Y < ymin ) { ymin = p.Y; }
    if( p.Z < zmin ) { zmin = p.Z; }
    if( p.X > xmax ) { xmax = p.X; }
    if( p.Y > ymax ) { ymax = p.Y; }
    if( p.Z > zmax ) { zmax = p.Z; }
  }
}

Bounding Box Determination for 2D Integer Points

Applying the same principles, here is a pretty optimal implemenetation of a bounding box for 2D integer-based points. It includes a constructor taking a collection of loops, which is the output I am generating from my furniture and equipment plan view calculation:

/// <summary>
/// A bounding box for a collection 
/// of 2D integer points.
/// </summary>
class JtBoundingBox2dInt
{
  /// <summary>
  /// Minimum and maximum X and Y values.
  /// </summary>
  int xmin, ymin, xmax, ymax;
 
  /// <summary>
  /// Initialise to infinite values.
  /// </summary>
  public JtBoundingBox2dInt()
  {
    xmin = ymin = int.MaxValue;
    xmax = ymax = int.MinValue;
  }
 
  /// <summary>
  /// Return current lower left corner.
  /// </summary>
  public Point2dInt Min
  {
    get { return new Point2dInt( xmin, ymin ); }
  }
 
  /// <summary>
  /// Return current upper right corner.
  /// </summary>
  public Point2dInt Max
  {
    get { return new Point2dInt( xmax, ymax ); }
  }
 
  /// <summary>
  /// Return current center point.
  /// </summary>
  public Point2dInt MidPoint
  {
    get
    {
      return new Point2dInt(
        (int)(0.5 * ( xmin + xmax )),
        (int)(0.5 * ( ymin + ymax )) );
    }
  }
 
  /// <summary>
  /// Expand bounding box to contain 
  /// the given new point.
  /// </summary>
  public void ExpandToContain( Point2dInt p )
  {
    if( p.X < xmin ) { xmin = p.X; }
    if( p.Y < ymin ) { ymin = p.Y; }
    if( p.X > xmax ) { xmax = p.X; }
    if( p.Y > ymax ) { ymax = p.Y; }
  }
 
  /// <summary>
  /// Instantiate a new bounding box containing
  /// the given loops.
  /// </summary>
  public JtBoundingBox2dInt( JtLoops loops )
  {
    foreach( JtLoop loop in loops )
    {
      foreach( Point2dInt p in loop )
      {
        ExpandToContain( p );
      }
    }
  }
}

Stay tuned to see how I use this to finally display and verify the extrusion analyser output and my integer-based boundary loop management implementation, coming next.

Overview of Sweep Sample Code and Issue Resolutions

Before closing, here is one last issue that just came up and I would like to mention here as well:

Question: I am trying to create a sweep in a new family using the Revit API, and am having some difficulties.

I found only one single example in the Revit SDK Samples, and can only get it working using your template. When I use my own, it fails.

Where can I find some more information on this, please?

Answer: I discussed some very advanced sweep issues with Bill Adkison, and we published the essence of his results on sweep path tolerance criteria. Normally, sweep issues are nowhere near as hard as the ones he encountered and mastered.

The most recent sample code demonstrating sweep generation was for the sweep family performance enhancement.

Furthermore, the AEC DevBlog discusses a number of sweep creation issues and provides several source code samples to generate them:

• Sweep creation
• Sweep paths and sketch planes
• NewSweptBlend code sample
• NewSweptBlend profile prerequisites

I hope this helps. Good luck!

Sweep Family Performance Enhancement

Now I am back at work again, enjoying the queries coming in from developers, postponing other important things such as my own long-term class and presentation preparations etc. Addicted to helping, that's me.

Anyway, here is a piece of doubly good news, in that the developers mentioned below did a good job of helping themselves, in addition to achieving a radical speed improvement from 40 hours down to 3 minutes, i.e. just 0.125% of the original time, to programmatically generate some Revit families.

Question: The problem was initially reported by Hu Zhao in a recent comment:

I have 80,000 elements to generate, now I use sweep; do you know which is faster of sweep and extrusion? Which can offer a better performance for the computer?

It took 40 hours for the sweep operations.

Is it possible to accelerate this?

In Rhino script, only 10 minutes is enough for this operation.

Hu's colleague and Revit API blogger David Tan clarifies:

Zhao's scenario is to create about 80,000 sweeps in Revit in one shot. Per his test, it will take about 20 hours, while his workmate can achieve it in Rhino within 10 minutes. Zhao expects that Revit could do faster.

As Zhao's test was done in an open family document (with UIDocument), I tried to use in-memory document but it still take about 18 hours to draw all 80K sweeps.

Zhao noticed that although all the drawing work is done in a single transaction, it seems that Revit tries to regenerate the document after there are sweeps created already automatically. We did set the RegenerationOption to be Manual. We say it because we saw Revit progress bar in the bottom-left corner indicates it.

Our questions:

1. Can we prohibit Revit's automatic regeneration?
2. More straightly, do we have any approach to get the job done faster?

Thanks a lot! And Happy Chinese Snake Year!

Answer: There may be a stray regeneration happening in sweep creation.

If you can demonstrate that (with a sample that creates something less than 80,000 sweeps, please :-), please provide a reproducible case for further analysis.

It is also worth asking what the use case is for 80,000 sweeps in one family. Are you possibly modelling things so detailed that that a building model with multiple instances of this will have performance problems?

Maybe you could add an image of what you are creating to motivate the development team by helping them understand.

Response: Here is an image showing what we are trying to achieve:

Each sweep corresponds to a single wooden roof in the image.

Here is also Hu Zhao's source code. We used an in-memory document and added a StopWatch to measure the time consumed.

The source code implements an external command in Program.cs. It will pop up a window and let you select a XML file, which contains creation data of all the sweeps. You can find the XML file along with the .sln file. To make things simple, I only put 2000+ sweeps creation data in the XML file.

Finally I want to share the good news from Hu Zhao. He resolved the performance problem by splitting all sweeps into 24 families and then combining them together. It only takes 3 minutes now. Of course, the cost is the reduced granularity; the model now no longer has individual roofs with embedded family instances. But as he is OK with it, we can say we have found the solution.

Hu added the following more detailed project description:

I am now working in a project plan team for the design of Arch_Tec_Lab in ETH Zürich (youtube link).

The parametric roof is generated in Rhino by my colleague, and the wooden beams will be assembled by robotic arms.

Before I joined this team, they imported the roof (including roof wooden structure) in DWG format, which did not display correctly in some plan and section views. In 3D view, it led to Revit crash because of too many triangle meshes in this imported format.

So I wrote a plugin to import the wooden beams (around 80k) of the roof.

We choose XML to exchange the position information, and I choose sweep instead of extrusion to generate each beam.

For now, the roof structure is divided into 7 parts of XML, which generates 7 families. It took me about 20 hours by using 3 dell precision computers.

Because the roof will be modified several times in the following days, I am now searching for a way to reduce the generation time.

I found that the speed of sweep is slower when the amount increased, and the regeneration that I cannot avoid is especially slow when the amount is above 1500.

Yesterday I found a way to accelerate the generation greatly.

I did like this: divided each 1 part into 24 pieces sections with the mark in XML, then generate each section into single family, and then combine them into a major family. These actions are all made by the plugin.

This is much more quicker.

Let me introduce our project once again.

The Arch_Tec_Lab is a role model project of department of Architecture, ETH Zürich. The team includes most important professors in the Institute of Technology in Architecture. The project aims to realize the BIM control in the life circle. Now we are using Revit to an extremely detail, and we enjoy the cloud rendering in Autodesk 360, except we wish it would also support animation rendering. Now we are working on the construction drawings in Revit.

In Switzerland, few architects use Autodesk products, because of the majority of the MAC users. But we want build a model for the architects and the students in department.

Many thanks to David and Hu for their research and sharing this remarkable performance enhancement!

Addendum: For completeness' sake, here is the slow source code and the complete fast solution. Hu clarifies: the code we posted yesterday is the slow version. The 'slow source code' shows how it works. The 'complete fast solution' is the quicker version.

There are 8 parts to generate. I finished all the work above in 20 hours using 3 computers, and now I can generate the smallest part in 3 minutes. Actually, the bigger part took about 6 hours by the slow method, and now takes about 50 minutes.

The time depends on how many parts I separate. I never test all the 80000 sweeps in one run, maybe it will cost one month ~:D – because the speed runs slower when time goes.

Adjustable Versus Perpendicular Spud

I recently presented an explanation of some Revit MEP family editor part type classes, which led to a follow-up:

Question: Thank you for the detailed answer about the duct fittings. I have a similar problem with one of the pipe fittings, namely spud. I know what a spud is, but not the difference between an adjustable and a perpendicular one.

Can you explain the actual difference, please?

Here is an image with some different spuds that I collected:

Answer: Spuds are analogous to taps in ductwork, which also have adjustable and perpendicular part types.

Their difference is probably best described by example. Here are two smaller branches, both routed from the larger main at 45 degrees:

The adjustable tap on the left adjusted to accommodate the 45-degree route.

The perpendicular tap on the right is constrained to tap perpendicularly off the main. Then, an elbow is automatically inserted after a short duct length to route the branch to the picked point.

Many thanks to Martin Schmid for this explanation.

Create FaceWall on Slanted Mass Face

Happy New Year!

I hope you had a wonderful break and a good start into the New Year.

I spent New Year's Eve with my sons and some friends in a Swiss mountain village. We had a nice hike up and snowboard ride down the neighbouring hill with the Wildhorn in the background:

Now back to work and the Revit API. Here is a question that came up just before Christmas:

Question: I'm trying to create a wall by face on a slanted conceptual mass face. Do you have any example code showing how this might work?

Answer: Here is a simple method that can be run in a project containing one single conceptual mass family instance. It searches the mass for a slanted face whose normal is (-1, 0, 1) and creates a FaceWall instance on that with no problem:

void CreateFaceWall( Document doc )
{
  FilteredElementCollector collector
    = new FilteredElementCollector( doc );
 
  FamilyInstance fi = collector
    .OfClass( typeof( FamilyInstance ) )
    .FirstElement() as FamilyInstance;
 
  XYZ nnorm = new XYZ( -1, 0, 1 ).Normalize();
 
  if( fi != null )
  {
    Options op = new Options();
    op.IncludeNonVisibleObjects = true;
    //op.DetailLevel = DetailLevels.Undefined;
    op.ComputeReferences = true;
 
    GeometryElement ge = fi.get_Geometry( op );
 
    if( ge != null )
    {
      foreach( GeometryObject obj in ge )
      {
        Solid solid = obj as Solid;
 
        if( solid != null && solid.Faces.Size > 0 )
        {
          foreach( Face f in solid.Faces )
          {
            PlanarFace pf = f as PlanarFace;
            if( pf != null )
            {
              XYZ fnorm = pf.Normal.Normalize();
 
              if( fnorm.IsAlmostEqualTo( nnorm ) )
              {
                string log = "";
                bool done = false;
                foreach( WallType t in doc.WallTypes )
                {
                  if( t != null )
                  {
                    ElementId id = t.Id;
                    using( Transaction trans
                      = new Transaction( doc ) )
                    {
                      trans.Start( "Add wall" );
                      try
                      {
                        FaceWall fw = FaceWall
                          .Create( doc, id,
                            WallLocationLine.CoreExterior,
                            f.Reference );
 
                        if( fw != null )
                        {
                          TaskDialog.Show(
                            "Succeeded",
                            "Succeeded" );
 
                          done = true;
                        }
                      }
                      catch( Exception ex )
                      {
                        log += t.Name + ": "
                          + ex.Message + "\r\n";
                      }
                      trans.Commit();
                    }
                    if( done )
                      break;
                  }
                }
                TaskDialog.Show( "Failed", log );
              }
            }
          }
        }
      }
    }
  }
}

Here is the resulting wall:

Inaccessible Location Property

Question: I tried to access the Location property of a FaceWall object.

However, nothing I tried leads to any useful result. In the following code snippet, both theCurve and thePoint remain null:

  Reference r1 = doc.Selection.PickObject(
    ObjectType.Element, "Please pick a wall: " );

  Element e1 = doc.GetElement( r1 );

  FaceWall faceWall = e1 as FaceWall;

  LocationCurve theCurve = faceWall.Location
    as LocationCurve;
    
  LocationPoint thePoint = faceWall.Location
    as LocationPoint;

Answer: Whenever a Revit element location is more complex than a simple point or curve, its Location property will contain more complex internal data (or possibly nothing at all) that currently cannot be represented by the Revit API.

In the case of a FaceWall, it is obvious that no simple point or curve would accurately represent the wall location.

In such cases, another option to determine a location for this kind of object is to analyse its geometry and use the information that provides.

Autodesk OrgOrgChart

For something completely different, here is an interesting graphical representation of the organisational changes Autodesk has been through in the last couple of years.

The OrgOrgChart (Organic Organization Chart) project looks at the evolution of a company structure over time. A snapshot of the Autodesk organizational hierarchy was taken each day between May 2007 and June 2011:

This representation is reminiscent of the Disk Tree visualization technique developed at Xerox Parc (Chi E.H., S.K. Card, 1999, Sensemaking of Evolving Web Sites Using Visualization Spreadsheets, Proceedings of the Symposium on Information Visualization (InfoVis '99), pp. 18-25), showing implicit and explicit affinities among information items and revealing relationships that are difficult to discover in traditional representations. Proximity or connections between items can reveal complex relationships in a comprehensive way, provide visual access to data structures, and enable detection of tendencies or patterns in the process.

Extra Transaction or Regeneration Required

Whenever your add-in modifies the model in any way and you wish to query the Revit database, you need to pay careful attention to ensure that you do not retrieve stale or invalid data.

If anything unexpected whatsoever happens, one of the first things to consider is the possible need for a document regeneration or additional separate transactions between steps.

These kinds of issues arise frequently.

I discussed adding an extra transaction to modify beam parameters and add openings to it and to create an opening in a slab.

Sometimes a simple document regeneration is also sufficient, e.g. to set the width of a newly created TextNote.

Here are two more typical examples:

• Extra transaction required after loading tag
• Extra regeneration required to populate materials

Extra Transaction Required After Loading Tag

Here is an issue raised by Max, Maciej Szlek, who already contributed code to help distinguish MEP fitting shapes:

Question: I have a duct system and want to attach my tag to its elements, using the code to set a tag type. I tried something like this:

  doc.LoadFamilySymbol(
    [my_tag_family.rfa],
    [type_name],
    out tagType);

  IndependentTag tag = doc.Create.NewTag(
    doc.ActiveView,
    element,
    true,
    TagMode.TM_ADDBY_CATEGORY,
    TagOrientation.Horizontal,
    XYZ.Zero);

  tag.ChangeTypeId(tagType.Id);

This code works fine in some projects, whereas in others Revit throws an InvalidOperationException saying that there is no tag available in the call to the NewTag method. The behaviour seems to vary between different projects and on different elements.

How can that be?

Answer: Have you tried either regenerating the document or placing the tag symbol loading and the tag creation calls in separate transaction, committed individually?

Response: Problem solved. As it turns out, the Revit project needs to have some suitable tag type loaded before calling NewTag. Your transaction hint was very helpful. My earlier code was not enough as it stands. It actually requires separate transactions to load the tag type and add a new tag if there was no other tag loaded before. I did not previously know what Revit meant by 'there is no tag available'.

Furthermore, I was initially using automatic transaction mode for this command, thinking that would free me from worrying about any transaction handling myself at all. I now learned that the automatic transaction mode does not enclose each action in a separate transaction, but wraps all executed functions in the whole external command into one single one. In this case, such an approach is not usable at all.

Thank you for a very useful API lesson :))

Answer: Yes, I already mentioned that automatic transaction mode is unofficially deprecated, and manual mode is recommended for all cases nowadays. Automatic transaction mode is considered obsolete.

Arnošt Löbel's AU class on Core Frameworks in the Revit API provides more details on this topic.

Many thanks to Max for raising this issue and verifying that the solution works!

Extra Regeneration Required to Populate Materials

One of the issues we took a look at during the DevLab at AU last Tuesday was the list of materials attached to a newly duplicated symbol.

At first glance, it appeared that a duplicated family symbol had zero entries in its list of materials, whereas the original symbols material list was correctly populated.

On further exploration, we discovered that this is another case of retrieving stale data after a model modification.

The behaviour is easily rectified by a call to regenerate the model after the symbol duplication.

Here is the final implementation of the external command implementing to test the issue. It expects a structural steel column to be pre-selected, which is a family instance whose associated symbol has exactly one entry in its materials list. We duplicate the symbol. This requires defining a new name. To simplify repeated testing, we generate a new name by simply appending the clock tick counter to the original one. Directly after the call to Duplicate, the new symbol's material list has zero entries, which makes no sense for this kind of symbol. A call to Regenerate fixes that:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
    Selection sel = uidoc.Selection;
    FamilyInstance inst = null;
 
    if( 1 == sel.Elements.Size )
    {
      foreach( Element e in sel.Elements )
      {
        inst = e as FamilyInstance;
 
        break;
      }
    }
 
    if( null == inst )
    {
      message = "Please select one "
        + "single structural column";
 
      return Result.Failed;
    }
 
    using( Transaction tx 
      = new Transaction( doc ) )
    {
      tx.Start( "Duplicate Symbol" );
 
      FamilySymbol symbol = inst.Symbol;
 
      string name = symbol.Name 
        + DateTime.Now.Ticks.ToString();
 
      int nMaterialsBefore 
        = symbol.Materials.Size;
 
      symbol = inst.Symbol.Duplicate( name ) 
        as FamilySymbol;
 
      // The model is in a temporary state that does 
      // not make sense. Regenerate to clean this up.
 
      int nMaterialsAfter 
        = symbol.Materials.Size;
 
      doc.Regenerate();
 
      nMaterialsAfter = symbol.Materials.Size;
 
      Debug.Assert( 
        nMaterialsAfter.Equals( nMaterialsBefore ),
        "why does the material get lost, please?" );
 
      tx.Commit();
    }
    return Result.Succeeded;
  }
}

For completeness' sake, here is DuplicatedSymbolLosesMaterial.zip containing the complete source code, Visual Studio solution and add-in manifest of this little test command.

AU Classes on the View, MEP and Link APIs

Wednesday was my first normal and full AU day, after completing the developer conference and DevLab activities. I was able to attend two interesting classes held by Revit API developers Steven Mycynek and Arnošt Löbel, and present my own Revit MEP API one. Here they are in chronological order:

• CP3133 Using the Revit Schedule and View APIs by Steven Mycynek
• CP4108 Revit MEP Programming: All Systems Go by Jeremy Tammik
• CP3455 Managing Revit Links with the Revit API by Arnošt Löbel

I am including the class materials below, both for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

Schedule and View APIs

Revit 2013 includes a major expansion of the Schedule and View APIs. This class introduces the API for Schedule and Elevation views as well as many methods and properties that apply to all views. Learn how to create and modify these views to help document and display your Revit model.

• Handout
• Presentation
• Sample code
• Sample models

This class should really resolve all those recurring questions associated with the creation of different views once and for all! Take a special deep look at Steve's multitude of useful utility classes in the sample code.

Revit MEP Programming

This class shows how to work programmatically with Revit MEP models. It provides an overview of the entire Revit MEP API with specific focus on the major enhancements in Revit 2013. The most important 2013 feature is the routing preference functionality. An overview of the available samples is provided. All MEP domains including HVAC, electrical, and plumbing are addressed. It shows how to analyse existing systems and create new MEP models from scratch; covers mechanical and electrical system traversal; display of system hierarchies in a tree view; components such as circuits, ducts, pipes, fittings, connectors, cable trays, and conduits; and automatic calculation and sizing based on room and space requirements.

• Handout
• Presentation
• Sample code

Managing Revit Links

This class explains common pitfalls working with links and how to avoid them. It details the creation of Revit link types and instances, and recommends how to easily check or modify the parameters of links. Material describing ways to inquire for data about the various types of external files, including Revit links, is included. It concludes with an overview of a larger Revit link API application – the eTransmit add-in, which enables users to move an entire package of Revit files while maintaining relationships with all linked files.

• Presentation
• Sample code and models

Implementing a BIM Business Transformation

Unrelated to any direct programming topic, here is a white paper on implementing a BIM business transformation that is of interest to visionaries and decision makers and neatly complements the recently released BIM for Infrastructure one.

Display a Geometry Debugging Point in the Model

Here are some pointers from a conversation I had with Daren Thomas on how to display a reference point in the model for debugging purposes that may be on general interest.

Question: I am playing around with the FindReferencesWithContextByDirection method and would like to display the references found as coloured blobs or something in the model.

How can I achieve this, please?

This question could also be simplified into: how to create an easily visible dot at a 3D point in the model?

Can such a "dot" exist on its own or must it be drawn onto a face? How?

I never really got into actually creating geometry in Revit.

Answer by Daren: I figured it out on my own now:

I can create a SketchPlane and draw a ModelCurve on it.

Given two points a and b, this RevitPythonShell code will create a green line between them in the 3D view:

  transaction = Transaction(doc)
  transaction.Start('draw a line')
  c = XYZ(0, 0, 0)
  v0 = XYZ(a.X - b.X, a.Y - b.Y, a.Z - b.Z)
  v1 = XYZ(a.X - c.X, a.Y - c.Y, a.Z - c.Z)
  plane = Plane(v0.CrossProduct(v1), a)
  sketchPlane = doc.Create.NewSketchPlane(plane)
  line = doc.Application.Create.NewLineBound(a, b)
  doc.Create.NewModelCurve(line, sketchPlane)
  transaction.Commit()

Answer by Jeremy: Yes, model lines is probably the simplest way to go.

You need model curves in 3D, and can use detail curves in a 2D view.

The Creator class included in The Building Code samples includes several usage examples implemented in C#. It was used to graphically highlight geometry in numerous previous posts, and last updated to display the boundaries of a slab.

All it does is package what you describe above nicely, though.

For more complex geometry and transient display, you can also use the analysis visualisation framework AVF. It could be used to draw a full 3D sphere as a marker, if you prefer, as I showed when displaying Apollonian spheres using AVF.

Sweep PickPath Tolerance Criteria

Here is a rather specialised and hitherto undocumented topic of great importance to anyone trying to model precise complex swept geometry.

The issues below arose exploring the tolerance requirements of the 'Pick Path' options in the Revit UI, which map to the ReferenceArray and Reference input to the two FamilyItemFactory API calls for generating this kind of geometry:

Sweep NewSweep(
  bool isSolid,
  ReferenceArray path,
  SweepProfile profile,
  int profileLocationCurveIndex,
  ProfilePlaneLocation profilePlaneLocation );

SweptBlend NewSweptBlend(
  bool isSolid,
  Reference path,
  SweepProfile bottomProfile,
  SweepProfile topProfile );

It required quite a bit of research to resolve, both by the Revit development team and most of all by Bill Adkison of MarinCAD Custom Software Engineering, who is using this to create detailed furniture families like this:

Bill ran into a number of issues creating these very precise and detailed sweeps.

Here is an example of some of the ensuing discussions and results:

Question: I have problems with sweeps created via PickPath.

I am creating many successful pickpath sweeps. However, in some cases, pickpath sweeps are failing with a MemoryAccessViolation.

One example has two model lines which can each be selected to create a PickPath sweep, but when both are selected together, the sweep fails. I have confirmed that their endpoints meet up. One curve is a Hermite spline, the other a line. When I convert the spline to a set of line segments connecting the fit points, it works. What is the problem with connecting these two curves into a common sweep pattern? They fail interactively as well as via API. This is still basically a programming problem, because I need to know the criteria for when attaching splines and arcs will work. In another case of failure, a model line and a model arc of short radius: 0.34 inches, and included arc of .61 radians, so the ultimate arc length is .224 inches, well above the 1/32" Revit precision threshold. You can sweep these curves independently, but they do not sweep when picked together. In the debugger, their endpoints line up.

Answer: There is a small gap between the line and arc in the model that causes the problems for that sweep path. Such gaps should be avoided.

Other conditions to watch out for are curves that are nearly tangent, but not quite tangent, or arcs with very large radii that are nearly indistinguishable from lines.

Here are some internal observations which may help give an idea of what is going on:

1. CollectPath3dCurveGRefs complains about the gap between the line and arc in the model. The gap has size about 9.8e-6, but that function uses DOUBLE_EPS (= 1.0e-9) as a point-to-point tolerance. It issues a DBG_WARN but returns ERR_SUCCESS when it finds a gap.

The unit tangents of the line and arc at the point where they (nearly) meet differ by about 0.002 in the z-coordinate (and somewhat less than that in the y-coordinate). Apparently, Revit can bridge huge angles in lines, while being rather intolerant of even small angles in other areas.

CreateSweptSolid calls fixGapsInSweepPath, which calls trimCurvesToNbrs, but the latter function uses sqrt(0.1)*DOUBLE_EPS as a point-to-point tolerance, so it considers the gap to need "repair". It attempts to intersect the line and the arc, but that ultimately calls circXLine2d, which uses DOUBLE_EPS as a tolerance, so that function does not find an intersection. TrimCurvesToNbrs therefore does not modify the path (i.e., it does not "fix" the gap). It does check that the result is continuous to within a certain tolerance, but it uses the vertex tolerance for that check, and this gap is smaller than the vertex tolerance (which is about 0.0005).

CreateSweptSolid ultimately fails because getCornerTurningTrf fails when finding the corner-turning transform from the line to the arc, because vecAlmostEqual(cornerPnt1, cornerPnt2) is false. This essentially uses DOUBLE_EPS as a point-to-point tolerance. I confirmed that avoiding that rejection in the debugger allows the swept solid to be constructed successfully. Nevertheless, such gap and lack of tangency should be avoided whenever possible.

2. In the model, the line and the Hermite spline are not accurately tangent. Their tangent vectors at the point where the curves meet differ by about 0.01 in one of the coordinates; they meet at an angle of about 0.017 radians (= 1.02 degrees). While computing the mitre surface between the line and the spline, getMiterCurve then calls pathSegsAreNearlyTangent, but that uses a tolerance of one degree, so this case doesn't even meet the criterion for being nearly tangent. getMiterCurve then fails at the check for parallel normVec = (0.49, -0.85, 0.13) and planeNorm = (-0.86, -0.5, 0.0) (approximately).

PlaneNorm is the normal vector of the plane of the sweep path, as computed by getMiterCurve, while normVec was passed down from createSweepAlongCurve, where it was computed by a call to getRadii, which gets it directly from the sweep frame passed to createSweptSolid.

3. Please make the line accurately tangent to the spline in the example. They meet at an angle slightly greater than one degree.

Of course, making the line accurately tangent to the spline is a difficult numerical problem, and will involve modifying both curves, which are in different planes, which will also have to be modified. Alternatively, one could recognize the situation and either break the sweep, or go back to all line segments.

4. Please make analytic computations (i.e., those involving lines, arcs, planes, and other simple curves or surfaces as accurate as possible for double-precision floating-point computations. In such cases, values that would ideally be equal should be considerably less than 1.0e-9. In general, Revit expects points that are ideally coincident to have a distance considerably less than about 1/160". In some cases, though, Revit code demands a tighter tolerance. Curves that are ideally tangent should have an angle at most 0.1 degrees.

The failure to create a sweep for the line/spline path in the sample with a circular profile of radius about 0.4329 might be fixed by making the line tangent to the spline.

5. There seem to be a number of hardcoded almost vertical and almost unit vectors in your code.

Revit definitely does not like slightly off-axis lines and planes.

It will certainly help stability if you can replace all vectors like the following one by the almost identical ones aligned with the cardinal axes:

  XYZ normalizedMajorAxis 
    = new XYZ( 1.0,
      -0.00000000000024924835886401896,
      0.0000000000000012680828609390458 );

Specifying very slightly off-axis data is just asking for trouble. Do you really need to model anything that absolutely has to be so slightly off-axis? Is rounding an option for the input data you provide? This is not hard, once you are aware of the issue.

Response: 1. Details such as the point-to-point tolerance is exactly the kind of information I am looking for.

The gap in my data is a somewhat bigger than I expected, so I will write code to re-close them after my Revit computations are finished.

Does the fact that the tangents differ by this amount matter, i.e. cause the failure? Sweep handles 90-degree corners for line segments. Do non-lines have to have matching tangents? If so, that is great to know, as well as utterly unobvious. I can take evasive action if the tangents must match.

What is 'the vertex tolerance' exactly, in contrast to 'point to point'? For use by sweeps or path validation after the basic point to point? Is it used for Angles? Should I just be concerned with the DOUBLE_EPS distance for this problem?

2. So you require tangency for connecting PickPath segments that aren't lines? That is good to know. As noted earlier, because PickPath works with corners between lines, I assumed there was no tangent requirement for connecting elements, nor did I see any in the documentation. So to clarify the rules: must connecting PickPath elements have shared tangents at their connection point, UNLESS they are bound line segments? Here is the current list of possibilities:

• Line – Line: no tangency requirements.
• Line – Spline: tangency required.
• Line – Arc: tangent required or no?
• Spline – Arc: ?
• Spline – Spline: ?
• Spline – Arc: ?

If tangency requirements are a problem, I will correct them if possible, or revert to line segments.

I updated my logic to detect gaps and tangential inequality at connection points of multi-curve PickPaths, leading to the key logic summarised in the following code:

  /// <summary>
  /// Revit angle tolerance: 1 degree
  /// has been shown to be stable.
  /// </summary>
  const double kRevitAngleTolerance = Math.PI / 180.0;
 
  XYZ curCurveStartPt = null; // from current curve
  XYZ prevCurveEndPt = null; // from previous curve or null
  XYZ shiftVector = null;
 
  // Use DOUBLE_EPS tolerance in IsAlmostEqualTo 
  // for legitimate endpoint proximity.
 
  bool shiftCurve = ( prevCurveEndPt != null ) 
    && !curCurveStartPt.IsAlmostEqualTo( 
      prevCurveEndPt );
 
  if( shiftCurve )
  {
    // This case very rarely triggers.
 
    shiftVector = curCurveStartPt.Subtract( 
      prevCurveEndPt );
  }
 
  XYZ nextCurveStartTan = null; // from next curve or null
  bool nextCurveIsLine = null; // from next curve, if any
 
  XYZ curCurveEndTan = null; // from current curve
  bool curCurveIsLine = null; // from current curve
 
  double epsTanAngle = nextCurveStartTan.AngleTo( 
    curCurveEndTan );
 
  // Use cited tolerance of 1 degree between 
  // connecting endpoint tangent vectors. 
  // I actually experimented with up to 5 degrees, 
  // and although I observed cases of tangent 
  // differences of at least 2.6 degrees to
  // successfully sweep, sometimes it works and 
  // sometimes it excepts.
  // 1 degree has held up well so far; 
  // I have no known failures with it.
  // But the result is annoying notches in Revit 
  // in places where AutoCAD sweeps can handle 
  // the same curves automatically.
 
  bool writeSweepNow = false;
 
  if( ( nextCurveStartTan != null )
    // connecting lines have unequal 
    // tangents but work in Revit.
    && ( !curCurveIsLine || !nextCurveIsLine ) 
    && ( epsTanAngle > kRevitAngleTolerance ) )
  {
    // Break off sweep and start a new one;
    // when tangent angles exceed this, 
    // the sweep can except.
 
    // Final code to tweak current curve tangents 
    // would go here; this is a big project in itself.
 
    writeSweepNow = true;
  }
 
  // if (shiftCurve)
 
  // Current curve is re-read, with shift in 
  // location set in shiftVector.
  // Append current curve to model and record its 
  // references in current curve reference array.
 
  // if (writeSweepNow)
 
  // Sweep is written with current curve, and new 
  // Sweep begins with the next curve.
  // Loop until all curves are accumulated, 
  // then write final sweep.

This eliminates all the failures due to connecting multiple curves in PickPath sweep creation.

MEP Calculations

A second question was raised on another rather specialised calculation topic:

Question: Can you point to any documents describing the Revit MEP calculation methodology?

Answer: The MEP calculations are described in the Revit WikiHelp Reference.

You can also look at Martin Schmid's Autodesk University 2010 classes ME330-3 Calculations in Revit MEP, primarily focused on duct and pipe, and ME231-2 Categorically, Demand It on Your Schedule: You Con-Du-It in Revit MEP, with a focus on electrical calculation. The former includes a video recording.

The Hub Class

Saikat Bhattacharya published an article taking a look at the Revit API Hub class, never before mentioned here. It lives in the Autodesk.Revit.DB.Structure namespace and is derived from the base Element class. It represents a connection between two or more Revit Elements, avoiding the need to connect them with each other directly. They each refer to the hub, which manages all the connectivity information for them. Its interface is pretty minimal; the only members not inherited from Element appear to be:

• GetHubConnectorManager to retrieve the hub ConnectorManager.
• HasOrigin to indicate whether the hub has a specific location in 3D space.
• GetOrigin to retrieve the hub 3D position, if it has one.

Saikat presents a sample code snippet showing how to access the elements connected to a given hub.

Leaving the Unshaved

I shaved again, after a couple of weeks of abstinence. Here is a last parting shot before leaving the unshaved masses, and afterwards:

Note the prow of a boat sticking out of the wall in the left-hand picture... special bonus points for anyone who can tell where this photo was taken :-)

Create Dimension between Two Lines

Another one of those recurring questions: how to create dimensioning.

I took the opportunity to highlight how to search the samples, find a solution, and apply a correction to RevitLookup yourself.

You have the code.

May the Force be with you.

Question: I tried to create detail drawings programmatically using the ItemFactoryBase NewDimension method.

I am creating detail lines in the drafting view based the on the geometry wall elements and would like to use Revit dimensioning to insert measurements into the detail drawings.

How do I obtain the reference for the detail lines of a drafting view to be able to call the NewDimension method?

I am sure that this is possible, since I can create dimension lines in a drafting view using the dimension line commands on the Annotate ribbon.

Answer: Whenever you are faced with a question like this, please always begin by studying the three main official sources of information:

• The Revit API help file RevitAPI.chm.
• The online wikihelp Revit API Developer's Guide.
• The Revit SDK sample source code.

Normally, when researching an issue like this myself, I perform a global search across the entire project in the SDKSamples2013.sln solution.

This time, happily, I extended it to the entire samples directory instead, including RevitLookup. To tell the truth, I even searched my whole hard disk for all C# files containing NewDimension, because there were not that many in total.

This turned up the following hits in the Revit SDK folder (copy and paste to an editor to see the truncated lines):

C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1255):               //        m_revitApp.ActiveUIDocument.Document.Create.NewDimension(dimension.View, line, dimension.References, dimension.DimensionType);
C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1470):            m_revitApp.ActiveUIDocument.Document.Create.NewDimension(m_revitApp.ActiveUIDocument.Document.ActiveView,
C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1475):            m_revitApp.ActiveUIDocument.Document.FamilyCreate.NewDimension(m_revitApp.ActiveUIDocument.Document.ActiveView,
C:\...\SDK\RevitLookup\CS\Utils\Elements.cs(272):            Dimension dimensionClone = app.ActiveUIDocument.Document.Create.NewDimension(dimension.View, line, dimension.References);
C:\...\SDK\Samples\CreateDimensions\CS\Command.cs(213):                    Dimension newDimension = doc.Create.NewDimension(
C:\...\SDK\Samples\CreateDimensions\CS\Command1.cs(219):                    Dimension newDimension = doc.Create.NewDimension(
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(31):    /// The class allows users to create dimension using Document.FamilyCreate.NewDimension() function
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(91):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(125):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(160):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);

The very first of those, in the RevitLookup test framework, looks like it should answer your question right away:

  XYZ location1 = GeomUtils.kOrigin;
  XYZ location2 = new XYZ( 20.0, 0.0, 0.0 );
  XYZ location3 = new XYZ( 0.0, 20.0, 0.0 );
  XYZ location4 = new XYZ( 20.0, 20.0, 0.0 );
 
  Curve curve1 = m_revitApp.Application.Create
    .NewLine( location1, location2, true );
 
  Curve curve2 = m_revitApp.Application.Create
    .NewLine( location3, location4, true );
 
  DetailCurve dCurve1 = null;
  DetailCurve dCurve2 = null;
 
  if( !doc.IsFamilyDocument )
  {
    dCurve1 = doc.Create.NewDetailCurve(
      doc.ActiveView, curve1 );
 
    dCurve2 = doc.Create.NewDetailCurve(
      doc.ActiveView, curve2 );
  }
  else
  {
    if( null != doc.OwnerFamily
      && null != doc.OwnerFamily.FamilyCategory )
    {
      if( !doc.OwnerFamily.FamilyCategory.Name
        .Contains( "Detail" ) )
      {
        MessageBox.Show(
          "Please make sure you open a detail based family template.",
          "RevitLookup", MessageBoxButtons.OK,
          MessageBoxIcon.Information );
 
        return;
      }
    }
    dCurve1 = doc.FamilyCreate.NewDetailCurve(
      doc.ActiveView, curve1 );
 
    dCurve2 = doc.FamilyCreate.NewDetailCurve(
      doc.ActiveView, curve2 );
  }
 
  Line line = m_revitApp.Application.Create.NewLine(
    location2, location4, true );
 
  ReferenceArray refArray = new ReferenceArray();
 
  refArray.Append( dCurve1.GeometryCurve.Reference );
  refArray.Append( dCurve2.GeometryCurve.Reference );
 
  if( !doc.IsFamilyDocument )
  {
    doc.Create.NewDimension( 
      doc.ActiveView, line, refArray );
  }
  else
  {
    doc.FamilyCreate.NewDimension( 
      doc.ActiveView, line, refArray );
  }

I tried running this sample command by selecting the ribbon tab Add-Ins > Revit Lookup > Test Framework... > Object Hierarchy > APIObject > Element > Dimension > OK.

That calls the DimensionHardWired method to do the job.

Unfortunately, it throws an exception saying "Attempt to modify the model outside of transaction".

I fixed it by adding the following lines right at the beginning of the method:

  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "DimensionHardWired" );

Obviously, I need to commit the transaction and close the using statement at the end again:

    tx.Commit();
  }

Now is successfully completes with the following result:

You can also look at two The Building Coder samples creating wall dimensioning, either by iterating over the wall faces to pick the two suitable ones, or using FindReferencesByDirection to shoot a ray and find them directly.

They both retrieve the geometry references from the wall faces, and not from a simple detail line, though.

All together, this should provide more than enough to solve your issue.

Accessing the Path of a Family Document from the Family Instance

Before closing, here is pointer to a cool discovery by Saikat Bhattacharya: if you try to find the family document of a family instance and go through the path family instance > family symbol > family > document, you end up at the document containing the family instance. If you are actually after the family document defining the instance, you need to go through the EditFamily method instead. More details on accessing the path of a family document from an instance.

DivideParts in F# and Line Styles

My internet connection died last night. After worrying and testing quite a bit last night and this morning, I laid a temporary cable from my neighbour's router. Shortly after I finished, my own connection came back up again, after about 14 hours downtime. Murphy's law remains valid, as always. Very reassuring :-) There is lots of building work going on nearby, so probably they broke it and fixed it with no explanations given. Anyway, I am back to normal now and keeping my fingers crossed.

Last week, I presented a C# sample by Piotr Zurek of CADPRO Systems Ltd exercising the PartUtils class and its DivideParts method.

As an experiment and for comparison purposes, Piotr decided to port this to F# as well. In his own words:

As an exercise, I decided to port this example to F# to see how it works and whether the F# syntax offers any benefits over C#.

Lessons Learned

Here are some of the lessons learned:

Let Not Use

Initially, the F# version of the command ran fine only the first time I launched it, and failed in the call to PickObject with an InvalidOperationException saying "The managed object is not valid" on the second call.

After isolating the call to PickObject, I changed the following four initialisation statements:

  use uiApp = commandData.Application
  use app  = uiApp.Application
  use uiDoc = uiApp.ActiveUIDocument
  use doc  = uiDoc.Document

It turns out that this is wrong, since the F# 'use' statement is just like 'using' in C#.

So when these objects fall out of scope, Dispose will be called on them. Since they belong to Revit, they don't like being disposed of by external code. Changing 'use' to 'let' fixed that problem:

  let uiApp = commandData.Application
  let app  = uiApp.Application
  let uiDoc = uiApp.ActiveUIDocument
  let doc  = uiDoc.Document

Thanks to Kean Walmsley for this explanation.

Pattern Matching Versus :?

At one point, I made a little bit of use of F# pattern matching to implement the WallSelectionFilter AllowElement method like this:

      member x.AllowElement(element) =
        match element with
        | :? Wall as element -> true
        | _ -> false

However, on further consideration, it is clearer and more succinct to use the F# ':?' operator, which is an equivalent of 'is' in C#, like this:

type WallSelectionFilter() =
  class
    interface ISelectionFilter with
      member x.AllowElement(element) = element :? Wall
      member x.AllowReference(reference, xyz) = false
  end

Implementing an Exception Handler

I initially removed the 'try-catch' exception handler around the call to PickObject to handle a user cancelling the pick operation. On consideration, I found that it translates to 'try-with' in F#. The piping symbol '|' means pretty much 'data received from the last operation':

  let reference = 
    try
      sel.PickObject(
        ObjectType.Element, 
        new WallSelectionFilter(), 
        "Select a wall to split into panels")
    with
      | :? Autodesk.Revit.Exceptions.
        OperationCanceledException -> null

Exiting the mainline execution requires an if-else statement as well: if reference is null, return Result.Canceled. The best solution is probably more functional, though.

Final Implementation

Here is the final complete F# implementation of this external command:

namespace FSharpPanelBuilder
 
open System
open System.Collections.Generic
 
open Autodesk.Revit
open Autodesk.Revit.UI
open Autodesk.Revit.Attributes
open Autodesk.Revit.DB
open Autodesk.Revit.UI.Selection
 
type WallSelectionFilter() =
  class
    interface ISelectionFilter with
      member x.AllowElement(element) = element :? Wall
      member x.AllowReference(reference, xyz) = false
  end
 
[<Transaction(TransactionMode.Manual)>]
type Command() =
  class
    interface IExternalCommand with
      member this.Execute(commandData, 
                          message : string byref, 
                          elements ) =
 
        try
          let uiApp = commandData.Application
          let app  = uiApp.Application
          let uiDoc = uiApp.ActiveUIDocument
          let doc  = uiDoc.Document
          let sel = uiDoc.Selection
 
          let reference = 
            try
              sel.PickObject(
                ObjectType.Element, 
                new WallSelectionFilter(), 
                "Select a wall to split into panels")
            with
              | :? Autodesk.Revit.Exceptions.
                OperationCanceledException -> null
 
          if reference = null then
            TaskDialog.Show(
              "F# Panel Builder", 
              "Operation was canceled") |> ignore
            Autodesk.Revit.UI.Result.Cancelled
          else
            let wall = 
              doc.GetElement(reference.ElementId) :?> Wall
 
            let locationCurve = 
              wall.Location :?> LocationCurve
 
            let line = locationCurve.Curve :?> Line
 
            use transaction = new Transaction(doc)
 
            let status = transaction.Start("Building panels")
 
            let wallList = new List<ElementId>(1)
            wallList.Add(reference.ElementId)
 
            PartUtils.CreateParts(doc, wallList)
            doc.Regenerate()
 
            let parts = 
              PartUtils.GetAssociatedParts(
                doc, wall.Id, false, false)
 
            let divisions = 15
            let origin = line.Origin
 
            let delta = 
              line.Direction.Multiply(
                line.Length / (float)divisions)
 
            let shiftDelta = 
              Transform.get_Translation(delta)
 
            let rotation = 
              Transform.get_Rotation(
                origin, XYZ.BasisZ, 0.5 * Math.PI)
 
            let wallWidthVector = 
              rotation.OfVector(
                line.Direction.Multiply(2. * wall.Width))
 
            let mutable intersectionLine = 
              app.Create.NewLineBound(
                origin + wallWidthVector, 
                origin - wallWidthVector)
 
            let curveArray = new List<Curve>()
 
            for i = 1 to divisions do
              intersectionLine <- 
                intersectionLine.get_Transformed(
                  shiftDelta) :?> Line
 
              curveArray.Add(intersectionLine)
 
            let divisionSketchPlane = 
              doc.Create.NewSketchPlane(
                new Plane(XYZ.BasisZ, line.Origin))
 
            let intersectionElementsIds = 
              new List<ElementId>()
 
            let partMaker = 
              PartUtils.DivideParts(
                doc, parts, intersectionElementsIds, 
                curveArray, divisionSketchPlane.Id)
 
            doc.ActiveView.PartsVisibility <- 
              PartsVisibility.ShowPartsOnly
 
            transaction.Commit() |> ignore
 
            Result.Succeeded
 
        with ex ->
          TaskDialog.Show(
            "F# Panel Builder", 
            ex.Message) |> ignore
 
          Result.Failed
 
  end

The code is a straight translation from C# into F#, almost without making any use of F# specific concepts.

Later on, it would be nice to rewrite it to be a bit more functional.

I really like how expressive and concise F# is, but switching between F# and C# causes me horrible headaches. :-)

Git and GitHub Source Code Management

I placed the entire project on GitHub:

• https://github.com/pzurek/FSharpPanelBuilder.

GitHub a source code collaboration platform based on the version control system git, a fast, efficient, distributed system for collaborative software development. It enables you to easily fork, send pull requests and manage all your public and private git repositories.

I love it. Here at CADPRO I don't get too much chance to use it collaboratively, since I am usually the only person working on a project.

When playing with open source projects, that's another story and git is a brilliant tool for it. Some people claim that is it hard and too complicated, but for me that was the first distributed source control system I used and I didn't find it too hard to grasp.

The thing that makes Git amazing is GitHub. They just put a nice desktop and web interface on it and make it nice and easy to use.

Besides looking at the main project page, you can download the whole project as a zip file.

GitHub also provides a little tool that help with publishing source code on the Internet. Gist.github.com allows you to create snippets of code and then embed them in other websites.

As an example, I pasted the command.fs file from the F# sample.

Many thanks to Piotr for all this information, research and comparison!

Retrieving Line Styles

Mikako Harada published sample code showing how to retrieve all line styles through the CurveElement GetLineStyleIds property.

If you don't have a curve element handy to invoke the property on, you can simply create a temporary one, for instance a detail line in the currently active view. Created in a separate transaction which is rolled back afterwards, it enables access to the line styles with no effect on the database.

Parts, Assemblies, PartUtils and DivideParts

Let's end this eventful week with another big and imporant topic that we've neglected for much too long.

So far, I presented just one single example of using the PartUtils class, and other information provided on it by a Google search is also awfully scarce.

Piotr Zurek of CADPRO Systems Ltd improved the situation by raising and promptly answering the following question:

Question: I wonder whether you have any sample code showing how to use the PartUtils.DivideParts method.

I'm trying hard to work it out but the documentation is pretty scarce on the topic.

Answer: I published a sample of using the PartUtils class demonstrating how to retrieve detailed wall layer geometry.

It exercises the CreateParts method, however, and not DivideParts, unfortunately.

Response: Seems like I cracked it. Attached a small working example. I'm just starting to play with the geometry related parts of the API, so this example is probably a bit clumsy :-)

Answer: I cleaned up your code a bit and tested it on the following simple wall:

I simply run your sample command 'Divide Parts' and select the wall. I then display parts instead of original elements by setting the 'Parts Visibility' view property to 'Show Parts', et voila:

The wall is split into parts two ways, both by the CreateParts method, which separates the individual layers of the compound structure, and by DivideParts, which cuts each layer into divisions using the specified cutting curves or planes:

I also appended the handout document from Harry Mattison and Enrique Galicia's class CP5211 – Construction Modelling and API for Builders at Autodesk University 2011, which explains the usage a bit more and is reproduced in full below.

Response: Yes, that really provides a nice explanation of the whole topic.

I fixed some issues that you pointed out, and here is some further explanation:

For every division point I create a line, collinear with the wall going from a point 2 wall width in front of the division point to 2 wall widths after the division point.

Then I rotate those lines by 90 degrees to create curves perpendicular to the wall – those curves will be used to define the cutting lines (if I understand correctly).

Then based on endpoints of those curves I define reference planes used to divide the wall. Through my tests I have determined that it is not enough if the intersection curve is just 2*wall width.

It must have something to do with going beyond the extents of the dashed outline visible during manual editing of the division sketch. I don't know exactly what it has to be but 4*wall width works fine – the dashed outline seems to be just a bit more than twice the wall width.

This seems to work, but that was just trial and error.

Initially, I couldn't see my parts after the command completed. That was easily solved by setting the parts visibility in the view by adding:

  doc.ActiveView.PartsVisibility 
    = PartsVisibility.ShowPartsOnly;

My impression is that I have to use calls to both CreateParts and DivideParts for this to work, just like in the user interface: first you click 'Create Parts', then the 'Divide Parts' button is enabled. If I don't call CreateParts first, the call to PartUtils.ArePartsValidForDivide returns false.

Initially, I was using two lists of 'cutting definitions', providing intersectingReferenceIds and the curveArray. Harry's AU materials make it clear that one of these can be empty. This very important detail is never mentioned anywhere in the API docs. Understanding that allowed me to clean up the code and get rid of all the lines having to do with reference planes that I was initially using.

Answer: Great job! I cleaned it up yet a little bit more, e.g. by adding an exception handler in case the user cancels the wall selection. I moved the selection and type checking out of the transaction and reordered the later statements.

I modified the definition of the wall width vector. It initially confused me that its direction followed the wall length instead of the width, and that you re-rotated it each time you translated it.

I simplified the geometrical manipulations a bit and changed the wall width vector to be perpendicular to the wall right from the start. The curveArray definition is significantly simplified, and I hope the geometrical manipulation is self-explanatory now.

Here is the final version of Piotr's 'Divide Parts' external command Execute method implementation:

  try
  {
    if( null == commandData )
    {
      throw new ArgumentNullException( "commandData" );
    }
 
    UIApplication uiapp = commandData.Application;
    Application app = uiapp.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    Reference r = null;
 
    try
    {
      r = uidoc.Selection.PickObject(
        ObjectType.Element,
        new WallSelectionFilter(),
        "Select a wall to split into panels" );
    }
    catch( Autodesk.Revit.Exceptions
      .OperationCanceledException )
    {
      return Result.Cancelled;
    }
 
    Wall wall = ( r == null || r.ElementId
        == ElementId.InvalidElementId )
      ? null
      : doc.GetElement( r.ElementId ) as Wall;
 
    if( wall == null )
    {
      message = "Unable to retrieve wall.";
      return Result.Failed;
    }
 
    LocationCurve location
      = wall.Location as LocationCurve;
 
    if( null == location )
    {
      message = "Unable to retrieve wall location curve.";
      return Result.Failed;
    }
 
    Line line = location.Curve as Line;
 
    if( null == location )
    {
      message = "Unable to retrieve wall location line.";
      return Result.Failed;
    }
 
    using( Transaction transaction = new Transaction( doc ) )
    {
      transaction.Start( "Building panels" );
 
      IList<ElementId> wallList = new List<ElementId>( 1 );
 
      wallList.Add( r.ElementId );
 
      if( PartUtils.AreElementsValidForCreateParts( 
        doc, wallList ) )
      {
        PartUtils.CreateParts( doc, wallList );
 
        doc.Regenerate();
 
        ICollection<ElementId> parts 
          = PartUtils.GetAssociatedParts( 
            doc, wall.Id, false, false );
 
        if( PartUtils.ArePartsValidForDivide( 
          doc, parts ) )
        {
          int divisions = 5;
 
          XYZ origin = line.Origin;
 
          XYZ delta = line.Direction.Multiply(
            line.Length / divisions );
 
          Transform shiftDelta
            = Transform.get_Translation( delta );
 
          // Construct a 90 degree rotation in the 
          // XY plane around the line start point
 
          Transform rotation = Transform.get_Rotation(
            origin, XYZ.BasisZ, 0.5 * Math.PI );
 
          // A vector perpendicular to the wall with
          // length equal to twice the wall witdh
 
          XYZ wallWidthVector = rotation.OfVector(
            line.Direction.Multiply( 2 * wall.Width ) );
 
          Curve intersectionLine
            = app.Create.NewLineBound( // Line.CreateBound
              origin + wallWidthVector,
              origin - wallWidthVector );
 
          IList<Curve> curveArray = new List<Curve>();
 
          for( int i = 1; i < divisions; ++i )
          {
            intersectionLine = intersectionLine
              .get_Transformed( shiftDelta );
 
            curveArray.Add( intersectionLine );
          }
 
          SketchPlane divisionSketchPlane
            = doc.Create.NewSketchPlane(
              app.Create.NewPlane(
                XYZ.BasisZ, line.Origin ) );
 
          // An empty list of intersecting ElementIds
 
          IList<ElementId> intersectionElementIds
            = new List<ElementId>();
 
          PartUtils.DivideParts( doc, parts, 
            intersectionElementIds, curveArray, 
            divisionSketchPlane.Id );
        }
        doc.ActiveView.PartsVisibility 
          = PartsVisibility.ShowPartsOnly;
      }
      transaction.Commit();
    }
    return Result.Succeeded;
  }
  catch( Exception e )
  {
    message = e.Message;
    return Result.Failed;
  }

Here is DivideParts.zip containing the source code, Visual Studio solution and add-in manifest of the 'Divide Parts' command. For completeness' sake, I also added the source code from Harry's AU presentation below to it.

Many thanks to Piotr for this exploration and sharing the result!

Revit Construction Modelling and API for Builders

As mentioned above, while exploring this issue for Piotr, I also came across Harry Mattison and Enrique Galicia's class CP5211 – Construction Modelling and API for Builders at Autodesk University 2011. It was mentioned in the overview of Revit and AEC API Classes at AU 2011, and unfortunately I never had a chance to participate live in that class myself.

It discusses applying Revit construction modelling functionality creating parts, assemblies and assembly views.

It provides sample code exercising some PartUtils methods such as CreateParts, GetAssociatedParts, DivideParts, the PartMaker class, offsetting individual sub-parts, creating assembly instances and assembly views.

It also demonstrates using the VIEW_PARTS_VISIBILITY built-in parameter to programmatically set the part visibility in the view. Piotr shows a more modern and comfortable way to achieve that in Revit 2013, though, using the PartsVisibility property instead.

All in all, a nice complement to the sample presented above.

For your convenience and effective web searches, here is the full content of the AU handout document.

Please note that I have not reformatted Harry's original source code, so the lines are sometimes rather long and truncated in the blog post view. To see them in full, you can either copy and paste them to a text editor, open the original handout document provided below, or download the DivideParts source code provided above.

Introduction

Revit contains a wide variety of functionality that can be useful throughout the construction process. Scheduling, estimating, and coordination are a few of these areas, and there are many opportunities to use the Revit API to automate tasks related to construction modelling. The Revit API can help you perform construction modelling faster and more accurately.

Applying Revit Construction Modelling Functionality

This handout focuses on the new Construction Modelling features in Revit 2012 that support workflows for improved 4D sequencing, cost estimating, quantification, and other construction-related tasks by allowing you to create parts, assemblies, and assembly views in your Revit model.

Parts

Parts are dividing elements that can be created in Revit hosts such as walls, ceilings, floor slabs, and roofs. Dividing one of these elements creates new elements called parts which are associated with the element used to create them. This parent element is not deleted or altered by the creation of the parts – the parent continues to exist and can be edited after parts have been created from it.

The importance of parts is that they allow your Revit model to reflect the difference between how objects are designed and how they are constructed. For example, a large floor slab may be modeled as a single floor element in Revit, but it may not be constructed as a single element at a single time during the construction schedule. By dividing the single floor into multiple parts, the model can better reflect the realities of the construction process and more construction data can be captured.

Parts can be divided into sub-parts using the UI or API by specifying curves that define the division or by providing a set of intersecting references such as levels, reference planes, or grids. Curves that divide parts can be created with either closed loops or open loops that intersect the boundaries of the parent element. These parts will allow you to improve the design intelligence in your Revit model so that it can be used to produce more granular and accurate schedules, quantity takeoffs, and graphical views of the model.

After parts are created and divided, many different attributes of these parts can be modified to accurately indicate how the building will be built. For example, the material of a part created from a floor slab may have a different material than the remainder of the slab.

After creating parts, part list schedules can be created to more accurately track cost estimation and quantification data in the BIM model.

This example shows the situation before and after parts are created and divided by the following code:

  Autodesk.Revit.ApplicationServices.Application app = commandData.Application.Application;
  Document doc = commandData.Application.ActiveUIDocument.Document;
  UIDocument uidoc = commandData.Application.ActiveUIDocument;
 
  IList<ElementId> idList = new List<ElementId>();
 
  // Select an element to use for part creation. Can be a host element (floor, roof, etc) or a part created from one of these elements.
  Element pickedElement = doc.GetElement( uidoc.Selection.PickObject( ObjectType.Element ) );
  idList.Add( pickedElement.Id );
 
  // Determine which elements to divide.
  ICollection<ElementId> elementIdsToDivide = new List<ElementId>();
  if( PartUtils.AreElementsValidForCreateParts( doc, idList ) )
  {
    // AreElementsValidForCreateParts returned true, so the selected element is not a part but it is an element that can be used to create a part. 
    Transaction createPartTransaction = new Transaction( doc, "Create Part" );
    createPartTransaction.Start();
    PartUtils.CreateParts( doc, idList ); // create the parts
    createPartTransaction.Commit();
 
    elementIdsToDivide = PartUtils.GetAssociatedParts( doc, pickedElement.Id, true, true ); // get the id of the newly created part
  }
  else if( pickedElement is Part )
  {
    // The selected element is a part, so that part will be divided. 
    elementIdsToDivide.Add( pickedElement.Id );
  }
 
  // Create geometry that will be used to divide the part. For this example, a new part will be divided from the main part that is one quarter of the face. More complex intelligence could be coded to divide the part based on construction logistics or the properties of the materials being used to create the part.
  XYZ pointRight = null;
  XYZ pointTop = null;
  XYZ pointCorner = null;
  XYZ pointCenter = null;
 
  SketchPlane sketchPlane = null;
 
  Options opt = new Options();
  opt.ComputeReferences = true;
  Autodesk.Revit.DB.GeometryElement geomElem = pickedElement.get_Geometry( opt );
  foreach( GeometryObject geomObject in geomElem.Objects )
  {
    if( geomObject is Solid ) // get the solid geometry of the selected element
    {
      Solid solid = geomObject as Solid;
      FaceArray faceArray = solid.Faces;
      foreach( Face face in faceArray )
      {
        // find the center of the face
        BoundingBoxUV bbox = face.GetBoundingBox();
        UV center = new UV( ( bbox.Max.U - bbox.Min.U ) / 2 + bbox.Min.U, ( bbox.Max.V - bbox.Min.V ) / 2 + bbox.Min.V );
        XYZ faceNormal = face.ComputeNormal( center );
        if( faceNormal.IsAlmostEqualTo( XYZ.BasisZ ) ) // this example is designed to work with a floor or other element with a large face whose normal is in the Z direction
        {
          Transaction sketchPlaneTransaction = new Transaction( doc, "Create Sketch Plane" );
          sketchPlaneTransaction.Start();
          sketchPlane = doc.Create.NewSketchPlane( face as PlanarFace );
          sketchPlaneTransaction.Commit();
 
          pointCenter = face.Evaluate( center );
 
          UV top = new UV( ( bbox.Max.U - bbox.Min.U ) / 2 + bbox.Min.U, bbox.Max.V );
          pointTop = face.Evaluate( top );
 
          UV right = new UV( bbox.Max.U, ( bbox.Max.V - bbox.Min.V ) / 2 + bbox.Min.V );
          pointRight = face.Evaluate( right );
 
          UV corner = new UV( bbox.Max.U, bbox.Max.V );
          pointCorner = face.Evaluate( corner );
 
          break;
        }
      }
    }
  }
  // Create the curves that will be used for the part division.
  IList<Curve> curveList = new List<Curve>();
  Curve curve1 = app.Create.NewLine( pointCenter, pointRight, true );
  curveList.Add( curve1 );
  Curve curve2 = app.Create.NewLine( pointRight, pointCorner, true );
  curveList.Add( curve2 );
  Curve curve3 = app.Create.NewLine( pointCorner, pointTop, true );
  curveList.Add( curve3 );
  Curve curve4 = app.Create.NewLine( pointTop, pointCenter, true );
  curveList.Add( curve4 );
 
  // intersectingReferenceIds will be empty for this example.
  ICollection<ElementId> intersectingReferenceIds = new List<ElementId>();
 
  // Divide the part
  Transaction dividePartTransaction = new Transaction( doc, "Divide Part" );
  dividePartTransaction.Start();
  PartMaker maker = PartUtils.DivideParts( doc, elementIdsToDivide, intersectingReferenceIds, curveList, sketchPlane.Id );
  dividePartTransaction.Commit();
  ICollection<ElementId> divElems = maker.GetDividedElementIds(); // Get the ids of the divided elements
 
  // Set the view's "Parts Visibility" parameter so that parts are shown
  Parameter partVisInView = doc.ActiveView.get_Parameter( BuiltInParameter.VIEW_PARTS_VISIBILITY );
  Transaction setPartVizTransaction = new Transaction( doc, "Set View Parameter" );
  setPartVizTransaction.Start();
  partVisInView.Set( 0 ); // 0 = Show Parts, 1 = Show Original, 2 = Show Both
  setPartVizTransaction.Commit();
 
  return Result.Succeeded;

Faces of parts (which correspond to layers of a compound host object) can be offset via the API to achieve the same result that can be obtained in the UI by dragging the part's shape handles. This functionality provides customized control beyond the default layer configuration created by Revit.

Here is a wall converted to parts:

The wall part faces can be individually offset by the code below to produce this result:

  GeometryElement geomElem = part.get_Geometry( new Options() );

  foreach( GeometryObject geomObject in geomElem.Objects )
  {
    if( geomObject is Solid )
    {
      Solid solid = geomObject as Solid;
      FaceArray faceArray = solid.Faces;
      foreach( Face face in faceArray )
      {
        if( part.CanOffsetFace( face ) )
          part.SetFaceOffset( face, offsetCtr );
        offsetCtr += 0.1;
      }
    }
  }

Assemblies and Assembly Views

Assemblies are collections of elements that can be used in the Revit model to create shop drawings for prefabricated building components such as pre-cast walls, columns, beams, and floors. Assemblies can be scheduled, visually isolated, and tagged.

Every assembly has a primary element that determines the assembly's category. Each assembly is shown in the Project Browser and can be used to create assembly views that display only that assembly.

Read, write and create access to assemblies in the Revit environment is provided through the following two classes:

• Autodesk.Revit.DB.Assembly.AssemblyInstance
• Autodesk.Revit.DB.Assembly.AssemblyType

Other important methods include AssemblyInstance.GetMemberIds, AssemblyInstance.SetMemberIds, and AssemblyInstance.Disassemble.

Assembly Views display only the elements in the assembly and are created with methods of the AssemblyViewUtils class. The command below shows how assemblies and assembly views can be created with the API.

Here are two columns and a beam selected before running it:

Running the command automatically creates an assembly and its associated views:

  Document doc = commandData.Application.ActiveUIDocument.Document;
  UIDocument uidoc = commandData.Application.ActiveUIDocument;
 
  ElementId categoryId = doc.get_Element( uidoc.Selection.GetElementIds().FirstOrDefault() ).Category.Id;
 
  if( AssemblyInstance.IsValidNamingCategory( doc, categoryId, uidoc.Selection.GetElementIds() ) )
  {
    Transaction transactionA = new Transaction( doc, "Create Assembly" );
    transactionA.Start();
    AssemblyInstance assemblyInstance = AssemblyInstance.Create( doc, uidoc.Selection.GetElementIds(), categoryId );
    transactionA.Commit(); // need to commit the transaction to complete the creation of the assembly instance so it can be accessed in the code below
 
    Transaction transactionB = new Transaction( doc, "Create Assembly Views" );
    transactionB.Start();
    assemblyInstance.AssemblyTypeName = "Assembly #1"; // rename the assembly
    if( assemblyInstance.AllowsAssemblyViewCreation() ) // check to see if views can be created for this assembly
    {
      ElementId titleblockId = doc.TitleBlocks.Cast<FamilySymbol>().First<FamilySymbol>().Id; // find a titleblock
      // create a sheet, 3d view, sections, a material takeoff, and parts list for this assembly
      ViewSheet viewSheet = AssemblyViewUtils.CreateSheet( doc, assemblyInstance.Id, titleblockId );
      View3D view3d = AssemblyViewUtils.Create3DOrthographic( doc, assemblyInstance.Id );
      ViewSection detailSectionA = AssemblyViewUtils.CreateDetailSection( doc, assemblyInstance.Id, AssemblyDetailViewOrientation.DetailSectionA );
      ViewSection detailSectionB = AssemblyViewUtils.CreateDetailSection( doc, assemblyInstance.Id, AssemblyDetailViewOrientation.DetailSectionB );
      ViewSection detailSectionH = AssemblyViewUtils.CreateDetailSection( doc, assemblyInstance.Id, AssemblyDetailViewOrientation.HorizontalDetail );
      View materialTakeoff = AssemblyViewUtils.CreateMaterialTakeoff( doc, assemblyInstance.Id );
      View partList = AssemblyViewUtils.CreatePartList( doc, assemblyInstance.Id );
 
      // Add graphical views to the newly created sheet. Schedules (the Parts List and Material Takeoff) cannot be added to sheets with the 2012 API.
      viewSheet.AddView( view3d, new UV( 1, 1 ) );
      viewSheet.AddView( detailSectionA, new UV( 1.3, 1 ) );
      viewSheet.AddView( detailSectionB, new UV( 1, 1.3 ) );
      viewSheet.AddView( detailSectionH, new UV( 1.3, 1.3 ) );
    }
    transactionB.Commit();
  }
  return Result.Succeeded;

For completeness' sake, here is the original handout document CP5211_Mattison.pdf itself.

If you log on to the AU web site, you will find that you have access to this very same handout document, and also to the original presentation, which I do not care to reproduce here, and 'additional materials', which turns out to be C# source code implementing three further external commands demonstrating Revit API functionality related to assemblies, groups and extensible storage:

• Create_Assembly_From_Group
• Update_Assemblies_From_Groups
• ReportStoredId

As far as I can tell, figuring out what they do and how they work is left as an exercise to the interested and motivated reader :-)

Many thanks to Harry and Enrique for this nice overview and all the sample code!

Validate Roof Type and View OBJ on Android

I spent some time exploring how to view the output generated by the OBJ exporter on an Android tablet.

Viewing an OBJ Model on Android

That proved to be easy. I installed the KiwiViewer open-source visualization app, which supports OBJ, and used Dropbox to upload the OBJ export of my Revit model to the Internet, from where I could access it on the tablet from anywhere. Anywhere with a wifi Internet link, that is.

It works fine as far as the pure geometry defined in the OBJ file is concerned. Unfortunately, the separate MTL material file was ignored, eliminating the colour and transparency information.

The viewer displays other models with colour and other rendering information perfectly well, so I'll explore how those are defined appropriately next.

Alternatively, I'll have to implement my own viewer. That may be the easiest route to go in order to achieve something useful, since that will soon require identifying the original Revit elements in the viewer, e.g. to communicate information from the tablet device back to the original Revit model. For example, I might want to pick a building element and add a comment to it on the tablet, then have that information integrated back into the original document. I hope to look at something like that soon.

Validate the Roof Type Compound Structure for the Little House

I also happened to run the 'little house' command provided by the Xtra ADN training labs again and was a bit surprised that the roof did not appear as expected.

Exploring the resulting model in more depth, I notice that the roof was in fact being created successfully, but was not visible in the graphic view.

I tracked it down to the roof type being used. The sample just picks the first roof type encountered, which happened to be 'sloped glazing'. This type has zero entries in its compound structure, or even worse, no compound structure defined at all.

After adding a check for a valid compound structure to the type selection code, the roof appeared again:

Here is the plan view as well, although that does not show the roof, of course:

This is the code checking for a valid compound structure in the list of roof types returned by the filtered element collector, then creating the roof and adding the slope to it:

  // Add a floor, a roof and the roof slope:
 
  bool structural = false;
  Floor floor = createDoc.NewFloor( 
    profile, structural );
 
  List<Element> roofTypes 
    = new List<Element>( 
      LabUtils.GetElementsOfType(
        doc, typeof( RoofType ), 
        BuiltInCategory.OST_Roofs ) );
 
  Debug.Assert( 0 < roofTypes.Count, 
    "expected at least one roof type"
    + " to be loaded into project" );
 
  // Ensure that we get a valid roof type. 
  // In Revit 2013, the first one encountered 
  // is sloped glazing with zero entries in
  // its compound layers; actually, the entire
  // compound structure is null:
 
  RoofType roofType = roofTypes
    .Cast<RoofType>()
    .FirstOrDefault<RoofType>(
      t => null != t.GetCompoundStructure() );
 
  ModelCurveArray modelCurves 
    = new ModelCurveArray();
 
  FootPrintRoof roof 
    = createDoc.NewFootPrintRoof( profile, 
      levelTop, roofType, out modelCurves );
 
  // Regenerate the model after roof creation, 
  // otherwise the calls to set_DefinesSlope and 
  // set_SlopeAngle throwing the exception "Unable
  // to access curves from the roof sketch."
 
  doc.Regenerate();
 
  // The argument to set_SlopeAngle is NOT an 
  // angle, it is really a slope, i.e. relation 
  // of height to distance, e.g. 0.5 = 6" / 12", 
  // 0.75  = 9" / 12", etc.
 
  double slope = 0.3;
 
  foreach( ModelCurve curve in modelCurves )
  {
    roof.set_DefinesSlope( curve, true );
    roof.set_SlopeAngle( curve, slope );
  }

Here is adn_labs_2013_2012-08-27.zip containing the complete source code, Visual Studio solution, and RvtSamples include file to load my version of the ADN Revit API training labs including the additional commands defined by the Xtra projects, among them the little house creation lab described above.

Updated ADN Revit API Training Material

This ties in very nicely with another little item: as Mikako just pointed out on the AEC DevBlog, the Revit API 2013 training labs material on the Revit Developer Center in the public Autodesk Developer Network site has been updated and is available for download in the 'Samples and Documentation' section. Here is also a direct link to it.

As Mikako points out, this is the material that we use for classroom trainings. If you know the basic of .NET programming and are interested in learning the Revit API, it also provides a good starting point for self-learning, since both source code and documents describing the steps to perform are included.

Structural Concrete Setout Point Add-in

I am back from my vacation now, having spent a wonderful relaxing time doing all kinds of things not related to the Revit API or computers at all, such as talking, walking, singing, playing music, painting, swimming, meditating, climbing, caving, canoeing and sharing time with friends...

Meanwhile, a whole bunch of interesting issues to share with you have been piling up, new ones keep pouring in, and I still have some long-standing pending posts to get around to as well.

One important utility that I have been wanting to publish for months now is for the automatic placement and management of structural concrete setout points which I implemented together with Paul Hellawell of GHD at the Melbourne DevLab back in March, thus also finally answering Ishfak's request for the full Revit 2013 source code to retrieve real world concrete coordinates.

This is a full-blown end-user-capable little application for the automatic creation of setout points for on-site location and construction of structural elements.

One of the most fascinating aspects of the implementation for me was the amount of choices that we were forced to make between implementing something ourselves programmatically versus discovering the proper way to use built-in Revit functionality to do it automatically for us instead with no work at all on our part.

For instance, we originally defined one single setout point marker type, and started implementing API functionality to select the main points and change their colour.

Happily, we soon found a much simpler solution which requires no programming at all: simply define two separate family types for the minor and major setout point markers with different colours, and let the user select which one to use through the standard Revit user interface. Several other equally important design decisions cropped up, demonstrating the importance of knowing the product well, which Paul luckily does.

They really highlighted the fact how important it is to know the user interface and best standard practices in depth before embarking on a serious programming project, however simple it may seem.

Let's start at the beginning, and reiterate the motivation for this undertaking:

Almost every construction professional has experienced the following kind of situation at some time in their career:

A large complex structure is constructed off-site. When assembled on site, it does not fit exactly. The workers continue nonetheless and force it into place. The error is discovered later and corrected using brute force and post adaption. Overall cost of exercise: days or weeks of delay and painful cost overruns.

This leads to the following important prophylactic task:

The Challenge: Provide a way to find the real world coordinates of the corners of potential elements to be set out in the field, automatically extracting relevant setout points from the model. In this example, we are dealing with concrete structural elements. Ideally, we would like to display these points in a Revit schedule, so that they can be formatted and placed on a drawing sheet. We would like to then define which of the points should be used as main setout points and list them in a schedule, preferably numbered sequentially for readability.

In Practice: Retrieved all the concrete corner point data via the API is not hard, and I presented the solution to retrieve real world concrete coordinates separately in the following three steps:

• Filtering for structural concrete elements.
• Retrieving their corners, i.e. geometry traversal to retrieve unique vertices.
• Converting from Revit model to real-world coordinates.

However, transferring this information directly into a schedule proved to be impossible. Instead we created a family definition containing shared parameters to hold the data required for scheduling. We then place instances of the family at the points extracted from the geometry. Through the API it is now possible to populate the parameters with the X, Y, Z coordinates extracted from the geometry, and add these values to the extracted project location, to convert them to real world coordinates.

Initially, we defined a setout point family with one single type in it. This did not enable the ability to select which points to schedule as main setout points. For this, we created two different family types, SetoutPoint_Major and SetoutPoint_Minor. This allows two separate schedules to be created, one capturing all the points, the other only points defined as major points for use on a drawing sheet for setout.

The schedule listing all points is useful, e.g. for export to a CSV file and subsequent import into a surveying device such as a Trimble, allowing site set-out directly from the model.

The setout point tool extracts the X, Y, Z coordinates of all concrete edges. The generated points can then be interactively marked as Major points (setout point) and renumbered sequentially to provide a schedule of key setout points. The remaining point are schedules as well, e.g. to be saved as a comma delimitated file CSV file to be sent to surveying equipment for site setout.

Usage

Ensure your project contains some elements whose structural material is set to concrete or precast concrete.

You can then click the Get Concrete Corners tool:

The tool automatically analyses al the concrete structural elements' geometry and placed setout point family instances representing a 3D pointer on all the concrete element corner vertices:

The family is defined using the Generic Model family template. The green indicators represent general setout points. You can select the ones you want to change to main setout points, also known as major or key, by simply selecting them and swapping their type to SetoutPoint_Major:

Major setout points are displayed in red instead of green:

The sample project provided below defines two schedules. One of them is populated with all setout points, marking every corner of every piece of concrete:

The second schedule lists only the selected main or major setout points and their coordinates:

Once you have all your key setout points defined, a separate 'Renumber setout Points' external command renumbers them sequentially and adds a SOP (Set Out Point) prefix to their number to differentiate them from the minor points.

The renumbered schedule can now be used on a drawing sheet.

Many thanks to Paul for our initiating this project, his deep Revit knowledge and experience, all the support he provided during the Melbourne Revit API training, and the great evening we had together in Melbourne after the training!

Implementation Details

I already pointed to the discussion of the main technical underpinnings for the retrieval of the concrete corners above, i.e.

• Filtering for structural concrete elements.
• Retrieving their corners, i.e. geometry traversal to retrieve unique vertices.
• Converting from Revit model to real-world coordinates.

Now let's look at some of the aspects of putting this functionality to use and wrapping it into a full-blown end-user application:

• External application and CmdData class
• Shared parameters
• Importance of product usage experience, content and best practices
• Marking all geometry vertices
• Major setout point renumbering

External Application and CmdData Class

The application defines two commands:

• CmdGeomVertices: filter for all relevant concrete structural elements, analyse their geometry, create the setout point markers, and populate their shared parameters to be reflected in the predefined schedules.
• CmdRenumber: renumber the main or major setout points consecutively.

They are presented in a custom ribbon panel defined by an external application.

In order to encapsulate all the information required to populate the ribbon panel push buttons, I define the following CmdData class defining the external command implementation class name, description and tool tip text:

  class CmdData
  {
    public CmdData( 
      string name, 
      string text, 
      string tip )
    {
      Name = name;
      Text = text;
      Tip = tip;
    }
    public string Name { get; set; }
    public string Text { get; set; }
    public string Tip { get; set; }
  }

The two instances can be populated like this:

  static CmdData[] data = new CmdData[] {
 
    new CmdData( 
      "GeomVertices", 
      "Mark Concrete Corners",
      "Place a setout point marker on every concrete corner." ),
 
    new CmdData( 
      "Renumber", 
      "Renumber major", 
      "Renumber major setout points" )
  };

The external application OnStartup method making use of this ends up very simple:

  public Result OnStartup( 
    UIControlledApplication a )
  {
    string path = System.Reflection.Assembly
      .GetExecutingAssembly().Location;
 
    // Create ribbon panel
 
    RibbonPanel p = a.CreateRibbonPanel( Caption );
 
    // Create buttons
 
    List<PushButtonData> buttonData 
      = new List<PushButtonData>( 
        data.Length );
 
    foreach( CmdData cd in data )
    {
      PushButtonData pbd = new PushButtonData(
        cd.Name, cd.Text, path,
        _class_name_prefix + cd.Name );
 
      pbd.ToolTip = cd.Tip;
 
      buttonData.Add( pbd );
    }
 
    p.AddStackedItems( buttonData[0], 
      buttonData[1] );

    return Result.Succeeded;
  }

Lacking icons, my panel does not look quite as impressive as Paul's one shown above, but it does the job:

Shared Parameters

As mentioned above, the functionality to retrieve the concrete corners geometry data has already been described in previous posts.

The question is how to handle this information in order to make it available to the user, populate schedules, etc. We ended up inserting family instances marking all concrete corners as minor setout points, and populating shared parameters on each to encapsulate the required data specifying the host element and its point coordinates. Here is the shared parameter file, slightly simplified for readability:

# This is a Revit shared parameter file.
# Do not edit manually.
*META VERSION MINVERSION
META 2 1
*GROUP ID NAME
GROUP  1 SetOut
*PARAM GUID NAME             DATATYPE ... GROUP VISIBLE
PARAM  .... Key_Setout_Point YESNO        1     1
PARAM  .... Host_Type        TEXT         1     1
PARAM  .... Host_Id          INTEGER      1     1
PARAM  .... X                LENGTH       1     1
PARAM  .... Y                LENGTH       1     1
PARAM  .... Z                LENGTH       1     1
PARAM  .... Point_Number     TEXT         1     1

Shared parameter access is implemented using their GUIDs throughout the code.

Importance of Product Usage Experience, Content and Best Practices

We initially defined a parameter in the setout point family to distinguish between minor and major points, and started working on a separate user interface to toggle between the two and change the family instance colour depending on its current setting.

At a certain point, we discovered that it was vastly simpler to define two separate types within the family instead and use the standard Revit user interface to toggle between those.

It is so important for every add-in developer to know the standard Revit possibilities and best-practice workflows.

That can save huge amounts of unnecessary programming effort, sometimes wasted to fight against the product and its standard paradigms instead of making optimal use of it.

Marking All Geometry Vertices

As said, most of the underlying functionality to retrieve the concrete corner geometry was already presented and discussed.

One additional helper method GetFamilySymbols loads the setout point family, if it is not already present, and retrieves the major and minor setout point symbols:

public static FamilySymbol [] GetFamilySymbols( 
  Document doc, 
  bool loadIt )
{
  FamilySymbol [] symbols = null;
 
  Family family 
    = new FilteredElementCollector( doc )
      .OfClass( typeof( Family ) )
      .FirstOrDefault<Element>( 
        e => e.Name.Equals( FamilyName ) ) 
      as Family;
 
  // If the family is not already loaded, do so:
 
  if( null == family && loadIt )
  {
    // Load the setout point family
 
    using( Transaction tx = new Transaction( 
      doc ) )
    {
      tx.Start( "Load Setout Point Family" );
 
      if( doc.LoadFamily( _family_path, 
        out family ) )
      {
        tx.Commit();
      }
      else
      {
        tx.RollBack();
      }
    }
  }
 
  if( null != family )
  {
    symbols = new FamilySymbol[2];
 
    int i = 0;
 
    foreach( FamilySymbol s in family.Symbols )
    {
      symbols[i++] = s;
    }
 
    Debug.Assert( 
      symbols[0].Name.EndsWith( "Major" ), 
      "expected major (key) setout point first" );
 
    Debug.Assert( 
      symbols[1].Name.EndsWith( "Minor" ), 
      "expected minor setout point second" );
  }
  return symbols;
}

Then, finally, here is the external command mainline pulling it all together, i.e.

• Determine project location transformation to real world coordinates.
• Load or retrieve setout point family symbols.
• Retrieve the relevant structural concrete elements.
• Retrieve element geometry.
• Place a setout point marker family instance on each geometry vertex.
• Check to see whether the required shared parameters have been bound.

Setout points are numbered starting at one each time the command is run with no decoration or prefix.

Here is Execute method implementation performing these tasks:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  Transform projectLocationTransform 
    = GetProjectLocationTransform( doc );
 
  // Load or retrieve setout point family symbols:
 
  FamilySymbol [] symbols 
    = GetFamilySymbols( doc, true );
 
  if( null == symbols )
  {
    message = string.Format(
      "Unable to load setout point family from '{1}'.",
      _family_path );
 
    return Result.Failed;
  }
 
  FilteredElementCollector col 
    = GetStructuralElements( doc );
 
  // Retrieve element geometry and place a
  // setout point on each geometry corner.
 
  // Setout points are numbered starting at 
  // one each time the command is run with
  // no decoration or prefix whatsoever.
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Place Setout Points" );
 
    Options opt = app.Create.NewGeometryOptions();
 
    // On the very first attempt only, run an error 
    // check to see whether the required shared 
    // parameters have actually been bound:
 
    bool first = true;
 
    foreach( Element e in col )
    {
      Solid solid = GetSolid( e, opt );
 
      string desc = ElementDescription( e );
 
      if( null == solid )
      {
        Debug.Print(
          "Unable to access element solid for element {0}.",
          desc );
 
        continue;
      }
 
      Dictionary<XYZ, int> corners
        = GetCorners( solid );
 
      int n = corners.Count;
 
      Debug.Print( "{0}: {1} corners found:", desc, n );
 
      foreach( XYZ p in corners.Keys )
      {
        ++_point_number;
 
        Debug.Print( "  {0}: {1}",
          _point_number, PointString( p ) );
 
        FamilyInstance fi
          = doc.Create.NewFamilyInstance( p,
            symbols[1], StructuralType.NonStructural );
 
        // Add shared parameter data immediately 
        // after creating the new family instance.
        // The shared parameters are indeed added 
        // immediately by Revit, so we can access and
        // populate them.
        // No need to commit the transaction that 
        // added the family instance to give Revit 
        // a chance to add the shared parameters to 
        // it, nor to regenerate the document, we 
        // can write the shared parameter values 
        // right away.
 
        if( first )
        {
          Parameter q = fi.get_Parameter(
            _parameter_x );
 
          if( null == q )
          {
            message = 
              "The required shared parameters "
              + "X, Y, Z, Host_Id, Host_Type and "
              + "Point_Number are missing.";
 
            tx.RollBack();
 
            return Result.Failed;
          }
          first = false;
        }
 
        // Transform insertion point by applying
        // project location transformation.
 
        XYZ r2 = projectLocationTransform.OfPoint( p );
 
        fi.get_Parameter( _parameter_host_type ).Set(
          GetHostType( e ).ToString() );
 
        fi.get_Parameter( _parameter_host_id ).Set(
          e.Id.IntegerValue );
 
        fi.get_Parameter( _parameter_point_nr ).Set(
          _point_number.ToString() );
 
        fi.get_Parameter( _parameter_x ).Set( r2.X );
        fi.get_Parameter( _parameter_y ).Set( r2.Y );
        fi.get_Parameter( _parameter_z ).Set( r2.Z );
      }
    }
 
    tx.Commit();
  }
  return Result.Succeeded;

That's about it... one more little thing:

Major Setout Point Renumbering

Such irrational creatures, these human beings.

Users apparently insist on consecutive numbering of items they deal with.

We therefore implemented a second command named CmdRenumber to renumber the major points.

They are basically renumbered randomly, since all major points are selected using a filtered element collector. We iterate over the result, assign a consecutive number to each instance, and store it in the Point_Number text-valued shared parameter with a "SOP " prefix string _sop_prefix.

The key setout points are family instances with the generic model category and the major setout point type.

The external command Execute implementation thus ends up looking like this:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  FamilySymbol[] symbols
    = CmdGeomVertices.GetFamilySymbols( 
      doc, false );
 
  if( null == symbols )
  {
    TaskDialog.Show( "Setout Points",
      "Setout point family not loaded, "
      + "so no setout points present." );
 
    return Result.Succeeded;
  }
 
  FamilyInstanceFilter instanceFilter
    = new FamilyInstanceFilter( doc, symbols[0].Id );
 
  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .OfCategory( BuiltInCategory.OST_GenericModel )
      .OfClass( typeof( FamilyInstance ) )
      .WherePasses( instanceFilter );
 
  Guid guid = CmdGeomVertices._parameter_point_nr;
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Renumber Setout Points" );
 
    int i = 0;
    string s;
 
    foreach( Element p in col )
    {
      s = _sop_prefix + ( ++i ).ToString();
 
      p.get_Parameter( guid ).Set( s );
    }
 
    tx.Commit();
  }
  return Result.Succeeded;

For all further details, please refer to the one and only really trustworthy reference, the full source code.

Here is SetoutPoints.zip including the complete source code, Visual Studio solution, add-in manifest and setout point marker family.

For easier testing, here is also a sample project based on the standard rst_basic_sample_project.rvt with a non-standard project location and the setout point schedules added.

Elbow Fitting Selection and Dimensioning

Vacation time is approaching fast for me and lots of things need finishing off beforehand.

Meanwhile, one thing that had a number of developers champing at their bits for a while now finally came to fruition:

Autodesk Exchange

The Autodesk Exchange store is now open for application submissions. Stephen Preston already published several articles exaplaining the full details:

• Summary information
• Information for Revit developers
• Publishing an app

Here is another topic that recently kept me busy, with some helpful input from Martin Schmid and Steve Mycynek:

Selecting a Pipe Elbow Fitting

Question: I need to set the diameter of a pipe elbow fitting programmatically. The elbow diameter obviously needs to be adapted to the pipe diameter. The two pipes may also have different diameters.

I tried using the NewElbowFitting method to insert the elbow and simply pass in the two pipe connectors to it like this:

  doc.Create.NewElbowFitting( con1, con2 );

This does successfully create an elbow fitting instance. However, I don't see how to control which elbow symbol is inserted by this method. Is there any way to influence this?

Answer: Calling the NewElbowFitting method is similar to using the Trim tool in the user interface. When this method is called, Revit automatically chooses the appropriate elbow for you.

In Revit 2013, you can control the selection process through the routing preferences, whereas previous versions only enabled you to define one single default elbow, tee, etc. The routing preferences support multiple settings for different materials and sizes.

The routing preferences API is demonstrated by the RoutingPreferenceTools SDK sample. It implements three commands, one for analysis and reporting purposes, two for importing and exporting routing preferences to XML:

• Routing Preference Analysis: Analyze the routing preferences of a given pipe type to check for common problems, using the routing preferences API to look at all rules and criteria for a given PipeType.
• Routing Preference Builder with its two commands CommandReadPreferences and CommandWritePreferences: Set pipe type, fitting, and routing preferences in a project from data in an XML file and export these preferences to XML for archival, documentation, and collaboration purposes, allowing a user to work with routing preference data in a shareable XML format suitable for reuse in a wide variety of BIM management environments.

When you call NewElbowFitting, it inspects the pipe type and finds the first elbow in the appropriate routing preferences.

If the elbow inlet and outlet sizes differ, you need a reducing elbow.

How to Use the Routing Preferences API to Set the Elbow Symbol

The NewElbowFitting method will insert the elbow symbol specified in the routing preferences. Please note that while RP will choose the first symbol in the rule list that matches its criteria, you can always programmatically either set size criteria to ensure a later symbol is chosen for a given scenario, or re-order the rules using RoutingPreferenceManager RemoveRule and AddRule methods, at least temporarily, to force RP to choose a different elbow symbol than normal.

For example, if you have defined routing preference for 'Elbow Reducing - Threaded - MI - Class 150.rfa' and call this method, you will get an elbow that has different connection sizes as shown below on the left. If you don't have a transitioning elbow, but you do have a reducer defined, you will get a result as below right. Note that the reducer is quite odd in this particular model file :-)

In this case, both the Reducing Elbow and the Elbow + Reducer 'work'; which is used depends on their order in the definition of the RP.

The RP is the only way to influence this selection, both in the UI and in the API.

I Beg to Differ

In some cases, the outer diameter of the fitting and the pipes may differ. This is a content issue. Pipes and fittings are selected and connected based on the pipe 'Nominal Diameter' and the 'Nominal Diameter' of the fitting connector. In the Pipe Settings, a user can make the 'outer diameter' of a pipe bigger or smaller than its nominal diameter.

Here is an example with the following pipe type properties:

• Diameter 18 mm
• Outer Diameter 18 mm
• Inner Diameter 16 mm
• Size 18 mm

The generic pipe elbow fitting connected to the pipes by calling the NewElbowFitting method has the following properties:

• Nominal Diameter 18 mm
• Size 18 mm - 18 mm

For a fitting, the geometry of the elbow is completely arbitrary.

If you would like the elbow and pipe to have the same outer diameter, there are two ways to achieve this:

1. Make the outer diameter of the pipes bigger.
2. Modify the geometry of the elbow to be smaller.

Welded pipe fittings, for example, would have the same outer diameter, whereas threaded fittings, PVC, and others, typically have a larger outer diameter than the pipe itself, because the pipe engages into the fitting.

Change Elbow Dimension

Saikat handled an independent but related case that also happened to catch my attention:

Question: How can I change the diameter of an elbow pipe fitting, depending on the pipe diameter?

Answer by Saikat Bhattacharya: To test this, I created a pipe with an elbow fitting attached at one end. In the user interface, you can see that the nominal diameter parameter of the pipe is disabled, i.e. greyed out. The only thing I can do interactively in the user interface is modify the Nominal Radius of the pipe.

Based on this observation, I wrote the following few lines of code to modify the Nominal Radius of the selected elbow fitting using the API and it worked well:

  UIApplication uiApp = commandData.Application;
  UIDocument uiDoc = uiApp.ActiveUIDocument;
  Document doc = uiDoc.Document;
 
  Transaction trans = new Transaction( doc );
  trans.Start( "Change Diameter" );
  foreach( Element e in uiDoc.Selection.Elements )
  {
    FamilyInstance i = e as FamilyInstance;
 
    Parameter p = i.get_Parameter( 
      "Nominal Radius" );
 
    p.Set( 10 * 0.08333 );
  }
  trans.Commit();

For the complete solution and additional background information, please refer to Saikat's article on changing the diameter of an elbow fitting.

Invoke External Command on Start-up

Finally, to wrap this up, a little note on another issue that also cropped up and really is completely unrelated :-)

Question: I would like to call my Revit add-in in a batch operation in order to process multiple Revit files. The process would involve starting Revit, loading a model, invoking my add-in, and shutting down the application afterwards. I don't see any obvious command line option to achieve this. Is it possible at all?

Answer: Yes. This can be easily addressed by creating an external application, implementing appropriate OnStartup and DocumentOpened events, and driving the whole thing through a journal file or even directly from the command line.

View of NewGroup Duplicated Elements

I already mentioned that you can work around the lack of programmatic creation possibilities for some element types by grouping existing ones, creating new instances of that group, and then ungrouping it again.

One question that came up in that context is what view the new group appears in:

Question: I am using code like this to duplicate one or more elements:

  void CreateGroup( 
    Document doc,
    ICollection<ElementId> ids,
    XYZ offset )
  {
    Group group = doc.Create.NewGroup( ids );
 
    LocationPoint location = group.Location 
      as LocationPoint;
 
    XYZ p = location.Point + offset;
 
    Group newGroup = doc.Create.PlaceGroup( 
      p, group.GroupType );
 
    group.UngroupMembers();
  }

However, under certain circumstances, the new group is not placed in the same view as the old one.

Is there any way to specify the target view?

Answer: Sorry, there is currently no direct API access to control the view used when placing a group.

The active view will be used to place the new group, so all you have to do is ensure that the target view really is activated.

To be on the really safe side, you might want to try closing all other views to absolutely force the open one to be used.

The Revit API calls should in theory obviously not be influenced by any of the user interface settings, but there may still be some obsolete remnants of such dependencies left.

Creating an Opening

Here is a question that we have looked at in the distant past, brought up again and reinforced by Jon Mirtschin of Geometry Gym, working on BIM and model exchange with Rhino, Grasshopper et al:

Question: Sorry to bother you, but trying to get a quick answer to this problem. If you happen to have 5 minutes to help, it will be greatly appreciated.

I've attached a sample Revit project. It simply creates a polyline curve array and slab outline, and then attempts to add an internal opening. This is a simplification from my IFC importer. When I run it, I get an error message about a circular reference.

Can you please advise what is wrong and how to fix? I've tried searching samples and online help to no avail.

Answer: Okey-doke, five minutes.

• Countdown starting at 9:45:34.70.
• I read the mail and stored your attachment: 9:47:09.20;
• Created a repository for your issue and unzipped: 9:48:12.65;
• Started up Visual Studio to look at your project: 9:49:02.60;
• Updated references to be able to compile: 9:49:55.64;
• Bumped .NET framework version to 4.0: 9:50:33.15;
• Fixed post-build event... or no, I'll just ignore that error: 9:51:21.87;

Sorry for being so literal, I just can't help it, and I even think it is fun :-)

Well, this looks like an interesting issue.

Before I dig any further, have you looked at the suggestions on creating a hole in a floor? They include exploring the NewOpenings and ShaftHolePuncher SDK samples.

Do those SDK samples work for you?

In additional to that very old post, here is another half-old one which raises another interesting and important point for you to explore: an extra transaction may be required after creating the slab and before punching a hole through it.

Please try that out as well.

I expect a full report including answers to every single one of the questions above, ok?

Thank you!

P.S.: 9:57:42.51 :-)

Response:

Well, at least you have a great stop watch. Most the time I'm too scared to even glance at the clock on the wall. I actually should also ask you to report your Revit start up time; I can probably allow a minute reduction for your great computers vs. my poor laptop ;-)

Ok, good news. You are correct about the transaction. It was one of the things I had in the back of my mind but hadn't checked yet. Thanks for pointing it out.

Adding the manual transactions and setting a commit and start before adding the opening profile worked. Note that when I went back to my real project, it has tiers of commands, so I was getting an exception to start a new transaction within the outer program command transaction. I added a call to the doc.Regenerate method instead, and that resolved this issue, so problem solved.

I did look at the examples you mention, and will be using them. In this case, the IFC data is presenting an outer and inner profile curves, so the nominated method is the best for this situation.

I don't know if I've answered every single one of your questions, but I'm close.

Here is my amended source code. Now I'm off to implement the change in my real project.

Please feel free to blog about this, I have read through most of your blog several times now and to me it is an invaluable resource. I would like to contribute in any small way.

Here is a sample image of a basic test:

This is an IFC generated from an Archicad model and now opened in Revit. I already had the wall openings working, and now slabs are there too. There are some more impressive and real world projects behind this.

Answer: For the stopwatch, I use the Windows command console time command, i.e. an old MS-DOS command :-)

C:\a\doc\revit\blog\ > time
The current time is: 10:43:48.29
Enter the new time:

My computer is pretty old and decrepit, actually. I am up for renewal soon :-)

Thank you for the appreciation and nice example!

Create Section View Parallel to Wall

Here is a nice case that just came up and helped me heal my latent view manipulation phobia.

Before getting to that, a short pointer to a non-API issue: The Shanghai Tower is currently being built to become one of the tallest and greenest buildings in the world. Take a look at Shanghai Tower: The Role of BIM in Building the Spirit of the City, a six-minute video explaining the concept and the role of Autodesk BIM solutions in its design, construction, and operation.

Back to the view creation issue, the question is how to set up a section view that is parallel to a given wall.

The CreateViewSection SDK sample can be used as a basis for exploration, and the discussion on section view creation spells it out a bit further still. We also previously discussed some further aspects of elevation and section views and looked at setting up the view parameters to crop a 3D view to a room.

Obviously all previous explorations in the area of creating views make use of the obsolete view creation methods on the creation document class, which have now been replaced by static methods on the view classes themselves.

The only sample using the new methods was the recent one to create a structural plan view, without any need to explore the required transformation, view direction, or crop box.

To alleviate that, I implemented a new sample external command named CreateWallSectionView which expects a single straight perpendicular wall to be pre-selected and creates a section view parallel to the wall with its crop box set up to display the wall in its entirety.

The code is extremely straight-forward and actually worked right out of the box without any further tweaking.

It uses the wall location line as the main source of geometrical input. It also queries the wall bounding box to obtain its height, and uses the wall type Width property to determine the total wall thickness, although the latter is not used anywhere.

From the location line, it determines the wall direction and length. It sets up the bounding box min and max values from the length and height.

The transform is defined using the wall direction defining the right-left and the global world coordinate system Z vector defining the upward direction.

Simple and precise.

Here is the entire code achieving this:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    // Retrieve wall from selection set
 
    Selection sel = uidoc.Selection;
 
    SelElementSet set = sel.Elements;
 
    Wall wall = null;
 
    if( 1 == set.Size )
    {
      foreach( Element e in set )
      {
        wall = e as Wall;
      }
    }
 
    if( null == wall )
    {
      message = "Please select exactly one wall element.";
 
      return Result.Failed;
    }
 
    // Ensure wall is straight
 
    LocationCurve lc = wall.Location as LocationCurve;
 
    Line line = lc.Curve as Line;
 
    if( null == line )
    {
      message = "Unable to retrieve wall location line.";
 
      return Result.Failed;
    }
 
    // Determine view family type to use
 
    ViewFamilyType vft
      = new FilteredElementCollector( doc )
        .OfClass( typeof( ViewFamilyType ) )
        .Cast<ViewFamilyType>()
        .FirstOrDefault<ViewFamilyType>( x =>
          ViewFamily.Section == x.ViewFamily );
 
    // Determine section box
 
    XYZ p = line.get_EndPoint( 0 );
    XYZ q = line.get_EndPoint( 1 );
    XYZ v = q - p;
 
    BoundingBoxXYZ bb = wall.get_BoundingBox( null );
    double minZ = bb.Min.Z;
    double maxZ = bb.Max.Z;
 
    double w = v.GetLength();
    double h = maxZ - minZ;
    double d = wall.WallType.Width;
    double offset = 0.1 * w;
 
    XYZ min = new XYZ( -w, minZ - offset, -offset );
    XYZ max = new XYZ( w, maxZ + offset, 0 );
 
    XYZ midpoint = p + 0.5 * v;
    XYZ walldir = v.Normalize();
    XYZ up = XYZ.BasisZ;
    XYZ viewdir = walldir.CrossProduct( up );
 
    Transform t = Transform.Identity;
    t.Origin = midpoint;
    t.BasisX = walldir;
    t.BasisY = up;
    t.BasisZ = viewdir;
 
    BoundingBoxXYZ sectionBox = new BoundingBoxXYZ();
    sectionBox.Transform = t;
    sectionBox.Min = min;
    sectionBox.Max = max;
 
    // Create wall section view
 
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( "Create Wall Section View" );
 
      ViewSection.CreateSection( doc, vft.Id, sectionBox );
 
      tx.Commit();
    }
    return Result.Succeeded;
  }
}

I tested the command in this simple project with three walls:

Here are the three section views created by running the command on all three walls:

The resulting section views are quite reasonably positioned:

Sign on the Dotted Line, Please

Question: I need the section box to equally surround the wall on both sides.

The section box generated by the code above has its dotted line in the middle of the wall.

How can I move the section box dotted line so that it is offset out of the wall instead?

Answer: The Min and Max properties of the bounding box determine the crop region and far clip distance. In the code above, I defined

  XYZ min = new XYZ( -w, minZ - offset, -offset );
  XYZ max = new XYZ( w, maxZ + offset, 0 );

This produces the dotted line in the middle of the wall, like this:

If I change the Max property Z value from zero to +offset, the section view dotted line is offset from the wall in the way you wish:

  XYZ min = new XYZ( -w, minZ - offset, -offset );
  XYZ max = new XYZ( w, maxZ + offset, offset );

This produces the dotted line offset to the other side of the wall:

Perpendicular, not Parallel

Question: How can I set up the section view to be perpendicular to the wall and located at the wall centre point?

Answer: Well, obviously the same parameters as above apply.

Here is one little additional nice twist, though: instead of calculating the required transformation vectors based on the vector from the wall start point to its end point, we can obtain the wall location line curve tangent at its midpoint using the ComputeDerivatives method. The advantage of this is that it will work for a curved wall as well.

Here as the method GetSectionViewPerpendiculatToWall taking a wall input argument. It sets up and returns a section box for the section view creation at the wall midpoint and perpendicular to its location line. It takes the wall thickness and height into account to set up a crop box showing just the wall with one foot of space around it:

/// <summary>
/// Return a section box for a view perpendicular 
/// to the given wall location line.
/// </summary>
BoundingBoxXYZ GetSectionViewPerpendiculatToWall(
  Wall wall )
{
  LocationCurve lc = wall.Location 
    as LocationCurve;
 
  // Using 0.5 and "true" to specify that the 
  // parameter is normalized places the transform
  // origin at the center of the location curve
 
  Transform curveTransform = lc.Curve
    .ComputeDerivatives( 0.5, true );
 
  // The transform contains the location curve
  // mid-point and tangent, and we can obtain
  // its normal in the XY plane:
 
  XYZ origin = curveTransform.Origin;
  XYZ viewdir = curveTransform.BasisX.Normalize();
  XYZ up = XYZ.BasisZ;
  XYZ right = up.CrossProduct( viewdir );
 
  // Set up view transform, assuming wall's "up" 
  // is vertical. For a non-vertical situation 
  // such as section through a sloped floor, the 
  // surface normal would be needed
 
  Transform transform = Transform.Identity;
  transform.Origin = origin;
  transform.BasisX = right;
  transform.BasisY = up;
  transform.BasisZ = viewdir;
 
  BoundingBoxXYZ sectionBox = new BoundingBoxXYZ();
  sectionBox.Transform = transform;
 
  // Min & Max X values define the section
  // line length on each side of the wall.
  // Max Y is the height of the section box.
  // Max Z (5) is the far clip offset.
 
  double d = wall.WallType.Width;
  BoundingBoxXYZ bb = wall.get_BoundingBox( null );
  double minZ = bb.Min.Z;
  double maxZ = bb.Max.Z;
  double h = maxZ - minZ;
 
  sectionBox.Min = new XYZ( -2 * d, -1, 0 );
  sectionBox.Max = new XYZ( 2 * d, h + 1, 5 );
 
  return sectionBox;
}

This produces the following section view through of a wall with a window in its midpoint:

Here is CreateWallSectionView.zip containing the entire source code, Visual Studio solution and add-in manifest for this command.

DocumentChanged versus Dynamic Model Updater

Here is an interesting little overview and comparison of possibilities to react efficiently to the addition of certain elements to the database. Two easy ways to achieve this are by subscribing to the unspecific DocumentChanged event, or by registering a more specific DMU dynamic model updater. If you subscribe to an event or register an updater, it is also important to keep in mind to unsubscribe or unregister when you are done with it.

We discussed both of these repeatedly in the past, e.g. when looking at preventing element deletion and avoiding Idling.

In this case, the aim is to display a message box to the user when a new elevation view is added.

Subscribe to DocumentChanged to React to Elevation View Creation

It is easy to detect when a specific element is added, such as a new elevation view, for instance by subscribing to the DocumentChanged event. This can be done either in the OnStartup method of an external application or from an external command. In either case, you should pay attention to also unsubscribe from the event when it is no longer needed, for instance on application shutdown, at the end of the command, or from some other place.

In order to test the behaviour simply from within the standard framework of The Building Coder sample collection, I implemented a simple external command CmdElevationWatcher subscribing to the event. The event handler receives a DocumentChangedEventArgs instance providing three separate collections of ids of added, deleted and modified elements. We pass in the list of added ids to the FindElevationView method, which returns the first elevation view in the given element id collection if one exists, causing a message box listing it to be displayed.

Here is the entire code of this external command implementation:

/// <summary>
/// React to elevation view creation subscribing to DocumentChanged event
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
class CmdElevationWatcher : IExternalCommand
{
  /// <summary>
  /// Return the first elevation view found in the 
  /// given element id collection or null.
  /// </summary>
  static View FindElevationView(
    Document doc,
    ICollection<ElementId> ids )
  {
    View view = null;
 
    foreach( ElementId id in ids )
    {
      view = doc.GetElement( id ) as View;
 
      if( null != view
        && ViewType.Elevation == view.ViewType )
      {
        break;
      }
 
      view = null;
    }
    return view;
  }
 
  /// <summary>
  /// DocumentChanged event handler
  /// </summary>
  static void OnDocumentChanged(
    object sender,
    DocumentChangedEventArgs e )
  {
    Document doc = e.GetDocument();
 
    View view = FindElevationView( 
      doc, e.GetAddedElementIds() );
 
    if( null != view )
    {
      string msg = string.Format( 
        "You just created an "
        + "elevation view '{0}'. Are you "
        + "sure you want to do that? "
        + "(Elevations don't show hidden line "
        + "detail, which makes them unsuitable "
        + "for core wall elevations etc.)", 
        view.Name );
 
      TaskDialog.Show( "ElevationChecker", msg );
    }
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    Application app = uiapp.Application;
 
    // Subscribe to DocumentChanged event
 
    app.DocumentChanged
      += new EventHandler<DocumentChangedEventArgs>(
        OnDocumentChanged );
 
    return Result.Succeeded;
  }
}

After this command has been executed, the event is subscribed to. Any subsequent elevation view insertion results in the message box being displayed, for instance when I duplicate the East elevation view:

This approach has two significant disadvantages:

1. It reacts erroneously when a family is loaded.
2. Its performance is suboptimal.

1. When a family is loaded into a project, its views are also inserted with it. This insertion currently triggers a DocumentChanged event on the elevation views as well. For instance, if I load the standard rectangular column 'family M_Rectangular Column.rfa', a similar message appears:

This is unintentional and potentially confusing.

2. The performance is not optimal, since DocumentChanged reacts to each and every modification of the document. Furthermore, every single added element needs to be examined to check whether it is an elevation view.

Both of these disadvantages can easily be avoided by using the dynamic model update mechanism DMU instead.

Install Dynamic Model Updater to React to Elevation View Creation

As said, the dynamic model updater mechanism can easily be used to determine that specific elements have been added to the database, and it avoids the DocumentChanged event disadvantages mentioned above, since it reacts only to certain well-defined modifications on a certain well-defined set of elements used to set up the updater trigger.

First we need to implement our updater class to display a message if an elevation view is added:

/// <summary>
/// Updater notifying user if an 
/// elevation view was added.
/// </summary>
public class ElevationWatcherUpdater : IUpdater
{
  static AddInId _appId;
  static UpdaterId _updaterId;
 
  public ElevationWatcherUpdater( AddInId id )
  {
    _appId = id;
 
    _updaterId = new UpdaterId( _appId, new Guid(
      "fafbf6b2-4c06-42d4-97c1-d1b4eb593eff" ) );
  }
 
  public void Execute( UpdaterData data )
  {
    Document doc = data.GetDocument();
    Application app = doc.Application;
    foreach( ElementId id in 
      data.GetAddedElementIds() )
    {
      View view = doc.GetElement( id ) as View;
 
      if( null != view 
        && ViewType.Elevation == view.ViewType )
      {
        TaskDialog.Show( "ElevationWatcher Updater",
          string.Format( "New elevation view '{0}'",
            view.Name ) );
      }
    }
  }
 
  public string GetAdditionalInformation() 
  { 
    return "The Building Coder, "
      + "http://thebuildingcoder.typepad.com"; 
  }
 
  public ChangePriority GetChangePriority() 
  { 
    return ChangePriority.FloorsRoofsStructuralWalls; 
  }
 
  public UpdaterId GetUpdaterId() 
  { 
    return _updaterId; 
  }
 
  public string GetUpdaterName() 
  {
    return "ElevationWatcherUpdater";
  }
}

With this in place, we can implement a second external test command CmdElevationWatcherUpdater to instantiate and register our updater and define a trigger for it. The trigger reacts only to the creation of new view elements:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  Application app = uiapp.Application;
 
  // Register updater to react to view creation
 
  ElevationWatcherUpdater updater 
    = new ElevationWatcherUpdater(
      app.ActiveAddInId );
 
  UpdaterRegistry.RegisterUpdater( updater );
 
  ElementCategoryFilter f
    = new ElementCategoryFilter(
      BuiltInCategory.OST_Views );
 
  UpdaterRegistry.AddTrigger(
    updater.GetUpdaterId(), f,
    Element.GetChangeTypeElementAddition() );
 
  return Result.Succeeded;
}

After this command has been executed once, the updater is registered and its trigger installed. Like before, any subsequent elevation view insertion results in its message box being displayed, for instance when I again duplicate the East elevation view:

Unsubscribe from Event and Unregister Updater

Before letting this loose on the general public, I thought I would be a good citizen for the nonce and clean up after myself.

To do so, I modified both command implementations so that each call to the command toggles the event subscription or updater registration on and off.

In both cases, this was very easily achieved. I simply implemented a static member variable to hold the event handler delegate or the updater and initialised it to null. It looks like this for the DocumentChanged event handler:

  /// <summary>
  /// Keep a reference to the handler, so we know 
  /// whether we have already registered and need 
  /// to unregister or vice versa.
  /// </summary>
  static EventHandler<DocumentChangedEventArgs> 
    _handler = null;

It is even simpler for the updater:

  /// <summary>
  /// Keep a reference to the updater, so we know 
  /// whether we have already registered and need 
  /// to unregister or vice versa.
  /// </summary>
  static ElevationWatcherUpdater _updater = null;

Each time the command is run, it either subscribes/registers and sets the reference if it was null previously, or unsubscribes/unregisters and nulls it in the other case. Here is the relevant updated code snippet for the DocumentChanged event:

  if( null == _handler )
  {
    _handler
      = new EventHandler<DocumentChangedEventArgs>(
        OnDocumentChanged );
 
    // Subscribe to DocumentChanged event
 
    app.DocumentChanged += _handler;
  }
  else
  {
    app.DocumentChanged -= _handler;
    _handler = null;
  }

Here is the corresponding code for DMU:

  if( null == _updater )
  {
    _updater = new ElevationWatcherUpdater(
      app.ActiveAddInId );
 
    // Register updater to react to view creation
 
    UpdaterRegistry.RegisterUpdater( _updater );
 
    ElementCategoryFilter f
      = new ElementCategoryFilter(
        BuiltInCategory.OST_Views );
 
    UpdaterRegistry.AddTrigger(
      _updater.GetUpdaterId(), f,
      Element.GetChangeTypeElementAddition() );
  }
  else
  {
    UpdaterRegistry.UnregisterUpdater( 
      _updater.GetUpdaterId() );
 
    _updater = null;
  }

Here is version 2013.0.99.0 of The Building Coder samples including the two new commands.

I hope you find this comparison useful, appreciate how simple both of these mechanisms are to use, and understand the advantages offered by the DMU.

Addendum: As Victor very correctly points out below, I omitted highlighting the main difference between the DocumentChanged event and the DMU mechanism, since we have discussed it several times in the past:

The DocumentChanged event is not raised until after the transaction causing it has been closed, so the changes made cannot be cancelled. If elements were deleted, they are gone by the time you receive the notification; all you receive from the event handler argument is their element ids, and you cannot even find out what type they were. The updater is called within the same transaction as the modification causing it, providing much more control.