The Building Coder

Units and RevitLookup

Here is a typical question from a Revit API newbie that prompts me to reiterate some important basic beginner information on units and the RevitLookup tool for exploring the Revit database:

Question: How can I retrieve the length and mass units from a Revit document?

Answer: The internal Revit database length unit is always imperial feet.

That cannot be changed, so there is you answer for that.

Similarly, the internal database unit for weight is kg, as far as I know.

Revit Database Units

In fact, most internal Revit database units except length are SI units, and length is handled differently.

The user interface can display other units, set up just as the user prefers. They can also be modified programmatically, as demonstrated by the ProjectUnit SDK sample.

You can determine any internal database unit by setting the value of a given parameter using it on some Revit element to a specific number, e.g. 1.0, in the user interface.

You can then use RevitLookup to examine the parameter's resulting underlying database value.

The quotient between the user display and the underlying database values provides a factor that you can use to convert between user display and internal database units and enables you to determine what the internal database unit actually is.

This topic has been discussed exhaustively on The Building Coder blog. In fact, one of the very first posts ever is still perfectly valid. It deals with and covers all the fundamental facts of units.

We presented a unit conversion tool and updated it for Revit 2011 and 2013.

Many other aspects of this topic are collected in The Building Coder units category.

RevitLookup

I mentioned RevitLookup above. This is one of the most important tools, both for developers and end users, that you absolutely must be aware of.

It was formerly named RvtMgdDbg. This detailed description still calls it so.

Here are step-by-step installation instructions for Revit 2011 that pretty much still apply. There is even a video demonstrating the installation for Revit 2013.

RevitLookup is included in the Revit SDK available from the Revit Developer Center, which also includes all the other important material for getting started with the Revit API. Here is also an updated version with a corrected add-in manifest file to simplify the installation.

I hope that fully answers your question and helps you get started successfully.

Determine Revit Demo Mode Revisited

Almost a year back, we talked about how to determine whether the current running Revit application is a demo version or not.

The initial suggestion was to test this by trying to execute real functionality modifying the model and then save it. That obviously incurs significant overhead and may cause other problems as well.

Rudolf Honke suggested simply reading and evaluating the Revit main window title text instead.

Now Madmed created and posted an implementation of Rudolf's idea. I took the opportunity of both adding that as a new command CmdDemoCheck to The Building Coder samples and simultaneously incrementing all the year number references in the source code comments from 2012 to 2013, so that that trivial yearly update step is over and done with.

Another obvious step to be performed is the elimination of all warning messages when compiling the code, since they indicate obsolete API usage that needs to be cleaned up. Stay tuned for that anon.

Rudolf suggested checking whether the main window caption contains the words "VIEWER" and "MODE". This is language dependent, of course, and would be "MODUS" in the German Revit, for instance. He provided a link to C# and VB GetWindowText implementations and pointed out that this approach works in a zero-document scenario and will fail if the current document is named something like "VIEWER-MODE". That problem could be worked around by more intelligent parsing of the string to extract the document name, for instance, before searching for the demo mode trigger string.

To begin with, here is Madmed's implementation:

  [DllImport( "user32.dll", SetLastError = true,
    CharSet = CharSet.Auto )]
  static extern int GetWindowText(
    IntPtr hWnd,
    StringBuilder lpString,
    int nMaxCount );
 
  [DllImport( "user32.dll", SetLastError = true,
    CharSet = CharSet.Auto )]
  static extern int GetWindowTextLength(
    IntPtr hWnd );
 
  static StringBuilder GetStatusTextMadmed(
    IntPtr mainWindow )
  {
    StringBuilder s = new StringBuilder();
    if( mainWindow != IntPtr.Zero )
    {
      int length = GetWindowTextLength( mainWindow );
      StringBuilder sb = new StringBuilder( length + 1 );
      GetWindowText( mainWindow, sb, sb.Capacity );
      sb.Replace( "Autodesk Revit Architecture 2013 - ", "" );
      return sb;
    }
    return s;
  }

He suggests using it like this:

  IntPtr revitHandle = System.Diagnostics.Process
    .GetCurrentProcess().MainWindowHandle;
 
  StringBuilder sb = GetStatusText(revitHandle);
 
  bool isDemo = sb.ToString()[0] != '['

When trying that out on my system, I noticed that I my Revit window title does not include the "Architecture" sub-string, since I am running the one-box version.

I also thought that it might be handy and cleaner to start off by implementing a method which simply returns the entire Revit main window caption string unmodified, for the caller to use freely in any desired fashion. I ended up with the following implementation:

  static string GetWindowText( IntPtr mainWindow )
  {
    if( IntPtr.Zero == mainWindow )
    {
      throw new ArgumentException(
        "Expected valid window handle." );
    }
    int len = GetWindowTextLength( mainWindow );
    StringBuilder sb = new StringBuilder( len + 1 );
    GetWindowText( mainWindow, sb, sb.Capacity );
    return sb.ToString();
  }

That returns "Autodesk Revit 2013 - Not For Resale Version - [Floor Plan: Level 1 - rac_empty.rvt]" on my system.

The sample command making use of this currently looks like this:

  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    IntPtr revitHandle = System.Diagnostics.Process
      .GetCurrentProcess().MainWindowHandle;
 
    string s = GetWindowText( revitHandle );
 
    // My system returns:
    // "Autodesk Revit 2013 - Not For Resale Version 
    // - [Floor Plan: Level 1 - rac_empty.rvt]"
 
    bool isDemo = s.Contains( "VIEWER" );
 
    TaskDialog.Show( "Demo Version Check",
      ( isDemo ? "Demo" : "Production")
      + " version." );
 
    return Result.Succeeded;
  }

Here is version 2013.0.100.0 of The Building Coder samples with incremented year numbers throughout and including the new CmdDemoCheck command.

Many thanks to Rudolf for his helpful ideas and to Madmed for prompting me to pick this up again.

Retain or Update External Command GUID

Here are some thoughts by my colleague Joe Ye on whether to retain or update an external command GUID:

It is acceptable to keep the GUID unchanged for different versions of your Revit add-in. If you release several different versions for the same Revit version, e.g. 2013, you obviously have to make sure that only one add-in manifest file to load it is found.

If you prefer, it is also okay to define a different GUID for each version of your add-in. In that case, please note that an external command with the same name from two different versions can be loaded simultaneously.

If the add-in creates its own Ribbon items, trying to create the same items twice over will also cause an error, since ribbon item names are unique.

Thank you, Joe, for these hints.

Categories Collection Item Accessor Fails

The document settings categories collection Item property returns null for certain built-in categories, and even throws an exception for certain others. You should be aware of this.

I mentioned a related issue back in the Revit 2011 timeframe, describing The Building Coder CmdCategories sample command.

Still, this is a bit unexpected and has caused issues for several developers.

Here are some examples:

Question 1: For some reason I cannot obtain the category for stacked walls, e.g. using

  Dim cat As Category = Doc.Settings.Categories
    .Item(BuiltInCategory.OST_StackedWalls)

This call returns nothing even though I have stacked walls in my document. I can also find the BuiltinCategory.OST_StackedWalls using RevitLookup.

Should I be looking somewhere else?

Question 2: I am adding several parameters through

  doc.ParameterBindings.Insert(
    information, caseTying, bipgroup );

Sometimes I get an error, even though the parameters all seem OK.

The stack trace says NullReferenceException in BindingMap.Insert.

What is causing this?

Here is a code snippet demonstrating the problem:

  DefinitionFile sharedParametersFile
    = app.OpenSharedParameterFile();
 
  DefinitionGroup group = sharedParametersFile
    .Groups.Create( "Reinforcement" );
 
  Definition def = group.Definitions.Create(
    "ReinforcementParameter", ParameterType.Text );
 
  List<BuiltInCategory> bics
    = new List<BuiltInCategory>();
 
  //bics.Add(BuiltInCategory.OST_AreaRein);
  //bics.Add(BuiltInCategory.OST_FabricAreas);
  //bics.Add(BuiltInCategory.OST_FabricReinforcement);
  //bics.Add(BuiltInCategory.OST_PathRein);
  //bics.Add(BuiltInCategory.OST_Rebar);
 
  bics.Add( BuiltInCategory
    .OST_IOSRebarSystemSpanSymbolCtrl );
 
  CategorySet catset = new CategorySet();
 
  foreach( BuiltInCategory bic in bics )
  {
    catset.Insert(
      doc.Settings.Categories.get_Item( bic ) );
  }
 
  InstanceBinding binding
    = app.Create.NewInstanceBinding( catset );
 
  doc.ParameterBindings.Insert( def, binding,
    BuiltInParameterGroup.PG_CONSTRUCTION );

