The Building Coder

DWG Export Filename

Here is a question handled by Joe Ye that I thought might be of general interest.

It makes use of the Revit SDK sample ImportExport converted to VB.NET. We mentioned the issue of converting Revit SDK samples from C# to VB in one post, and Adam Nagy later presented a more complete port.

Question: I am making an application to export Revit views to DWG files. I used the ImportExport sample converted to VB.NET as a basis. I am having trouble defining filenames other than the built-in solution. The syntax for defining the DWG filename for a given view seems to be:

[FileName] & " - " & [ViewType] & " - " & [ViewName] 

The filename can be changed, but the other substrings seem to be hardcoded, or at least I can't find where they are defined. I would like the FileName and ViewType substrings to be optional and maybe replaced by some other project defined prefix. Is this possible through the API?

If not, a workaround could be to rename the DWG files afterwards, but I hope to avoid that.

Answer: In this case, you are using one of the overloads of the Export method taking four arguments, the fourth of which specifies the type of export required. The first three are folder, name, and views:

• folder: the output folder into which the files will be exported.
• name: either the name of a single file or a prefix for a set of files. If null or empty, automatic naming will be used.
• views: a selection of views to be exported. If null or empty, only the active view will be exported.

As the documentation says, the exported DWG file name is in fact generated using a hardcoded algorithm inside Revit if the view set contains more than one single element.

If only one view is specified, then the filename string constructed from three substrings provided by specific variables is used. It is defined in the module ExportData.vb, in the Initialize function:

Private Sub Initialize()
  ' The directory into which the file will be exported 
  Dim dllFilePath As String _
    = Assembly.GetExecutingAssembly().Location
 
  m_exportFolder = Path.GetDirectoryName(dllFilePath)
 
  ' The file name to be used by export 
  Dim docTitle As String = m_activeDoc.Title
 
  Dim v As View = m_activeDoc.ActiveView
 
  Dim viewName As String = v.Name
  Dim viewType As String = v.ViewType.ToString()
 
  m_exportFileName = docTitle _
    + "-" + viewType _
    + "-" + viewName _
    + "." + getExtension().ToString()
 
  ' Whether current active view is 3D view 
 
  If v.ViewType = Enums.ViewType.ThreeD Then
    m_is3DView = True
  Else
    m_is3DView = False
  End If
End Sub

Therefore, you can easily make FileName and ViewType optional or replace them by some other prefix. Simply change the string values in the definition of m_exportFileName as you please, for instance like this:

m_exportFileName = docTitle + "-" + “aaaa” + “.” + getExtension().ToString

Note that changes to the specified filename have no effect if more than one view is given in the third argument to the Export method. If the third argument includes more than one view, Revit will automatically name each exported DWG file using a hard-coded rule including the second argument to the Export method as a prefix. If the third argument includes just one single view, then the file name passed in is used. So the workaround to use your own naming rule is to export only one view at a time. In case of multiple views, you can export them one by one in a loop.

This information obviously also applies to the other overloads of the Export method taking a ViewSet argument, including export to:

• DGN
• DWF2D
• DWF3D
• DWFX2D
• DWFX3D
• DWG
• FBX

Thank you very much Joe for this answer!

DWG and DWF Family Creation

Here is another question on family creation, this time not regarding parameters, but the geometrical content and reuse of existing geometry.

Revit is a strongly parametric system, and the Revit family management obviously also. However, if one happens to have important predefined static geometry for certain components, that can be reused as well. It is of course a shame to be using static, non-parametric geometry in an environment with such powerful support for parameterisation. In some cases, however, reusing pre-existing content is the most efficient solution. The following question deals with this kind of geometry reuse.

Question: How can I use existing DWG and DWF files to define new Revit types and create families? In particular:

• Do I need to create a separate family or a family type for each DWG or DWF file?
• Do I need to create a physical RFA file before inserting it into the project, or can I use the API to insert the in-memory Document object directly? The RFA file is not required later, and the inserted family is embedded in the project.

Answer: The first place to look for an idea of how to automate importing external CAD files into a family is the Revit SDK sample DWGFamilyCreation. It shows how to import a DWG file into a family document, create a new type, and add parameters to it. In this sample, one single DWG file is imported into the family document. The new type is defined, and two parameters are added to it for the DWG file name and creation time.

Let's reiterate some basics. In Revit, a family is a collection of the types or symbols it defines. Normally, the types contained in one single family are closely related.

