The Building Coder

Store Structured Data

After yesterday's exciting and successful Revit Family API webcast, here is a complete and mature solution to a frequently asked question that I mulled over for some time.

Question: I read your post on creating a shared parameter on the model group, which also shows how I can store arbitrary application data on almost any Revit element. However, due to the way that Revit parameters are defined, the type of the data item contained within the parameter is limited to Double, Integer, String or ElementId. What can I do to store arbitrary structured application data in a Revit project file?

Answer: Just as you say, the data types supported by Revit parameters are limited to integer, real, string or element id. The string data type will allow you to store any kind of data in a single parameter, as long as it is represented as a string. Obviously, any kind of data can be encoded into string format. You can either implement code to do this yourself, or make use of existing functionality provided by the .NET framework or other sources.

In case you are worrying about the data size, you can store strings of any length in a Revit string-valued parameter. This technique has been used to store some pretty large strings in Revit parameters. As far as we know, the only limitation is memory size, but of course Revit has never been exhaustively tested in this context. So please be aware, as always, that you are using this technique at your own risk!

You can peek into the parameter string value using RvtMgdDbg; although it will display only a certain maximum number of characters, you can still copy and paste the complete data into an editor using Ctrl + C and Ctrl + V.

The final encoding of binary data to a string can be achieved using base64 encoding, for example, which is provided by the .NET Convert.ToBase64String method. The retrieval of the string data to a binary representation can be achieved using Convert.FromBase64String.

The data being stored can also be compressed by using the zip file format, for instance with the zlib library implementing compression and decompression algorithms for the zip data specification. A port of zlib to C# is provided by #ziplib, whose usage is discussed in this MSDN article including some background info and an example usage. Other links are provided in the article describing the file format.

Once you have the structured binary data in its final form, whether compressed or not, some method to convert it to string format needs to be defined and implemented. A simple possibility is to implement a .NET class to hold the structured data and set the .NET attribute [Serializable] on it. Then the .NET framework can automagically serialise it into a binary stream for you, which can then be either compressed or directly encoded into a base64 string for storage in the Revit string-valued parameter.

Here is a more detailed description of the technique using the Serializable attribute:

Generic Compound Parameters

Question: How can we store any kind of custom data in a Revit model, be it a large XML file, a binary chunk, or other custom data? Shared parameters can be used to store text, numbers, URLs, Boolean Yes/No values, but not for any complex data structures such as custom objects and binary chunks.

Answer: If the complex data is converted to a string, it can be stored in any text parameter. Per-object data can be stored in the appropriate Revit element parameters, per-document data on the Project Information singleton.

Various techniques exist to package complex data structures into strings, i.e. algorithmically pack and unpack: XML serialisation, SOAP serialisation, custom XML, custom algorithms and more. The drawback of custom algorithms is obviously the additional development effort required; furthermore, the resulting string size may be non-optimal. A simple solution is provided by the .NET framework:

• Declare the custom .NET class as [Serializable].
• Serialise and deserialise it using a binary formatter.
• Encode and decode the binary data to and from text using base64 encoding.

Converting from binary to text using only printable characters only causes a 33% size increase. Furthermore, it can be achieved in just a few lines of code in .NET.

Here is the skeleton of an example class declaration:

  [Serializable()]
  public class B
  {
    . . .
  }

This code converts an instance 'obj' into a string which can be stored in a Revit parameter by serialising into a binary stream and then encoding the binary data in a base64 string:

  BinaryFormatter f = new BinaryFormatter();
  MemoryStream stream = new MemoryStream();
  f.Serialize( stream, obj );
  stream.Position = 0;
 
  long n2 = stream.Length;
  int n = (int) n2;
  byte[] buf = new byte[n];
  stream.Read( buf, 0, n );
  return Convert.ToBase64String( buf );

To retrieve the data from Revit, the string is read from the parameter, decoded back to binary data, and deserialised:

  MemoryStream s = new MemoryStream( Convert.FromBase64String( s64 ) );
  s.Position = 0;
 
  BinaryFormatter f = new BinaryFormatter();
  return f.Deserialize( s );

Additional notes:

1. Make sure to use invisible parameters to avoid any user interface issues.
2. If you already have other binary chunks, custom packed by yourself or otherwise, then you do not need the first part to serialise the class instance, but just the base64 encoding of the binary chunk.
3. If you implement the simplest form listed above, then deserialisation will work only if your DLL is located in the same folder as Revit.exe. If it is not, you will see an error saying something like this:

System.Runtime.Serialization.SerializationException
Unable to find assembly 'StoreData, Version=1.0.0.0, 
  Culture=neutral, PublicKeyToken=null'.

One solution is to ensure that assembly resides in same directory as acad.exe or Revit.exe. To make it work regardless of where your DLL is located, you need a custom deserialisation helper class such as the following:

public sealed class JtLinkBinder 
  : System.Runtime.Serialization.SerializationBinder
{
  public override System.Type BindToType( 
    string assemblyName, 
    string typeName )
  {
    return Type.GetType( string.Format( "{0}, {1}", 
      typeName, assemblyName ) );
  }
}

Using the custom serialisation binder class, the deserialisation to convert the string back to binary data looks like this:

  BinaryFormatter f = new BinaryFormatter();
  // add this line to avoid the "unable to find assembly" issue:
  f.Binder = new JtLinkBinder(); 
  return f.Deserialize( s );

Here is a complete Visual Studio solution StoreData implementing an example class and the storage functionality in a Revit parameter.

Scale a Curve

Now let us get back to really practical things again, after the practical notes on impractical things, and the more or less practical boot camp note.

Question: I have a CurveArray object containing data defined in inches. Now I need to scale it to feet in order to feed it into a Revit API method to create an extrusion. How can I perform this scaling operation? I would obviously prefer not having to rebuild the entire CurveArray. How does one apply a scale factor to an existing CurveArray?

I tried iterating over the Curve objects in the CurveArray but cannot figure out how to change the existing X, Y and Z coordinate values of the Curve objects.

There appears to be a Multiply function for the XYZ object, which doesn't actually act on the XYZ object itself, but instead acts on and returns a new copy of the original object. No such function appears to exist for the Curve, CurveArray or CurveArrArray objects.

Even if it did, acting on a copy wouldn't achieve the desired result. A 'Scale' method for the XYZ, Curve, CurveArray and CurveArrArray objects, which acts on the data in those objects directly, would be a great thing to have. It is especially important due to the fact that Revit requires the data be in one specific set of database units only, for example when submitting it to functions for doing things like creating an extrusion.

Answer: Unfortunately, this is not possible in the current API. You need to create a new curve. Here is an idea which may at least partly alleviate the problem:

Curve.get_Transformed() can be used to simplify the process of creating a new curve scaled as desired.

public void ScaleCurves()
{
  CurveArray cArray = PrepareCurveArray();
 
  Transform x = Transform.Identity;
  x = x.ScaleBasis( 1.0 / 12.0 );
 
  int numCurves = cArray.Size;
  for( int i = 0; i < numCurves; ++i )
  {
    Curve curve = cArray.get_Item( i );
 
    Curve newCurve = curve.get_Transformed( x );
 
    cArray.set_Item( i, newCurve );
  }
 
  WriteProfile( "After transformation", cArray );
}

You are still creating new curves, but not required to figure out how to scale each curve independently based on type.

Reply: That is definitely helpful code. I've been writing some extension methods to get around some of the limitations, essentially adding my own functions to the class definitions provided by the Revit API so my methods 'look' like they are part of the API itself. This new method for scaling curves is much cleaner than what I came up with, so I will definitely replace my extension method with this code.

