The Building Coder

Analytical Support Tolerance

Here is an interesting issue dealing with the analytical model in Revit Structure. As we see below, the issue is not really API related, but since one symptom is the missing data obtainable through the API, it is worth an explanation.

Question: We have created two columns over a three-pile cap foundation and are trying to retrieve the support data from their analytical models:

Unfortunately, the support data of the column is available only if its centre line is exactly over the analytical model location of the pile cap foundation. Else, it is not available and the property simply returns null. The main purpose of this requirement is actually to find the link between the column and the pile cap. How can we achieve this, please?

Answer: Happily, this situation is easily resolved by modifying the analytical support tolerance. First, note that the missing support data is not an API-specific problem. If you select the column through the user interface, the Show Related Warnings button is active and the warning says that the column may not be supported.

The pile cap foundation is actually four foundations – one cap foundation and three pile foundations. Geometry for the cap foundation starts at Level 1 and goes down 900. The geometries for the three pile foundations start at -900 and go down 6900. In Revit, the default position for the Isolated Foundation analytical model is at the top of the geometry. Since this is at -900, the analytical models for the pile foundations are at that elevation.

Analytical Support is governed by the Analytical Support tolerance, shown on the Analytical Model Settings tab of the Structural Settings dialog. In the attached file, this tolerance is set at 300. So even when the column's analytical model is directly over the pile foundation's analytical model, the thickness of the cap foundation (900) is keeping the column from seeing the pile foundation's analytical model.

To overcome this obstacle, increase the tolerance from 300 to 900. Then when you move the column over the top of the pile foundation, it will see the pile foundation, and the column will consider the pile foundation as a valid support.

Although that resolves the current problem, here are two additional general hints for approaches to find the link between two elements located close to each other:

• FindReferencesByDirection.
• Geometric analysis.

The FindReferencesByDirection method to find the link between the two elements determines that the pile cap foundation is located directly underneath the second column and hence is supporting it. This can be achieved by shooting a ray straight down from a point slightly raised up from the lower endpoint of the column and using FindReferencesByDirection to discover the foundation element directly underneath. FindReferencesByDirection returns an array of elements, faces, and references found when moving through the model from a specified point in a specified direction. Its use is demonstrated by the RayTraceBounce SDK sample.

You can also determine their relationship by pure geometric analysis, e.g. using a filter to collect all the structural elements on the relevant levels and then comparing the locations of their solids' faces with each other. The AreSolidsCut method defined by the RoomsRoofs SDK sample may be helpful in this context. Geometric analysis may or may not be simpler than using FindReferencesByDirection.

Door Marks

Here is a question from Håvard Dagsvik of Cad Quality as on door marks. It can obviously be generalised to other model marks in the BIM as well.

Question: One of the best documentation features of Revit is the function assigning numeric values to the Mark parameters. If you insert 5 doors they are marked 1-5. Now if door 3 and 5 are deleted, then a new door will still start its mark on 6. Even if the project is closed and reopened, the next door still gets Mark# 6. That means there has to be a list inside Revit somewhere of the mark numbers that previously has been used, and Revit avoids reusing those numbers again. Is there a way through the API to get to that list? And somehow manipulate it to make Revit start counting on our choice of number?

Answer: Using the RvtMgdDbg BIM debugging and analysis tool or the Revit API introduction labs built-in parameter checker to explore various element parameters, I see that the Mark parameter is accessible through the built-in parameters ALL_MODEL_MARK. This is a read-write parameter:

ALL_MODEL_MARK  Mark  String/Text  read-write  4

You can therefore obtain a list of all door marks by filtering for all door instances and reading their ALL_MODEL_MARK parameter value.

I do not believe that you can manipulate Revit to influence the automatic mark counting setting used by the automatic assignment, but what you certainly can do is implement an external command which renumbers existing door instances by changing the value of their ALL_MODEL_MARK parameter value in any way you please.

To demonstrate reading and listing all existing door marks as well as modifying the marks of existing doors, I created a new Building Coder sample command CmdListMarks, which implements the following functionality:

• Select all door instances in the model.
• Iterate over the selected door instances.
• Create a dictionary whose keys are all door marks in the model and mapping each mark to a list of all doors with that mark.
• Print out the sorted dictionary contents.
• If any door elements have been selected prior to running the command, modify their door marks to a predefined hardcoded value "42".

Here is the output produced by running this command in a small model with four doors with the marks 1, 2 and 4, where 4 is duplicated on two doors.

4 doors found.
3 door marks found:
  1: 1 door
  2: 1 door
  4: 2 doors

If I select the two doors marked 4 and run the command again, their marks are modified to 42. Running it yet again lists the new mark settings:

4 doors found.
3 door marks found:
  1: 1 door
  2: 1 door
  42: 2 doors

Here is the complete code of the new external command:

static bool _modify_existing_marks = true;
const string _the_answer = "42";
 
public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  Autodesk.Revit.Creation.Filter cf
    = app.Create.Filter;
 
  List<Element> doors
    = new List<Element>();
 
  Filter f1 = cf.NewTypeFilter(
    typeof( FamilyInstance ) );
 
  Filter f2 = cf.NewCategoryFilter(
    BuiltInCategory.OST_Doors );
 
  Filter f = cf.NewLogicAndFilter( f1, f2 );
 
  int n = doc.get_Elements( f, doors );
 
  Debug.Print( "{0} door{1} found.",
    n, Util.PluralSuffix( n ) );
 
  if( 0 < n )
  {
    Dictionary<string, List<Element>> marks
      = new Dictionary<string, List<Element>>();
 
    foreach( FamilyInstance door in doors )
    {
      string mark = door.get_Parameter(
        BuiltInParameter.ALL_MODEL_MARK )
        .AsString();
 
      if( !marks.ContainsKey( mark ) )
      {
        marks.Add( mark, new List<Element>() );
      }
      marks[mark].Add( door );
    }
 
    List<string> keys = new List<string>(
      marks.Keys );
 
    keys.Sort();
 
    n = keys.Count;
 
    Debug.Print( "{0} door mark{1} found{2}",
      n, Util.PluralSuffix( n ),
      Util.DotOrColon( n ) );
 
    foreach( string mark in keys )
    {
      n = marks[mark].Count;
 
      Debug.Print( "  {0}: {1} door{2}",
        mark, n, Util.PluralSuffix( n ) );
    }
  }
 
  n = 0; // count how many elements are modified
 
  if( _modify_existing_marks )
  {
    ElementSet els = doc.Selection.Elements;
 
    foreach( Element e in els )
    {
      if( e is FamilyInstance
        && null != e.Category
        && (int) BuiltInCategory.OST_Doors
          == e.Category.Id.Value )
      {
        e.get_Parameter(
          BuiltInParameter.ALL_MODEL_MARK )
          .Set( _the_answer );
 
        ++n;
      }
    }
  }
 
  // return Succeeded only if we wish to commit 
  // the transaction to modify the database:
 
  return 0 < n
    ? CmdResult.Succeeded
    : CmdResult.Failed;
}

The command returns Succeeded only if the BIM has actually been modified, otherwise Failed. This ensures that the document dirty flag stored in its IsModified property is not set unnecessarily.

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

The Revit MEP API

By the time you read this, I will be away happily on a one-week vacation in Italy. I hope you and the blog manage yourselves and behave well until I return. I scheduled some items to be published in my absence, though.

In previous posts, we already had a look at the new MEP-specific API features in Revit 2010 and the classes involved in defining and representing MEP connectors in particular. On August 27^th 2009, we held the first webcast dedicated entirely to Revit MEP programming. This post provides an abbreviated overview of the complete Revit MEP and the webcast contents with links to available related materials, including the following topics:

• The Revit MEP API
• MEP model analysis
• Hierarchical systems and connectors
• Electrical systems
• HVAC and plumbing systems
• Sample applications
• Materials and further reading

The Revit MEP API