The family file defines the geometry, which can be parameterised. There can be any number of types in a family file. Each type can have parameters, and these parameters can be used to modify the geometry by driving pre-defined dimensions and constraints. Several types can thus share the same geometry.

If the geometry is defined by an imported DWG or DWF file, it will obviously be static and not have any dimensions or constraints that can be driven by parameters. If you import two DWG or DWF files into the same family document, they would by default both be visible. However, portions of the geometry can also be selectively hidden for different types.

If you have a one-to-one correspondence between the types and the DWG or DWF files defining the geometry, you will want to display only the portion of geometry defined by DWG or DWF file X for the corresponding type X. This can be achieved in two ways: either by creating a separate family for each DWG or DWF file, or by adding several DWG or DWF files and hiding all the geometry from the other ones for type X.

Here is an example of binding geometry with family types using DWF files:

In this example, three separate groups of static geometry are loaded into one single family file from three separate DWF files. Three types are created. Each type refers to one group of static geometry, and the other two are hidden for that type.

The three DWF files represent desks of different sizes: 60x30, 60x40, and 72x36.

• Load them into a new family, and create three family types: 60x30, 60x40, and 72x36.
• Add three family type Yes/No parameters: 60x30Visible, 60x40Visible, 72x36Visible.
• Bind the visibility parameter to the respective imported instance visibility property:

• Set 60x30Visible to true and the other two parameters to false for type 60x30, and analogously for the other two types:

Now you can control the geometry visibility depending on the selected type.

One can use this approach to load all DWG or DWF files into one single family, create a separate type for each one, and hide all of the other geometry for each, so each type displays exactly one DWG or DWF file.

Alternatively, of course, you can create a separate family file for each DWG or DWF file. The advantage of that would be less complexity and smaller files, and also the possibility to define different parameters for different source files; the disadvantage is the loss of the grouping into a single coherent family, the larger number of files, and ensuing management overhead.

In order to actually load the newly defined family type into a Revit project, one can use one of the two methods for loading families and types provided by the Document class:

• LoadFamily, which loads an entire family and all its types or symbols.
• LoadFamilySymbol, which loads only one specified family type or symbol from a family file.

Both of these are provided in two flavours each, one taking a string argument specifying the file name of the RFA file to load, and the other taking a Document argument. You can use the Document argument overload to load a family document that has not yet been saved in an external file. Therefore, you can create a new family document in memory and load it without saving it first.

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.

Access to Linked File Geometry

Here are some notes on accessing the geometry of imported or linked files from a case handled by my colleague Joe Ye:

Question: How can I access the geometry of imported or linked Revit RVT, AutoCAD DWG, and SketchUp SKP files?

For instance, I have created a file Wall.rvt containing a wall and use Import/Link to insert it into LinkWall.rvt. Now, when traversing the entities of LinkWall.rvt, I see an Autodesk.Revit.Element.Instance using a Symbol which seems to be the imported or linked Wall.rvt file. How can I access the elements from the Symbol so that I can recursively traverse the imported/linked file? Furthermore, how can I do the same for an imported or linked SketchUp or DWG file?

Answer: Each imported or linked Revit project generates a document instance in the Revit Application object's document collection Application.Documents. Each imported RVT file maps to one document. You can determine the document name from the symbol, and then traverse all documents in the collection to find the appropriate one. From the corresponding document instance, you can access its elements in the usual way, for instance using Document.get_Element or Document.get_Elements. Unfortunately, we currently have no solution for resolving the issue of two identically named linked files.

With regard to imported DWG or SKP files, there is no way to access elements in the imported or linked file.

For more details on these steps, please refer to the preceding discussions on linked files, how to hide them, and listing their elements.

Hiding Linked Files

Rod Howarth raised a question in the discussion on linked files:

Question: I'm trying to make a command to turn off the visibility of linked Revit and DWG models in the current view.

The intent is to turn off the visibility for all imported categories in the drawing, i.e. all imported CAD files. This would be like going to Visibility/Graphics > Imported Categories > Show imported categories in this view.

Is there an easy way to do this, or am I going to have to loop over each element, checking if its symbol's name ends in '.dwg' or '.rvt' or is there a certain thing I can look for, i.e. something that tells me it is an imported category, instead of just going by the name?

For DWG, I simply loop through the document settings categories and make each category whose name ends with ".dwg" invisible in the current view.