On a very vaguely related note, here is a pointer to some Revit tools for both users and developers:

Revit Family Tools

Version 2.3.0.0 of the Revit Family Tools is available from the Revit Tools page with the following functionality useful for all flavours of Revit:

• Comparing shared parameter files.
• Merging shared parameter files.
• Deleting RFA backup files, optionally recursively.
• Copying CSV files created for Type Catalog usage to TXT files for easy change testing.
• Reporting the versions of Revit used to create family files, optionally recursively.

Retrieving Newly Created Elements

The day before yesterday, I demonstrated the use of the Mirror method. Henrik Bengtsson of Lindab immediately came back with a question on this. Funnily enough, the reason I quickly posted the article the day before yesterday was because someone completely different asked the exact same two questions as Henrik in the exact same sequence. There seems to be some kind of morphogenetic resonance going on among Revit developers. Anyway, here is Henrik's question:

Question: The mirror command works all right according to the description. I now face another issue that I had not thought of before. How can I get a reference to the newly created mirrored objects? Those are actually the objects that I want to continue working with.

Answer: Because this question was already asked once this morning, I had some time to meditate deeply on how to retrieve the newly created elements generated by the mirroring operation. My first idea was to grab them by parsing the tail of the journal file, but unfortunately they are not listed there. My second idea works, however:

• Ask the document for all its elements before the mirroring operation and remember the total number n.
• Call the Mirror method, generating a number of new elements.
• Ask the document for all its elements again, and retrieve the ones whose index exceeds n.

I make use of two helper methods for this:

• GetElementCount determines the total number of document elements before the mirroring operation.
• GetElementsAfter returns a list of all document elements whose index exceeds a given number.

Here is the implementation of these two methods:

int GetElementCount( Document doc )
{
  int count = 0;
  ElementIterator it = doc.Elements;
  while( it.MoveNext() ) 
  { 
    ++count; 
  }
  return count;
}
 
List<Element> GetElementsAfter( int n, Document doc )
{
  List<Element> a = new List<Element>( n );
  ElementIterator it = doc.Elements;
  int i = 0;
 
  while( it.MoveNext() ) 
  {
    ++i;
 
    if( n < i )
    {
      a.Add( it.Current as Element );
    }
  }
  return a;
}

Here is the code for the new external command implementing this. It is a simple extension of the mirroring command CmdMirror presented on Wednesday:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
ElementSet els = doc.Selection.Elements;
 
Line line = app.Create.NewLine( 
  XYZ.Zero, XYZ.BasisX, true );
 
int n = GetElementCount( doc );
 
doc.Mirror( els, line );
 
List<Element> a = GetElementsAfter( n, doc );
 
string s = "The following elements were mirrored:\r\n";
 
foreach( Element e in a )
{
  s += string.Format( "\r\n  {0}",
    Util.ElementDescription( e ) );
}
Util.InfoMsg( s );
 
return CmdResult.Succeeded;

Here is version 1.1.0.41 of the complete Visual Studio solution including the mirroring command CmdMirror and the new command CmdMirrorListAdded.

Disclaimer: Please note that there is nothing in the Revit API documentation stating that the iterator returned by doc.Elements will traverse the elements in the order they were added to the database. That happens to be the case today and has been so in the past. This behaviour may change without notice in the future.

Space Adjacency

We looked at the topic of room and wall adjacency a while back. Martin Schmid now implemented a nice little related utility to check adjacencies between spaces. It demonstrates a beautiful use of the new Space.IsPointInSpace method. Here is an example of the kind of situation he is interested in:

The aim is to obtain a list of all adjacent spaces from this model.

Martin added a new external command CmdSpaceAdjacency to The Building Coder sample application to analyse and report the space adjacency relationships in such a model. Here are some more implementation notes on this from Martin:

Basically, this command starts by collecting all the segments from all spaces, tessellating any curved segments. It then iterates each space's segments over all the other spaces' segments to find the segment 'closest' to it. This is done by FindClosestSegments( segmentPairs, segments );

However, just because a pair of segments from two different spaces are 'close' to one another, doesn't necessarily mean they are to be considered adjacent. There could be an outlying 'space', e.g., a storage shed or garage, and one surface of the space would be considered 'closest' to the main building itself, but in terms of being 'adjacent' for analysis, there is actually a considerable 'air space' between them. Therefore, we need to limit how far apart spaces can be to be considered adjacent.

To achieve this, DetermineAdjacencies( spaceAdjacencies, segmentPairs ) checks whether the midpoints between each pair are closer than a specified tolerance. It also calculates a test point that should be within the adjacent space and uses the new Space.IsPointInSpace method to check whether this is true.

This work s on the test models so far. I have not yet tested on a larger dataset. The implementation is probably not optimal, but is a start.

After speaking with a customer about this, I learned that they needed to limit 'adjacency' to spaces that share a common door between them. Implementing this was actually a little more straightforward: each door knows its 'to room' and 'from room', and this can be queried from the model by inspecting the 'linked' model data. Each space knows what room encloses it, and this info is available in the 'host' model. Thus, I was able to establish a relationship between doors and Spaces to figure out the adjacencies. So that is yet another different method for a different analysis scenario.

It would be nice if there was actually a relationship in Revit between spaces and the walls that enclose it. Also, this is all more cumbersome when working with linked files. There may be another route, for instance if the ray intersection algorithm could be used to intelligently to seek for room or space boundaries and wall surfaces only. However, I found that in linked models, it seems that there is no way to determine exactly what object is being hit by the ray. Apparently, it only tells you that it hit a 'linked model', but not what particular object or type within that linked model. There are probably some API requirements to eke out of these example scenarios, but I'll leave that for later.

So much for Martin's explanation of this algorithm and other related work of his. Here are some more comments of mine on this command implementation based on reverse engineering:

The CmdSpaceAdjacency command works with the following data items:

• Segment: a helper class to manage a space boundary segment, managing start and end point and the associated space and including some methods to obtain and compare slope and distance to other segments.
• List<Segment> segments: a list of all spaces' boundary segments.
• Dictionary<Segment, Segment> segmentPairs: a dictionary mapping each segment to the closest other segment in the set.
• Dictionary<Space, List<Space>> spaceAdjacencies: a dictionary mapping each space to a list of all other spaces directly adjacent to it.

This data is generated and processed step by step by the following methods:

GetBoundaries: determine all boundary segments for a given space. This method is applied in a loop to all selected spaces, or all spaces in the project if none were manually preselected.
• FindClosestSegments: iterate over the list of segments and determine the closest other segment for each one. This is not fool-proof, since it simply calculates the distance between the midpoints of each segment.
• DetermineAdjacencies: determine the space adjacencies from the pairs of closest boundary segments using the Space.IsPointInSpace method.
• ReportAdjacencies: print the results to the Visual Studio debug output console.

Here is the Segment class implementation:

class Segment
{
  XYZ _sp;
  XYZ _ep;
  Space _space;
 
  public XYZ StartPoint
  {
    get { return _sp; }
  }
 
  public XYZ EndPoint
  {
    get { return _ep; }
  }
 
  public Space Space
  {
    get { return _space; }
    set { _space = value; }
  }
 
  public Segment( XYZ sp, XYZ ep, Space space )
  {
    _sp = sp;
    _ep = ep;
    _space = space;
  }
 
  public double Slope
  {
    get
    {
      double deltaX = _sp.X - _ep.X;
      double deltaY = _sp.Y - _ep.Y;
      if( deltaX != 0 )
      {
        return deltaY / deltaX;
      }
      return 0;
    }
  }
 