Answer: The first issue is due to OST_StackedWalls being marked 'Hidden to User', causing certain internal methods to return false. As a final result, the Categories Item accessor returns null.

'Hidden to User' means that the user interface to Object Styles, Visibility/Graphics, and Export Layers will not include these categories.

It does not mean that the categories are hidden everywhere in the product. Some features get a specific category from an element and display its name. For example, the status prompt displays the category of the element that the mouse is hovering over, and the Selection Filter dialog displays the categories of selected elements. This works because other methods return all categories regardless of the 'Hidden to User' flag.

Aside from OST_StackedWalls, here are some other categories that may correspond to real elements that users can see, select, and whose category name may appear:

• OST_Reveals
• OST_ArcWallRectOpening
• OST_SWallRectOpening
• OST_SitePropertyLineSegment
• OST_RvtLinks
• OST_LegendComponents
• OST_ConnectorElem

Some features also display lists of categories that don't come from the CategoryTableInterface methods. Schedules, project parameters, the Family Category and Parameters dialog are examples. Typically those can also include 'Hidden to User' categories. For example, OST_SitePropertyLineSegment is a schedulable category despite being 'Hidden to User'.

In some cases it may be incorrect for the API to prevent people from working with 'Hidden to User' categories. Of course any APIs for category-related features should have proper validation so that people can only use appropriate categories. For example, APIs for category visibility, project parameters, and schedules should restrict which categories can be used for those features, just like the UI does. We have to be careful about exposing 'Hidden to User' categories without checking other APIs for proper validation. For example, the project parameters API may allow more categories that it should.

I expanded The Building Coder samples CmdCategories external command to determine and display a list of all the built-in categories causing the Categories.Item property to either return null or throw an exception. Here is the code that demonstrates that:

  Array bics = Enum.GetValues(
    typeof( BuiltInCategory ) );
 
  int nBics = bics.Length;
 
  Debug.Print( "{0} built-in categories and the "
    + "corresponding document ones:", nBics );
 
  Category cat;
  string s;
 
  List<BuiltInCategory> bics_null
    = new List<BuiltInCategory>();
 
  List<BuiltInCategory> bics_exception
    = new List<BuiltInCategory>();
 
  foreach( BuiltInCategory bic in bics )
  {
    try
    {
      cat = categories.get_Item( bic );
 
      if( null == cat )
      {
        bics_null.Add( bic );
        s = "<null>";
      }
      else
      {
        s = string.Format( "{0} ({1})",
          cat.Name, cat.Id.IntegerValue );
      }
    }
    catch( Exception ex )
    {
      bics_exception.Add( bic );
 
      s = ex.GetType().Name + " " + ex.Message;
    }
    Debug.Print( "  {0} --> {1}", 
      bic.ToString(), s );
  }
 
  int nBicsNull = bics_null.Count;
  int nBicsException = bics_exception.Count;
 
  TaskDialog dlg = new TaskDialog(
    "Hidden Built-in Categories" );
 
  s = string.Format(
    "{0} categories obtained from the Categories collection;\r\n"
    + "{1} built-in categories;\r\n"
    + "{2} built-in categories retrieve null result;\r\n"
    + "{3} built-in categories throw an exception:\r\n",
    nCategories, nBics, nBicsNull, nBicsException );
 
  Debug.Print( s );
 
  dlg.MainInstruction = s;
 
  s = bics_exception
    .Aggregate<BuiltInCategory, string>(
      string.Empty,
      ( a, bic ) => a + "\n" + bic.ToString() );
 
  Debug.Print( s );
 
  dlg.MainContent = s;
 
  dlg.Show();

This is the resulting output in an empty architectural project reporting the count of document categories, built-in categories, and built-in categories for which a document category cannot be retrieved, either because the call the Categories.Item returns null or throws an exception:

To spell it out in full text:

• 259 categories obtained from the Categories collection;
• 897 built-in categories;
• 358 built-in categories retrieve null result;
• 12 built-in categories throw an exception:
  • OST_FurnitureHiddenLines
  • OST_SplitterProfile
  • OST_HostTemplate
  • OST_MassFaceSplitter
  • OST_MassCutter
  • OST_ZoningEnvelope
  • OST_StairsSupports
  • OST_InstanceDrivenLineStyle
  • OST_CurtainGridsSystem
  • OST_StairsStringerCarriage
  • OST_IOSNotSilhouette
  • OST_InvisibleLines

The complete lists of built-in categories for which no corresponding document category can be retrieved are logged to the Visual Studio debug output window. They obviously depend on the document that you run this command in.

You should probably run it yourself in the documents you are working with to be aware of what is going on. In any case, all code accessing the Categories.Item property with untested built-in categories needs to implement appropriate handling of these conditions.

Here is the updated version 2013.0.99.1 of The Building Coder samples including the expanded version of the CmdCategories external command displaying the list of hidden built-in categories.

Addendum: Saikat presented another example of an inaccessible category, the Profiles category OST_ProfileFamilies.

Brute Force Computing

I stumbled across this interesting article on brute force computing explaining one interesting aspect of cloud based computing and access to huge amounts of computing power.

One fact I was totally unaware of, and that had me a bit surprised in the past year or two, is that "brute force computing is behind Google's successful language translation. By comparing thousands of Web pages in different languages to find patterns, in one year Google was able to discern and refine translation better than linguistic theorists had been able to do with their fancy programs for years."

As you of course know, Autodesk offers the Autodesk 360 cloud-based platform providing access to storage, a collaboration workspace, and a fast-growing number of cloud services to help improve design, visualisation, simulation, and work sharing.

Blending Profiles with Different Vertex Counts

Arjen de Pater raised a question on using the NewBlend method that Mikako Harada just addressed:

Question: I want to create a blend with 8 curves in the BottomProfile and 4 curves in the TopProfile.

When I try this the Document.FamilyCreate.NewBlend method throws an ApplicationException saying "Unexpected internal error: code 1. at Autodesk.Revit.Creation.FamilyItemFactory.NewBlend(Boolean isSolid, CurveArray topProfile, CurveArray baseProfile, SketchPlane sketchPlane)".

How can I create such a blend?

Answer: There are some points you need to pay attention to. These points are documented in the page explaining the NewBlend method in Revit API help file RevitAPI.chm file. It also includes sample code to create a blend form:

1. The two profiles should be parallel.
2. Each of the profiles must be planar.
3. If the profile shape is circle or ellipse, it must be split into at least two segments, so that Revit can find vertices to use for mapping the blend.

Once that is clear, you should definitely ensure that you can create the same shape through the user interface, as recommended for debugging form creation. If that fails, then it will fail through the API as well. It may provide you with a more informative error message, though.

Response: Yes, I can create the blend in the UI.

The problem is the different number of curves in the BottomProfile and TopProfile because the NewBlend method lacks a parameter for the VertexConnectionMap.

Answer: Ah. Well, here are two NewSweptBlend samples, which may or may not prove useful.

However, Mikako hopefully provided the ultimate solution by demonstrating blending two profiles with different top and bottom vertex counts.

Creating a ViewPlan in a Family Document

On the topic of Revit API blog posts by my colleagues on the AEC DevBlog, here is another interesting topic brought up by Saikat Bhattacharya:

You can create a new ViewPlan in a family document using the View.Duplicate method taking a ViewDuplicateOption, something that I was not previously aware of.

You cannot use the NewViewPlan method to achieve this in a family document, because it throws an InvalidOperationException, as Saikat explains very clearly.

Determine Revit Demo Mode

Here is yet another interesting example of an apparent gap in the Revit API that can be easily filled using a little workaround.

We have seen numerous examples of performing a certain operation within a temporary transaction that is then rolled back to cancel it, such as to determine gross material quantities for an element with openings, a host reference and, more generally, all object relationships.

Here is an example of using a related but different approach: the trick consists in attempting to perform a certain operation and gracefully handling a specific expected failure condition, in ths case a specific exception being thrown, to determine whether Revit is running in demo mode:

Question: Is it possible to determine whether Revit runs in demo mode? I need this for two different reasons:

• It is a licensing issue, since read-only viewing should not occupy a license.
• Some add-in commands should be greyed out or hidden in the ribbon bar in demo mode.

Answer: You could try to save the model (after making a modification!) and then see if you get an InvalidLicenseException.

I implemented a little sample application TestDemoMode to test a simplified version of this idea.

Here is the test method I created:

  static bool IsDemoMode( Document doc )
  {
    Application app = doc.Application;
 
    try
    {
      Transaction tx = new Transaction( doc );
 
      tx.Start( "Modify Document" );
 
      SketchPlane sp 
        = new FilteredElementCollector( doc )
          .OfClass( typeof( SketchPlane ) )
          .FirstElement() as SketchPlane;
 
      Line line = app.Create.NewLineBound( 
        XYZ.Zero, XYZ.BasisX );
 
      ModelCurve mc = doc.Create.NewModelCurve(
        line, sp );
 
      tx.Commit();
 
      string filename = Path.GetTempFileName();
      File.Delete( filename );
 
      doc.SaveAs( filename );
      File.Delete( filename );
 
      tx.Start( "Unmodify Document" );
      doc.Delete( mc );
      tx.Commit();
 
      return false;
    }
    catch( InvalidLicenseException ex )
    {
      return true;
    }
  }

This is the external command Execute mainline code:

  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    bool rc = IsDemoMode( doc );
 
    string s = string.Format( 
      "This is {0}a Revit demo version.", 
      rc ? "" : "not " );
 
    TaskDialog.Show( "Test Demo Mode", s );
 
    return Result.Succeeded;
  }

I have not tested it for both cases, though, since I do not have a demo version handy.

I did run it in a non-demo version, which was correctly reported:

I have also not added any checks to determine whether the write and save attempt may be failing due to the document being read-only, disk full, or anything like that.

A much better approach would be to create a new document from scratch and attempt to save that.

Anyway, here is TestDemoMode.zip including the source code, add-in manifest and full Visual Studio solution of the simplified test command.

A full-blown implementation requires a number of additional considerations and lots of testing, of course. As said, the '1 new document' - '2 edit document' - '3 save as' strategy might be best. Hopefully all exceptions thrown during the first two steps will have to do with the licensing. Step three is less certain, since for instance the hard drive may be full.

Saving the current document is a really bad idea and might take a long time, without even thinking about detaching from central and keeping work-shares.

Rotate True North

We have previously looked at how to handle the project location properties and more specifically how to handle the effect of a rotated Project North on an element azimuth.

Here is a question on the 'opposite' topic, how to set up a project north rotation in the first place:

Question: Is there any way to rotate the truth north using the Revit API?

It can be done in the user interface using the Manage > Project Location > Position > Rotate True North command:

Here is the English command with its expanded tooltip:

Answer: I believe the same effect can be achieved by rotating the Project North which is available in the API.

If this fits the bill, then here are some working code snippets making use of the related classes and methods:

  ProjectLocation plCurrent
    = _doc.ActiveProjectLocation;
 
  // . . . 
 
  ProjectPosition newPosition
    = _app.Create.NewProjectPosition(
      scaleToFT * cs.OriginX,
      scaleToFT * cs.OriginY,
      scaleToFT * cs.OriginZ,
      theRotationYouWant );
 
  plCurrent.set_ProjectPosition(
    ptOrigin, newPosition );

You may have to do this for all project locations. A bit of 3D maths and brainwork may be required, but it should be doable.

Many thanks to Katsuaki Takamizawa and Miroslav Schonauer for this discussion and suggestion!

Family Instance Room Phase

We already looked at some examples of confusion due to the interaction of phases with the room property on family instances. Here is a new aspect of this encountered and solved by Patrick Rosendahl of SOLAR-COMPUTER GmbH, who kindly explains the issue and its resolution like this:

Problem: I am having a problem with the FamilyInstance Room property. I looked at the discussion of issues with the Room property and its phase dependency but have not been able to solve it yet.

This is the situation:

• Customer makes use of design options and phasing.
• Most rooms are in the main model, some rooms are in design options.
• There are three phases: phase_A, phase_B, phase_C.
• Phase_C is not used, have not checked the impact if deleted.
• Most architecture is created in phase_A and located in the main model.
• Some architecture is created in phase_B and located in design options.
• All family instances and all rooms are created in phase_B.
• Room volume computation is turned on.
• Revit's schedules work correctly, i.e. show the correct room-wise list of family instances.

These are the problems encountered:

• Sometimes, the family instance Room property returns null, even though the family instance is clearly within a room.
• Even worse: sometimes, the family instance method get_Room( familyinstance.CreationPhase ) returns null.

Questions:

• Might there be a problem with the design options?
• Is there any better workaround than the two approaches mentioned above?
• What function is the Revit schedule using to successfully determine the room property of family instances?

As a workaround, I thought of calling the get_Room method on the family instance in a loop over all available phases in the project, and making use of the document PointInRoom method if that fails.

Solution: Here is a promising start for a solution that I am currently exploring:

• Obviously, first try using the family instance Room property directly.
• If that fails, try
  

  foreach(Phase p) { familyinstance.get_Room(p) }

• Hard part: determine primary options;
  

  foreach(Room r where r.DesignOption.IsPrimary) { 
    r.IsPointInRoom( fi.Location ) }

• Emergency:
  

  foreach( Room r ) { r.IsPointInRoom( fi.Location ) }

Here is the actual method implementating this that I am currently working with, including some todo items left as an exercise for the reader ;)

public static Room DetermineRoom( Element el )
{
  FamilyInstance fi = el as FamilyInstance;
 
  if( fi == null )
  {
    return null;
  }
 
  // As simple as that?
 
  try
  {
    if( fi.Room != null )
    {
      //Debug.WriteLine("fi.Room != null");
      return fi.Room;
    }
  }
  catch 
  { 
  }
 
  // Try phasing
 
  Room r = null;
 
  foreach( Phase p in el.Document.Phases )
  {
    try
    {
      // TODO should check fi.GetPhaseStatus 
      // instead of provoking an exception
 
      r = fi.get_Room( p );
 
      if( r != null )
      {
        //Debug.WriteLine("fi.get_Room( " 
        //  + p.Name + ") != null");
 
        return r;
      }
    }
    catch 
    { 
    }
  }
 
  LocationPoint lp = el.Location as LocationPoint;
 
  if( lp != null )
  {
    // Try design options
 
    List<Element> roomlst = get_Elements( 
      el.Document, typeof( Room ) );
 
    // Try rooms from primary design option
 
    foreach( Element roomel in roomlst )
    {
      Room priroom = roomel as Room;
 
      if( priroom == null )
        continue;
 
      if( priroom.DesignOption == null )
        continue;
 
      if( priroom.DesignOption.IsPrimary )
      {
        // TODO should check whether priroom 
        // and el phasing overlaps
 
        if( priroom.IsPointInRoom( lp.Point ) )
        {
          //Debug.WriteLine(
          //  "priroom.IsPointInRoom != null");
 
          return priroom;
        }
      }
    }
 
    // Emergency: try any room
 
    foreach( Element roomel in roomlst )
    {
      Room room = roomel as Room;
 
      if( room == null )
        continue;
 
      // TODO should check whether room 
      // and el phasing overlaps
 
      if( room.IsPointInRoom( lp.Point ) )
      {
        //Debug.WriteLine(
        //  "room.IsPointInRoom != null");
        return room;
      }
    }
  }
 
  // Nothing found
 
  return null;
}

I think this approach provides is a good starting point. A more complete solution might possibly take the phase and design option as arguments. In my context, the function above rarely returns a non-primary design option room.

Many thanks to Patrick for his research and sharing this solution!

Set New Pipe Type Properties

Here is an interesting Revit MEP API question on setting the preferred elbow, tee and junction type information after creating a new Revit MEP pipe type, answered by my colleague Joe Ye in Beijing:

Question: I am creating a new Revit MEP pipe type by filtering for all element types of the category OST_PipeCurves and selecting the one named "Standard". On the resulting new ElementType instance, I would like to define the preferred settings as follows:

• Change the preferred elbow from 'Elbow - Generic: Standard ' to 'Elbow - Thread - MI - Class 150: Standard'.
• Change the preferred tee from 'Tee - Generic: Standard' to 'Tee - Thread - MI - Class 150: Standard'.
• Change the preferred junction type from 'Tee' to 'Tap'.

Can you show me in C# how to achieve this, please?