Revit MEP is a flavour of Revit for work in the mechanical, electrical and plumbing domains. HVAC, i.e. heating, ventilation and air conditioning, is considered part of the mechanical domain. Efficient work in these areas requires strong model analysis tools in addition to read and write access to the components and data used to model the electrical, HVAC and piping systems in Revit MEP. Some of the required MEP specific functionality includes access to the MEP project information, Green Building XML, spaces and zones, the electrical, duct and pipe systems, their components, properties and parameters, methods for element creation and modification, and system traversal and analysis.

Most of the Revit API is generic and applies to all three flavours of the Revit product, i.e. Architecture, MEP and Structure. All three flavours of Revit also include the same .NET assembly named RevitAPI.dll providing API access to third-party applications. However, some specific additional features exist for each of the flavours as well, for instance some room-related functionality in Revit Architecture and access to the analytical and MEP models in Revit Structure and MEP respectively. If API functionality not supported by the currently running flavour is accessed, the call will simply do nothing or return null.

In Revit 2008, no MEP-specific functionality was provided by the API. It was still possible to analyse and manipulate an HVAC system using the generic Revit API methods, for instance by accessing ducts as generic Revit elements and reading and writing their properties using the generic parameter access. We used this to create a sample application for HVAC air terminal analysis and sizing, presented at Autodesk University 2007. Revit 2009 introduced the first MEP-specific API support, including classes for electrical and mechanical equipment, lighting device and fixture, connector, electrical system, space and zone, the MEP model property on family instances, and the ability to create and modify MEP elements. In Revit 2010, the MEP-specific API was a focal point of the API development and greatly enhanced, especially the support for HVAC and piping systems.

MEP Model Analysis

Access to the MEP Project Info is provided through the gbXMLParamElem element and its properties, which is accessed through the ProjectInfo.gbXMLSettings property. The available data includes PostalCode, ProjectLocation, BuildingService, BuildingConstruction, GroundPlane, ShadingSurfaces, and ProjectPhase.

Green Building XML or gbXML export is initiated by a call to the Document.Export method:

Document.Export( string folder, string name, GBXMLExportOptions );

Using spaces instead of rooms, and zones to group spaces, enables a subdivision of the architectural rooms into subspaces required for MEP analysis. The AddSpaceAndZone SDK sample demonstrates the programmatic creation and management of spaces and zones. The FamilyInstance class already had a Room property to determine in which room an instance is located, and now an analogous Space property has been added for MEP usage.

Several model inspection utility methods added in Revit 2010 are especially useful in the MEP domain. One group helps determine the relationships between and contents of volumes, rooms and spaces:

• Room.IsPointInRoom determines if a 3D point is in the volume of a room.
• Space.IsPointInSpace determines if a 3D point is in the volume of a space.
• GetRoomAtPoint and GetSpaceAtPoint return the room or space containing a given 3D point.

The new ray intersection method can be used to determine proximity of elements:

• FindReferencesByDirection returns an array of elements, faces, and references found when moving through the model from a specified point in a specified direction.

One use of FindReferencesByDirection is demonstrated by the RayTraceBounce SDK sample.

Hierarchical Systems and Connectors

Many of the building blocks of an MEP system are represented in Revit by family instances. The generic family instance definition in the Revit API has been enhanced to provide access to additional MEP-specific properties and data, and provide classes to represent systems and connections between system components.

The objects dealt with in the MEP domain are organised into hierarchical structures. The top level node in these structures is an MEP system, represented by the MEPSystem class. This is the base class for the derived classes ElectricalSystem, MechanicalSystem and PipingSystem. The system has properties to access the base equipment or panel, the terminal elements, and the connector manager. The derived classes have many additional domain specific properties.

The Revit 2009 API introduced the MEPModel and Connector classes as fundamentals for programmatically representing and accessing the MEP model. It is accessed through the FamilyInstance.MEPModel property, and one of its main purposes is to provide access to the connector manager.

We have logical and physical connections between MEP components. Logical connections are used in the electrical domain, where wires and cables are not necessarily modelled individually. Physical connections are used in the mechanical and plumbing domains, where the connectors define and transmit sizing and flow information from one part to the next.