  public bool IsHorizontal
  {
    get
    {
      return _sp.Y == _ep.Y;
    }
  }
 
  public bool IsVertical
  {
    get
    {
      return _sp.X == _ep.X;
    }
  }
 
  public new string ToString()
  {
    return string.Format( "{0} {1}",
      Util.PointString( _sp ),
      Util.PointString( _ep ) );
  }
 
  public XYZ MidPoint
  {
    get
    {
      return _sp + 0.5 * ( _ep - _sp );
    }
  }
 
  public XYZ DirectionTo( Segment a )
  {
    XYZ v = a.MidPoint - MidPoint;
    return v.IsZero ? v : v.Normalized;
  }
 
  public double Distance( Segment a )
  {
    return MidPoint.Distance( a.MidPoint );
  }
 
  public bool Parallel( Segment a )
  {
    return ( IsVertical && a.IsVertical )
      || ( IsHorizontal && a.IsHorizontal )
      || Util.IsEqual( Slope, a.Slope );
  }
}

GetBoundaries simply asks a space for its boundary curves, tessellates them, and generates Segment instances for the result:

private void GetBoundaries(
  List<Segment> segments,
  Space space )
{
  BoundarySegmentArrayArray boundaries
    = space.Boundary;
 
  foreach( BoundarySegmentArray b in boundaries )
  {
    foreach( BoundarySegment s in b )
    {
      Curve curve = s.Curve;
      XYZArray a = curve.Tessellate();
      for( int i = 1; i < a.Size; i++ )
      {
        Segment segment = new Segment(
          a.get_Item( i - 1 ),
          a.get_Item( i ), space );
 
        segments.Add( segment );
      }
    }
  }
}

FindClosestSegments iterates over the list of segments and determines the closest other segment for each one by comparing the distance between their midpoints, returning The resulting closest pairs:

private void FindClosestSegments(
  Dictionary<Segment, Segment> segmentPairs,
  List<Segment> segments )
{
  foreach( Segment segOuter in segments )
  {
    bool first = true;
    double dist = 0;
    Segment closest = null;
 
    foreach( Segment segInner in segments )
    {
      if( segOuter == segInner )
        continue;
 
      if( segInner.Space == segOuter.Space )
        continue;
 
      double d = segOuter.Distance(
        segInner );
 
      if( first || d < dist )
      {
        dist = d;
        first = false;
        closest = segInner;
      }
    }
 
    segmentPairs.Add( segOuter, closest );
  }
}

DetermineAdjacencies determines the space adjacencies from the pairs of closest boundary segments using the Space.IsPointInSpace method. It analyses the relationship between the two closest segments s and t. If their distance exceeds the maximum wall thickness, the spaces are not considered adjacent. Otherwise, a test point two millimetres away from s in the direction of t is calculated and the Space.IsPointInSpace method applied to it to test whether it really lies within the candidate neighbouring space:

private void DetermineAdjacencies(
  Dictionary<Space, List<Space>> a,
  Dictionary<Segment, Segment> segmentPairs )
{
  foreach( Segment s in segmentPairs.Keys )
  {
    Segment t = segmentPairs[s];
    double d = s.Distance( t );
    if( d < MaxWallThickness )
    {
      XYZ direction = s.DirectionTo( t );
      XYZ startPt = t.MidPoint;
      XYZ testPoint = startPt + direction * D2mm;
      if( t.Space.IsPointInSpace( testPoint ) )
      {
        if( !a.ContainsKey( s.Space ) )
        {
          a.Add( s.Space, new List<Space>() );
        }
        if( !a[s.Space].Contains( t.Space ) )
        {
          a[s.Space].Add( t.Space );
        }
      }
    }
  }
}

Finally, ReportAdjacencies prints the results to the Visual Studio debug output console:

private void PrintSpaceInfo(
  string indent,
  Space space )
{
  Debug.Print( "{0}{1} {2}", indent,
    space.Name, space.Number );
}
 
private void ReportAdjacencies(
  Dictionary<Space, List<Space>> spaceAdjacencies )
{
  Debug.WriteLine( "\nReport Space Adjacencies:" );
  foreach( Space space in spaceAdjacencies.Keys )
  {
    PrintSpaceInfo( "", space );
    foreach( Space adj in spaceAdjacencies[space] )
    {
      PrintSpaceInfo( "  ", adj );
    }
  }
}

Here is the code of the Execute method which performs these steps in sequence:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
List<Element> spaces = new List<Element>();
if( !Util.GetSelectedElementsOrAll(
  spaces, doc, typeof( Space ) ) )
{
  Selection sel = doc.Selection;
  message = (0 < sel.Elements.Size)
    ? "Please select some space elements."
    : "No space elements found.";
  return CmdResult.Failed;
}
 
List<Segment> segments = new List<Segment>();
 
foreach( Space space in spaces )
{
  GetBoundaries( segments, space );
}
 
Dictionary<Segment, Segment> segmentPairs
  = new Dictionary<Segment, Segment>();
 
FindClosestSegments( segmentPairs, segments );
 
Dictionary<Space, List<Space>> spaceAdjacencies
  = new Dictionary<Space, List<Space>>();
 
DetermineAdjacencies(
  spaceAdjacencies, segmentPairs );
 
ReportAdjacencies( spaceAdjacencies );
 
return CmdResult.Failed;

Here is the result of running the new command CmdSpaceAdjacency on the sample shown above:

Report Space Adjacencies:

Space 1 1
  Space 2 2
Space 2 2
  Space 4 4
  Space 3 3
  Space 1 1
Space 3 3
  Space 2 2
  Space 4 4
Space 4 4
  Space 2 2
  Space 5 5
  Space 3 3
Space 5 5
  Space 4 4

Here is version 1.1.0.38 of the complete Visual Studio solution with the new command.

As Martin pointed out above, this sample provides a solution for one specific case. It may not be totally reliable under all circumstances, and as Martin already discovered, many other approaches and different requirements for space adjacency analysis may occur. It does however provide a wonderful example of what can be achieved with relatively little effort. And as said, it also shows a really nice use of the new Space.IsPointInSpace method.

Very many thanks to Martin for providing this interesting sample!

Language Integrated Query Linq

The Language Integrated Query or Linq is a .NET Framework component that adds powerful native data querying capabilities to .NET languages.

Here is a contribution by Joel Karr of Environmental Systems Design, Inc on this exciting topic, demonstrating how it can be used to achieve huge performance improvements when analysing large Revit models.

Using LINQ to Query

Here at Environmental Systems Design, www.esdesign.com, we have seen that a simple task in Revit, such as changing a single parameter of an object, can take an immense amount of time when multiplied over thousands of elements in a model. Through the use of LINQ, we have found that we have a wide range of powerful query tools that can help us avoid the costly time associated with constant calls to the Revit API. We can store the information we need once, and then efficiently query that data in a similar way to the familiar SQL database queries.

LINQ was introduced with the .NET Framework 3.5. The main benefit is an advanced native data query capability. For example, if we wanted to find all diffusers in a model that had a CFM of over 500, we could use a LINQ query to find them:

  var results 
    = from d in allDiffusers
      let x = 500
      where d.CFM < x
      select d;

Although LINQ takes a little more time to set up initially, repeated queries will perform much faster. We had an instance where we wanted to place nearly 15,000 connectors in our model to correspond with an architectural model.

LINQ queries have a running time of O(n), but when used with Revit we find that we can greatly reduce our search time if we store information in an object that we will reuse. Our initial method kept a list of elements and then checked each element.Location for a match. This caused us to use the Revit API thousands of times unnecessarily. By storing the location in an object and then using LINQ to find a match, our process time went from over 14 hours down to under 10 minutes.