Answer: These three changes can be achieved by changing the values of some properties on the PipeType element:

• Elbow: the default elbow fitting of the MEP curve type.
• Tee: the default tee fitting of the MEP curve type.
• PreferredJunctionType: the preferred junction type of the MEP curve type.

The values stored in the first two properties are family symbols. You need to find the desired target element in the Revit database and assign it to them.

For example, for the elbow, you can filter out the desired FamilySymbol 'Elbow - Thread - MI - Class 150: Standard'. This element's class is 'FamilySymbol' and its built-in category is 'OST_PipeFitting'. Use these two filters and the traverse the returned element collection to find the target FamilySymbol by name comparison, and assign it to the Elbow property.

Instead of using the PipeType Elbow property, you can also use the generic Revit parameter access and the appropriate built-in parameter. This can be determined by exploring an existing pipe type using the RevitLookup database snoop tool. In that case, you can assign the value by calling the Parameter.Set(ElementId) method and passing in the family symbol element id.

Setting the desired tee is similar to the elbow. In this case, you can filter out the target FamilySymbol 'Tee - Thread - MI - Class 150: Standard' and assign it to the Tee property, or its element id to the equivalent parameter.

For the preferred Junction Type, you specify your choice using an integer value to indicate one of the two available options. 0 indicates Tap, and 1 indicates Tee.

So in your case, you would assign the integer value 0 to the 'Preferred Junction Type' property or parameter.

The complete code making use of the generic parameter access might look like this:

using System;
using System.Collections.Generic;
using System.Linq;
using Autodesk.Revit.ApplicationServices;
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.DB.Plumbing;
using Autodesk.Revit.UI;
 
[TransactionAttribute( TransactionMode.Manual )]
public class RevitCommand : IExternalCommand
{
  public Result Execute( 
    ExternalCommandData commandData, 
    ref string messages, 
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    Document rvtDoc = app.ActiveUIDocument.Document;
 
    FilteredElementCollector collector 
      = new FilteredElementCollector( rvtDoc );
 
    collector.OfCategory( BuiltInCategory.OST_PipeCurves );
    collector.OfClass( typeof( ElementType ) );
 
    PipeType pipeType = null;

    foreach( Element ptype in collector )
    {
      if( string.Compare( ptype.Name, "standard", true ) == 0 )
      {
        pipeType = ptype as PipeType;
        break;
      }
    }
 
    if( pipeType != null )
    {
      string name = "ADNNewType";
 
      Transaction trans = new Transaction( rvtDoc )
      trans.Start(  "Set Pipe Type Information" );
 
      ElementType newType = pipeType.Duplicate( name );
 
      if( newType != null )
      {
        ElementId id1 = FindFamilyType( rvtDoc, 
          typeof( FamilySymbol ), 
          "Elbow - Threaded - MI - Class 150", "Standard", 
          BuiltInCategory.OST_PipeFitting ).Id;
 
        ElementId id2 = FindFamilyType( rvtDoc, 
          typeof( FamilySymbol ), 
          "Tee - Threaded - MI - Class 150", "Standard", 
          BuiltInCategory.OST_PipeFitting ).Id;
 
        newType.get_Parameter( 
          BuiltInParameter.RBS_CURVETYPE_DEFAULT_ELBOW_PARAM )
            .Set( id1 );
 
        newType.get_Parameter( 
          BuiltInParameter.RBS_CURVETYPE_DEFAULT_TEE_PARAM )
            .Set( id2 );
 
        newType.get_Parameter( 
          BuiltInParameter.RBS_CURVETYPE_PREFERRED_BRANCH_PARAM )
            .Set( 0 );
 
      }
      trans.Commit();
    }
    return Result.Succeeded;
  }
 
  /// <summary>
  /// Find an element of the given type, name, 
  /// and category (optional).
  /// You can use this, for example, to find a 
  /// specific wall and window family with the 
  /// given name, e.g.:
  /// FindFamilyType( _doc, GetType(WallType), 
  ///   "Basic Wall", "Generic - 200mm" ) 
  /// FindFamilyType( _doc, GetType(FamilySymbol), 
  ///   "M_Single-Flush", "0915 x 2134mm", 
  ///   BuiltInCategory.OST_Doors ) 
  /// </summary>
  public static Element FindFamilyType( 
    Document rvtDoc, 
    Type targetType,
    string targetFamilyName, 
    string targetTypeName, 
    Nullable<BuiltInCategory> targetCategory )
  {
    var collector 
      = new FilteredElementCollector( rvtDoc )
        .OfClass( targetType );
 
    if( targetCategory.HasValue )
    {
      collector.OfCategory( targetCategory.Value );
    }
 
    // Parse the collection for the given names 
    // using LINQ
 
    var targetElems =
        from element in collector
        where element.Name.Equals( targetTypeName ) 
          && element.get_Parameter( 
            BuiltInParameter.SYMBOL_FAMILY_NAME_PARAM )
              .AsString().Equals( targetFamilyName )
        select element;
 
    // Put the result as a list of element fo accessibility. 
 
    IList<Element> elems = targetElems.ToList();
 
    // Return the result.
 
    if( elems.Count > 0 )
    {
      return elems[0];
    }
    return null;
  }
}

By the way, these preferred element options can also be set to None. This is achieved just like we described for setting the underlay display property, by using the parameter setting approach and providing ElementId.InvalidElementId as a value, e.g.

    newType.get_Parameter( 
      BuiltInParameter.RBS_CURVETYPE_DEFAULT_ELBOW_PARAM )
        .Set( ElementId.InvalidElementId );

Many thanks to Joe for this solution!

Locking the Add-Ins Ribbon Tab

Here is a minute user interface question of interest to developers that comes up from time to time:

Question: When I select an element in the Revit model, the ribbon tab is always switched. Is there any way to keep 'Add-Ins' tab focused at all times?

Answer: Here are two little tricks that might help:

• Drag the panel you wish to have available off the ribbon add-ins tab somewhere else on the screen. It will then remain available at all times, regardless of how the other ribbon tabs are switched back and forth.
• As I already mentioned discussing the ribbon tab context toggle, you can also select Big R > Options > User Interface and uncheck 'Display the contextual tab on Selection':

Visual Studio, C# and VB Express

Yesterday Kean mentioned that debugging AutoCAD.NET projects using the Visual C# and VB Express editions is now directly supported by the latest version of the AutoCAD .NET Wizard.

That prompted me to have a look and see what the current situation is with Revit add-ins.

Obviously, we poor Revit developers do not have such a sophisticated wizard available ... or so I thought!

I installed Visual C# Express and started my experiment:

I launched the new installation and selected New Project > Visual C#.

My intention was to select 'Class Library' next and manually set up the Revit API references and all that stuff, then move on to explore how to define appropriate debug settings.

However, guess my surprise to see the Revit Add-in option already listed:

Apparently, the Visual Studio Add-In Wizards for Revit 2012 that I have installed for the full version of Visual Studio are also picked up by Visual C# Express.

Well, that simplifies matters a lot, doesn't it?

There is actually nothing else whatsoever to do.

Debugging is already set up by the add-in wizard, and Revit has been specified as the start-up project, although it is not displayed in the Visual C# Express debug properties:

Simply hitting F5 to start debugging launches Revit, and on opening a project and looking at the Add-Ins tab external tools, I see my new Visual C# Express add-in loaded and raring to go:

After setting a breakpoint using F9 in Visual C# Express and picking the external command in Revit, the breakpoint is hit and full debugging functionality is available in Visual C#:

Wow. I expected this exploration and blog post to take an hour or two, but I was done after fifteen minutes.

I am assuming that all of the above remains valid analogously for Visual Basic 2010 Express as well. Please let me know if you can verify this, or have any problems with either that or the C# version.

So the short and sweet message is: all you need to do is install Visual C# or Visual VB Express and the appropriate Visual Studio add-in wizard for Revit, and you will be all set to create stand-alone add-ins and develop and debug them using the Express tools. I hope you have fun!

Addendum: Here are some additonal notes on this by Augusto Gonçalves of Autodesk Brazil, the original implementer of the Revit add-in wizards:

• One issue with Express is that the project is initially created under \Temp\, and therefore the add-in manifest file is also configured to use this path. Usually on my trainings (with Express), I recommend immediately saving the project after creating it by clicking on 'Save All', selecting a folder, and then updating the path in the add-in manifest file <Assembly> tag.
• Also, keep in mind that Express builds the Debug version when you press F5 (or Star Debugging), and the Release version when you select the command in the Build menu.