However, this does not work for RVT, so I had a look with RvtMgdDbg, and it says that my linked file on the plan is part of the OST_RvtLinks built-in category.

So I changed my code to do:

Document doc = app.ActiveDocument;
Categories categories = doc.Settings.Categories;
 
// get category for linked files
Category linkedRevitCat
  = categories.get_Item(
    BuiltInCategory.OST_RvtLinks );
 
// loop through all categories in document
foreach( Category c in categories )
{
  // if they end with dwg or rvt toggle
  // their current visibility in current view
  if( c.Name.ToLower().EndsWith( ".dwg" )
    || c.Name.ToLower().Contains( ".rvt" )
    || c.Name.ToLower().EndsWith( ".dwf" )
    || c.Name.ToLower().EndsWith( ".dxf" )
    || c.Name.ToLower().EndsWith( ".dwfx" )
    || ( linkedRevitCat != null
      && c.Id.Equals( linkedRevitCat.Id ) ) )
  {
    // toggle visibility 
    doc.ActiveView.setVisibility( c,
      !c.get_Visible( doc.ActiveView ) );
  }
}

Unfortunately, linkedRevitCat always is null, and when I run the elements filter API sample, OST_RvtLinks doesn't come up as a category list?

Answer: First of all, thank you Rod for raising this interesting question and for pointing out the positive information on how simple it is to hide the linked DWG files.

Joe Ye discovered the following built-in category behaviour: There is no easy way to filter out those imported categories quickly. I found one hint that can make your add-in quicker, though:

• For the built-in categories, the element id is always negative.
• For imported ones, which are created after the DWG is imported, the element id is positive.

Using this rule, it is no longer necessary to extract the substring and perform a string comparison for built-in categories.

Phil Xia responded to the question on the OST_RvtLinks built-in category: indeed we cannot retrieve the OST_RvtLinks built-in category from the document settings categories. We can get it from the element category property, however:

  BuiltInCategory bic = BuiltInCategory.OST_RvtLinks;
  ElementIterator i = doc.Elements;
  Element e;
  while( i.MoveNext() )
  {
    e = i.Current as Element;
    if( e.Name.Contains( ".rvt" )
      && e.Category != null
      && e.Category.Id.Value.Equals( (int) bic ) )
    {
      break;
    }
  }

Unfortunately, since we cannot obtain the document category for the RVT link element, it is not possible to hide this category via the View.SetVisibility method like we do for the DWG link element. Also, unlike the DWG link elements, all the RVT ones return the same category OST_RvtLinks, so we cannot control the visibility for them individually using this method, even if we were able to obtain the appropriate document category.

I hope these various hints are of some use and will be interested in hearing whether they help resolve your issue, Rod.

Linked Files

Here is pretty thorough exploration by Joe Ye on how to retrieve linked Revit files in a project.

The built-in category of a linked Revit file is BuiltInCategory.OST_RvtLinks, and the class storing it in the Revit database is Instance. Therefore, we can retrieve all linked Revit files in a document like this:

Autodesk.Revit.Creation.Filter cf
  = app.Create.Filter;
 
BuiltInCategory bic
  = BuiltInCategory.OST_RvtLinks;
 
Filter f1
  = cf.NewCategoryFilter( bic );
 
Filter f2
  = cf.NewTypeFilter( typeof( Instance ) );
 
Filter f3
  = cf.NewLogicAndFilter( f1, f2 );
 
List<Element> links = new List<Element>();
 
Document doc = app.ActiveDocument;
doc.get_Elements( f3, links );

We simply set up filters for the category and class, which is also the System.Type, combine them in a Boolean expression, and ask the document for the elements matching this filter.

Revit 2008 did not provide a valid category property for the linked model, and at that time the API did not support filtering for specific elements, so one had to use a slower and more complex approach such as this:

BuiltInParameter bip
  = BuiltInParameter.ELEM_TYPE_PARAM;
 
Document doc = app.ActiveDocument;
ElementIterator it = doc.Elements;
 
List<Element> links = new List<Element>();
 
while( it.MoveNext() )
{
  Instance inst = it.Current as Instance;
  if( null != inst )
  {
    Parameter p = inst.get_Parameter( bip );
    ElementId id = p.AsElementId();
    Element e = doc.get_Element( ref id );
    string n = e.Name;
    string s = n.Substring( n.Length - 4 );
    if( s.ToLower().Equals( ".rvt" ) )
    {
      links.Add( inst );
    }
  }
}