We created an object that stored the information about each lighting fixture in the architect's model and also the information we needed about our connectors. Through the use of a LINQ query, we were able to search to see if a connector existed at the same location as the architect's lighting fixture.

It became as simple as the following code to find out if a connector existed in the same location as the lighting fixture we were checking:

  var found 
    = from con in Connectors
      where con.ConLocation.Equals( location )
      select con;

LINQ can work with a ton of different type of data sources. Some of the most popular are SQL, XML, ADO.NET datasets, .NET objects and several other third party sources which even include an ongoing project for the creation of LINQ to Google. In order to keep our code self contained and as simple as possible, we create a custom object to use with our LINQ queries.

To start with, we need to create a new class to store the information that we would like to query:

class InstanceData
{
  #region Field Data
  private Element _instance;
  private String _param1;
  private bool _param2;
  private int _param3;
  #endregion
 
  #region Properties
  public Element Instance
  {
      get { return _instance; }
      set { _instance = value; }
  }
  public String Param1
  {
      get { return _param1; }
      set { _param1 = value; }
  }
  public bool Param2
  {
      get { return _param2; }
      set { _param2 = value; }
  }
  public int Param3
  {
      get { return _param3; }
      set { _param3 = value; }
  }
  #endregion
 
  #region Constructors
  public InstanceData( Element instance )
  {
    Instance = instance;
 
    foreach( Parameter param in Instance.Parameters )
    {
      // Param1 returns string value
      if( param.Definition.Name == "Param1" )
      {
        Param1 = param.AsString();
      }
 
      // Param2 is a checkbox returning 0 or 1
      if( param.Definition.Name == "Param2" )
      {
        Param2 = (0 != param.AsInteger());
      }
 
      // Param3 returns an integer value
      if( param.Definition.Name == "Param3" )
      {
        Param3 = param.AsInteger();
      }
    }
  }
  #endregion
}

Now that we have our custom class created, we just need to populate it with the data we would like to query. This can be done many ways. For this example we will simply retrieve all the family instances in the model:

CreationFilter cf = app.Create.Filter;
Filter f1 = cf.NewTypeFilter( typeof( FamilyInstance ) );
 
List<Element> a = new List<Element>();
doc.get_Elements( f1, a );
 
List<InstanceData> instanceDataList 
  = new List<InstanceData>();
 
foreach( Element e in a )
{
  instanceDataList.Add( 
    new InstanceData( e ) );
}
 
string s = "value1";
bool b = true;
int i = 42;
 
var found = from instance in instanceDataList where 
  (instance.Param1.Equals( s )
  && b == instance.Param2
  && i < instance.Param3)
select instance;
 
foreach( InstanceData instance in found )
{  
  // Do whatever you would like
}

So that was it from Joel, and back to Jeremy again. Thank you ever so much, Joel, for this fantastic introduction and example!

While preparing this article, I was a bit stumped to compile the sample code as part of The Building Coder samples until I noticed that I have to switch to the .NET Framework 3.5 before I can use Linq in C#. Watch out for this if you are trying to add Linq functionality to existing older projects.

Two things to note here, which make this information ever more globally usable:

• This is a very powerful optimisation technology in any environment, whether inside of Revit or elsewhere.
• Possibly the same kind of performance enhancement could be achieved by using some other caching mechanism independent of Linq. The main factor here is possibly the local storage of the data to be processed, avoiding repeated expensive calls to query it from Revit.

One extremely powerful advantage of Linq is its extremely readable query syntax.

Convex Hull and Volume Computation

Max raised an interesting question in a comment on the discussion on the calculation of 2D polygon areas:

Question: If I have an array of 3d points, how can I do to get volume information?

Answer: The answer is maybe not quite as easy as you expected. To calculate that volume, you have to solve two tasks:

• Determine the convex hull of the given point cloud.
• Calculate the volume of the resulting 3D polyhedron.

Both of these steps are non-trivial. A number of different convex hull algorithms exist both for the two-dimensional and for higher dimensional cases. Several open source libraries for solid modelling or computational geometry implement these. One of the best known and most reliable tools which is specifically targeted at these two issues is Qhull. Here is the blurb from its home page:

Qhull computes the convex hull, Delaunay triangulation, Voronoi diagram, halfspace intersection about a point, furthest-site Delaunay triangulation, and furthest-site Voronoi diagram. The source code runs in 2-d, 3-d, 4-d, and higher dimensions. Qhull implements the Quickhull algorithm for computing the convex hull. It handles roundoff errors from floating point arithmetic. It computes volumes, surface areas, and approximations to the convex hull.

I downloaded the current version of Qhull to explore exactly what you might be able to use for your purposes. The Qhull distribution includes a list of sample programs. One of these is qconvex, and one of its output options is FA to compute total area and volume of the input points, which is pretty exactly what you want.

Now how can you make use of this inside the Revit API?

Qhull is implemented in standard C, the Revit API is a .NET environment. The easiest way to make use of C source code from .NET is to compile a DLL and call it from .NET. In this case you would need to analyse the source code for the qconvex program, which is contained in the file qconvex.c, and package the required functionality in a DLL that you make accessible from .NET.

The relevant lines of code from qconvex.c are:

  qh_checkflags (qh qhull_command, hidden_options);
  qh_initflags (qh qhull_command);
  points= qh_readpoints (&numpoints, &dim, &ismalloc);
  qh_init_B (points, numpoints, dim, ismalloc);
  qh_qhull();
  qh_check_output();
  qh_produce_output();

This program reads its input from a file or the console standard input stream, performs its calculations, and produces its output into a file or the standard output stream. You would need to adapt this to pass the information from and to the .NET calling application.

Another alternative, possible much simpler, but obviously less efficient, would be to set up the .NET application to write and read files in the expected Qhull input and output formats and then execute the unchanged qconvex executable provided by the Qhull package.

Reply from Max: Very good this library, but we need a wrapper for .NET, and how can I encapsulate this library in a C# project?

What do you think about this alternative solution for polyhedra volume calculation?

Answer: The polyhedra volume calculation article looks interesting, it seems like a simple approach for solving the second part of the problem, the volume calculation. It still needs to be ported from Java to .NET, though. It also does nothing to help you with the first part of the problem, the determination of the convex hull.

Revit will not automatically provide a convex hull for a room or any element's faces and edges. Imagine an L-shaped room: its convex hull does not include some of the vertices of the walls in the inner corner. Imagine any shape at all that is not already convex. You need to eliminate all 'inner' vertices to obtain the convex hull.

Regarding access to Qhull from .NET, I explained two methods for making use of the library from a .NET client above:

• Create a DLL from the C code, and implement a C function that can be called from .NET, read the input from .NET, and return the output to .NET.
• Create a .NET application that writes and reads files in the expected Qhull input and output formats, and then execute the unchanged qconvex executable provided by the Qhull package as an external process using the files to communicate. Maybe you can use pipes instead of physical files on the disk.

Category Comparison and Model Elements Revisited

This is a follow-up to two previous posts, on category comparison and the selection of model elements.

Regarding the category comparison, we discussed the fact that categories cannot be compared directly, and one should use their element id instead. We also underlined that every category comparison should be made language independent by using the built-in category enumeration and not comparing the localised category names. The analysis of the model element selection examined how to eliminate the preview legend components from the selected elements, since they suddenly acquired geometry in Revit 2010 and also fit the other criteria applied in the selection process.

As Miroslav Schonauer pointed out, the model element selection that I suggested in that post will not work, because various model elements exist that do not have a valid level assigned to them. He suggests that the previous selection algorithm with an additional check added for the preview legend components probably remains the simplest and most reliable method.