A connector is part of an MEP element such as a duct, pipe, fitting, or piece of equipment. The Connector class is used to represent connectors in the project environment. Individual stand-alone connector elements need to be created inside a family to define the component and are represented there by the DuctConnector, PipeConnector and ElectricalConnector classes.

The connector defines geometry, e.g. its oval, round or rectangular shape, and dimensions such as width, height and radius. It also maintains a coordinate system and system data such as domain, system type, flow, direction.

Electrical Systems

Electrical systems are organised hierarchically in Revit MEP. The root elements are panels. Each panel is connected to a number of systems, also known as circuits. Each system or circuit consists of a number of circuit elements, some of which may be further panels, and so on, recursively. Cables and wires need not be modelled individually, and the connections between the electrical system components are defined by logical connectors rather than physical ones. The Revit 2009 API introduced the classes ElectricalEquipment, LightingDevice, LightingFixture, ElectricalSystem, specialisations of the base MEPModel and MEPSystem classes, to represent electrical components and systems. These elements all have a connector manager, whose Connectors property returns logical as well as physical type connectors:

ElectricalSystem sys;
ConnectorSet connectors = sys.ConnectorManager.Connectors;

This makes it very simple to analyse and traverse the electrical system hierarchies similarly to the approach demonstrated by the TraverseSystem SDK sample for duct and piping ones.

HVAC and Plumbing Systems

New support for HVAC and plumbing was provided with Revit 2010, which introduced the Autodesk.Revit.MEP namespace containing a wealth of new classes and functionality, as well as moving existing MEP-related classes to the MEP namespace. The main components in HVAC and piping hierarchy are the top level systems, ducts, pipes, fittings and connectors:

• Systems to manage the top level system properties.
• Ducts and pipes to define the main flow elements.
• Fittings to implement bends and branches in the system.
• Connectors to hook up the ducts, pipes and fittings.

The classes MechanicalSystem and PipingSystem introduced in Revit 2010 provide the following top-level system functionality:

• Access to equipment, connectors and system type.
• Access to system properties such as flow and static pressure.
• Analysis of system contents through the DuctNetwork or PipeNetwork property.

The elements contained within a system are not automatically returned in the flow direction. The TraverseSystem SDK sample demonstrates how to query the connector managers to implement traversal in direction of flow for a given system.

Ducts and pipes are represented by the classes Duct, FlexDuct, Pipe and FlexPipe, derived from the MEP curve type. They provide the following functionality:

• Read access to duct properties, types, and geometry.
• Change duct or pipe type.
• Move or layout duct or pipe.

The layout functionality can be driven by two points, one point and a connector, or two connectors.

Fittings are represented by family instances, which are created with dedicated methods on the Autodesk.Revit.Creation.Document class for inserting Elbow, Tee, Cross, Takeoff, Transition, and Union elements. The fitting properties, shape and dimensions can be accessed through the FamilyInstance.MEPModel property.

Connectors limited to the electrical realm were introduced in Revit 2009. In Revit 2010, we have connectors for the mechanical and piping domains as well. The connector is an item that is a part of another element such as a duct, pipe, fitting, or equipment. The basic features of connectors and the different classed used to represent them in the family and project contexts were mentioned above. The additional HVAC-specific connector features include properties to read the flow, coefficient and demand. They also provide access to physical properties like Origin, Angle, Height, Width and Radius.

We have read and write access to so-called assigned connector properties. These are connector properties that can be overridden by the user and are dependent on the overall network condition, including characteristics like Flow, Flow Config, Coefficient, Loss etc. These depend on the system being well connected, the configuration of the family within the system, and how the family is constructed.

Connector size and location can be modified. Connectors can be disconnected to insert a new fitting into a network or connect two ducts into a transition.

• The family connector elements define Flow, Flow Configuration, Coefficients, and Loss Method.
• Read duct, pipe, and fitting connector properties such as Flow, Coefficient, and Demand.
• Access physical connector properties e.g. Origin, Angle, Height, Width, Radius.
• Change connector size and location.
• Connect and disconnect.