In this loop we check all elements whose class is Instance. On those, we check for the built-in parameter ELEM_TYPE_PARAM, which gives us the family. The parameter is an element id. With the id, we can ask the document to retrieve the element 'e' and ask it for its name 'n'. The linked file's element name is the file name, which ends in ".rvt".

Linked File Path

This quickly leads to a new question: Having the file name, is it possible to also get the file path for a given Revit link?

For that, we can make use of the fact that Application.Documents manages all imported Revit files. The linked Revit files' full path can be retrieved from the Document.PathName property. Here is some code to set up a dictionary mapping each Revit link's file name to its full path:

DocumentSet docs = app.Documents;
int n = docs.Size;
 
Dictionary<string, string> dict
  = new Dictionary<string, string>( n );
 
foreach( Document doc in docs )
{
  string path = doc.PathName;
  int i = path.LastIndexOf( "\\" ) + 1;
  string name = path.Substring( i );
  dict.Add( name, path );
}

Unfortunately, the question still has some thorny bits in it, because it remains unclear how to get the linked files in a Revit project when there are two open projects, both referencing a files with the same name are but at different paths. For example:

• Open a Revit project: C:\tmp\a\link.rvt with a link to C:\tmp\a\x.rvt.
• Open another Revit project in the same Revit session: C:\tmp\b\x.rvt.

Now we want the Revit links for the project "link.rvt". From the elements collection we can find the name of the linked file "x.rvt". But there are two files with the same name in the documents collection and we don't know which one of them to choose. The files in the documents collection are:

• C:\tmp\a\link.rvt
• C:\tmp\a\x.rvt
• C:\tmp\b\x.rvt

For this situation, you can distinguish between the opened Revit document and the imported one. When you retrieve a document from Application.Documents and it is currently open in Revit, its property Document.ActiveView is not null. If the document is imported, its Document.ActiveView is null. This can be used to tell which one is imported.

Unfortunately, this still does not solve the problem if two opened documents import two Revit files with the same file name in different folders.

Here is the mainline of an external command making use of these methods:

Application app = commandData.Application;
 
Dictionary<string, string> dict
  = GetFilePaths( app );
 
List<Element> links
  = GetLinkedFiles( app );
 
int n = links.Count;
Debug.WriteLine( string.Format(
  "There {0} {1} linked Revit model{2}.",
  (1 == n ? "is" : "are"), n,
  Util.PluralSuffix( n ) ) );
 
string name;
char[] sep = new char[] { ':' };
string[] a;
 
foreach( Element link in links )
{
  name = link.Name;
  a = name.Split( sep );
  name = a[0].Trim();
 
  Debug.WriteLine( string.Format(
    "Link '{0}' full path is '{1}'.",
    name, dict[name] ) );
}
return CmdResult.Succeeded;

It makes use of the fact that the link instance element names use " : " to delimit the file name, as in:

"two_rooms.rvt : 2 : location "

Here is the output from running this command in a simple sample file:

There are 2 linked Revit models.
Link 'roof.rvt' full path is 'C:\tmp\roof.rvt'.
Link 'two_rooms.rvt' full path is 'C:\tmp\two_rooms.rvt'.

Joe suggests that yet another situation also needs to be considered. Assuming the following situation:

• C:\temp\a\file1.rvt is opened.
• C:\temp\a\main.rvt is also opened.
• C:\temp\b\file1.rvt is imported into main.rvt.

In this case, the GetFilePaths method retrieves two file paths:

1. C:\temp\a\file1.rvt
2. C:\temp\b\file1.rvt

From the link name file1.rvt alone, we cannot tell which path is the imported one. To do so, we need to remove the non-imported files from the mapping. In this case, GetFilePaths should remove the opened Revit file and only contain non-opened ones, which represent the imported files. This can be achieved by using the ActiveView property, for instance by enhancing GetFilePaths like this:

Dictionary<string,string> GetFilePaths(
  Application app,
  bool onlyImportedFiles )
{
  DocumentSet docs = app.Documents;
  int n = docs.Size;
 
  Dictionary<string, string> dict
    = new Dictionary<string, string>( n );
 
  foreach( Document doc in docs )
  {
    if( !onlyImportedFiles
      || ( null == doc.ActiveView ) )
    {
      string path = doc.PathName;
      int i = path.LastIndexOf( "\\" ) + 1;
      string name = path.Substring( i );
      dict.Add( name, path );
    }
  }
  return dict;
}