One deplorable aspect of the code presented there with the preview legend component check added is its language dependence. It compares the element category name with the preview legend component one, which is "Legend Components". I left that in there because I thought I would use the alternative approach anyway, checking for a valid level.

So now the issue is how to compare a given element's category against a built-in one without using the category name. In previous similar situations, I achieved this by asking the document for the built-in category object and using its element id. The Revit developers guide includes some sample code which demonstrates an extremely effective alternative method. It avoids the string comparison and achieves language independence, and it also does not require the effort of querying the document settings for the element id of a built-it category.

For built-in categories, the value of the element id is exactly the same as the integer resulting from casting the built-in category enumeration value. The section 5.2.1 Category discusses details of the element category classification and explains:

An element's category is determined by the Category ID.

• Category IDs are represented by the ElementId class.
• Imported Category IDs correspond to elements in the document.
• Most categories are built-in and their IDs are constants stored in ElementIds.
• Each built-in category ID has a corresponding value in the BuiltInCategory Enumeration. They can be converted to corresponding BuiltInCategory enumerated types.
• If the category is not built-in, the ID is converted to a null value.

The Code Region 14-1: 'Distinguishing permanent dimensions from constraints' in section 14.1 'Dimensions and Constraints' shows that we can actually use the built-in enum value to compare with an element category id directly, as in the following excerpted lines:

  if ( (int) BuiltInCategory.OST_Dimensions
    == dimension.Category.Id.Value )
  {
    message += "\nDimension is a permanent dimension.";
  }

Making use of this for the model element selection, we can implement the following filter which is both language independent and efficient:

BuiltInCategory _bicPreviewLegendComponent 
  = BuiltInCategory.OST_PreviewLegendComponents;
 
public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  ElementIterator it = doc.Elements;
  string s = string.Empty;
  int count = 0;
 
  Geo.Options opt = app.Create.NewGeometryOptions();
 
  int iBic = (int) _bicPreviewLegendComponent;
 
  while( it.MoveNext() )
  {
    Element e = it.Current as Element;
 
    if ( !(e is Symbol)
      && !(e is FamilyBase)
      && (null != e.Category)
      && ( iBic != e.Category.Id.Value )
      && (null != e.get_Geometry( opt )) )
    {
      ++count;
      s += string.Format( 
        "\r\n  Category={0}; Name={1}; Id={2}",
        e.Category.Name, e.Name, 
        e.Id.Value.ToString() );
    }
  }
 
  s = "There are " + count.ToString() 
    + " model elements:" + s;
 
  LabUtils.InfoMsg( s );
 
  return CmdResult.Failed;
}

Here is a snapshot of an updated version of the Revit API introduction labs including the updated version of Lab 2-2 to select all model elements using this criterion and other on-going improvements we have made. In particular, it includes two completely new modules, Labs6 dealing with external application and event issues, and Labs7 demonstrating the form creation API. We are still continuing the process of updating and enhancing them for the Revit 2010 API and its new features. All of the labs are provided in two versions, one each for C# and VB. This version also includes a set of HTML instructions for self-learning and AdnSamples.txt, an include file for RvtSamples that I use to load all my external commands, updated to the 2010 RvtSamples format.

Revit Inside

By the way, if you are interested in seeing who else is using Revit, there is a Revit Inside website which tells you just that. The people running the list are always interested in new entries as well, so don't hesitate to check it out and sign up if it applies to you.

Imports in Families

I will have left on vacation once again by the time this is posted. In case you wonder why I am on vacation so much, the trip to Italy in March and the wonderful experiences I had there were actually to use up last year's contingent. Now I am getting started on this years', going off on a climbing and driving trip to southern France with my two sons Christopher and Cornelius, especially to the Provence and Avignon to visit my mother, sister and nephew. So I will be posting a bit less or not at all for the coming two weeks.

Before leaving, though, here is an interesting and practically oriented question by my colleague Martin Schmid of Autodesk. I wrote a new command for The Building Coder samples to answer it, which may even be useful for some in everyday life. Martin is an experienced AutoCAD MEP and Revit MEP expert and application engineer and helped me a lot with the preparation of the Revit MEP API class at Autodesk University.

Question: How hard do you think it would be to put together a quick bit of code that would:

1. Iterate over all family definitions in a project.
2. For each family definition, identify if there are any ‘import symbols’, i.e., imported DWG, SAT, DXF and other non-native Revit geometry?

The reason I ask is that performance is degraded if very complex geometry is imported. Some complaints about performance were caused by such complex imported geometry.

I have an example demonstrating slow graphics generation in a mechanical view with an ‘offending’ family. It takes more than 30 seconds to zoom in on the area with the ‘bad’ family. In the family editor, one can see that there is an imported DXF symbol at that location. If you return to the project and delete the offending family instances, the zoom is nearly instantaneous.

Unfortunately, it is difficult to isolate these family instances. I am hoping there is a simple way to check families using the API, instead of the rote manual inspection method I have relied on so far.

Do you think you could bang something together on this? I’ve got another large customer dataset to wade through, and was hoping for some help!

Answer: This is not at all hard to do. Here is a description of an algorithm that achieves what you need:

• Select all family instances.
• For each instance, open the corresponding family definition.
• Within the family definition, list all imported symbols.

We could also select the families themselves directly, without going over the instances first. I chose not to do so in the code presented below, because then we have to deal with various built-in families that are not actually used and we are not interested in anyway.

Here is the approach I have taken in more detail. I added an additional step to ensure every family is processed only once, even if multiple family instances refer to it. To achieve this, I create a dictionary mapping the family name to the family, and insert the families used by the family instances only if not already present. This way, I can later also process the families in alphabetical order, to make it easier to analyse the report produced. In-place families cannot be opened for editing, so we need to skip those. I am currently not aware of any way to examine their contents. Here are the detailed steps:

• Select all family instances.
• For each instance, determine its family.
• Add an entry to the family dictionary, if not already present.
• Sort the family dictionary keys.
• Open each non-in-place family and search for ImportInstance elements.
• List the total count and symbol names of all import instances found.

I added a new command class CmdImportsInFamilies to implement this functionality. Here is the source code of its Execute method:

public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  List<Element> instances = new List<Element>();
  doc.get_Elements( typeof( FamilyInstance ),
    instances );
 
  Dictionary<string, Family> families
    = new Dictionary<string, Family>();
 
  foreach( FamilyInstance i in instances )
  {
    Family family = i.Symbol.Family;
    if( !families.ContainsKey( family.Name ) )
    {
      families[family.Name] = family;
    }
  }
 
  List<string> keys = new List<string>(
    families.Keys );
 
  keys.Sort();
 
  foreach( string key in keys )
  {
    Family family = families[key];
    if( family.IsInPlace )
    {
      Debug.Print( "Family '{0}' is in-place.", key );
    }
    else
    {
      Document fdoc = doc.EditFamily( family );
 
      List<Element> imports = new List<Element>();
      fdoc.get_Elements( typeof( ImportInstance ),
        imports );
 
      int n = imports.Count;
 
      Debug.Print(
        "Family '{0}' contains {1} import instance{2}{3}",
        key, n, Util.PluralSuffix( n ),
        Util.DotOrColon( n ) );
 
      if ( 0 < n )
      {
        foreach( ImportInstance i in imports )
        {
          Debug.Print( "  '{0}'", i.ObjectType.Name );
        }
      }
    }
  }
  return CmdResult.Failed;
}

As usual, we return Failed when not modifying the database in any way, so that Revit understands that no changes were made to the project and no dirty flags need to be set.