The creation document provides a number of methods for the creation of HVAC and plumbing elements within the project environment, including new mechanical or piping systems, new duct and pipe elements, and new fittings. In the context of a family, the different types of duct, pipe and electrical connectors are represented by specific elements that can be created by the FamilyItemFactory class, accessed through the Document.FamilyCreate property.

Sample Applications

The MEP-specific sample applications include both those provided in the standard Revit SDK as well as a non-SDK one created for this presentation on the RME API.

The introduction of an MEP specific API with Revit 2009 was accompanied by two SDK samples:

• AddSpaceAndZone demonstrates handling the new space and zone elements.
• PowerCircuit demonstrates manipulation of electrical power circuits.

The Revit 2010 SDK includes the following new MEP-specific SDK sample applications:

• AutoRoute: Route a set of ducts and fittings between a source, the air supply equipment, and the sink, two air outlet terminals.
• AvoidObstruction: Detect and resolve obstructions between ducts, pipes, and beams.
• TraverseSystem: Traverse a well-connected mechanical or piping system in the direction of flow.
• CreateAirHandler: Create an air handler and add connectors.

The first three demonstrate RME API features in the project context, the fourth uses the family API.

Finally, we provide a non-SDK sample application named ‘mep’. It implements some HVAC oriented commands making use of the generic Revit API to analyse and manipulate duct elements for automatic air terminal sizing, and others which implement an electrical sample for analysis and display of an electrical system in a tree view reproducing the Revit system browser structure or showing the full connection hierarchy tree:

• HVAC air terminal analysis and sizing.
• Electrical system connectivity analysis and hierarchical display.

Materials and Further Reading

A more extensive document discussing the Revit MEP API and the related samples in deeper detail as well as other useful material is provided with the recording of Revit MEP Programming Webcast held on August 27th 2009, available through the ADN or Autodesk Developer Network API training schedule (also accessible via www.autodesk.com/apitraining), filter for 'Revit MEP API', and click on the download link. This material is accessible to all developers, regardless of ADN membership.

Remove all Geometry from a Family

Here is a question from Joel Karr of Environmental Systems Design, Inc that nicely complements the issue of identifying model elements in a project file with the subsequent correction added.

Question: Is it possible to delete all geometry from a Revit RFA family file? I would like to keep all parameters but delete all geometry.

Answer: To achieve what you desire, we first need to identify all elements contributing geometry to the model, similarly to the model element selection issues mentioned above.

This is simpler in a family file than in a project file, since there are normally less elements and almost all elements having geometry are the ones we are interested in.

I implemented a sample application RemoveRfaGeom to test this, with the following mainline code for its Execute method:

public IExternalCommand.Result Execute( 
  ExternalCommandData commandData, 
  ref string message, 
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  ElementIterator it = doc.Elements;
  Options opt = app.Create.NewGeometryOptions();
  List<Element> a = new List<Element>();
 
  while( it.MoveNext() )
  {
    Element e = it.Current as Element;
 
    if( null != e.get_Geometry( opt ) )
    {
      a.Add( e );
    }
  }
 
  int n = a.Count;
  Debug.Print( 
    "{0} element{1} have non-null geometry{2}", 
    n, 
    ( 1 == n ? "" : "s" ),
    ( 0 == n ? "." : ":" ) );
 
  ElementSet els = new ElementSet();
 
  foreach( Element e in a )
  {
    string cat = (null == e.Category)
      ? "<null>"
      : e.Category.Name;
 
    Debug.Print(
      "Category={0}; Name={1}; Id={2}; Type={3}",
      cat,
      e.Name,
      e.Id.Value.ToString(),
      e.GetType().Name );
 
    if( null == e.Category )
    {
      els.Insert( e );
    }
  }
 
  ElementIdSet ids = doc.Delete( els );
 
  n = (null == ids) ? 0 : ids.Size;
 
  Debug.Print( "{0} element{1} deleted.",
    n,
    ( 1 == n ? "" : "s" ) );
 
  return IExternalCommand.Result.Succeeded;
}