I hope that this discussion is useful for exploring situations requiring handling of linked files in Revit. Many thanks to Joe for his thorough exploration!

Here is version 1.0.0.17 of the complete Visual Studio solution with the new command CmdLinkedFiles discussed here.

Running AutoCAD inside Revit

The preceding post on RealDWG and object enablers discussed one potential method for making use of AcDb functionality to read and write AutoCAD DWG files inside of Revit. Assuming that you have a license for a full version of AutoCAD in addition to your Revit one, there is another easy method to achieve this which has been implemented and tested.

It is possible to run AutoCAD as a full-blown process in the background inside Revit. This functionality is new in AutoCAD 2009, and the code we present is based on a demo by Kean Walmsley on embedding AutoCAD 2009 in a standalone dialog. Obviously this requires a full version of AutoCAD to be installed on the machine. Among other things, Kean's code defines a MainForm class, which can be used to load and run AutoCAD and access its API functionality.

Markus Hannweber of SOFiSTiK AG has made use of this within a Revit plug-in. Here are some examples of what is possible:

MainForm mainform = new MainForm();
AxACCTRLLib.AxAcCtrl c = mainform.axAcCtrl1;
c.Src = "d:\\demo\\embed.dwg";
c.PostCommand("(setvar \"cmddia\" 0) ");
c.PostCommand("(arxload\"sofibldarx\") ");
c.PostCommand("(load\"blist\") ");
c.PostCommand("SOF_BLIST ");
c.PostCommand("(S:ENDACAD) ");
c.Src = null;

The individual lines do the following:

• Instantiate Kean's MainForm class and open AutoCAD in the background.
• Initialise a variable 'c' to address the AutoCAD control. It also helps keep the source code line length under control.
• Load a drawing, object enablers are automatically loaded with it, if set up to do so.
• Suppress AutoCAD command line output.
• Load an ARX application into AutoCAD.
• Load an AutoLISP application into AutoCAD.
• Start any application command, whether defined in Lisp or ARX.
• Run a command to reset the 'drawing dirty' flag, so the next command can quit AutoCAD without user interaction.
• Close AutoCAD.

Obviously, the actions you trigger in your background AutoCAD process must not require any user interaction, or, if they do, you must feed them the appropriate command line user input through something like mainform.axAcCtrl1.PostCommand(...).

RealDWG and Object Enablers

Revit uses the RealDWG toolkit to implement the DWG file export and import functionality. A frequent question is whether there is any way to hook into this functionality, and how this relates to custom objects and DBX object enablers, like for instance: Is there a way to load a DBX application into Revit as a RealDWG extension? It would be handy to be able to reuse the functionality of some custom ObjectDBX classes.

First of all, let us clarify some terms required in this context:

• ObjectARX: The AutoCAD Runtime Extension, originally just ARX.
• ObjectDBX: The AutoCAD-independent subset of ObjectARX that deals only with the AutoCAD database, the DWG file.
• RealDWG: An AutoCAD-independent library for reading and writing DWG files using ObjectDBX in a stand-alone application. Requires a separate license.
• Custom object: An instance of a C++ class that can be stored in an AutoCAD database, implemented by an ObjectARX or ObjectDBX plug-in.
• Custom entity: An custom object that defines graphics and can reside in the block table of an AutoCAD database.
• Object enabler: An AutoCAD-independent plug-in module, i.e. an ObjectDBX plug-in, that defines the properties and behaviour of a custom object or entity.
• Proxy graphics: Hard-coded graphics data stored in a DWG file and used to render a custom object in the absence of its object enabler.

ObjectARX supports extending AutoCAD during runtime with plug-in modules implemented in C++. An ObjectDBX plug-in makes use of only an AutoCAD independent subset of ObjectARX. It can therefore be loaded both inside of AutoCAD, and outside into other non-AutoCAD host applications such as TrueView.

More details about RealDWG are provided in the RealDWG Developer Center. Thanks to Adam Nagy from our DevTech team in Europe, we also have a DevTV recording explaining how to make use of this API, available for download (97.5 MB) or for online viewing. Kean Walmsley provides a list of more DevTV recordings on various Autodesk APIs.