I expect that this approach may need some tweaking to achieve the exact functionality you require, but I hope it provides a useful starting point at least.

After some initial testing, Martin came up with two requests for improvement:

• One thing I’m wondering about is that a family can have families nested in it. Have you considered that?
• In the attached project, the ‘Duplex Receptacle’ family has a nested ‘Annotation Symbol’ called ‘Duplex Annotation’. That ‘Duplex Annotation’ has a DWG nested in it. How can one inspect the annotation symbol for imports?

The initial solution above does indeed not take into account nested families.

Regarding the annotation symbols, we can in fact access the families used by them by making use of the property sequence AnnotationSymbol > AsFamilyInstance > Symbol > Family and then proceeding in the same way as for standard family symbols.

In order to adapt the code to support these two enhancements, I implemented two separate helper methods:

• GetFamilies to retrieve all families used by the family instances and annotation symbols in the given document and return a dictionary mapping the family name to the corresponding family object.
• ListImportsAndSearchForMore to list all import instances in all the given families, retrieve nested families within them, and recursively search in them as well.

Here is the source code for GetFamilies, taking an input document argument and returning a dictionary as described:

Dictionary<string, Family> GetFamilies( Document doc )
{
  Dictionary<string, Family> families
    = new Dictionary<string, Family>();
 
  List<Element> instances = new List<Element>();
  doc.get_Elements( typeof( FamilyInstance ),
    instances );
 
  foreach ( FamilyInstance i in instances )
  {
    Family family = i.Symbol.Family;
    if ( !families.ContainsKey( family.Name ) )
    {
      families[family.Name] = family;
    }
  }
 
  List<Element> annotations = new List<Element>();
  doc.get_Elements( typeof( AnnotationSymbol ),
    annotations );
 
  foreach ( AnnotationSymbol a in annotations )
  {
    Family family = a.AsFamilyInstance.Symbol.Family;
    if ( !families.ContainsKey( family.Name ) )
    {
      families[family.Name] = family;
    }
  }
  return families;
}

The two loops collect all family instances and annotation symbols and determine their families, respectively.

Here is the source code for ListImportsAndSearchForMore. Besides the input document argument and the dictionary of all families to list and explore further recursively, it also takes an argument indicating the recursion level, which is used to indent the output report appropriately according to the nesting level of the nested families:

void ListImportsAndSearchForMore(
  int recursionLevel,
  Document doc,
  Dictionary<string, Family> families )
{
  string indent
    = new string( ' ', 2 * recursionLevel );
 
  List<string> keys = new List<string>(
    families.Keys );
 
  keys.Sort();
 
  foreach ( string key in keys )
  {
    Family family = families[key];
 
    if ( family.IsInPlace )
    {
      Debug.Print( indent
        + "Family '{0}' is in-place.",
        key );
    }
    else
    {
      Document fdoc = doc.EditFamily( family );
 
      List<Element> imports = new List<Element>();
      fdoc.get_Elements( typeof( ImportInstance ),
        imports );
 
      int n = imports.Count;
 
      Debug.Print( indent
        + "Family '{0}' contains {1} import instance{2}{3}",
        key, n, Util.PluralSuffix( n ),
        Util.DotOrColon( n ) );
 
      if ( 0 < n )
      {
        foreach ( ImportInstance i in imports )
        {
          Debug.Print( indent
            + "  '{0}'", i.ObjectType.Name );
        }
      }
 
      Dictionary<string, Family> nestedFamilies
        = GetFamilies( fdoc );
 
      ListImportsAndSearchForMore(
        recursionLevel + 1, fdoc, nestedFamilies );
    }
  }
}

Using these two helper functions, the source code for the mainline of the Execute method is reduced to very little:

public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  Dictionary<string, Family> families
    = GetFamilies( doc );
 
  ListImportsAndSearchForMore( 0, doc, families );
 
  return CmdResult.Failed;
}

Running this in a project containing one family with an import symbol and another family with nested families within it produces the following output in the debug output window displayed by Debug > Windows > Output:

Family 'Family1' contains 1 import instance:
  'xr.dwg'
Family 'myFamily3' contains 0 import instances.
  Family 'M_Rectangular Column' contains 0 import instances.
  Family 'myFamily1' contains 0 import instances.
    Family 'M_Rectangular Column' contains 0 import instances.
  Family 'myFamily2' contains 0 import instances.
    Family 'M_Rectangular Column' contains 0 import instances.

In another project containing an annotation symbol with a nested family with an import symbol, it produces the following:

Family 'Duplex Receptacle' contains 0 import instances.
  Family 'Duplex Annotation' contains 1 import instance:
    'star.dwg'

Here is version 1.1.0.33 of the complete Visual Studio solution with the new command.

Model Line Sketch Plane

Model lines always reside in a sketch plane, which can give rise to some issues. One of these issues is the question of whether it really is necessary to generate a separate sketch plane for every single model line. Another question which recently came up is how to handle a Move request which would take the model line off the sketch plane it belongs to. Before diving into these topics, there are two bits of recent Revit API relevant news to share.

Revit API Introduction Webcast Recording

The recording of the Revit API Introduction webcast held last week on Wednesday April 29^th has been posted to the Developer Center and the ADN web site.

Updated Revit 2010 SDK

An updated version of the Revit 2010 SDK is available. The changes mostly affect the documentation.

Model Line must Reside in Sketch Plane

Returning to the model lines and sketch planes, here are some slightly edited musings on that by Miroslav Schonauer of Autodesk:

Question: In the Revit user interface, a model line is always created on the current work plane. Subsequently moving the line or grip-moving the endpoints always retains the line within that given plane. This plane can be accessed via the API through the Line element SketchPlane property.

In the API, we create a new model curve using the method

public ModelCurve NewModelCurve(
  Curve geometryCurve,
  SketchPlane sketchPlane )

One might expect an exception to be thrown if the curve specified does not reside within the given SketchPlane. This is not the case, though. One can create any line on any plane, for instance using the Revit SDK ModelLines sample. As an example, I created a vertical line using the first SketchPlane stored in the Revit database, which always seems to be the XY plane.

The recommended approach is to create a plane containing the desired line and use that as the sketch plane when creating the line. I would like to avoid this for two reasons:

• I want to avoid having potentially thousands of extra SketchPlane objects in my model.
• I want to avoid the additional code to create or find a suitable plane for each line.

It would be convenient if we could use one single default sketch plane to host all our model lines, regardless of whether the line actually resides on that plane or not. One would not have to care about the sketch plane, or create a sketch plane containing the line every time a new line is required.

The question is whether this behaviour is intentional or allowed by omission, in which case it would be dangerous to design any code based on these premises. Maybe the API will throw an error in future releases, or the model will misbehave under certain circumstances.

After more experimenting in the user interface, I observe that if I grip move the endpoints of such a line after its out-of-plane API creation, the line drops onto the plane, so it starts to behave as standard in the user interface. If the line is not edited, for instance by pinning it to prevent this, the RVT file can be happily saved, re-opened and the line legally remains as created via API.

So apparently there is no absolute requirement built into the Revit geometrical parametric engine for a line to fully reside on its sketch plane. It may be different for other curve types like arcs and splines, etc. Apparently it is only the user interface layer that forces such behaviour, which of course is consistent with Revit’s parametric BIM concepts.

The question is, can one rely on this extended API behaviour?

Answer: The answer is no. The NewModelCurve method should actually check if the geometry curve lies within the given sketch plane. If the curve lies outside plane, other functions relying on the sketch plane might go wrong.