It performs the following steps, assuming that the active document is indeed a family document:

• Iterate over all family document elements.
• Identify and list all elements with non-null geometry.
• Create a set of all elements with geometry whose category is null.
• Delete the latter set and display the number of deleted elements.

Running this in the metric library rectangular column family file 'M_Rectangular Column.rfa' produces the following output:

2 elements have non-null geometry:
Category=; Name=Extrusion; Id=105; Type=Extrusion
Category=Cameras; Name=View 1; Id=427; Type=Element
13 elements deleted.

As you can see from this, there are some elements having geometry that you presumably do not want to eliminate, such as the camera, so you will need to remove those from the set before deletion. In this case, I simply noted that the camera has a non-null category, whereas the category of the extrusion I want to remove is null, so I just check the null category property to select the extrusion.

Secondly, deleting an element causes other dependent elements to be deleted also, so even though we just pass in one single extrusion element to the Delete method, a whole group of other elements are eliminated as well. We already discussed and made use of this effect to determine the association between a tag and the tagged element and between a host and its hosted elements.

Here is the complete Visual Studio solution RemoveRfaGeom implementing the new command.

Integration with a Database or ERP System

A while ago, I published Miroslav Schonauer's popular high-level overview of Revit and database integration. Here is an additional useful note from Anthony Hauck on this topic:

Question: How can I integrate Revit with an ERP solution or an SQL database?

Answer: Revit information can be exported to an ODBC-compatible database. ODBC export is a native feature of Revit. The Labs posting RDBLink demonstrates a similar capability using the API, with the additional feature of being able to change some parameters within a Revit model by editing the resulting database and re-importing the changes. Some of these parameter changes can affect Revit model geometry.

The availability of RDBLink has already been mentioned briefly previously.

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.

View Sketch Plane

Some views provide a sketch plane, others do not. In particular, the section views do not. Here is a little exploration into this subject prompted by the following question from Toste Wallmark of Tecton Limited:

Question: I'm trying to get the SketchPlane property of currently active view, which is a section view. However, it returns null. Do I need to manually create a sketch plane for section views? Other types of views, like floor plans, do correctly return a SketchPlane object.

Answer: I implemented a little dedicated sample application to test your assertion, and I can reproduce what you say in the sample projects that I have looked at so far.

I would recommend to always check whether the sketch plane returned from a view is null or not. In case it is null, you will obviously have to create your own. You can do so using the view origin and direction. These values are always available from the corresponding properties on the view object, even though the view plane is null.

Here is the result of searching for all document elements that are of the View class or one of its five derived classes. Looking at a separate listing of all database elements, I noticed that many of the view related objects occur in pairs, like the elements used for level 1 and 2 below with the element id pairs (13073, 13077) and (15915, 15919). In the other cases, the object type of only one of the two related objects is View, whereas the other is simply a Revit Element and thus does not appear in this list:

I also print out this list to the Visual Studio debug output window. The overly long lines can be seen by copying this text to an editor:

List of document views' sketch planes: 

View [3651] Project View origin (0,0,0) direction (0,-1,0): 
ViewPlan [13073] Level 1 origin (0,0,0) direction (0,0,1): Level 1 plane origin (0,0,0), plane normal (0,0,1)
ViewPlan [13077] Level 1 origin (0,0,0) direction (0,0,1): Level 1 plane origin (0,0,0), plane normal (0,0,1)
ViewPlan [15915] Level 2 origin (0,0,0) direction (0,0,1): Level 2 plane origin (0,0,13.12), plane normal (0,0,1)
ViewPlan [15919] Level 2 origin (0,0,0) direction (0,0,1): Level 2 plane origin (0,0,13.12), plane normal (0,0,1)
View [29152] North origin (-1.04,84.1,3.94) direction (0,1,0): 
View [29193] East origin (84.12,-2.54,3.94) direction (1,0,0): 
View [29214] West origin (-84.13,-2.42,3.94) direction (-1,0,0): 
View [29233] South origin (-1.08,-84.12,3.94) direction (0,-1,0): 
ViewPlan [29273] Site origin (0,0,0) direction (0,0,1): Level 1 plane origin (0,0,0), plane normal (0,0,1)
View [92030] System Browser origin (0,0,0) direction (0,0,1): 
View [138046] Section 1 origin (-20.55,2.78,13.12) direction (-1,0,0): 