RealDWG itself does include a full ObjectARX runtime kernel which provides the ability to load an object enabler. It needs it to manage the ARX class relationships, and it includes the acrxLoadModule API call to load a DBX module. It obviously cannot load an ARX module, i.e. a module that depends on AutoCAD, because it is not AutoCAD.

On the other hand, RealDWG within Revit is a different story. In that context, no object enablers are loaded. Revit only uses RealDWG to display the graphics of the primitive entities within the DWG file, without bothering to load object enablers for custom classes. It does not load object enablers, even though RealDWG itself is theoretically capable of doing so.

For export, Revit uses RealDWG to generate DWG files with primitive built-in ObjectARX entities. For importing DWG files, it uses it to read and display entities and other data from the DWG file. It does not use any additional classes or do anything to manage the object hierarchy, so it does not load object enablers. All it uses is primitives already available in the RealDWG system. All custom objects just render their proxy graphics.

When you call an ObjectARX entity's worldDraw function and its object enabler is not loaded, it just returns its proxy graphics. If the enabler is loaded, the real entity calculates and returns its proper live graphics. This functionality is automatically handled by worldDraw.

Revit does not register itself as a RealDWG application, and so the object enabler installers do not see it and do not set up any object enabler autoloading.

The result is that you cannot use the RealDWG functionality built in to Revit to load an object enabler or make use of ObjectDBX functionality.

You may be able to implement your own .NET based RealDWG application inside a Revit plug-in. This combination has not been tested, however, and is not explicitly supported. You may run into problems where the RealDWG licensing mechanism interferes with the Revit plug-in security features.

If this combination works, it would enable you to make use of the AcGe library within your Revit application. It would also give you access to the acrxLoadModule, thus providing the complete required kernel functionality in able to load a DBX object enabler or handle custom objects in DWG files. If anybody has succesfully made use of this combination, it would be interesting to hear from you and discuss further details. However, there is another easy way to achieve the same result ...

A related topic is the possibility to run AutoCAD as a hidden process and make full use of all its API functionality from within Revit, which we will look at next.

Adding a Shared Parameter to a DWG File

I was recently asked whether it is possible to attach a shared parameter to a DWG drawing file imported into a Revit model. The exploration of this issue was interesting enough for me to like to share it.

First of all, if you are interested in attaching a shared parameter to Revit elements, there are some pretty clear examples available demonstrating how to achieve this. One is the FireRating sample in the Revit SDK, the other is the Revit API introduction labs suite 4-3-1, 4-3-2, and 4-3-3, which is based on the FireRating sample and includes some extensions as well. The former is in VB, the latter both C# and VB.

When defining a new shared parameter, you need to specify which categories it applies to. The FireRating sample attaches a shared parameter 'FireRating' to all doors in the Revit model, and it identifies them using the BuiltInCategory OST_Doors. The labs extend this slightly in order to show that you can attach a shared parameter to walls as well. Doors are standard family instances, whereas walls use a system family.

The interesting thing that cropped up exploring this for imported drawing files is that the process of importing the drawing into Revit causes Revit to create a new category specifically for the inserted file on the fly, named the same as the original drawing file. For instance, after inserting Drawing1.dwg, a new category named Drawing1.dwg appears in Document.Categories. Therefore, for imported drawing files, we obviously cannot use a built-in category to identify which instances to attach the parameter to.

So, to create a new shared parameter for an inserted drawing file, you will need to keep track of the drawing name and use that to identify the category to define the shared parameter for. I have tested this procedure in the attached C# version of the labs and verified that it works.

The set of categories defined in a document is managed using the Revit API Categories container class. One nice thing about this class is that it provides keyed access to the categories it contains by either category name or by built-in category enumeration value. In C#, we see the following two overloads:

  public virtual Category get_Item(
    string key );

  public virtual Category get_Item(
    BuiltInCategory categoryId );

In our case, this means that we can use both BuiltInCategory.OST_Doors and "Drawing1.dwg" as identifiers to define the category we are interested in:

  static public BuiltInCategory Target
    = BuiltInCategory.OST_Doors;

  static public BuiltInCategory Target
    = BuiltInCategory.OST_Walls;

  static public string Target
    = "Drawing1.dwg";

In this simple example, we are using a hard-wired drawing file name. In real life, this would have to be managed more flexibly.

For the full code of the external command class Lab4_3_1_CreateAndBindSharedParam that creates the shared category for an imported drawing file, please look at the corresponding C# file in the Revit API introduction labs provided here.