In Revit 2010, when working in a mass family, you can create a CurveByPoints without having to use a sketch plane. In any other family or project environment, however, a sketch plane is still required.

An earlier discussion on creating model lines provides sample code demonstrating the sketch plane creation for each model line. Here is another method for creating a model line with an associated sketch plane to host it, also provided by Miro. It uses the Z axis to span the sketch plane for non-vertical lines, and otherwise the Y axis:

public static ModelLine CreateModelLine(
  Autodesk.Revit.Application app,
  XYZ p,
  XYZ q )
{
  if( p.Distance( q ) < Util.MinLineLength ) return null;

  XYZ v = q - p;
 
  double dxy = Math.Abs( v.X ) + Math.Abs( v.Y );
 
  XYZ w = ( dxy > Util.TolPointOnPlane )
    ? XYZ.BasisZ
    : XYZ.BasisY;
 
  XYZ norm = v.Cross( w ).Normalized;
 
  Plane plane = app.Create.NewPlane( norm, p );
 
  Autodesk.Revit.Creation.Document creDoc
    = app.ActiveDocument.Create;
 
  SketchPlane sketchPlane = creDoc.NewSketchPlane( plane );
 
  return creDoc.NewModelCurve(
    app.Create.NewLine( p, q, true ),
    sketchPlane ) as ModelLine;
}

With this discussion in place, let us look at a related question on moving model lines.

Using the Move method on model lines

Question: I am attempting to use the Move method on an ElementSet containing ModelCurve instances. The Move method returns true, signifying that the elements were moved, but they are not. Looking at the elements in 3D, they still remain at elevation 0.0, although the Move operation changed the elevation 0.0 to elevation -10.0 using the vector NewXYZ(0,0,-10). Does Move only work of some element types? Do I need to do something different to get it to work with ModelCurve instances?

Is there an example of using the Move method with ModelCurve instances? Is there a better way to change the elevation of these elements?

Answer: As far as I know, the Move method can be used on any Revit model elements. However, there may be other constraints on these elements as well, which take priority over the Move request.

The case of model curves is probably one example of such behaviour. Every model curve resides on a specific sketch plane, and cannot be moved off it. In your case, the sketch plane hosting the model lines may well be a horizontal plane with elevation 0.0. In that case, attempts to change the elevation of the model curves will fail, because regardless of the Z coordinate you specify, they will always be forced back into the sketch plane they reside in.

As explained above, a model curve really must lie in the sketch plane it belongs to. An application generating model lines programmatically can take two approaches:

• The simplistic approach generates a separate sketch plane for every new model line.
• A more complex approach searches for an existing sketch plane containing the new model line to use to host it, and only generates a new sketch plane if no fitting one already exists.

In any case, the application needs to ensure that the model lines generated really do lie in the sketch plane they are assigned to.

In your case, you need to check that the move operation retains the curve within the same plane. From your description above, though, that would not appear to be the case.

Alternatively, you would have to place the model curves on a new sketch plane, which will probably require recreating them from scratch, for instance using a method similar to the ones described above.

Nested Instance Geometry

This is in response to a query from Benson about the structure and geometry of nested family instances. In the answer, we also present some useful comparison operators which enable us to use Revit XYZ points and vectors as keys in generic .NET dictionaries, and sort them lexicographically, as well as utility functions for extracting and listing all the vertices of a solid. Here is the original query, slightly rephrased:

Question: I would like to obtain the internal hierarchy defined within a family instance, but its geometry only returns a flat list of solids.

For example: a top level family instance F includes one column C0, and two nested family instances F1 and F2. F1 includes two more columns C1 and C2, and F2 includes two further columns C3 and C4. The result I am trying to achieve is the geometry with the associated hierarchy:

  F
  }
  +-- C0
  }
  +-- F1
  }   }
  }   +-- C1
  }   }
  }   +-- C2
  }
  +-- F2
      }
      +-- C3
      }
      +-- C4

Here are my steps to create the family instances in this structure:

1. Run Revit 2009.
2. Select File > New > Family and open a metric template such as Metric Funiture.rft.
3. Delete all objects in the new family project, switch to 3D view.
4. Select File > Load from Library > Load Family and select an RFA file, with a column in it.
5. Now, we can find the column in the project browser panel > Families > Columns.
6. Select this column, right click on it, and select "Create Instance". Repeat step 6, so we now have two columns in the family project.
7. Save the project as myFamily1.rfa, then click File > Save As to save it again as myFamily2.rfa. Now, we have two family projects myFamily1.rfa and myFamily2.rfa.
8. Repeat steps 2, 3, and 4, this time selecting a column family, myFamily1, and myFamily2.
9. Create instances of the column, myFamily1, myFamily2 in the current family project like step 6.
10. Save the project as myFamily3.rfa.
11. Create a normal project, for instance named Project1.rvt, using File > New > Project.
12. Load myFamily3.rfa like step 4.
13. Add an instance of myFamily3 like step 6.

Now we have the structure shown above, with F represented by myFamily3, and F1 and F2 by myFamily1 and myFamily2 respectively.

Answer: The geometry of the top level family instance F does indeed just contain a flat list of solids. You can obtain some information about the hierarchical structure of the nested family instances by recursively exploring the family instance symbol family components. For a given family instance a, they are accessible through a.Symbol.Family.Components. These components include information about their location within the containing family. Using this information, you can build up the structure you seek.

I created the project as you suggest and analysed the geometry and symbol family components of the top level family instance F. I used a rectangular column, so each of the columns is a simple quadrilateral with six faces.

In the geometry of the top level family instance F, I see one instance object. The important properties of a geometry instance are its Symbol, SymbolGeometry, and Transform:

• Symbol, the symbol element that this object is referring to.
• SymbolGeometry, the geometric representation of the symbol.
• Transform, the affine transformation of the symbol into the instance coordinate space.

In my case, the symbol geometry contains six solids. One of these is empty, i.e. has no edges or faces, so I simply ignore that one. The remaining five represent the five different column instances visible in the project. These five different instances can be differentiated by the different face vertex coordinates.

To explore and compare complex geometry like that of a solid, it is important to have some powerful tools at your disposal to reduce the amount of detailed information you have to analyse and compare. In this case, in order to display the solids in an easily read fashion, I implemented a helper method named GetVertices to extract the vertices of a solid and store them in a sorted list in a XYZArray.

GetVertices iterates over all the faces of the given solid, triangulates each face, and iterates over the vertices of the resulting mesh. These are added into a container, which is designed to ensure that every vertex occurs once only. I implement this container by using a generic dictionary class and attaching an equality comparison class which ensures that almost equal points are regarded as being exactly equal, allowing for some fuzziness due to numerical imprecision. Here is the definition of my XyzEqualityComparer class:

class XyzEqualityComparer : IEqualityComparer<XYZ>
{
  public bool Equals( XYZ p, XYZ q )
  {
    return p.AlmostEqual( q );
  }
 
  public int GetHashCode( XYZ p )
  {
    return Util.PointString( p ).GetHashCode();
  }
}

The hash code calculation could certainly be optimised by avoiding the detour through a string representation, but this is the quickest and easiest solution that came to mind. I am not sure that it will work reliably under all circumstances, though. It is probably necessary to increase the precision in the string representation generated by PointString to match the precision used by the AlmostEqual method.

With this equality comparer, we can employ the standard .NET generic dictionary class using Revit XYZ points and vectors as dictionary keys.