Note that this list includes a view object for the system browser, which obviously has no sketch plane at all. It still returns valid values for the view origin and direction.

Here are the utility methods used by the external command which generates this list:

static string RealString( double a )
{
  return a.ToString( "0.##" );
}
 
static string PointString( XYZ p )
{
  return string.Format( 
    "({0},{1},{2})",
    RealString( p.X ), 
    RealString( p.Y ),
    RealString( p.Z ) );
}
 
static string PlaneString( Plane p )
{
  return string.Format( 
    "plane origin {0}, plane normal {1}",
    PointString( p.Origin ), 
    PointString( p.Normal ) );
}
 
static Filter OrType( 
  Filter f, 
  Type t, 
  Autodesk.Revit.Creation.Filter cf )
{
  Filter f2 = cf.NewTypeFilter( t );
  return cf.NewLogicOrFilter( f, f2 );
}

Here is the code of the external command Execute method:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
View activeView = doc.ActiveView;
 
Autodesk.Revit.Creation.Filter cf 
  = app.Create.Filter;
 
Filter f1 = cf.NewTypeFilter( typeof( View ) );
Filter f2 = OrType( f1, typeof( View3D ), cf );
Filter f3 = OrType( f2, typeof( ViewDrafting ), cf );
Filter f4 = OrType( f3, typeof( ViewPlan ), cf );
Filter f5 = OrType( f4, typeof( ViewSection ), cf );
Filter f6 = OrType( f5, typeof( ViewSheet ), cf );
 
List<RvtElement> views = new List<RvtElement>();
doc.get_Elements( f6, views );
 
Debug.Assert( 0 < views.Count, 
  "expected document to have at leat one view" );
 
string msg 
  = "List of document views' sketch planes: " 
  + Environment.NewLine;
 
foreach( View view in views )
{
  msg += string.Format( 
    "{0}{1} [{2}] {3} origin {4} direction {5}: ", 
    Environment.NewLine, 
    view.GetType().Name, 
    view.Id.Value, 
    view.Name,
    PointString( view.Origin ),
    PointString( view.ViewDirection ) );
 
  SketchPlane sketch = view.SketchPlane;
  msg += ( null == sketch ) 
    ? "<null sketch>" 
    : sketch.Name + " " + PlaneString( sketch.Plane );
}
Debug.Print( msg );
WinForms.MessageBox.Show( msg, "View Sketch Planes" );
return IExternalCommand.Result.Failed;

Note that specifying a type filter when calling the document get_Elements method does not return derived types, only the specific type given. Since I wish to retrieve all types derived from the View class as well as base class View elements, I need to create a Boolean expression or'ing together all of them. For this purpose, I invented a nice new little OrType method for succinctly or'ing together a sequence of type filters.

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!

Rename a Group

I have very busy this last week answering cases and preparing training material. Lots of interesting issues are cropping up that I would love to blog about, but I can hardly find the time to do so. Here is one little item of interest raised by Henrik Bengtsson of Lindab on renaming a group:

Question: Is there a way to change the name of a group that is created via the API? If you use the Document.Create.CreateNewGroup method and provide an ElementSet argument, it returns a Group object. If you then call Group.Name = "Test", it will raise an error saying that this operation is not valid due to the current state of the object. Is there perhaps some other method of changing the name of the group?

This group issue is of great importance since I am working on creating walls with studs and beams, so called structural framing. I want all these profiles to be connected in some way and this is one method. They both graphically and parametrically belong to each other, since you can use the Group.Members property to find all the different members in the group. Good when you are specifying products.