Thank you, Augusto, for pointing this out!

Set Copy Local to False

I cannot count the number of times I have pointed out that the Copy Local flag should be set to false on the Revit API assembly references. Here are some of the numerous previous examples and explanations of this:

• A C++ Revit add-in
• Selection watcher using Idling event
• The DevTV add-in templates
• Pipe to conduit converter
• Custom ribbon tab
• Porting from C# to VB.NET
• Exporting a family instance to gbXML
• Application events in VB
• Debugging a Revit add-in
• The SDK samples solution

This flag appears in the properties of the Revit API references. It is also displayed in the list of the references themselves in a VB project. Here they are set to True, which is what we want to avoid:

In a C# project, you can right click on the Revit API references in the Visual Studio solution explorer and selecting its properties in the context menu to see and modify its current setting:

You can toggle this property with a double click.

If this flag is set to True, Visual Studio will create local copies of RevitAPI.dll and RevitAPIUI.dll when compiling the plug-in and use these copies when loading them. This confuses the debugger and Revit when running the add-in, as well as unnecessarily polluting your hard disk with copies of this multi-MB file.

To avoid having to reset this property when modifying an existing reference, for instance when migrating to a new version of the Revit API, do not delete the existing reference. Instead, simply add the new reference to the current assembly to overwrite the old one. The old, existing data will be updated, the new path will be stored, and the existing 'Copy Local' setting will be preserved.

By the way, the same applies to the AutoCAD.NET assemblies.

At least this post gives me a completely comprehensive description to refer to next time I have to point this out...

Retrieving Materials

Some people have reported issues using the Document.Settings.Materials collection. For instance, its Contains method may throw an exception when used with Revit Structure 2012, while it works fine with Revit Architecture 2012.

The problem actually probably has nothing to do with the flavour of Revit being used, but is caused by the template file that the project is based on. If you retrieve materials in a project based on the architectural template in Revit Structure, it also works fine.

In any case, here is a workaround you can use instead. Simply retrieve the materials using a filtered element collector instead of the Materials collection, for example like this:

  FilteredElementCollector collector 
    = new FilteredElementCollector( document )
      .OfClass( typeof( Material ) );
 
  IEnumerable<Material> materialsEnum 
    = collector.ToElements().Cast<Material>();
 
  var materialReturn1 
    = from materialElement in materialsEnum
      where materialElement.Name == "Default"
      select materialElement;

Point Cloud Snap and Freeze

Here are some questions that came up a while ago regarding point clouds:

Question: As far as I can tell, the standard object snap settings also control snapping to point clouds:

Is there any way to snap to individual points in the point cloud?

Answer: Revit itself never asks for the pick of an individual point in a point cloud, so there is no mechanism to support this in the API either. Even when Revit prompts the user to pick things via snapping using the UI option 'snap to point cloud', it creates a small window, asks for 100 points, and is satisfied if there is at least one. Revit does not do anything at all to determine the forward most point or the point closest to the cursor from the cloud.

Here is some sample code showing how to prompt the user to select a box containing points and use a PointCloudFilter to retrieve them:

public void PromptForPointCloudSelection(
  UIDocument uiDoc,
  PointCloudInstance pcInstance )
{
  Application app = uiDoc.Application.Application;
  Selection currentSel = uiDoc.Selection;
 
  PickedBox pickedBox = currentSel.PickBox( 
    PickBoxStyle.Enclosing, 
    "Select region of cloud for highlighting" );
 
  XYZ min = pickedBox.Min;
  XYZ max = pickedBox.Max;
 
  // Transform points into filter 
 
  View view = uiDoc.ActiveView;
  XYZ right = view.RightDirection;
  XYZ up = view.UpDirection;
 
  List<Plane> planes = new List<Plane>();
 
  // X boundaries 
 
  bool directionCorrect = IsPointAbovePlane( 
    right, min, max );
 
  planes.Add( app.Create.NewPlane( right, 
    directionCorrect ? min : max ) );
 
  planes.Add( app.Create.NewPlane( -right, 
    directionCorrect ? max : min ) );
 
  // Y boundaries 
 
  directionCorrect = IsPointAbovePlane( 
    up, min, max );
 
  planes.Add( app.Create.NewPlane( up, 
    directionCorrect ? min : max ) );
 
  planes.Add( app.Create.NewPlane( -up, 
    directionCorrect ? max : min ) );
 
  // Create filter 
 
  PointCloudFilter filter = PointCloudFilterFactory
    .CreateMultiPlaneFilter( planes );
 
  Transaction t = new Transaction( uiDoc.Document ); 
  t.Start( "Highlight" );
 
  pcInstance.SetSelectionFilter( filter );
 
  pcInstance.FilterAction 
    = SelectionFilterAction.Highlight;
 
  t.Commit();
}
 
private static bool IsPointAbovePlane( 
  XYZ normal, 
  XYZ planePoint, 
  XYZ point )
{
  XYZ diff = point - planePoint;
  diff = diff.Normalize();
  double dotProduct = diff.DotProduct( normal );
  return dotProduct > 0;
}

If you don't want the user to have to create the small rectangular window for obtaining points, you may be able to do one of the following:

1. Prompt for element selection using the PickObject method and the ObjectType.PointOnElement, with a filter that is limited to PointCloudInstances or even one specific instance – it may however be difficult to get the cursor to switch from the "don't pick" option for this.
2. Prompt for picking a point using the PickPoint method. You may have to set an active sketch plane for the view to allow this work in 3D.

In either case, you should be able to obtain a 3D point representing the user's selection. The point will have no real relationship to the view and the front of the point cloud. Then you could use the View.ViewDirection property to compute a small rectangle centred on the picked point, and build planes for the PointCloudFilter through the boundary lines of the rectangle and extending parallel to the view direction. That will give you a filter capable of intersecting the point cloud and returning actual points. If too many points are returned, you may need a back clipping plane added to the filter to focus on the points nearest the user's eye position.

Note that View.EyePosition should not be used to compute the distance directly, since the eye position for orthographic views is very close to the model bounding box. Instead, a plane should be computed normal to view direction passing through eye position, and the distance of points measured to this plane.

Question: In Revit, the point cloud can be moved around in the model. Is it possible to disable this?

I want my point cloud to appear as a static object. It should not be moved or modified in CAD environment once it is brought in.

Answer: You can lock the point cloud by pinning it. In the API, simply set the property Element.Pinned to true. This will prevent accidental moves.

Of course, the user can unpin the cloud if they really want to, but at least that requires a conscious decision.

A more complicated way to prevent changes would be to use the Dynamic Update Framework and post an error on an illegal operation; the user will have to cancel the action and restore the original state.

Another completely untested idea might possibly be to assign the point cloud to a workset and check it out with a fake user.

Text Size

I am back again from the Autodesk European Football Tournament 2011 in Verona, Italy, vividly described in more detail by Kean on his blog. We were both part of the combined Global Services (to which we of ADN belong) and Worldwide Marketing team:

Back to the Revit API, we already looked at some aspects of text formatting such as textnote alignment and rotation. Here is a still more immediate and simpler issue:

Question: I created some text using the NewTextNote method. Now I would like to change its size or font like a normal user might do using Edit type > Text size. How can that be achieved programmatically?

Answer: The Text Size parameter can be set as follows:

  Reference r = uidoc.Selection.PickObject( 
    ObjectType.Element );
 
  TextElement text = doc.GetElement( r ) 
    as TextElement;
 
  TextElementType textType = text.Symbol;
 
  Parameter textSize = textType.get_Parameter( 
    "Text Size" );
 
  Transaction transaction 
    = new Transaction( doc );
 
  transaction.Start( "change text size" );
 
  // units are in feet, so this is 1/8"
 
  double newSize = ( 1.0 / 8.0 ) * ( 1.0 / 12.0 ); 
 
  textSize.Set( newSize );
 
  transaction.Commit();

Obviously, it would be better still to use the built-in parameter enumeration value to identify the text size parameter, rather than the language dependent user display parameter name.

Implicit Line Continuation in VB 2010

An new feature that is of interesting to us VB Revit add-in developers is the implicit line continuation that was added in Visual Basic 2010.

In prior versions of VB, all statements that continue beyond the end of the line have to be explicitly marked using an underscore '_' character. Since some of the Revit API method signatures force rather long lines, this can become a bit overwhelming. This is what it might look like in VB 2008:

''' <summary>
''' Hello World #2 - simplified without full namespace.   
''' </summary>
<Transaction(TransactionMode.Automatic)> _
Public Class HelloWorldSimple
  Implements IExternalCommand
 
  Public Function Execute( _
    ByVal commandData As ExternalCommandData, _
    ByRef message As String, _
    ByVal elements As ElementSet) _
    As Result _
    Implements IExternalCommand.Execute
 
    TaskDialog.Show("My Dialog Title", "Hello World Simple!")
    Return Result.Succeeded
 
  End Function
 
End Class

With the new implicit line continuation feature, many of the underscores can be omitted in VB 2010:

<Transaction(TransactionMode.Automatic)>
Public Class HelloWorldSimple
  Implements IExternalCommand
 
  Public Function Execute(
    ByVal commandData As ExternalCommandData,
    ByRef message As String,
    ByVal elements As ElementSet) _
    As Result _
    Implements IExternalCommand.Execute
 
    TaskDialog.Show("My Dialog Title", "Hello World Simple!")
    Return Result.Succeeded
 
  End Function
 
End Class

Note that two of the underscores still remain; the implicit line continuation is only available after certain syntax elements, such as after a comma or an opening parenthesis, or before a closing parenthesis.

Here is an interview with Doug Rothaus of the Visual Studio User Education team describing it:

Updated Visual Basic Add-in Wizard

Here is an updated VB version of the Visual Studio Revit 2012 add-in wizard making use of the implicit line continuation:

• TemplateRevitArch2012AddinVbJt_3.zip – copy to
  [My Documents]\Visual Studio 2010\Templates\ProjectTemplates\Visual Basic

The only change I made was to remove the line continuation underscores wherever possible.

For the C# version, please refer to the original post.

Visual Studio Line Length Guide Line

Another complementary Visual Studio feature of special interest to all of us who have to limit the line length of our source code due to one reason or another is the guide-line for Visual Studio pointed out yesterday by Augusto and Kean.

Since I have the same issue as Kean, having to limit my source code line length strictly to fit into the blog post format, I installed it as described and verified that it works well.

Set the Visual Style of a View

Today is the day of the Chinese Revit API webcast, and also the holiday of Ascension Day in many part of Europe. Just like last year, it is raining cats and dogs again.

Anyway, here is a useful answer to a little question that arises from time to time:

Question: I'm creating a new 3D view of a family instance like this:

  Dim v As View3D = doc.Create.NewView3D( _
    famInst.FacingOrientation)

  v.SectionBox = famInst.BoundingBox(v)

Now I would like to set its visual style to 'Shaded' or 'Shaded with Edges'.

Is there any way to achieve this using the API?

Answer: The view style can be changed by modifying the value of the 'Visual Style' parameter, which corresponds to the built-in parameter MODEL_GRAPHICS_STYLE. Each option in the 'Visual Style' property drop-down list in the property dialog corresponds to an integer value from 0 to 6:

1. Wireframe
2. Hidden line
3. Shaded
4. Shaded with Edges
5. Consistent Colors
6. Realistic

In order to change the visual style to 'Shaded with edges', please set the parameter value to 4, for instance like this:

  view.get_Parameter( 
    BuiltInParameter.MODEL_GRAPHICS_STYLE )
    .set( 4 );

These numbers may have changed since they were first established. You can determine the correct numbers to use yourself by simply cycling through all the styles manually and checking the current parameter value as an integer each time, e.g. using the RevitLookup tool.

Project Vasari 2

The technology preview 2 of the conceptual design and analysis tool Project Vasari, which includes access to the Revit API, is now available in an updated version compatible with Revit 2012:

Set Preview Image

While I am away, here is a useful article to keep you occupied by my colleague Saikat Bhattacharya:

Setting preview image/view for a Revit document using Revit 2012 API

Question: How can I set the preview image/view for a Revit document using the Revit 2012 API? In particular, when I load an older version of Revit document and do a SaveAs using the API, how can I set its preview image?

Answer: There are two ways to set a preview image on a Revit document using the API.

The first approach uses DocumentPreviewSettings to assign a permanent view to the document to always be used for preview settings. This is done by serializing this preview id into the document. Using this approach, the preview view will be permanently set for the document.

In the user interface, when we save a file, typically a permanent view for the preview generation is not assigned. It is only assigned if the users click on the Options button in the SaveAs dialog and select a view other than 'Active view/sheet' in the Preview Source of the dialog. It is this permanent view that can be extracted and set using the DocumentPreviewSettings API. If there is no permanent preview view assigned here, Revit will use the default active view/sheet to generate the preview.

The other approach set a temporary preview view id which will be used during the single save operation and is not serialized to the document. This can be done using the Document.Save(SaveOptions) or Document.SaveAs(SaveAsOptions). Both these option classes have a setting for the preview view id.

In a typical use case of OpenDocumentFile(), performing certain changes to the document and then saving the file either using a Save or SaveAs results in Revit having no way to know how to save a preview and so previews are lost. This is where Save(SaveOptions) or SaveAs(SaveAsOptions) helps. However, setting the temporary preview view settings using the save options can become challenging since API users would still not know which view to be set as preview – the Document.ActiveView does not work for an un-displayed document. Here, there are two ways of approaching this:

1. Using a new API called StartingViewSettings, which helps access the initial view settings for a document which returns the view that will be initially opened when a model is opened. This view is usually set by the user and can be accessed from the user interface by accessing the 'Manage' tab in which we need to click on the 'Starting View' button. If API users get a valid view from the StartingViewSettings and end up using this for setting the preview view, it is recommended that this view be set as preview using the temporary setting (which is to use the Save(SaveOptions) or the SaveAs(SaveAsOptions) method and not the DocumentPreviewSettings. StartingViewSettings works only for Revit projects and will throw an exception if used with a Revit family file (RFA). If the starting view has not been set by the user, we will see '<Last Viewed>' as the current settings. On the API side, this means that the StartingViewSettings.ViewId will return a InvalidElementId in which case we need to follow the second approach.

2. The other approach is to make an algorithmic choice e.g. finding the 3D view (ensuring that this is not a template) and using this view as temporary preview view setting. If no 3D views are found, then the API user can decide on using plan views instead, etc. If you end up using this algorithmic approach for setting the preview view, it is recommended that the preview be set using the temporary setting (which is to use the Save(SaveOptions) or the SaveAs(SaveAsOptions) method and not the DocumentPreviewSettings.

The following lines of code show a typical use of the various APIs which help in setting the preview. It covers all the various approaches mentioned above:

  // Open Revit file
  Document doc = cmdData.Application.Application
    .OpenDocumentFile( file.FullName );
 
  // Create transaction and start
  Transaction trans = new Transaction( doc, "T1" );
  trans.Start();
 
  doc.Regenerate();
 
  // Create thumbnails for preview 
  DocumentPreviewSettings previewSettings =
    doc.GetDocumentPreviewSettings();
 
  SaveAsOptions saveOpts = new SaveAsOptions();
 
  // Check for permanent preview view
  if( doc
    .GetDocumentPreviewSettings()
    .PreviewViewId
    .Equals( ElementId.InvalidElementId ) )
  {
    // Access the intial view
    StartingViewSettings startingViewSettings 
      = StartingViewSettings.GetStartingViewSettings( 
        doc );
 
    if( !startingViewSettings.ViewId.Equals( 
      ElementId.InvalidElementId ) )
    {
      // If valid, then set the viewId
      //previewSettings.PreviewViewId 
      //  = startingViewSettings.ViewId;
 
      saveOpts.PreviewViewId 
        = startingViewSettings.ViewId;
    }
    else
    {
      // Algorithmic approach - look for 3D views
 
      FilteredElementCollector collector 
        = new FilteredElementCollector( doc )
          .OfClass( typeof( View ) );
 
      IEnumerable views 
        = from Autodesk.Revit.DB.View f
          in collector
          where ( f.ViewType == ViewType.ThreeD
            && !f.IsTemplate )
          select f;
 
      bool bNotFound = true;
 
      foreach( View vw in views )
      {
        if( !vw.IsTemplate )
        {
          //If we were to set the preview view permanently, 
          // we would use the following two commented lines
          //previewSettings.PreviewViewId = vw.Id;
          //previewSettings.ForceViewUpdate( true );
 
          // Set the temporary view
          saveOpts.PreviewViewId = vw.Id;
          bNotFound = false;
          break;
        }
      }
 
      // If no 3D view is obtained, look for other valid views
      if( bNotFound )
      {
        IEnumerable viewsNon3D
          = from View fNon3D
            in collector
            where ( fNon3D.ViewType == ViewType.FloorPlan
              || fNon3D.ViewType == ViewType.EngineeringPlan
              || fNon3D.ViewType == ViewType.Elevation
              || fNon3D.ViewType == ViewType.Section
              && !fNon3D.IsTemplate )
            select fNon3D;
 
        foreach( View vw in viewsNon3D )
        {
          if( !vw.IsTemplate )
          {
            // If we were to set the preview view permanently, 
            // we would use the following two commented lines
            //previewSettings.PreviewViewId = vw.Id;
            //previewSettings.ForceViewUpdate( true );
 
            saveOpts.PreviewViewId = vw.Id;
            break;
          }
        }
      }
    }
  }
 
  // Commit transaction
  trans.Commit();
 
  // Save Revit file to target destination
  doc.SaveAs( destPath + "\\" + file.Name, saveOpts );
 
  // Close document
  doc.Close();
 

Many thanks to Saikat for this useful explanation!

Product GUIDs for Revit 2012 and Forever More

Every year anew, people ask for the Revit product GUIDs used to identify the Revit installation and stored in the Windows registry under

• HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall

There are different keys for each of the three Revit flavours, and for both 32 and 64 bit operating systems.

The first time around, we discussed the Revit 2010 and previous versions' installation path and product GUIDs, and then updated the list for Revit 2011 last year.

As I mentioned last time, the install path is less of an issue nowadays. There is no longer any need to determine the location of Revit.ini to install an add-in, because you have to use an add-in manifest to inform Revit how to load your add-in instead.

Even though I mostly do not follow this advice myself, it is actually recommended to install .NET add-ins for both AutoCAD and Revit in or under the same directory as acad.exe and revit.exe, respectively: "It's safest to place assemblies at a location beneath the calling executable."

Another way to determine the Revit install location is to use the RevitAddInUtility. It provides an API for an installer to query the Revit installation location, i.e. the path of Revit.exe, and also to generate an add-in manifest file from the relevant properties you specify.

In Revit 2011, there was an issue with using the RevitAddInUtility for 64 bits. That is resolved in Revit 2012, and the same assembly DLL should work transparently on all flavours of Windows now.

Revit Product GUIDs up to Revit 2012

Still, the product GUID may be important for other uses. Here is the updated list including the GUIDs for the initial Revit 2012 versions:

2012	64 bit	RAC	7346B4A0-1200-0110-0409-705C0D862004
		RME	7346B4A0-1200-0310-0409-705C0D862004
		RST	7346B4A0-1200-0210-0409-705C0D862004
	32 bit	RAC	7346B4A0-1200-0100-0409-705C0D862004
		RME	7346B4A0-1200-0300-0409-705C0D862004
		RST	7346B4A0-1200-0200-0409-705C0D862004
2011	64 bit	RAC	94D463D0-2B13-4181-9512-B27004B1151A
		RME	C31F3560-0007-4955-9F65-75CB47F82DB5
		RST	23853368-22DD-4817-904B-DB04ADE9B0C8
	32 bit	RAC	4AF99FCA-1D0C-4D5A-9BFE-0D4376A52B23
		RME	CCCB80C8-5CC5-4EB7-89D0-F18E405F18F9
		RST	0EE1FCA9-7474-4143-8F22-E7AD998FACBF
2010	64 bit	RAC	2A8EEE2F-4A9E-43d8-AA07-EC8A316B2DEB
		RME	A1BD042B-8A6F-4e37-92A3-78921BB45B05
		RST	BC9C0A08-DEA4-4138-A7FB-8F68866DB0C1
	32 bit	RAC	572FBF5D-3BAA-42ff-A468-A54C2C0A17C3
		RME	5C8281B1-B927-495a-A0FF-AB4BDFAE505C
		RST	939D29FC-B82D-42a7-BB1E-8E3F121505CC
2009	64 bit	RAC	D2466208-7348-4214-B01E-7BC8729E2BD3
		RME	4A98F976-01B5-40e8-A496-AEFD85C3A446
		RST	B354FCF5-CF64-4fa2-AA84-9D9B2A6FA649
	32 bit	RAC	A3A37DA6-70C0-497C-BCB1-148E9EC1D32E
		RME	E3781DCB-A650-4E66-9B74-67A1B17F052C
		RST	C4B3B3C3-2EE9-48D3-9BF5-4443F7ECF759
2008		RAC	4A11206C-4377-49E8-911E-B11548658FF3
		RME	60A2743E-C881-4880-94ED-96445E38616F
		RST	8D0AE0BB-4FE5-491D-A284-3B363F02E639
9.0		Revit Building	D11DB6CB-0332-4735-B312-B919741D975E
3		RST	3F11CEE0-D30D-41ce-8522-922B5D8BB324
8.1		Revit Building	7EBC0489-5E47-498D-BE31-B094484612E9
2		RST	BE814F63-629D-4fd8-B628-1437AC10F9D4

ADN members may also refer to the technical solution TS87598 [How to detect where Revit has been installed?], which has been updated with this new information as well.

Perpetual Revit Product GUIDs

As you may have noted above, the Revit 2012 GUIDs exhibit a strong similarity with each other.

From Revit 2012 onwards, the Revit products codes are generated according to the following pattern:

    {7346B4At-uuvv-wwxy-zzzz-705C0D862004}

The alphabetical characters above stand for:

20. [0/1]: ProductCode/UpgradeCode
21. [11, 12, ...]: Major release version [11,12]
22. [00, 01, ...]: Release subversion
23. [01/02/03]: RAC/RST/RME
24. [0/1]: Win32/x64
25. [0/1]: Global/Language Pack
26. [0409...]: Language

The last item, represented by 'z', identifies the language. It uses the hexadecimal LCID, which I assume stands for language code identifier or something like that, and is defined in the following table:

lang	.NET code	HEX LCID	DEC LCID	Language name	Codepage
chs	zh-CN	0804	2052	Chinese Simplified	936
cht	zh-TW	0404	1028	Chinese Traditional	950
csy	cs-CZ	0405	1029	Czech	1250
deu	de-DE	0407	1031	German	1252
enu	en-US	0409	1033	English	1252
esp	es-ES	040A	1034	Spanish	1252
fra	fr-FR	040C	1036	French	1252
hun	hu-HU	040E	1038	Hungarian	1250
ita	it-IT	0410	1040	Italian	1252
jpn	ja-JP	0411	1041	Japanese	932
kor	ko-KR	0412	1042	Korean	949
plk	pl-PL	0415	1045	Polish	1250
ptb	pt-BR	0416	1046	Brazilian Portuguese	1252
rus	ru-RU	0419	1049	Russian	1251

Applying this rule to Revit 2012 for the RAC flavour, 64 bit operating system, initial release and US English generates the following value:

    {7346B4A0-1200-0110-0409-705C0D862004}

I checked my 32 bit Windows registry values, and see the following entries beginning with "7346B4A":

{7346B4A0-1200-0100-0409-705C0D862004}

Revit Architecture 2012

{7346B4A0-1200-0101-0409-705C0D862004}

Revit Architecture 2012 Language Pack - English

{7346B4A0-1200-0200-0409-705C0D862004}

Revit Structure 2012

{7346B4A0-1200-0201-0409-705C0D862004}

Revit Structure 2012 Language Pack - English

{7346B4A0-1200-0300-0409-705C0D862004}

Revit MEP 2012

{7346B4A0-1200-0301-0409-705C0D862004}

Revit MEP 2012 Language Pack - English

These Revit product keys and the corresponding 64 bit ones produced the data that I added to the GUID table above.

Visual Studio Add-In Wizards for Revit 2012

As I mentioned yesterday, this weekend was spent traveling to Verona to give a Revit API training here. Happily, I enjoyed some mountain air the weekend before, on Helgenhorn 2837m, Basodino 3273m and Cima di Lago south of All'Acqua in the Bedretto Valley (more photos by Jogi):

Anyway, that was last weekend; back to here and now in Verona, where I was busy yesterday, preparing for the training, starting today.

I already updated the DevTV Visual Studio wizards for creating skeleton C# and VB Revit 2011 add-ins several times in the past:

• Original introduction, benefits, and usage example for C# and VB.
• Personalised minimal C# version for Revit 2011.
• A short additional usage note.
• 64 bit versions for C# and VB.
• Updated C# version without the extraneous transaction attribute on the external application.

One step in my preparations was to migrate the wizard templates to Visual Studio 2010 and the Revit 2012 API. Here is the first result:

• TemplateRevitArch2012AddinCsJt_1.zip – copy to
  [My Documents]\Visual Studio 2010\Templates\ProjectTemplates\Visual C#
• TemplateRevitArch2012AddinVbJt_1.zip – copy to
  [My Documents]\Visual Studio 2010\Templates\ProjectTemplates\Visual Basic

The two most important changes that I made for 2012 are:

• Added required vendor id and optional vendor description to the add-in manifest file.
• Removed the obsolete regeneration option attribute.

This is what the auto-generated add-in manifest now looks like:

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Command">
    <Text>Command RevitAddin1</Text>
    <Description>Some description for RevitAddin1</Description>
    <Assembly>c:\tmp\revit\RevitAddin1\RevitAddin1\bin\debug\RevitAddin1.dll</Assembly>
    <FullClassName>RevitAddin1.Command</FullClassName>
    <ClientId>4e980ab7-e6f4-456f-b8cc-646ef733128c</ClientId>
    <VendorId>TBC_</VendorId>
    <VendorDescription>The Building Coder, http://thebuildingcoder.typepad.com</VendorDescription>
  </AddIn>
  <AddIn Type="Application">
    <Name>Application RevitAddin1</Name>
    <Assembly>c:\tmp\revit\RevitAddin1\RevitAddin1\bin\debug\RevitAddin1.dll</Assembly>
    <FullClassName>RevitAddin1.App</FullClassName>
    <ClientId>dddfad28-c7a0-45fe-836e-0eb03e919e81</ClientId>
    <VendorId>TBC_</VendorId>
    <VendorDescription>The Building Coder, http://thebuildingcoder.typepad.com</VendorDescription>
  </AddIn>
</RevitAddIns>

I used The Building Coder Autodesk Registered Developer Symbol RDS "TBC_" for the vendor id. You should obviously replace that with your own id before using the template.

Whatever you would like to change, it is extremely easy to adapt the templates for your own personal use:

Simply unpack the zip file somewhere, make your changes, update the zip file with the modified files, and copy the new zip file to the appropriate location.

Performant Hardware

I spent all day yesterday in trains, which was unfortunate, since it was the most beautiful Sunday, and springtime is in full bloom. It also forced upon me some unfortunate comparisons of the Swiss and Italian train systems. Needless to say, I arrived later than expected.

Still, I ended up happily back in Verona, Italy, where I started seriously learning Italian two years ago, for a repeat visit to provide a Revit API training class to Steel & Graphics srl.

One funny thing about Verona is that it has almost exactly the same flag as Sweden, where I grew up:

It is also the city of Shakespeare's Romeo and Juliet. Maybe I can manage to get to Sirmione and the Sirmio peninsula today and complete the final training preparations there.

Meanwhile, here is a non-API related question affecting all Revit users from Augusto Gonçalves:

Question: To specify a new machine for Revit, what should I consider, i.e. spend more money on? Amount of memory? Speed of memory? Processor clock? Multi-processors? HD speed?

Answer: Anthony Hauck provides a very succinct answer:

In order, and dependent on how large the models you wish to edit are:

1. More RAM
2. Faster Processor
3. More Processers
4. Faster RAM
5. Faster HD

For a more complete and long-winded answer, you may want to peruse the Revit model performance technical note pointed out by Martin Schmid.

It has been around for quite a while now and includes some detailed software optimisation suggestions as well, which are well worth reading and understanding for add-in developers as well as end users, including:

• Revit Platform Model Optimization and Best Practices
  • Arrays
  • Constraints
  • Design Options
  • DWG Files
  • Family Creation
  • Importing & Linking
  • Modeling Economically
  • Project Templates
  • Railings
  • Raster Images
  • Stairs
  • Upgrading Linked Projects to a New Version of Revit
  • Views
  • Volumes - Rooms and Spaces
  • Worksets
  • Worksharing
• Revit Structure 2010 Software Optimization and Best Practices
• Revit MEP 2010 Software Optimization and Best Practices

Note that this document applies to Revit 2010, although I am assuming that most remains valid for Revit 2012 as well.

Nested Lighting Fixture Instances

We already looked at a couple of aspects of nested family instances, such as access to nested instance geometry, creating nested families and determining whether a family instance is nested.

Now Joel Spahn of Lighting Analysts, Inc. submitted a comment on the nested family utility methods raising a new question related to nested lighting fixtures, efficiently resolved by Harry Mattison of the Revit development team:

Question: I have adapted this code to extract nested family instances and it works beautifully. However, I have a new problem.

I need to extract the location and position of all the light source elements in a lighting fixture family which contains nested lighting fixture family instances.

Based on my testing, the filtered element collector does not return nested family instances. If this is true, how can I query the nested family instances?

My initial solution to this problem was to open the family document to collect and iterate the nested family instances. There are two problems to this approach:

1. It is performance intensive and dramatically slows the operation.
2. It cannot handle "dynamic" families (most important).

That is, how can I extract the nested family instances if the quantity and position of the nested family instances is different for each instance of the parent family in the project?

Example: I have a lighting fixture family (track light) that contains nested lighting fixture family instances (each can-light on the track). The nested instances are part of an array which is defined by the parent instance in the project. Each parent instance can have a different number of nested instances, as described in the documentation on creating lighting fixtures with multiple light sources.

Initially I thought that the FamilyInstance.SubComponents property would work for this, however it is always null! When does the SubComponents property return anything? The API documentation is very sparse.

Any ideas on how to access nested family instances given the parent instance?

Answer: I need more information about the SubComponents property that is not working for you. I tried the following code with the "Table-Dining Round w Chairs.rfa" from the Revit Furniture library:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  FamilyInstance fi = doc.get_Element( 
    uidoc.Selection.PickObject( 
      ObjectType.Element ).ElementId ) 
    as FamilyInstance;
 
  ElementSet subElemSet = fi.SubComponents;
 
  if( subElemSet != null )
  {
    string subElems = "";
 
    foreach( Element ee in subElemSet )
    {
      FamilyInstance f = ee as FamilyInstance;
      subElems = subElems + f.Name + "\n";
    }
 
    TaskDialog.Show( "Revit", 
      "Subcomponent count = " + subElemSet.Size 
      + "\n" + subElems );
  }
 
  FamilyInstance super = fi.SuperComponent 
    as FamilyInstance;
 
  if( super != null )
  {
    TaskDialog.Show( "Revit", 
      "SUPER component: " + super.Name );
  }

It provides the expected output:

Response: The sample code works for me as well when I select an instance of Table-Dining Round w Chairs.

However, it does not work when I select an instance Nested Table Lamp, which is a very simple Lighting Fixture family with four nested Lighting Fixture Families. Both family instances are visible from the 3D view.

Answer: The mesh geometry of the light sources can be found as follows:

  FamilyInstance fi;
  GeometryElement geomElem = fi.get_Geometry( 
    app.Create.NewGeometryOptions() );
 
  foreach( GeometryObject geomObj 
    in geomElem.Objects )
  {
    GeometryInstance geomInst 
      = geomObj as GeometryInstance;
 
    if( geomInst != null )
    {
      foreach( GeometryObject geomObject 
        in geomInst.SymbolGeometry.Objects )
      {
        GraphicsStyle gStyle = doc.get_Element( 
          geomObject.GraphicsStyleId ) 
          as GraphicsStyle;
 
        if( gStyle != null )
        {
          if( gStyle.GraphicsStyleCategory.Name 
            == "Light Source" )
          {
            Mesh mesh = geomObject as Mesh;
          }
        }
      }
    }
  }

Is that sufficient for you to get the location & position information that you mentioned?

The lamps are not found by the SubComponents property because the "Shared" property is false:

We will update the API documentation to explain this requirement.

Response: I thought of using the mesh geometry, but this approach doesn't allow access to important parameter data such as the photometric data that the mesh is built from.

However, I forgot about the behaviour of "shared" light fixtures. This seems to solve the issue and after sharing all the nested light fixtures, the subcomponents property works as expected.

Many thanks to Joel and Harry for this fruitful exploration, and for kindly sharing the results with us!