In order to further facilitate the comparison of solids with each other, I sort their vertices before storing them into the array. The sorting process requires another fuzzy comparison routine, a Compare function which determines whether a given point is larger than, equal to, or smaller than another one, and correspondingly returns 1, 0 or -1. We define this comparison algorithm by comparing the X, Y and Z coordinates in the canonical order. If all three are almost equal, the two points are considered equal. Otherwise, the first pair of coordinates to differ is used to determine whether the first point is considered to be greater or smaller than the second. Here is the implementation of this comparison method:

const double _eps = 1.0e-9;
 
public static bool IsZero( double a )
{
  return _eps > Math.Abs( a );
}
 
public static bool IsEqual( double a, double b )
{
  return IsZero( b - a );
}
 
public static int Compare( double a, double b )
{
  return IsEqual( a, b ) ? 0 : ( a < b ? -1 : 1 );
}
 
public static int Compare( XYZ p, XYZ q )
{
  int diff = Compare( p.X, q.X );
  if( 0 == diff ) {
    diff = Compare( p.Y, q.Y );
    if( 0 == diff ) {
      diff = Compare( p.Z, q.Z );
    }
  }
  return diff;
}

With these two comparison helpers in place, I can implement my GetVertices helper method to extract a sorted list of solid vertices and store them in a sorted manner in a XYZArray like this:

static void GetVertices( XYZArray vertices, Solid s )
{
  Debug.Assert( 0 < s.Edges.Size,
    "expected a non-empty solid" );
 
  Dictionary<XYZ, int> a
    = new Dictionary<XYZ, int>(
      new XyzEqualityComparer() );
 
  foreach( Face f in s.Faces )
  {
    Mesh m = f.Triangulate();
    foreach( XYZ p in m.Vertices )
    {
      if( !a.ContainsKey( p ) )
      {
        a.Add( p, 1 );
      }
      else
      {
        ±±a[p];
      }
    }
  }
  List<XYZ> keys = new List<XYZ>( a.Keys );
 
  Debug.Assert( 8 == keys.Count,
    "expected eight vertices for a rectangular column" );
 
  keys.Sort( Util.Compare );
 
  foreach( XYZ p in keys )
  {
    Debug.Assert( 3 == a[p],
      "expected every vertex of solid to appear in exactly three faces" );
 
    vertices.Append( p );
  }
}

The two assertions checking the total number of vertices, 8, and the number of coincident vertices in each corner, 3, are only valid for this special case, where I am looking at quadrilateral columns. They will be removed in a future version, if I make use of this method for more general cases.

With this code in place, I can easily retrieve a sorted list of each of the solids' vertices for display and comparison purposes.

I used the code you provided in your original comment as a basis for a new command named CmdNestedInstanceGeo, specifically tailored to explore this situation. It first iterates over the solids contained in the top level family instance geometry and lists their vertices. It then explores the family instance components and lists their names and location points. Here is the code for the Execute methods that implements this:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
List<RvtElement> a = new List<RvtElement>();
 
if( !Util.GetSelectedElementsOrAll( a, doc,
  typeof( FamilyInstance ) ) )
{
  Selection sel = doc.Selection;
  message = ( 0 < sel.Elements.Size )
    ? "Please select some family instances."
    : "No family instances found.";
  return CmdResult.Failed;
}
FamilyInstance inst = a[0] as FamilyInstance;
 
Options opts = app.Create.NewGeometryOptions();
GeoElement geoElement = inst.get_Geometry( opts );
 
GeometryObjectArray a1 = geoElement.Objects;
int n = a1.Size;
 
Debug.Print(
  "Family instance geometry has {0} geometry object{1}{2}",
  n, Util.PluralSuffix( n ), Util.DotOrColon( n ) );
 
int i = 0;
foreach( GeometryObject o1 in a1 )
{
  GeoInstance geoInstance = o1 as GeoInstance;
  if( null != geoInstance )
  {
    GeoElement symbolGeo = geoInstance.SymbolGeometry;
    GeometryObjectArray a2 = symbolGeo.Objects;

    foreach( GeometryObject o2 in a2 )
    {
      Solid s = o2 as Solid;
      if( null != s && 0 < s.Edges.Size )
      {
        XYZArray vertices = app.Create.NewXYZArray();
        GetVertices( vertices, s );
        n = vertices.Size;
 
        Debug.Print( "Solid {0} has {1} vertices{2} {3}",
          i++, n, Util.DotOrColon( n ),
          Util.PointArrayString( vertices ) );
      }
    }
  }
}
ElementSet components = inst.Symbol.Family.Components;
n = components.Size;
 
Debug.Print(
  "Family instance symbol family has {0} component{1}{2}",
  n, Util.PluralSuffix( n ), Util.DotOrColon( n ) );
 
foreach( RvtElement e in components )
{
  LocationPoint lp = e.Location as LocationPoint;
  Debug.Print( "{0} at {1}",
    Util.ElementDescription( e ),
    Util.PointString( lp.Point ) );
}
return CmdResult.Failed;

It accesses the one and only family instance in the file and stores it in 'inst'. It then iterates over its geometry, extracts the vertices from each solid, and lists them in the debug output window. Here is the result of that listing:

Family instance geometry has 1 geometry object:
Solid 0 has 8 vertices: (32.15,8.02,0), (32.15,8.02,13.12), (32.15,9.57,0), (32.15,9.57,13.12), (34.15,8.02,0), (34.15,8.02,13.12), (34.15,9.57,0), (34.15,9.57,13.12)
Solid 1 has 8 vertices: (28.24,3.23,0), (28.24,3.23,13.12), (28.24,4.79,0), (28.24,4.79,13.12), (30.24,3.23,0), (30.24,3.23,13.12), (30.24,4.79,0), (30.24,4.79,13.12)
Solid 2 has 8 vertices: (16,7.4,0), (16,7.4,13.12), (16,8.96,0), (16,8.96,13.12), (18,7.4,0), (18,7.4,13.12), (18,8.96,0), (18,8.96,13.12)
Solid 3 has 8 vertices: (12.08,2.61,0), (12.08,2.61,13.12), (12.08,4.17,0), (12.08,4.17,13.12), (14.09,2.61,0), (14.09,2.61,13.12), (14.09,4.17,0), (14.09,4.17,13.12)
Solid 4 has 8 vertices: (10.16,-4.19,0), (10.16,-4.19,13.12), (10.16,-2.19,0), (10.16,-2.19,13.12), (12.16,-4.19,0), (12.16,-4.19,13.12), (12.16,-2.19,0), (12.16,-2.19,13.12)

These lines are probably too long to be displayed in their entirety, but the main thing is to see that we have five identical solids which only differ from each other by a translation. You can see the full lines by copying and posting them into an editor.

The command next iterates over the family instance symbol family components, just like you suggested, and lists each one of these together with its location point:

Family instance symbol family has 3 components:
Columns M_Rectangular Column <2384 610 x 610mm> at (11.16,-3.19,0)
Furniture myFamily1 <3525 myFamily1> at (-2.48,2.65,0)
Furniture myFamily2 <4665 myFamily2> at (13.68,3.26,0)

As you can see, the column instance C0 and the two furniture family instances myFamily1 and myFamily2 are listed. Diving into myFamily1 in the debugger and again traversing into its family instance components, I see the two nested columns C1 and C2, and so on. We could enhance the code to traverse this structure recursively.

If you look at the location points of these instances and compare them with the offsets between the five solids, you can determine the correspondence between the internal nested structure and the detailed geometrical representation.

In this case, we defined our families extremely haphazardly, which makes it harder to understand the results. In a well designed family, I would expect both the structure and the locations of internal components to be less arbitrary.

I hope that this exploration helps you understand the structure, and provides some useful tools to explore it further.

Here is version 1.0.0.32 of the complete Visual Studio solution with the new command.