Answer: We already discussed the creation of a group. Changing the name of a group is not achieved by using the Name property on the group itself, but on the group type, like this:

  Group g = <wherever you got the group from>
  Symbol groupType = g.ObjectType;
  groupType.Name = "New group name";

There is no real difference between these two properties, even though one can be changed and the other cannot. They return the same value and are probably pointing to the same data field somewhere.

The split into Group and GroupType classes was probably made to reuse the typical Revit family structure, similar to the relationship between Wall and WallType or family instance and family symbol. In the case of a group, the distinction between Group and GroupType may seem a bit contrived, but it certainly has valid internal reasons.

Host Reference

Still enjoying my climbing and sunshine holiday with my sons in Avignon. Yesterday we went climbing and exploring the cliffs or 'calanque' of Cassis, east of Marseille (more images):

Besides climbing, swimming in the Gard river and Mediterranean Sea, and blogging now and then, my sons are also artistically active:

Returning to the Revit API, however: We already touched on the relationship between a host and its hosted elements in some previous posts. The first such topic was the relationship inverter, making use of the explicit property providing a reference to the host of hosted elements such as doors, windows and other family instances. Since this property only specifies the relationship in one direction, we implemented the relationship inverter to obtain the inverse references.

No such explicit property is provided in either direction in the association between a tag and the tagged element, and that discussion mentions four ideas for possible workarounds instead.

Here is another question on a similar topic, the relationship between a wall and its wall footing:

Question: How can I obtain a reference to a wall footing from the wall attached to it? And vice versa, is it possible to obtain a reference to the wall supported by a wall footing?

Answer: As in the case of the tag and the tagged element, the Revit API does not provide any direct access to the link in either direction, neither to get the reference of a wall footing from the wall attached to it or vice versa. The workaround via the Document.Delete method mentioned as one of the four workarounds to determine the association between a tag and the tagged element can be used in this case as well: You call the method to delete the wall. It automatically includes the wall footing in the deletion, and returns the element ids of all deleted objects in an ElementIdSet, from which you can pick out the wall footing. If you encapsulate this operation in a transaction which is aborted after the call, the deletion will not be committed, and you will have obtained the desired information with no changes made to the model. Here is a sample code snippet to implement this:

I added a new command class CmdWallFooting to The Building Coder sample implementing this functionality. Here is the source code of its Execute method:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
ContFooting footing = null;
 
Wall wall = Util.SelectSingleElementOfType( 
  doc, typeof( Wall ), "a wall" ) as Wall;
 
if ( null == wall )
{
  message = "Please select a single wall element.";
}
else
{
  doc.BeginTransaction();
  ElementIdSet delIds = null;
  try
  {
    delIds = doc.Delete( wall );
  }
  catch ( System.Exception )
  {
    message = "Deletion failed.";
    doc.AbortTransaction();
    return CmdResult.Failed;
  }
  doc.AbortTransaction();
 
  foreach ( ElementId id in delIds )
  {
    ElementId refId = id;
    Element elem = doc.get_Element( ref refId );
    if ( null == elem )
      continue;
    footing = elem as ContFooting;
    if ( null != footing )
      break;
  }
}
string s = Util.ElementDescription( wall );
 
Util.InfoMsg( ( null == footing )
  ? string.Format( "No footing found for {0}.", s )
  : string.Format( "{0} has {1}.", s,
    Util.ElementDescription( footing ) ) );
 
return CmdResult.Failed;

This is the result of running the new command on the wall depicted above:

Another efficient workaround has become possible in Revit 2010 by making use of the new API method FindReferencesByDirection. It finds both elements and geometric references that intersect a ray extending in a certain direction from an origin point. The Revit 2010 SDK Samples AvoidObstruction and RaytraceBounce demonstrate the use of this new method. By using a couple of points on the wall footing, we can easily determine which wall is located directly above it, and vice versa as well. This provides a much stronger possibility to the workarounds using general geometric proximity suggested in the post on the tag association.

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