The Building Coder

Correct Detail Component Rotation in Elevation View

My colleague Miroslav Schonauer of Autodesk Consulting ran into and solved a critical issue to fix the unexpected values reported by the Rotation property on detail components in elevation views.

Here are the steps describing the problem and happy resolution in detail, followed by a quick note on my tech summit cloud-based round-trip 2D Revit model editing project:

• Detail component rotation problem 1
• Detail component rotation problem 2
• Workaround description
• Workaround implementation
• Live recording and plans

I was so busy wrapping up the Tech Summit and having internal meetings with colleagues here in the Autodesk Waltham and Manchester offices that I never got around to posting anything in the last two days It is nice to finally take some time and get some fresh information out to you again.

Here is Miro's problem description and solution:

Problem Description 1

I’ve been banging my head against this problem in Revit 2012 that I can reproduce in 2014 as well, both via UI and API. Basically, the Rotation property of LocationPoint for Detail Components in Elevation Views seems to be wrong. It all seems fine in Plan Views, by the way.

For example, if one creates an instance of a 225mm Steel Purlin Detail Item from Arch.Template (top one below), the rotation should be 0, but RevitLookup shows it as 90 degrees. I rotated it by 30 degrees in UI, visually all worked as expected, but the property then reports 93.84 (middle one below, also snapshot provided of RevitLookup) instead of 30. Finally, the bottom instance is rotated by 90 degrees, but the reported value is 120.

How can I correct the reported value, please?

By experimenting a bit, I’ve concluded that the values reported seem to correspond to the following wrong mapping (in degrees):

0	→	90
30	→	93.8409
45	→	98.4210
60	→	104.4775
90	→	120
120	→	138.5903
135	→	148.6002
150	→	158.9094
180	→	180

By the way, mimicking the actual rotation action in API works fine, just as in UI, e.g. this behaves as expected:

  FamilyInstance fiDetComp = null;

  try
  {
    FamilySymbol fs = doc.get_Element(
      idSymbol ) as FamilySymbol;
 
    fiDetComp = doc.Create.NewFamilyInstance(
      data.Origin, fs, data.ParentView );
 
    // Rotate it if needed

    if( Math.Abs( data.Rotation ) > 0.0001 )
    {
      Line axis = app.Create.NewLineBound(
        data.Origin, data.Origin
          + data.ParentView.ViewDirection );
 
      ElementTransformUtils.RotateElement( doc,
        fiDetComp.Id, axis, data.Rotation );
    }
  }

This produces the correct result, but the Rotation property still reports the wrong value afterwards.

Problem Description 2

I just hit another manifestation of this issue that unfortunately may be a showstopper for the project I am working on.

I cannot believe nobody hit this issue in the last 5-6 years/releases since adding Details Families to the Views (i.e. NewFamilyInstance Method (XYZ, FamilySymbol, View) ) has been supported in API.

It is very easy to reproduce and understand using pure Revit 2014 UI and RevitLookup.

I created a very simple Detail Family from 'Metric Detail Component.rft' template as follows:

I inserted the same Family Type four times in each of South/North/East/West Views without rotating the instance (i.e. as-is from 'Create Instance' right-click). Each of these family instances looks correct in each view, but the Rotation part of the Location Point, which I would expect to be 0.0 for each case, reports strange results, i.e. 90 degrees for South, 120 for East/West and 180 for North. Just check each of the Arrows in each of the Sheet Views (using 'Activate View' one by one):

The problem is now obviously that when I create family instances programmatically, using something like the following with data.Rotation = 0.0, the results are not as expected, i.e. the instances are weirdly rotated:

  FamilyInstance fiDetComp = null;
  try
  {
    FamilySymbol fs = doc.get_Element(
      idSymbol ) as FamilySymbol;
 
    fiDetComp = doc.Create.NewFamilyInstance(
      data.Origin, fs, data.ParentView );
 
    // Rotate it if needed
    if( Math.Abs( data.Rotation ) > 0.0001 )
    {
      Line axis = app.Create.NewLineBound(
        data.Origin, data.Origin
          + data.ParentView.ViewDirection );
 
      ElementTransformUtils.RotateElement( doc,
        fiDetComp.Id, axis, data.Rotation );
    }
  }

The bottom line is: how can I programmatically know which angle to use in place of data.Rotation in the above code to reliably obtain the expected results? If I use 0.0 as logical to place the component 'unrotated', the result is not as-expected and, even worse, not the same (i.e. rotation is wrong in different manners) in different elevations depending on the view direction of each elevation.

Workaround Description

It seems clear that the Rotation property is not set up properly to deal with items placed outside of the XY plane.

Revit should indeed not be presenting a calculated rotation angle without the corresponding calculated rotation axis that this number comes from.

The fact that sometimes the instance is rotated on placement, but not always, seems to be a second issue to be aware of.

However, more relevantly, here is some good news: you can get what you need working with the result obtained from the FamilyInstance.GetTransform method and computing rotation angles from that.

Here are the routines to help, GetRotationAngleOfInstance and RotateInstance.

GetRotationAngleOfInstance calculates the rotation angle by comparing the transform with the transform generated from the X/Y/Z of the view.

RotateInstance rotates the instance using the view direction – it is hardcoded in this example for testing purposes. You can use the rotation angle difference you calculate and it should work:

public void GetRotationAngleOfInstance()
{
  UIDocument uiDoc = this.ActiveUIDocument;
 
  Selection selection = uiDoc.Selection;
 
  foreach( ElementId id in selection.GetElementIds() )
  {
    FamilyInstance fi = uiDoc.Document.GetElement(
      id ) as FamilyInstance;
 
    Transform trf = fi.GetTransform();
 
    XYZ viewDirection = uiDoc.ActiveView.ViewDirection;
    XYZ rightDirection = uiDoc.ActiveView.RightDirection;
    XYZ upDirection = uiDoc.ActiveView.UpDirection;
 
    TaskDialog.Show( "Trf", String.Format(
      "X{0} Y{1} Z{2}\nX{3} Y{4} Z{5}",
      trf.BasisX, trf.BasisY, trf.BasisZ,
      rightDirection, upDirection, viewDirection ) );
 
    TaskDialog.Show( "Rotation Angle",
      trf.BasisX.AngleOnPlaneTo( rightDirection,
        viewDirection ) * 180 / Math.PI );
  }
}
 
public void RotateInstance()
{
  UIDocument uiDoc = this.ActiveUIDocument;
 
  Selection selection = uiDoc.Selection;
 
  foreach( ElementId id in selection.GetElementIds() )
  {
    FamilyInstance fi = uiDoc.Document.GetElement(
      id ) as FamilyInstance;
 
    using( Transaction t = new Transaction(
      uiDoc.Document, "Rotate me" ) )
    {
      t.Start();
 
      LocationPoint lp = fi.Location as LocationPoint;
      XYZ location = lp.Point;
      XYZ direction = uiDoc.ActiveView.ViewDirection;
      Line line = Line.CreateBound( location,
        location - direction );
      lp.Rotate( line, Math.PI / 2.0 );
      t.Commit();
    }
  }
}

Workaround Implementation

I can report that the workaround works very well.

I added one minor adjustment, changing:

  Line line = Line.CreateBound( location,
    location - direction );

I replaced it by this instead:

  Line line = Line.CreateBound( location,
    location + direction );

For convenience, we can also directly use this property:

  fi.HandOrientation;

That can replace the following two lines of code:

  Transform trf = fi.GetTransform();
 
  trf.BasisX;

Here is my implementation code. Some variables/custom classes come from the specific cached context I have set up. Their meaning should be clear from the comments added to them:

  // Loop all cached data
  // NOTE: DetailFaceData is a custom class 
  // caching all relevant data about the 
  // View / Origin and Rotation
  // to insert each Detail Components into/at.
 
  foreach( DetailFaceData data in lstDFD )
  {
    // Get Symbol ID.
    // This is the id of the Detail Component 
    // FamilySymbol to be inserted
 
    ElementId idSymbol = GetSymbolId();
 
    // Insert Symbol
 
    ElementId idDetComp
      = ElementId.InvalidElementId;
 
    try
    {
      // 1) Insert with default rotation (should 
      // be 0.0, but due to some issues not so - 
      // see later)
 
      using( SubTransaction tr
        = new SubTransaction( doc ) )
      {
        tr.Start();
        FamilySymbol fs = doc.GetElement(
          idSymbol ) as FamilySymbol;
 
        FamilyInstance fiDetComp = doc.Create
          .NewFamilyInstance( data.Origin, fs,
            data.ParentView );
 
        idDetComp = fiDetComp.Id;
        tr.Commit();
      }
 
      // 2) Rotate it if needed
      // IMPORTANT NOTE: The commented 5 lines of 
      // code below should be sufficient and fine,
      // but there that rotation is NOT correct 
      // for non-planar views :-(.
      // E.g., if using 0 as the rotation, the 
      // instance IS weirdly rotated. Luckily, the 
      // .Rotate method itself still works fine, 
      // so the workaround is to first use the 
      // Transform or HandOrientation to "measure 
      // the wrongness" and only then to .Rotate 
      // it to the desired angle.
 
      //if (Math.Abs(data.Rotation) > 0.0001)
      //{
      //    Line axis = app.Create.NewLineBound(
      //      data.Origin, data.Origin 
      //        + data.ParentView.ViewDirection);
      //    ElementTransformUtils.RotateElement(
      //      doc, fiDetComp. Id, axis, data.Rotation);
      //}
 
      // 2.1) Use Instance's Transform (or 
      // directly HandOrientation) and View Axes 
      // to measure which angle (random for non-
      // plan views) Revit has created in step 1)
 
      using( SubTransaction tr
        = new SubTransaction( doc ) )
      {
        tr.Start();
 
        FamilyInstance fiDetComp = doc.GetElement(
          idDetComp ) as FamilyInstance;
 
        XYZ viewDirection = data.ParentView.ViewDirection;
        XYZ rightDirection = data.ParentView.RightDirection;
 
        double rotActual = fiDetComp.HandOrientation
          .AngleOnPlaneTo( rightDirection,
            viewDirection );
 
        double rotDelta = data.Rotation - rotActual;
 
        // 2.2) Use .Rotate to fix the problem
 
        if( Math.Abs( rotDelta ) > 0.0001 )
        {
          // Either works fine:
          // Option 1:
          Line axis = app.Create.NewLineBound(
            data.Origin, data.Origin
              + data.ParentView.ViewDirection );
 
          ElementTransformUtils.RotateElement(
            doc, fiDetComp.Id, axis, rotDelta );
 
          //// Option 2:
          //LocationPoint lp = fiDetComp.Location as LocationPoint;
 
          //XYZ location = lp.Point;
          //XYZ direction = data.ParentView.ViewDirection;
          //Line axis2 = _App.Create.NewLineBound(location, location + direction);
          //lp.Rotate(axis2, rotDelta);
        }
 
        tr.Commit();
      }
    }
    catch( Exception ex )
    {
      // log or handle this
      continue;
    }
  }

Very many thanks to Miro for researching this and sharing the solution.

I hope this is of use to others also.

By the way, note that this is the first time ever that Miro provided C# code instead of VB.

What's up, Miro? :-)

Live Recording and Plans

As I already repeated all too often, I presented my cloud-based round-trip 2D Revit model editing project at the Autodesk internal tech summit.

I recorded the session and posted the 30-minute live recording including an additional ten minutes of Q&A at the end.

The 30-minute preview recording that I already posted also remains available, and the content is somewhat different, in case you want the full monty.

Work on this project has not finished yet, of course.

I added a significant number of new features to the Revit add-in that I have not yet discussed.

My plan is to migrate the add-in from Revit 2013 to 2014, post it to GitHub and discuss the new features soon.

Furthermore, the technology implemented has proven effective and reliable so far, and far simpler than any other approach I have seen to achieve similar results, so I should explore where else I can take this.

If you have any suggestions or wishes, please let me know. I might implement whatever you ask for.

Tech Summit and More AutoExport Considerations

Today is the day I have been working towards with my cloud-based round-trip 2D Revit model editing project, which I am presenting this afternoon (cf. the 30-minute pre-recorded video).

Before I get to that, I would like to pass on the following thoughts and suggestions on yesterday's auto PDF batch printing system from Constantin Gherasim of Genivar Inc. on a similar project of his own, up in use and running for over a year already, expanding on what he already said in his comment yesterday:

Thoughts on the Genivar AutoExport System

As I mentioned, this is another Revit "AutoExport" utility, using a similar approach as Dan's: an overnight batch exporter based on the Windows task scheduler and the Revit Idling event.

I would like to share some information on the similarities and differences in the hope that it be useful for others as well.

In order to see what the interface looks like, here is a screen snapshot of it showing the list of files to export:

Here is the tab handling the DWF format export settings:

The utility uses a configuration file, which is stored in XML format:

It is controlled through a couple of registry keys which are preconfigured for the task by an AutoIT script:

The first registry key specifies the XML configuration file path. The second one is a pseudo Boolean flag (in fact it's a string), which controls whether the utility is run or not at the Revit startup (this is necessary when using Revit out of this setup).

The exported formats are PDF, DWG, DXF, DWF and DGN. As a new extension project, I would like to add support for the IFC format.

The way it works is pretty similar with the tool presented by Mr Tartaglia. Here is a detailed explanation:

The setup:

1) A scheduled task on a server starts a dedicated remote session each midnight, by logging on a specific account on a specific machine on the network (ideally on the LAN), machine which is dedicated to this task, therefore it's "On" all the time and has all the resources available for the task.

2) When the logon process is completed, a main AutoIT script placed in the StartUp folder of the logged account, triggers successively two other auxiliary AutoIT scripts. The reason for the two other scripts is the fact that two distinct exporting processes are required for two different teams, each with its own configuration file (obviously the setup can be extended, there could be a third and a fourth session, and so on, depending on how long it takes for one process and knowing that the time we have it’s eventually between midnight and 7:00 AM).

3) The first auxiliary script writes to the registry the path for a specific configuration file (which is maintained somewhere on the network), writes "True" to a specific key in the registry named "RunOnStartup", and then it starts Revit (with a dummy document for Revit 2012).

4) When the Revit Idling event is fired, the AutoExport utility first checks the registry and if the key "RunOnStartup" is "True", it opens the configuration file from the specified path and starts exporting the documents listed in the configuration file to the target folder, specified in the same configuration file (along the export process, it writes a log file).

5) Meanwhile, the first auxiliary script is waiting for the same "RunOnStartup" registry value to be switched to "False" by the AutoExport application, which happens as soon as all the documents listed in the configuration file are processed. As soon as the last exported document is closed, the AutoExport application changes the value for "RunOnStartup" to "False", then the first auxiliary script kills the Revit process by its PID, sends an email (with the last log file attached) to me and to the person which maintains the configuration file, and it stops.

It's important to mention the fact that leaving the value of "RunOnStartup" key to "False" is the mechanism that ensures that the AutoExport application won't run out of this setup.

6) After a brief delay, the main script triggers the second auxiliary script, which writes to the registry its own values and the whole process (steps 3 to 5) restarts, only with a different configuration file and a different export folder.

7) After the second auxiliary script is over and the Revit process is killed again, the main script closes the remote session on the dedicated machine, which is now waiting for the next AutoExport session in next 24 hours.

This setup has been in place for more than a year now, and basically works without a glitch. As you can see in the email screen snapshot, it can process up to 25-30 Revit files in one session, which takes about 30 to 40 minutes.

I was quite surprised by the similarity of this project with the one described yesterday, although similar requirements do generally lead to similar solutions.

Then I thought that the approach with the auxiliary scripts through the registry offers a little bit more flexibility and control.

My approach is a little bit more optimistic, since I process multiple RVT files per Task Scheduler Task.

I would also like to mention that maintaining a log file seems to me a good thing to do, which together with the automated email is a nice bonus in my opinion.

These both confer some kind of peace of mind, when you know that you don’t have to wait for somebody to complain that there were problems, since it’s possible to check the night’s job on the mobile phone in the early morning and alert the concerned people!

Of course, these are more or less cosmetic improvements, but when put together, it all seems to me a handy and solid tool.

For me it’s enough that it works and my folks are happy :-)

Unfortunately this is an in-house application only, so I cannot share it as openly as Mr Tartaglia very graciously did.

I hope these ideas are of use, not necessarily as an improvement, because it depends, to anyone with similar needs and the necessary skills.

I hope I was clear in my explanations and also that you will find this useful.

Thanks for your interest and time.

Thank you, Constantin, for sharing these additional thoughts.

Rod's Revit Remote Boot

In another comment on yesterday's post, Barry Ralphs of Tipping Mar pointed out an interesting neat and generic use of the Idling event by Rod Howarth: Revit remote boot – a technique to run an API add-in on a particular Revit model without user interaction.

Other Important Posts on this Topic

If you are interested in this kind of automation, you should not miss the old posts on a pattern for semi-asynchronous Idling API access and driving Revit through a WCF service.

Ok, I hope I have not missed anything important now. Wish me luck for this afternoon!

Auto PDF Print from Revit 2014

Below, we will take a look at a Revit multi-project batch PDF printer project driven by the Windows task scheduler and the Revit Idling event.

Before getting to that, though, let me share some of my Sunday activities.

Contact Impro Jam and Tech Summit Arrival

From the Fells, I continued along the Mystic Valley Parkway and stopped to enjoy the beautiful Mystic Lakes on my way to the weekly Sunday contact improvisation jam in the Arlington Center, followed by a magnificent lunch at Sabzi Persian restaurant and wonderful conversation with Mike Klinger of Anzu Global, who actually used to work with Revit at Autodesk, as it turns out. Small world.

In the evening I checked in to the Tech Summit hotel on the Charles River in Cambridge and went for a very nice dinner with Adam, Manu and Mikako to the Spanish Tapeo restaurant on Newbury Street in Boston. That was the first time I set foot in the city since my arrival.

As Mikako pointed out, it is quite a novelty for me to be pleased with restaurant food – I normally prefer to cook myself – and on Sunday I had two good experiences in a row! Yay!

Back to the Revit API.

Batch Processing RVT Files Overnight

This is a contribution from Dan Tartaglia of design technology@NBBJ.

It started off from the following query:

Question: I created a tool that uses a UIControlledApplication Idling event when Revit launches. It works perfectly correctly in Revit Architecture 2013. However, if I use the same code on the same computer in Revit Architecture 2012, the Idling event does not fire.

Answer: In Revit 2012, the Idling event is not fired until a document is opened.

Response: Is it possible to open launch Revit then open a RVT file programmatically in Revit 2012? I can do this in Revit 2013 via the Idling event.

Answer: Yes, definitely. Simply specify the project filename on the Revit.exe command line.

Response: I got it to work after all. I just open a small dummy RVT before processing the RVTs for the users. I am using this to implement a batch PDF printer than can run from the Windows Task Scheduler overnight.

Based on this approach, Dan implemented AutoPDFPrint, a Revit multi-project batch PDF printer than can be driven by the Windows Task Scheduler overnight.

Task Scheduler and Revit Idling

Dan underlines that the Task Scheduler and Revit API Idling event allow you to automate almost any task. A few that help my firm are:

• PDF creation
• DWG creation
• Audit RVT files
• Compact RVT files
• Standards compliance checking
• Extracting data from RVT files

Some new features in the Revit 2014 API make the above tasks easier still, e.g. the OpenDocumentFile method that now enables you to open workshared RVT files detached from central and determine which user created worksets are open or closed.

There are a couple of things you need to consider before running any of the above tasks:

• Make sure the computer you use has enough RAM. Process one RVT file at a time to determine how much time and RAM it takes to finish. You may need to process one RVT file per Task Scheduler Task since Revit does not free memory until it closes.
• Warnings can cause the process to fail. The tool currently clicks OK for any dialog that opens. If a warning opens during the open process that cannot be closed by clicking OK, the file is skipped. This can be a good thing since it will inform you if an RVT has an issue while opening you need to investigate.

AutoPDFPrint Components

Looking in more detail at the PDF printer system, one its parts is the AutoPDFPrint_Bridge executable run from the task scheduler:

The second component and the main actor in the process is the AutoPDFPrint Revit add-in:

Here are the detailed steps required to set up the system:

1. Adobe PDF print preferences
2. CFG file
3. Task scheduler

All components presented are available for download below.

Step #1 – Set Up the Adobe PDF Print Preferences

1. Click the Windows 'Start' button and select 'Devices and Printers'.
2. Right-click the 'Adobe PDF printer' and select 'Printing Preferences'.
3. Change these settings:
   1. 'Adobe PDF Page Size' to user Documents folder.
   2. 'View Adobe PDF results': disable.

Step #2 – Set Up the CFG File

1. The CFG file goes here:

   C:\AutoPDFPrint2014\Scripts
   

2. CFG file example name:

   100XXX.00 - My Project.cfg
   

3. CFG file format (comma delimited):

   <view/sheet set>,<print set>,<RVT file>,<output folder for PDFs>
   

Notes:

• Multiple files/print jobs can be processed in the same CFG file.
• Make sure enough hard drive space and RAM exists on the computer.

Step #3 – Set Up the Task Scheduler

1. Open the Windows Task Scheduler:
   Click the Windows 'Start' button and select All Programs > Administrative Tools > Task Scheduler.
2. Create a new Task.
   In the Actions tab:
   1. Program/script:

      C:\AutoPDFPrint2014\Program\AutoPDFPrint_Bridge.exe
      

   2. Add arguments (optional):

      “100XXX.00 - My Project.cfg”
      

Notes:

• No guarantee the tool will work if a user is not logged on to the computer. This is related to the issue specified in the add-in flowchart above concerning PrintManager.PrintToFileName.
• Make sure the value for 'Add Arguments (optional)' is surrounded by quotes.

Download

Here is Auto_PDF_Print_from_Revit_2014_example.zip containing the following:

0. ReadMe.txt (this list).
1. Auto PDF Print from Revit 2014.vsd (pseudo logic).
2. Auto PDF Print from Revit 2014.docx (instructions for use).
3. Folders.zip (copy the Projects and AutoPDFPrint folders to the root C:).
4. AutoPDFPrint.zip (Revit 2014 add-in Application).
5. AutoPDFPrint_Bridge.zip (EXE run from Task Scheduler).

Thank you very much, Dan, for implementing and sharing this powerful tool.

Reloading and Debugging External Commands on the Fly

After publishing the little sample code snippet yesterday showing how to load and reload an external Revit command from a byte stream to avoid locking the .NET assembly DLL, I realised that this can be combined rather nicely with my own external command lister.

The combination of these two enables loading, debugging, reloading and re-debugging any simple external command on the fly, which has been a subject of regular discussion in the past.

By 'simple', I mean commands that do not have external dependencies or special loading requirements that make it difficult to load them lacking additional information beyond the .NET assembly path name.

The external command lister initially used the Assembly.LoadFrom method to load the .NET assembly, which locks the DLL.

Replacing this by reading the byte stream from the DLL and passing the result into Assembly.Load instead avoids that lock.

Adding a method to instantiate an external command implementation object and invoke its Execute method enables execution and debugging of an arbitrary external command.

Here is a live five-minute demonstration to show exactly what I mean:

To achieve this, I basically just added two methods to the existing code:

• ExternalCommandLister.Launch
• Command.OnDoubleClick

If you are impatient, uninterested or already know it all yourself, please go ahead and jump straight down to the summary and download section.

ExternalCommandLister Enhancements

I extended the ExternalCommandLister class by adding a Launch method taking the fully specified class name of the external command implementation.

I also modified the constructor to load the add-in assembly from a byte stream instead of directly from the .NET assembly file to avoid the DLL locking issue preventing subsequent reloading.

The Launch method requires the current instance of the ExternalCommandData to pass in to the external command it invokes, and the assembly we create needs to be kept available as well, so I added two new member variables for these.

It also checks the Result code returned by the invocation and reports that together with an optional error message in case of failure.

Here is the complete updated class implementation:

class ExternalCommandLister
{
  string _assembly_filename;
  string[] _external_commmand_class_names;
  ExternalCommandData _commandData;
  Assembly _asm;
 
  public ExternalCommandLister(
    string assembly_filename,
    ExternalCommandData commandData )
  {
    _assembly_filename = assembly_filename;
    _external_commmand_class_names = null;
    _commandData = commandData;
 
    if( !File.Exists( assembly_filename ) )
    {
      throw new ArgumentOutOfRangeException(
        "assembly_filename", "file not found" );
    }
    try
    {
      // No need to load the Revit API assemblies, 
      // because we are ourselves a Revit API add-in 
      // inside of Revit, so they are guaranteed to
      // be present.
 
      //Assembly revit = Assembly.LoadFrom( "C:/Program Files/Autodesk/Revit Architecture 2014/RevitAPI.dll" );
      //string root = "C:/Program Files/Autodesk Revit Architecture 2014/";
      //Assembly adWindows = Assembly.LoadFrom( root + "AdWindows.dll" );
      //Assembly uiFramework = Assembly.LoadFrom( root + "UIFramework.dll" );
      //Assembly revit = Assembly.LoadFrom( root + "RevitAPI.dll" );
 
      // Load the selected assembly into 
      // the current application domain:
 
      //Assembly asm = Assembly.LoadFrom(
      //  assembly_filename );
 
      // Load the selected assembly into the current 
      // application domain via byte array to avoid
      // locking the DLL:
 
      byte [] assemblyBytes = File.ReadAllBytes(
        _assembly_filename );
 
      _asm = Assembly.Load( assemblyBytes );
 
      if( null == _asm )
      {
        Util.ErrorMsg( string.Format(
          "Unable to load assembly '{0}'",
          assembly_filename ) );
      }
      else
      {
        IEnumerable<Type> types = _asm.GetTypes()
          .Where<Type>( t =>
            null != t.GetInterface(
              "IExternalCommand" ) );
 
        _external_commmand_class_names = types
          .Select<Type, string>( t => t.FullName )
          .ToArray();
      }
    }
    catch( Exception ex )
    {
      Util.ErrorMsg( string.Format(
        "Exception '{0}' processing assembly '{1}'",
        ex.Message, assembly_filename ) );
    }
  }
 
  public string AssemblyFilename
  {
    get
    {
      return Path.GetFileName( _assembly_filename );
    }
  }
 
  public string[] CommandClassnames
  {
    get
    {
      return _external_commmand_class_names;
    }
  }
 
  public Result Launch( string command_name )
  {
    Debug.Assert(
      _external_commmand_class_names.Contains(
        command_name ),
      "expected valid command name" );
 
    Type typ = _asm.GetType( command_name );
 
    object cmd = _asm.CreateInstance( typ.FullName );
 
    string message = null;
    Autodesk.Revit.DB.ElementSet elements = null;
 
    object [] args = new object[] {
      _commandData, message, elements };
 
    BindingFlags flags = (BindingFlags)
      ( (int) BindingFlags.Default
      | (int) BindingFlags.InvokeMethod );
 
    Result r = (Result) typ.InvokeMember( "Execute",
      flags, null, cmd, args );
 
    message = args[1] as string;
 
    int n = (null == message) ? 0 : message.Length;
 
    Util.InfoMsg( string.Format(
      "{0} returned {1}{2}{3}",
      command_name, r,
      ( 0 == n ? "." : ": " ),
      ( 0 == n ? "" : message ) ) );
 
    return r;
  }
}

Command Class Enhancements

The external command implementation class obviously also needs to be extended in order to enable call the Launch method.

The initial version prompts the user to select an assembly to parse and lists the external command implementation classes it detects in a multi-line text box.

I initially thought of adding a context menu to the text box to enable launching a selected command.

However, it turned out to be easier to implement handling of a double click event instead.

The double click event handler detects the current line and extracts the full external command implementation class name from that to pass to the Launch method:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  /// <summary>
  /// Define the initial .NET assembly folder.
  /// </summary>
  const string _assembly_folder_name
    = "C:\\ProgramData\\Autodesk\\Revit\\Addins\\2014";
 
  /// <summary>
  /// Select a .NET assembly file in the given folder.
  /// </summary>
  /// <param name="folder">Initial folder.</param>
  /// <param name="filename">Selected filename on success.</param>
  /// <returns>Return true if a file was successfully selected.</returns>
  static bool FileSelect(
    string folder,
    out string filename )
  {
    OpenFileDialog dlg = new OpenFileDialog();
    dlg.Title = "Select .NET Assembly or Cancel to Exit";
    dlg.CheckFileExists = true;
    dlg.CheckPathExists = true;
    dlg.InitialDirectory = folder;
    dlg.Filter = ".NET Assembly DLL Files (*.dll)|*.dll";
    bool rc = ( DialogResult.OK == dlg.ShowDialog() );
    filename = dlg.FileName;
    return rc;
  }
 
  void OnDoubleClick( object sender, EventArgs e )
  {
    Debug.Print( "{0}: {1}", sender, e );
 
    TextBox tb = sender as TextBox;
 
    if( null != tb )
    {
      string text = tb.Text;
      int i = tb.GetFirstCharIndexOfCurrentLine();
      text = text.Substring( i );
      int n = text.IndexOf( '\n' );
      if( 0 <= n )
      {
        text = text.Substring( 0, n );
      }
      text.Trim();
      Debug.Print( text );
      if( 0 < text.Length )
      {
        ExternalCommandLister lister = tb.Tag
          as ExternalCommandLister;
 
        lister.Launch( text );
      }
    }
  }
 
  void DisplayExternalCommands(
    string filename,
    IWin32Window owner,
    ExternalCommandData commandData )
  {
    ExternalCommandLister lister
      = new ExternalCommandLister(
        filename, commandData );
 
    string[] a = lister.CommandClassnames;
    int n = a.Length;
 
    System.Windows.Forms.Form form
      = new System.Windows.Forms.Form();
 
    form.Size = new Size( 400, 150 );
 
    form.Text = string.Format(
      "{0} defines {1} external command{2} - double click to launch",
      lister.AssemblyFilename, n,
      ( 1 == n ? "" : "s" ) );
 
    form.FormBorderStyle
      = FormBorderStyle.SizableToolWindow;
 
    System.Windows.Forms.TextBox tb
      = new System.Windows.Forms.TextBox();
 
    tb.Dock = System.Windows.Forms.DockStyle.Fill;
    tb.Location = new System.Drawing.Point( 0, 0 );
    tb.Multiline = true;
    tb.TabIndex = 0;
    tb.WordWrap = false;
    tb.ReadOnly = true;
 
    tb.Text = string.Join( "\r\n",
      lister.CommandClassnames );
 
    tb.Tag = lister;
 
    tb.DoubleClick += new EventHandler(
      OnDoubleClick );
 
    form.Controls.Add( tb );
 
    form.ShowDialog( owner );
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    IWin32Window revit_window
      = new JtWindowHandle(
        ComponentManager.ApplicationWindow );
 
    string filename;
 
    while( FileSelect(
      _assembly_folder_name,
      out filename ) )
    {
      DisplayExternalCommands( filename,
        revit_window, commandData );
    }
    return Result.Succeeded;
  }
}

Summary and Download

One very neat benefit of this approach is that it almost completely replaces the functionality provided by RvtSamples, in that any simple external command can be immediately launched and debugged. It is obviously also much more flexible, 100% totally flexible, in fact. I cannot think of any way to make it more so.

The only remaining advantage of RvtSamples is basically its very inflexibility, the fact that it provides a neat user interface with a static overview of all available samples, plus optional additional add-ins that you specify yourself using include files or by editing and adding new entries to RvtSamples.txt itself. You thus see what you have at your disposal, whereas the flexible new loader requires to to know it in advance yourself.

Come to think of it, this is probably exactly what the AddInManager does as well to enable reloading and re-debugging of already loaded add-ins without restarting Revit and regenerating the RVT project file.

Here is JtExternalCommandLister2.zip containing the complete source code, Visual Studio solution and add-in manifest of the updated version 2014.0.0.2 of this external command.

I hope you find this useful, instructive and inspiring.

Effortless Extensible Storage

Today we proudly present an exciting and powerful extensible storage utility class library by Victor Chekalin. I'll also add some other assorted items at the end:

• Extensible storage extension
• Example 1 – save integer value to an element
• Example 2 – map field and sub-entity value
• Extensible storage extension conclusion
• Zoom and pan in Revit 2013 preview control
• Display real-time interactive element properties

Extensible Storage Extension

I think everyone of us has used shared parameters to save custom data in a Revit document. If you created shared parameters programmatically, you know it was not easy. Unfortunately, it was the only way to store own data in a Revit document.

When Revit 2012 was released I was very happy that Autodesk made one more way to store auxiliary data in a document. It was a really exciting enhancement.

But when I started to use it in the real projects I noticed some inconveniences when using ExStorage in code. I need to create a lot of code to create a schema, need to remember entity field names and their types, always check if schema or entity or field is null etc. It was especially difficult to use complex schemas, with Sub-Schemas and with Array or Map fields. It is even harder when using Sub-Schema in the Map field. For example, here is the sample code snippet from a real project:

  Family family = ( elementType as FamilySymbol )
    .Family;
 
  var familyEntity = family.GetEntity(
    _familySchema );
 
  if( !familyEntity.IsValid() )
  {
    familyEntity = new Entity( _familySchema );
  }
 
  var fsField = _familySchema.GetField(
    "FamilySymbolsInfo" );
 
  var familySymbolsData =
    familyEntity.Get<IDictionary<string, Entity>>(
      fsField );
 
  Entity elementTypeEntity;
 
  if( !familySymbolsData.TryGetValue(
    elementType.Name, out elementTypeEntity ) )
  {
    elementTypeEntity = new Entity(
      fsField.SubSchemaGUID );
  }
 
  elementTypeEntity.Set( "Entity",
    serializedString );
 
  if( !familySymbolsData.ContainsKey(
    elementType.Name ) )
  {
    familySymbolsData.Add( elementType.Name,
      elementTypeEntity );
  }
 
  familyEntity.Set( fsField, familySymbolsData );
 
  family.SetEntity( familyEntity );

Pretty simple, isn't it? :-)

Of course not...

Very easy to make a mistake and quite difficult to understand what is written there. The more I used ExStorage, the more I wanted to make it easier to use.

The Revit API help states the following about Extensible Storage: '... allows you to create your own class-like Schema data structures and attach instances of them...' I thought – 'Why it is class-like and instances? Why can't I use exactly a class to define Schema and use instance of a class to attach it to the Revit element?'

Thus was born the idea of the Extensible Storage Extension. The idea is simple: define a special class describing the ExStorage schema, where class properties are schema fields. To attach data to an element, create an instance of the class, set it properties and set to the element. Sounds good.

As the result I implemented all what I wanted to do in my extension.

The extension supports all extensible storage features such as:

• Simple field
• Array field
• Map field
• Sub entities
• Documentations
• VendorID
• DisplayUnit

Let's look at the examples and compare it with the default using Extensible Storage.

Example 1 – Save Integer Value to an Element

To save an integer value to an element using standard Extensible storage methods, we can use the following code:

  // 1. Looking for the schema in the memory
 
  Schema schema = Schema.Lookup( new Guid(
    "4E5B6F62-B8B3-4A2F-9B06-DDD953D4D4BC" ) );
 
  // 2. Check if schema exists in the memory or not
 
  if( schema == null )
  {
    // 3. Create it, if not
 
    schema = CreateSchema();
  }
 
  // 4. Create entity of the specific schema
 
  var entity = new Entity( schema );
 
  // 5. Set the value for the Field.
  // HERE WE HAVE TO REMEMEBER THE 
  // NAME OF THE SCHEMA FIELD
  // It would be better to check if the field with
  // such name exists in the schema
 
  entity.Set( "SomeValue", 888 );
 
  // 6. Attach entity to the element
 
  element.SetEntity( entity );
 
  private Schema CreateSchema()
  {
    SchemaBuilder schemaBuilder =
      new SchemaBuilder( new Guid(
        "4E5B6F62-B8B3-4A2F-9B06-DDD953D4D4BC" ) );
 
    schemaBuilder.SetSchemaName( "SimpleIntSchema" );
 
    // Have to define the field name as string and 
    // set the type using typeof method

    schemaBuilder.AddSimpleField( "SomeValue",
      typeof( int ) );
 
    return schemaBuilder.Finish();
  }

Here we achieve the same using the Extensible Storage Extension:

Define the special class at first:

  // Set schema Id and Schema name as class attributes
 
  [Schema( "4E5B6F62-B8B3-4A2F-9B06-DDD953D4D4BB",
    "SimpleIntSchema" )]
 
  public class IntEntity : IRevitEntity
  {
    // Mark the property as Schema field using attributes
 
    [Field]
    public int SomeValue { get; set; }
  }

Attach an instance of this class to the element:

  // Create a new instance of the class
 
  IntEntity intEntity =
      new IntEntity();
 
  // Set property value
 
  intEntity.SomeValue = 777;
 
  // Attach to the element
 
  element.SetEntity( intEntity );

That's it.

Amazing, isn't it?

Just compare the two approaches.

What is easier – to work with the ordinary .NET classes, or use a lot of methods to work with Schemas and Entities?

I think the answer is obvious.

Here is a similar comparison of the code to read a value.

Default approach:

  var schema = Schema.Lookup( new Guid(
    "4E5B6F62-B8B3-4A2F-9B06-DDD953D4D4BC" ) );
 
  if( schema != null )
  {
    var entity = element.GetEntity( schema2 );
    var someValue = entity.Get<int>( "SomeValue" );
    TaskDialog.Show( "Entity value",
      someValue.ToString() );
  }

My extensible storage extension approach:

  var intEntity2 = element.GetEntity<IntEntity>();
 
  if( intEntity2 != null )
  {
    TaskDialog.Show( "Entity value",
      intEntity2.SomeValue.ToString() );
  }

Let's look at another more complicated example.

Example 2 – Map Field and Sub-Entity Value

Here is some code to set up a complex entity using the default ExStorage methods:

  // Check if schema exists in the memory.
 
  var schema3 = Schema.Lookup( new Guid(
    "1899FD3C-7046-4B53-945A-AA1370B8C577" ) );
 
  if( schema3 == null )
  {
    // Create if not
 
    schema3 = CreateComplexSchema();
  }
 
  var entity4 = new Entity( schema3 );
 
  // Map fields
  IDictionary<int, Entity> mapOfEntities
    = new Dictionary<int, Entity>();
 
  // Create sub-entity 1
  var entity7 = new Entity( new Guid(
    "4E5B6F62-B8B3-4A2F-9B06-DDD953D4D4BC" ) );
 
  entity7.Set( "SomeValue", 7 );
 
  // create sub-entity 2
  var entity8 = new Entity( new Guid(
    "4E5B6F62-B8B3-4A2F-9B06-DDD953D4D4BC" ) );
 
  entity8.Set( "SomeValue", 8 );
 
  mapOfEntities.Add( 7, entity7 );
  mapOfEntities.Add( 8, entity8 );
 
  entity4.Set( "MapField", mapOfEntities );
 
  element.SetEntity( entity4 );
 
  private Schema CreateComplexSchema()
  {
    SchemaBuilder schemaBuilder = new SchemaBuilder(
      new Guid( "1899FD3C-7046-4B53-945A-AA1370B8C577" ) );
 
    schemaBuilder.SetSchemaName( "ComplexSchema" );
 
    var mapField = schemaBuilder.AddMapField(
      "MapField", typeof( int ), typeof( Entity ) );
 
    mapField.SetSubSchemaGUID( new Guid(
      "4E5B6F62-B8B3-4A2F-9B06-DDD953D4D4BC" ) );
 
    mapField.SetDocumentation(
      "Map field documentation" );
 
    return schemaBuilder.Finish();
  }

We can use the following to change a value in the map field:

  var entity10 = element.GetEntity( schema3 );
 
  var mapField =
    entity10.Get<IDictionary<int, Entity>>(
      "MapField" );
 
  if( mapField != null )
  {
    if( mapField.ContainsKey( 8 ) )
    {
      var entity11 = mapField[8];
      entity11.Set( "SomeValue", 999 );
 
      // Write changes
 
      entity10.Set( "MapField", mapField );
 
      element.SetEntity( entity10 );
    }
  }

Here is the code to achieve the same result using the extension:

  [Schema( "93CC69FC-AB6F-451A-B075-A5D9467569C2",
    "ComplexSchema" )]
  public class ComplexEntity : IRevitEntity
  {
    [Field]
    public string SimpleField { get; set; }
 
    [Field]
    public List<IntEntity> ArrayField { get; set; }
 
    [Field]
    public Dictionary<int, IntEntity> MapField { get; set; }
  }
 
  ComplexEntity complexEntity = new ComplexEntity();
 
  complexEntity.MapField
    = new Dictionary<int, IntEntity>
    {
      {9, new IntEntity(){SomeValue = 9}},
      {10, new IntEntity(){SomeValue = 10}}
    };
 
  element.SetEntity( complexEntity );

Change the value like this:

  var complexEntity2 = element
    .GetEntity<ComplexEntity>();
 
  if( complexEntity2 != null )
  {
    if( complexEntity.MapField.ContainsKey( 9 ) )
    {
      var entityInMapField = complexEntity.MapField[9];
 
      entityInMapField.SomeValue = 9898;
 
      element.SetEntity( complexEntity2 );
    }
  }

Extensible Storage Extension Conclusion

My extensible storage extension provides an easy and safe way to use extensible storage. You use standard .NET classes instead a lot of RevitAPI classes and methods.

If you use extensible storage a lot, you should evaluate the benefits of my extension. If you never used ExStorage, I hope that my extension will help you to begin using it.

You may download the source code and more samples from the GitHub repository. If you do not know how to use Git you can simply download it as a complete zip archive.

If you do not need the source code, you may download the .NET assembly only, reference it in your add-in project and immediately take advantage of all the benefits of my extension.

I hope this information is useful for all Revit developers.

Many thanks to Victor for this beautiful and powerful tool!

Zoom and Pan in Revit 2013 Preview Control

I myself ran into some confusion using the preview control in Revit 2013. Others ran into similar issues, so here is a clarification:

Question: I notice varying behaviour of the preview control in different versions of Revit 2013. If you compile and load the PreviewControl sample add-in from the Revit 2013 UIAPI SDK sample, you can pan around in the model using the mouse wheel or the context menu. This no longer works in the service packs. How should we deal with this, please?

Answer: Yes, I noticed something similar myself when implementing my minimal DevCamp PreviewControlSimple sample for the session on Revit 2013 UI API enhancements.

I would suggest trying to encapsulate the whole use of the preview control in a transaction.

The zoom and pan is actually affecting the real live Revit viewport, i.e., modifying the database, so it requires a transaction.

I believe that you can get all three kinds of behaviour by panning and zooming in a preview control:

• No transaction → exception on touching the view cube
• No transaction → nothing happens (like you describe)
• Transaction → should work afaik

Therefore, the simple solution is to simply encapsulate your use of the control in a transaction.

If you commit it afterwards, the Revit viewport will be affected by the panning and zooming. If not, not.

I'm happy to announce that this should no longer be an issue in Revit 2014.

Display Real-time Interactive Element Properties

Question: I have implemented a tool that displays some properties of a selected element on the add-in button click.

I would like to enable the user to just click my add-in button once, go on selecting elements, and display updated properties on each new selection.

How could that be achieved?

Answer: To achieve this, you have to work in a modeless context and make use of the Idling event.

Here is an obsolete sample describing a modeless pressure drop tool posted before the advent of Idling. That might give you some bright ideas, but definitely do not use it as is!

Here is a more up-to-date sample making use of the Idling event to display the contents of the current selection set, which is pretty close to what you are searching for.

I strongly suggest basing anything making use of the Idling event, or an external event, which is a simplified wrapper around that, on the ModelessForm_ExternalEvent and ModelessForm_IdlingEvent SDK samples introduced in Revit 2013.

CouchDB Implementation and GitHub Repository

I more or less completed the research for my cloud-based round-trip 2D Revit model editing project.

I'll describe some parts of that, and also address

• Three aspects of life and programming
• Room editor navigation
• Nested asynchronous database call-back functions
• Roomedit – my first GitHub project
• Debugging JavaScript with Firebug
• Screen snapshots on mobile devices
• Open source components used by Autodesk
• Retrieve slabs above specific walls

Lazy, Simple and Perfect

You will like the first slide of my upcoming tech summit presentation.

I start off with a couple of quotes on three fundamental aspects of software engineering and life in general:

• Lazy
• ... develop the three great virtues of a programmer: laziness, impatience, and hubris – Larry Wall
• Simple
• Simplicity is the ultimate sophistication – Leonardo da Vinci
• There is no greatness where there is no simplicity – Leo Tolstoy
• KISS
• Perfect
• Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away – Antoine de Saint-Exupéry

Basically, I demonstrate how easy it is to implement simple model navigation and 2D graphical editing using server-side scripting so that it works on all mobile devices.

So it is all about keeping it simple and easy.

Room Editor Navigation

The last instalment on this topic included a two-minute minimal demo recording illustrating its use and started describing the simplest aspect of the implementation, the server-side generated index.html home page that lists all models and prompts to select one of them.

From there, one navigates through the hierarchy of model > level > room > furniture and equipment. The latter finally reference the symbol objects that determine their geometry.

Now lets move on to the more interesting parts where the inter-related objects need to execute more complex queries to establish their relationships. I still have not covered the juicy part of rendering the SVG model, and the even juicier part of interacting with it, editing it, and updating the database with the changes made, either.

As said, the navigation logic is pretty trivial:

• Home page: list all models and prompt to select one of them.
• Model selected: list all levels in model and prompt to select one of them.
• Level selected: list all rooms on the level and prompt to select one of them.
• Room selected: display the room boundary and the furniture and equipment instances graphically and enable editing their location and rotation.

Basically, the entire implementation is all squeezed into one single overgrown index.html file.

Moving on from the home page to the second simplest part of it, we have selected a specific model and list all the levels it contains.

This navigation takes place by invoking the same index.html URL and adding a modelId parameter to it.

This parameter is picked up and used to query the database for all levels in the specified model.

To retrieve only the required ones, I use a CouchDB view mapping model id keys to level documents like this:

  map_model_to_level = {
    map: function (doc) {
      if( 'level' == doc.type ) {
        emit(doc.modelId, doc);
      }
    }
  };

I can specify a key to CouchDB when querying this view, i.e. make a REST API call with a parameter like this:

  .../roomedit/_design/roomedit/_views?key=12345

This will retrieve only those level documents from the database whose modelId value matches the given key.

Here is the part of index.html handling that interaction:

. . .

else if ( paramdict.hasOwnProperty( 'modelid' ) ) {

  //======================================================
  // display a menu of all levels in selected model
  //======================================================

  var mid = paramdict['modelid'];
  db.getDoc( mid,
    function(err,resp) {
      if (err) {
        return alert(JSON.stringify(err));
      }
      var modeldoc = resp;
      db.getView('roomedit',
        'map_model_to_level',
        { key: JSON.stringify(mid) },

        function (err, data) {
          if (err) {
            return alert(err);
          }
          var n = data.rows.length;
          for (var i = 0; i < n; ++i) {
            var doc = data.rows[i].value;
            if( doc.modelId != mid ) {
              alert( 'model ids differ: doc '
                + doc.modelId + ", url " + mid );
            }
            var s = url + '?levelid=' + doc._id;
            $('<li/>')
              .append($('<a>').attr('href',s).text(doc.name))
              .appendTo('#navigatorlist');
          }
          var p = $('<p/>').appendTo('#content');
          p.append( $('<a/>').text('Home').attr('href',url) );
          p.append( document.createTextNode( three_spaces ) );
          p.append( $('<a/>').text('Back').attr('href',url) );

          $('<p/>')
            .text( 'Please select a level in the list below.' )
            .appendTo('#content');

          var table = $('<table/>').appendTo('#content');
          table.append( '<tr><td>' + 'Model:'
            + '</td><td>' + modeldoc.name + '</td></tr>' );

          var prompt = n.toString() + ' level'
            + pluralSuffix( n ) + ' in model ';

          var p = $('<p/>').text( prompt ).appendTo('#content');
          p.append( $('<i/>').text( modeldoc.name ) );
          p.append( document.createTextNode( dotOrColon( n ) ) );
        }
      );
    }
  );
}

As I already mentioned, this is populating an super simple HTML skeleton containing the following nodes:

  <h1>Room Editor</h1>

  <div id="content"></div>

  <ul id="navigatorlist"></ul>

Here is the result in a model named 'Roombook' containing a single level 'Fondations':

Nested Asynchronous Database Call-back Functions

One challenge for me in the room editor CouchDB implementation was understanding how the asynchronous database call-back functions work, and how I can nest them to retrieve all the results I need.

In the case above, the situation is still very simple: I need to perform two database queries:

• Query a specific document, the model, using the db.getDoc function.
• Query all the levels it contains, which are returned by the map_model_to_level view with the model id key, using the getView function.

Both the getDoc and getView functions take an asynchronous call-back function as an argument.

I found out the hard way that I can nest these within each other to ensure that I have all up-to-date results before I display my page.

This gets a bit more hairy as the number of queries and thus the number of nested functions grows...

Roomedit – My First GitHub Project

Anyway, I have it all happily running now, and published the roomedit CouchDB application implementing this as my first ever GitHub project.

Debugging JavaScript with FireFox FireBug

Everybody makes errors. In my HTML and JavaScript code, these sometimes caused my index.html not to display anything at all.

Often this was due to some trivial JavaScript typo that would have been really hard to chase down.

Enter Firebug, thank God.

This is a great tool that I have started to rely on greatly to help me out of tight corners.

The Firebug debugging console is integrated in FireFox and includes support for examining and debugging all kinds of aspects of a web page.

You can open the Firebug console on any web page through Tools > Web Developer > Firebug > Open Firebug. That displays a new panel at the bottom of the browser with tabs for

• Console
• HTML
• CSS
• Script
• DOM
• Net
• Cookies

I use Console and Script, mostly.

The former displays the location of a JavaScript error and jumps to it when loading the file. It also lists the URLs visited and stuff like that, which is very useful for analysing the REST API calls being made.

The script tab provides a JavaScript debugger allowing you to set breakpoints and analyse variable values etc.

There are lots of tutorials and documentation available on this feature, such as these ones on Firebug and JavaScript debugging, so I will not trouble you any further with my description.

To tell the truth, though, I never looked at any of them.

The thing just worked for me, is incredibly valuable, and I am grateful.

Screen Snapshots on Mobile Devices

Here is a quick guide how to create a screen snapshot on various types of mobile devices:

• iPhone – Press the Sleep/Wake and Home buttons together; the screen will fade temporarily, signalling that the screen shot was saved in your Camera Roll:
  
• Android – Press the Power and Home buttons together, or hold down the Lock/Power and Volume Down buttons together:
  
• Windows 8 – Press the Lock/Power and Home/Windows buttons together:
  

Open Source Components used by Autodesk

A colleague pointed out this open source repository containing all open source components used in AutoCAD, Map 3D and other Autodesk products.

I was actually surprised how short the list is. Anyway, it might be useful to know about.

Retrieve Slabs Above Certain Walls

Let's wrap this up with a standard Revit API question:

Question: I want to determine the slab above the walls of a particular room.

How can retrieve those using the Revit API, please?

Answer: As so often in Revit, there are a number of different possibilities, and it depends in part upon how the building has been modelled.

In a structural model, you may be able to query the analytical support data. I have no idea whether this information is included there, but my naive assumption would be that this should be possible.

Much more generally, you can analyse and query the geometry in a number of different ways.

The two possibilities that immediately spring to mind are:

• Use the ray casting functionality provided by the Document FindReferencesWithContextByDirection method and the ReferenceIntersector wrapper class.
• Use the geometric proximity functionality provided by some element filters, e.g.

The discussion on determining the columns supporting a beam demonstrates several different variations of the latter. Earlier blog posts include examples of the former as well.

Response: I was able to use the functionality for finding the supporting columns for beams from your link to solve my issue as well.

In my case, beam.GetGeneratingElementIds returns the desired supported floors.

I also tested using an ElementIntersectsSolidFilter to retrieve all walls that intersect the floor using the floor solid geometry object:

  Solid solid = null;
  ElementFilter slabIntersectFilter
    = new ElementIntersectsSolidFilter( solid );
 
  FilteredElementCollector walls
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .OfClass( typeof( Wall ) )
      .WherePasses( slabIntersectFilter );

This also solved my issue. It can be the alternative when beams are not there.

My Cloud-Based 2D Editor Implementation and Status

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, here are some issues I tackled since my last report:

• Updated project description and status
• CouchDB SVG editor implementation
• Home page: list all models and select one

Updated Project Description

I originally thought I would be implementing three cooperating components: the Revit add-in, a cloud-based data repository, and a browser-based JavaScript SVG viewer and editor client for the mobile devices.

After struggles with and resolution of the same origin policy, I discover that I need to use server-side scripting instead, which moves all the JavaScript and SVG handling to the cloud-based data repository component as well.

I updated my proposal accordingly as follows:

Cloud-based Round-trip 2D Revit Model Editing on any Mobile Device
using Server-side Scripting, CouchDB and SVG

I demonstrate round-trip editing a 2D rendering of a Revit model on any mobile device with no need for installation of any additional software whatsoever beyond a browser.

How can this be achieved?

A Revit add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository implemented using a CouchDB NoSQL database.

On the mobile device, the repository is queried and the data is rendered in a standard browser using server-side generated JavaScript and SVG.

The rendering supports graphical editing, specifically translation and rotation of the furniture and equipment.

Modified transformations are saved back to the cloud database.

The Revit add-in picks up these changes and updates the Revit model in real-time.

All of the components used except Revit are completely open source.

This round-trip editing workflow is based on the following main components:

• A Revit add-in that determines room boundary and furniture and equipment family instance polygons for a simplified 2D plan view rendering.
• A cloud-based database repository managing the models, levels, rooms, furniture, equipment meta- and polygon data.
• A server hosted JavaScript SVG editor running in the browser on any device, rendering the model and supporting simple geometric modification of the model.

The presentation outline, the final proof of the pudding, looks like this:

• Show a Revit model.
• Export the model to a cloud-based data repository.
• Query and display the repository contents as a 2D rendering on a mobile device.
• Edit the model in the browser on the mobile device, updating the data repository.
• Watch the BIM in Revit auto-update.

I have now completed the implementation of all these steps with the single minute exception of the prefix 'auto'.

In other words, I currently have two commands in my Revit add-in:

• CmdUpload uploads the room and equipment boundary data to the cloud repository, either from a manually selected set of rooms, or all rooms in the model.
• CmdUpdate retrieves the changes applied to furniture and equipment on the mobile device. This is currently a command triggered by the user.

The next step for me will be adding the 'auto' to the update, i.e. the implementation of an external event that subscribes to changes in the cloud database caused by the user editing the furniture and equipment transforms on the mobile device and automatically applies real-time updates to the BIM.

Before I get to that, though, I have a huge backlog of information to share about all that has already been achieved, and how.

Without further ado, here is a little two-minute film demonstrating the current functionality to give you the idea:

CouchDB SVG Editor Implementation

I described the room editor database structure consisting of the model, level and room hierarchy.

Furniture and equipment instances are placed within the room and refer to separate symbol objects that store their geometry.

Two of the main tasks listed in my last to-do list were:

• Implement the rendering and editing of the 2D plan view in SVG on the mobile device.
• Reflect the modifications made back to the cloud-based CouchDB data repository.

Let's look at how I achieved that.

First, I must admit that I struggled quite a bit and burnt a significant amount of night oil on this. Maybe it would have been more efficient to do some reading up on basics before starting. Instead, I found various tutorials that did "almost" what I wanted that I tried to reproduce and tweak. Each and every one finally turned into a dead end, and I was thrown back to square one, or sometimes square 1.15 or so.

One impressive little sample application that really did help was Opto3, a small CouchDB application entirely hosted within CouchDB. It uses JQuery Mobile to serve a single-page mobile application that presents a four-panel drill-down approach to find an optometrist in a desired US location.

All the information stems from one single CSV file of US optometrician addresses. Here is its description, GitHub project repository and CodeProject article that also provides a useful list of additional references.

As said, I can use Kanso to maintain and install the database, push the views and upload my documents in JSON format to the local CouchDB database 'roomedit' using commands such as these:

$ kanso install

$ kanso push http://localhost:5984/roomedit

$ kanso upload mydata.json http://localhost:5984/roomedit

I ended up implementing my totally own version of a CouchDB application, unlike anything I saw in any of the samples.

Basically, I only use a couple of CouchDB views and a rather heavy-weight index.html file that renders them for various contexts, guiding the user through the model and room selection process and finally displaying the SVG editor page.

The selection logic is simple:

• Home page: list all models and prompt to select one of them.
• Model selected: list all levels in model and prompt to select one of them.
• Level selected: list all rooms on the level and prompt to select one of them.
• Room selected: display the room boundary and the furniture and equipment instances graphically and enable editing their location and rotation.

The first three steps were not so hard once I understood about CouchDB views and discovered how to render them in index.htm.

Integrating the SVG editor posed some really tough problems, but ended up being really simple as well.

For a while I was unsure whether I would be able to use the Raphaël JavaScript SVG library as is, or whether it needed to be packaged as a Kanso package. As it turned out, that was not necessary. Until I discovered that the hard way, though, I tried to avoid the use of any non-Kanso libraries at all, and struggled with SVG editing issues instead.

So let's start by looking at the simplest step first, how to list all models and prompt the user to select one of them.

Home Page: List all Models and Select One

The initial home page of my application is very simple. It looks like this, listing the available models and prompting the user to select one of them:

I represent each Revit model as a separate CouchDB document. All the data it carries is inherited from the DbObj base class, which specifies its type "model", description and name. I populate the two latter with information from the Revit ProjectInfo singleton object, and I use the Revit UniqueId as the CouchDB document identifier as well.

The resulting CouchDB JSON representation of my sample model looks like this (copy to an editor or view the HTML source to see the truncated lines in full):

{
  "_id": "bf0552b6-b7f7-4331-96d5-b19843262895-00015084",
  "_rev": "14-4e1c947c3d3e354117a1f016f2e23f63",
  "type": "model",
  "description": "ProjectInfo Project Information <86148 Project Information>",
  "name": "room_with_hole.rvt"
}

CouchDB implements and extremely scalable architecture and can host millions of documents.

Views are used to efficiently extract the ones required. A view can implement a map and a reduce function. The map function identifies the documents of interest and maps them to a key-value pair. The optional reduce function can be applied to reduce the results by accumulation or other means. I have no use for reduce in my application.

To list all available models, I use an utterly trivial view function that does not even create real key-value pairs. All I need is to extract all model documents and list the model document information itself, so I just emit all model documents as keys directly:

exports.models = {
  map: function (doc) {
    if( 'model' == doc.type ) {
      emit(doc, null);
    }
  }
};

To render the results of the view into my HTML target file, I define the following scaffolding:

  <h1>Room Editor</h1>

  <div id="content"></div>

  <ul id="navigatorlist"></ul>

In the JavaScript section, I require the Kanso db and jquery packages:

  var db = require('db').current();
  var $ = require('jquery');

The db package provides access to the current CouchDB database, and jquery is a Kanso wrapper for the standard jquery library.

Oh, and what is Kanso itself? Kanso is a framework enabling me to maintain my CouchDB views and other bits and pieces in standard file system files on the hard disk and upload them easily to the CouchDB database.

With that in place, the following JavaScript code queries the 'models' view and populates the HTML placeholder tags:

// display a menu of all available models

db.getView('room_loops', 'models',
  function (err, data) {
    if (err) {
      return alert(err);
    }
    var n = data.rows.length;
    for (var i = 0; i < n; ++i) {
      var doc = data.rows[i].key;
      var s = url + '?modelid=' + doc._id;
      $('<li/>').append($('<a>')
        .attr('href',s)
        .text(doc.name))
      .appendTo('#navigatorlist');
    }
    var p = $('<p/>').appendTo('#content');
    p.append( $('<a/>').text('Home').attr('href',url) );
    p.append( document.createTextNode( three_spaces ) );
    p.append( $('<a/>').text('Back').attr('href',url) );

    $('<p/>')
      .text( 'Please select a model in the list below.' )
      .appendTo('#content');

    var prompt = n.toString() + ' model'
      + pluralSuffix( n ) + dotOrColon( n );

    $('<p/>').text( prompt ).appendTo('#content');
  }
);

As you can see, the db.getView method is provided with three arguments: the database name, the view name, and a call-back function.

Understanding how the call-back function works was another big stumbling block for me.

In this simple case, all is clear, of course.

We submit the query to get the view and return immediately.

CouchDB processes the request and invokes the call-back function when completed.

The call-back function processes the resulting data rows, extracting the model document data from the key provided with each row and populating the HTML scaffolding accordingly.

Again, here is the final result with two models listed, just as you can see in the video above:

Well, I am spending much too much time documenting this for you, and really need to get on with the implementation and my real day work, so I will call it wraps for today now.

Room and Furniture Loops Using Symbols

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I now implemented the first of the next steps mentioned at the end:

• Separation of symbol and instance data in my add-in and database structure: currently, the furniture loops are placed absolutely, and multiple instances of a symbol duplicate the same loop over and over again at different locations. I will rewrite this to separate the furniture loop definition, defined by the family symbol, and its placement, defined by the instance. This needs to be done anyway to enable editing the placement data through the editor interaction on the mobile device.

The first implementation just uploaded the room and furniture instance 2D boundary polygon loops, absolutely placed.

Besides converting that to defining and reusing symbols, I also added support for exporting the model and level data to the cloud.

I discuss the implementation of that here now:

• Database structure
• Database upload
• Integer based 2D placement
• Populating symbols and instances
• Retrieving the boundary loops
• GeoSnoop loop display
• Caveats
• Download
• Next steps

Database Structure

I enhanced the database classes to include a new class DbSymbol. It defines the family symbol loop, which is reused by the family instances.

The DbFurniture class no longer has its own individual loop data. Instead, it has a reference to a symbol and placement data defining its 2D translation and rotation.

All the database classes are derived from the DbObj base class:

• DbObj
• Type
• Description
• Name

Some of the derived classes have no additional properties of their own at all. The data structure is this as simple as this:

• DbModel
• DbLevel
• ModelId
• DbRoom
• LevelId
• Loops
• ViewBox
• DbSymbol
• Loop
• DbFurniture
• RoomId
• SymbolId
• Transform

The source code does nothing but exactly reproduce this structure. Here is the complete implementation of these classes:

  /// <summary>
  /// Base class for all Jeremy Room Editor classes.
  /// </summary>
  class DbObj : CouchDocument
  {
    protected DbObj()
    {
      Type = "obj";
    }
    public string Type { get; protected set; }
    public string Description { get; set; }
    public string Name { get; set; }
  }
 
  /// <summary>
  /// Current model, i.e. Revit project.
  /// </summary>
  class DbModel : DbObj
  {
    public DbModel()
    {
      Type = "model";
    }
  }
 
  /// <summary>
  /// Level.
  /// </summary>
  class DbLevel : DbObj
  {
    public DbLevel()
    {
      Type = "level";
    }
    public string ModelId { get; set; }
  }
 
  /// <summary>
  /// Room
  /// </summary>
  class DbRoom : DbObj
  {
    public DbRoom()
    {
      Type = "room";
    }
    public string LevelId { get; set; }
    public string Loops { get; set; }
    public string ViewBox { get; set; }
  }
 
  /// <summary>
  /// Family symbol, i.e. element type defining 
  /// the geometry, i.e. the 2D boundary loop.
  /// </summary>
  class DbSymbol : DbObj
  {
    public DbSymbol()
    {
      Type = "symbol";
    }
    public string Loop { get; set; }
  }
 
  /// <summary>
  /// Family instance, defining placement, i.e.
  /// transform, i.e. translation and rotation,
  /// and referring to the symbol geometry.
  /// </summary>
  class DbFurniture : DbObj
  {
    public DbFurniture()
    {
      Type = "furniture";
    }
    public string RoomId { get; set; }
    public string SymbolId { get; set; }
    public string Transform { get; set; }
  }

Database Upload

The database upload has not changed very much from the previous version, except that the model, level and symbol data is now added, and the furniture and equipment instances store their symbol reference and transformation:

/// <summary>
/// Upload model, level, room and furniture data 
/// to an IrisCouch hosted CouchDB data repository.
/// </summary>
static public void DbUploadRoom(
  Room room,
  List<Element> furniture,
  JtLoops roomLoops,
  Dictionary<string, JtLoop> furnitureLoops,
  List<JtPlacement2dInt> furnitureInstances )
{
  CouchClient client = new CouchClient(
    _web_url,
    5984 );
 
  CouchDatabase db = client.GetDatabase(
    _database_name, true );
 
  Document doc = room.Document;
 
  Element projectInfo
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ProjectInfo ) )
      .FirstElement();
 
  string uid = projectInfo.UniqueId;
 
  DbModel dbModel;
 
  if( db.DocumentExists( uid ) )
  {
    dbModel = db.GetDocument<DbModel>( uid );
 
    Debug.Assert(
      dbModel.Id.Equals( projectInfo.UniqueId ),
      "expected equal ids" );
 
    dbModel.Description = Util.ElementDescription(
      projectInfo );
 
    dbModel.Name = projectInfo.Document.Title;
 
    dbModel = db.UpdateDocument<DbModel>(
      dbModel );
  }
  else
  {
    dbModel = new DbModel();
 
    dbModel.Id = uid;
    dbModel.Description = Util.ElementDescription(
      projectInfo );
 
    dbModel.Name = projectInfo.Name;
    dbModel = db.CreateDocument<DbModel>( dbModel );
  }
 
  Level level = room.Level;
 
  uid = level.UniqueId;
 
  DbLevel dbLevel;
 
  if( db.DocumentExists( uid ) )
  {
    dbLevel = db.GetDocument<DbLevel>( uid );
 
    Debug.Assert(
      dbLevel.Id.Equals( level.UniqueId ),
      "expected equal ids" );
 
    dbLevel.Description = Util.ElementDescription(
      level );
 
    dbLevel.Name = level.Name;
    dbLevel.ModelId = projectInfo.UniqueId;
 
    dbLevel = db.UpdateDocument<DbLevel>(
      dbLevel );
  }
  else
  {
    dbLevel = new DbLevel();
 
    dbLevel.Id = uid;
    dbLevel.Description = Util.ElementDescription(
      level );
 
    dbLevel.Name = level.Name;
    dbLevel.ModelId = projectInfo.UniqueId;
 
    dbLevel = db.CreateDocument<DbLevel>(
      dbLevel );
  }
 
  uid = room.UniqueId;
 
  DbRoom dbRoom;
 
  if( db.DocumentExists( uid ) )
  {
    dbRoom = db.GetDocument<DbRoom>( uid );
 
    Debug.Assert(
      dbRoom.Id.Equals( room.UniqueId ),
      "expected equal ids" );
 
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
    dbRoom.ViewBox = roomLoops.BoundingBox.SvgViewBox;
 
    dbRoom = db.UpdateDocument<DbRoom>( dbRoom );
  }
  else
  {
    dbRoom = new DbRoom();
 
    dbRoom.Id = uid;
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
    dbRoom.ViewBox = roomLoops.BoundingBox.SvgViewBox;
 
    dbRoom = db.CreateDocument<DbRoom>( dbRoom );
  }
 
  foreach( KeyValuePair<string, JtLoop> p in furnitureLoops )
  {
    uid = p.Key;
    Element e = doc.GetElement( uid );
    if( db.DocumentExists( uid ) )
    {
      DbSymbol symbol = db.GetDocument<DbSymbol>(
        uid );
 
      symbol.Description = Util.ElementDescription( e );
      symbol.Name = e.Name;
      symbol.Loop = p.Value.SvgPath;
 
      symbol = db.UpdateDocument<DbSymbol>( symbol );
    }
    else
    {
      DbSymbol symbol = new DbSymbol();
      symbol.Id = uid;
      symbol.Description = Util.ElementDescription( e );
      symbol.Name = e.Name;
      symbol.Loop = p.Value.SvgPath;
 
      symbol = db.CreateDocument<DbSymbol>( symbol );
    }
  }
 
  foreach( FamilyInstance f in furniture )
  {
    uid = f.UniqueId;
    if( db.DocumentExists( uid ) )
    {
      DbFurniture dbf = db.GetDocument<DbFurniture>(
        uid );
 
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.SymbolId = f.Symbol.UniqueId;
      dbf.Transform = new JtPlacement2dInt( f )
        .SvgTransform;
 
      dbf = db.UpdateDocument<DbFurniture>( dbf );
    }
    else
    {
      DbFurniture dbf = new DbFurniture();
      dbf.Id = uid;
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.SymbolId = f.Symbol.UniqueId;
      dbf.Transform = new JtPlacement2dInt( f )
        .SvgTransform;
 
      dbf = db.CreateDocument<DbFurniture>( dbf );
    }
  }
}

Integer Based 2D Placement

I implemented the following simple class to manage the 2D placement.

It is based on the 2D point class, storing the coordinate data in integers, for various reasons:

• Revit precision is no smaller than one sixteenth of an inch, ca. 1.2 mm.
• The data is stored in the cloud and rendered on a mobile device: the use of integers
• eliminates rounding issues,
• lowers the data volume,
• enhances performance,
• simplifies storage,
• improves human reading and understanding.

Since I am already using millimetres for the length measurement, I find it fitting to store the rotation in degrees. The SVG rendering expects degrees as input, anyway.

Here is the class implementation:

/// <summary>
/// A 2D integer-based transformation, 
/// i.e. translation and rotation.
/// </summary>
class JtPlacement2dInt
{
  /// <summary>
  /// Translation.
  /// </summary>
  public Point2dInt Translation { get; set; }
 
  /// <summary>
  /// Rotation in degrees.
  /// </summary>
  public int Rotation { get; set; }
 
  /// <summary>
  /// The family symbol UniqueId.
  /// </summary>
  public string SymbolId { get; set; }
 
  public JtPlacement2dInt( FamilyInstance fi )
  {
    LocationPoint lp = fi.Location as LocationPoint;
 
    Debug.Assert( null != lp,
      "expected valid family instanace location point" );
 
    Translation = new Point2dInt( lp.Point );
 
    Rotation = (int) (
      ( ( 180 * lp.Rotation ) + 0.5 ) / Math.PI );
 
    SymbolId = fi.Symbol.UniqueId;
  }
 
  /// <summary>
  /// Return an SVG transform,
  /// either for native SVG or Raphael.
  /// </summary>
  public string SvgTransform
  {
    get
    {
      return string.Format(
        "R{2}T{0},{1}",
        //"translate({0},{1}) rotate({2})",
        Translation.X, Translation.Y, Rotation );
    }
  }
}

The placement is instantiated from a family instance, and returns a suitably formatted SVG transformation string, either for native SVG or the Raphaël JavaScript SVG library.

Populating Symbols and Instances

To populate the symbol and instance data, I loop over all the instances exactly like I did previously.

Now, instead of exporting the family instance boundary loop in situ, I transform it back to the symbol definition coordinate system instead, and save that in a dictionary mapping the family symbol UniqueId to its boundary loop.

The family instance exports a reference to that symbol and its placement data:

  List<Element> furniture
    = GetFurniture( room );
 
  // Map symbol UniqueId to symbol loop
 
  Dictionary<string, JtLoop> furnitureLoops
    = new Dictionary<string, JtLoop>();
 
  // List of instances referring to symbols
 
  List<JtPlacement2dInt> furnitureInstances
    = new List<JtPlacement2dInt>(
      furniture.Count );
 
  int nFailures;
 
  foreach( FamilyInstance f in furniture )
  {
    FamilySymbol s = f.Symbol;
 
    string uid = s.UniqueId;
 
    if( !furnitureLoops.ContainsKey( uid ) )
    {
      nFailures = 0;
 
      JtLoops loops = GetPlanViewBoundaryLoops(
        f, ref nFailures );
 
      if( 0 < nFailures )
      {
        Debug.Print( "{0}: {1} extrusion analyser failure{2}",
          Util.ElementDescription( f ), nFailures,
          Util.PluralSuffix( nFailures ) );
      }
      ListLoops( f, loops );
 
      if( 0 < loops.Count )
      {
        // Assume first loop is outer one
 
        furnitureLoops.Add( uid, loops[0] );
      }
    }
    furnitureInstances.Add(
      new JtPlacement2dInt( f ) );
  }

Retrieving the Boundary Loops

The boundary loop retrieval has not changed very much, although the following significant enhancements were made:

• Store the symbol loop in the original symbol definition coordinate system.
• Store the instance transformation data.
• Manage the dictionary of symbols and the instances referencing them.
• Save intermediate tessellated curve points, not just start and end point. This functionality can be toggled on and off by setting the Boolean _tessellate_curves switch.

The implementation is separated into two methods:

• AddLoops: add the plan view boundary loops from a given solid to the list of loops.
• GetPlanViewBoundaryLoops: Retrieve the plan view boundary loops from all solids of given element united together. If the element is a family instance, transform its loops from the instance placement coordinate system back to the symbol definition one.

Here is the implementation:

/// <summary>
/// Add all plan view boundary loops from 
/// given solid to the list of loops.
/// The creation application argument is used to
/// reverse the extrusion analyser output curves
/// in case they are badly oriented.
/// </summary>
/// <returns>Number of loops added</returns>
int AddLoops(
  Autodesk.Revit.Creation.Application creapp,
  JtLoops loops,
  GeometryObject obj,
  ref int nExtrusionAnalysisFailures )
{
  int nAdded = 0;
 
  Solid solid = obj as Solid;
 
  if( null != solid
    && 0 < solid.Faces.Size )
  {
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    ExtrusionAnalyzer extrusionAnalyzer = null;
 
    try
    {
      extrusionAnalyzer = ExtrusionAnalyzer.Create(
        solid, plane, XYZ.BasisZ );
    }
    catch( Autodesk.Revit.Exceptions
      .InvalidOperationException )
    {
      ++nExtrusionAnalysisFailures;
      return nAdded;
    }
 
    Face face = extrusionAnalyzer
      .GetExtrusionBase();
 
    foreach( EdgeArray a in face.EdgeLoops )
    {
      int nEdges = a.Size;
 
      List<Curve> curves
        = new List<Curve>( nEdges );
 
      XYZ p0 = null; // loop start point
      XYZ p; // edge start point
      XYZ q = null; // edge end point
 
      foreach( Edge e in a )
      {
        // This returns the curves already
        // correctly oriented:
 
        curve = e.AsCurveFollowingFace(
          face );
 
        if( _debug_output )
        {
          p = curve.get_EndPoint( 0 );
          q = curve.get_EndPoint( 1 );
          Debug.Print( "{0} --> {1} following face",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        curves.Add( curve );
      }
 
      q = null;
 
      JtLoop loop = new JtLoop( nEdges );
 
      foreach( Curve curve in curves )
      {
        p = curve.get_EndPoint( 0 );
 
        Debug.Assert( null == q
          || q.IsAlmostEqualTo( p, 1e-05 ),
          string.Format(
            "expected last endpoint to equal current start point, not distance {0}",
            (null == q ? 0 : p.DistanceTo( q ))  ) );
 
        q = curve.get_EndPoint( 1 );
 
        if( _debug_output )
        {
          Debug.Print( "{0} --> {1}",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        if( null == p0 )
        {
          p0 = p; // save loop start point
        }
 
        int n = -1;
 
        if( _tessellate_curves
          && _min_tessellation_curve_length_in_feet
            < q.DistanceTo( p ) )
        {
          IList<XYZ> pts = curve.Tessellate();
          n = pts.Count;
 
          Debug.Assert( 1 < n, "expected at least two points" );
          Debug.Assert( p.IsAlmostEqualTo( pts[0] ), "expected tessellation start equal curve start point" );
          Debug.Assert( q.IsAlmostEqualTo( pts[n-1] ), "expected tessellation end equal curve end point" );
 
          if( 2 == n )
          {
            n = -1; // this is a straight line
          }
          else
          {
            --n; // skip last point
 
            for( int i = 0; i < n; ++i )
            {
              loop.Add( new Point2dInt( pts[i] ) );
            }
          }
        }
 
        // If tessellation is disabled,
        // or curve is too short to tessellate,
        // or has only two tessellation points,
        // just add the start point:
 
        if( -1 == n )
        {
          loop.Add( new Point2dInt( p ) );
        }
      }
      Debug.Assert( q.IsAlmostEqualTo( p0, 1e-05 ),
        string.Format(
          "expected last endpoint to equal current start point, not distance {0}",
          p0.DistanceTo( q ) ) );
 
      loops.Add( loop );
 
      ++nAdded;
    }
  }
  return nAdded;
}

/// <summary>
/// Retrieve all plan view boundary loops from 
/// all solids of given element united together.
/// If the element is a family instance, transform
/// its loops from the instance placement 
/// coordinate system back to the symbol 
/// definition one.
/// </summary>
JtLoops GetPlanViewBoundaryLoops(
  Element e,
  ref int nFailures )
{
  Autodesk.Revit.Creation.Application creapp
    = e.Document.Application.Create;
 
  JtLoops loops = new JtLoops( 1 );
 
  Options opt = new Options();
 
  GeometryElement geo = e.get_Geometry( opt );
 
  if( null != geo )
  {
    Document doc = e.Document;
 
    if( e is FamilyInstance )
    {
      // Retrieve family instance geometry 
      // transformed back to symbol definition
      // coordinate space by inverting the 
      // family instance placement transformation
 
      LocationPoint lp = e.Location
        as LocationPoint;
 
      Transform t = Transform.get_Translation(
        -lp.Point );
 
      Transform r = Transform.get_Rotation(
        lp.Point, XYZ.BasisZ, -lp.Rotation );
 
      geo = geo.GetTransformed( t * r );
    }
 
    Solid union = null;
 
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    foreach( GeometryObject obj in geo )
    {
      Solid solid = obj as Solid;
 
      if( null != solid
        && 0 < solid.Faces.Size )
      {
        // Some solids, e.g. in the standard 
        // content 'Furniture Chair - Office' 
        // cause an extrusion analyser failure,
        // so skip adding those.
 
        try
        {
          ExtrusionAnalyzer extrusionAnalyzer
            = ExtrusionAnalyzer.Create(
              solid, plane, XYZ.BasisZ );
        }
        catch( Autodesk.Revit.Exceptions
          .InvalidOperationException )
        {
          solid = null;
          ++nFailures;
        }
 
        if( null != solid )
        {
          if( null == union )
          {
            union = solid;
          }
          else
          {
            union = BooleanOperationsUtils
              .ExecuteBooleanOperation( union, solid,
                BooleanOperationsType.Union );
          }
        }
      }
    }
    AddLoops( creapp, loops, union, ref nFailures );
  }
  return loops;
}

GeoSnoop Loop Display

I obviously had to update my GeoSnoop display to take the symbol loop dictionary lookup into account.

I invoke it passing in the room loops, symbol loops, and instance placements:

  GeoSnoop.DisplayLoops( revit_window,
    "Room and furniture", roomLoops,
    furnitureLoops, furnitureInstances );

The new implementation displays the instances at their respective location by transforming the referenced symbol geometry accordingly.

I make use of two transformations:

• Matrix transform: Transform from native loop coordinate system to target display coordinates.
• Matrix placement: Additional transformation from symbol definition to instance location for placing an individual instance.

It also takes the aspect ratio of the room to display into account and adjusts the window height to fit, based on the room bounding box aspect ratio:

/// <summary>
/// Display a collection of loops in a .NET form.
/// </summary>
class GeoSnoop
{
  /// <summary>
  /// Pen size.
  /// </summary>
  const int _pen_size = 1;
 
  /// <summary>
  /// Pen colour.
  /// </summary>
  static Color _pen_color = Color.Black;
 
  /// <summary>
  /// Margin around graphics.
  /// </summary>
  const int _margin = 10;
 
  /// <summary>
  /// Draw loops on graphics with the specified
  /// transform and graphics attributes.
  /// </summary>
  static void DrawLoopsOnGraphics(
    Graphics graphics,
    List<Point[]> loops,
    Matrix transform )
  {
    Pen pen = new Pen( _pen_color, _pen_size );
 
    foreach( Point[] loop in loops )
    {
      GraphicsPath path = new GraphicsPath();
 
      transform.TransformPoints( loop );
 
      path.AddLines( loop );
 
      graphics.DrawPath( pen, path );
    }
  }
 
  /// <summary>
  /// Display loops in a temporary form generated
  /// on the fly.
  /// </summary>
  /// <param name="owner">Owner window</param>
  /// <param name="caption">Form caption</param>
  /// <param name="loops">Boundary loops</param>
  public static void DisplayLoops(
    IWin32Window owner,
    string caption,
    JtLoops roomLoops,
    Dictionary<string, JtLoop> furnitureLoops,
    List<JtPlacement2dInt> furnitureInstances )
  {
    JtBoundingBox2dInt bb = roomLoops.BoundingBox;
 
    // Adjust target rectangle height to the 
    // displayee loop height.
 
    int width = 400;
    int height = (int) (width * bb.AspectRatio + 0.5);
 
    // Specify transformation target rectangle 
    // including a margin.
 
    int bottom = height - (_margin + _margin);
 
    Point[] parallelogramPoints = new Point[] {
      new Point( _margin, bottom ), // upper left
      new Point( width - _margin, bottom ), // upper right
      new Point( _margin, _margin ) // lower left
    };
 
    // Transform from native loop coordinate system
    // to target display coordinates.
 
    Matrix transform = new Matrix(
      bb.Rectangle, parallelogramPoints );
 
    Bitmap bmp = new Bitmap( width, height );
    Graphics graphics = Graphics.FromImage( bmp );
 
    graphics.Clear( System.Drawing.Color.White );
 
    DrawLoopsOnGraphics( graphics,
      roomLoops.GetGraphicsPathLines(), transform );
 
    List<Point[]> loops = new List<Point[]>( 1 );
    loops.Add( new Point[] { } );
 
    foreach( JtPlacement2dInt i in furnitureInstances )
    {
      Point2dInt v = i.Translation;
      Matrix placement = new Matrix();
      placement.Rotate(i.Rotation);
      placement.Translate(v.X, v.Y, MatrixOrder.Append);
      placement.Multiply( transform, MatrixOrder.Append );
      loops[0] = furnitureLoops[i.SymbolId]
        .GetGraphicsPathLines();
 
      DrawLoopsOnGraphics( graphics, loops, placement );
    }
 
    Form form = new Form();
    form.Text = caption;
    form.Size = new Size( width + 7, height + 13 );
    form.FormBorderStyle = FormBorderStyle
      .FixedToolWindow;
 
    PictureBox pb = new PictureBox();
    pb.Location = new System.Drawing.Point( 0, 0 );
    pb.Dock = System.Windows.Forms.DockStyle.Fill;
    pb.Size = bmp.Size;
    pb.Parent = form;
    pb.Image = bmp;
 
    form.ShowDialog( owner );
  }
}

Still very short and sweet, isn't it?

Here is the result of displaying a room from the advanced sample project provided with Revit:

Those eight straight lines in the corners are columns. I should eliminate those. We don't want to move those around indiscriminately on a mobile device anyway, or the whole house might come crashing down around us.

Caveats

Rudolf Honke wrote in a reaction to my plan described last time:

You say that you want to avoid redundant geometry data in your cloud project:

As you know, it is possible to modify the geometry of an individual family instance by cutting voids off it. The geometry of such an instance differs from other ones.

As far as I remember, modifying instance geometry this way has been possible since Revit 2012 or so; the API 2013 says:

"FamilyInstance.GetOriginalGeometry: Returns the original geometry of the instance, before the instance is modified by joins, cuts, coping, extensions, or other post-processing."

Thus, there are at least three groups of elements to be handled:

• Individual elements, such as walls – have individual geometry, cannot be reused
• Family instances which have not been modified – can be instantiated, geometry is reusable
• Family instances which are post-processed, resulting in individual geometry – not reusable

In this case, I am only handling furniture and equipment instances that I do not expect to be modified.

After all, the plan is to move them around in the room, so they have to be free of constraints for it to work.

Still, these considerations obviously have to be taken into account for other applications.

Download

To wrap this up for the moment, here is GeoSnoopSymbols.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

Next Steps

My next steps will be:

• Migrate this add-in from Revit 2013 to 2014.
• Implement server-side generated SVG code to display the room and furniture plan in CouchDB using Kanso.
• Implement editing of SVG on the mobile device and reflect changes back to CouchDB (I know how now).
• Implement Idling event handler and polling of CouchDB in the desktop add-in to reflect the changes back to the BIM in real-time.
• Implement an external application wrapper for the add-in providing four commands:
• Upload to cloud
• Refresh from cloud
• Subscribe to cloud
• Unsubscribe from cloud

I know exactly how to address all these points now, no exceptions left. Yay!

I look forward to hearing your comments and suggestions.

Setting up your ViewOrientation3D

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

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

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

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

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

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

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

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

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

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

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

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

I hope you find this useful.

Personally, I do indeed.

Many thanks to Mario for sharing!

GeoSnoop .NET Boundary Curve Loop Visualisation

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I explained how I use the ExtrusionAnalyzer to create a plan view boundary profile for the furniture and equipment family instances, sort and orient its output curves, and determine their bounding box for visualisation.

Today let's look at a simple loop visualisation implementation in a dynamically generated .NET form.

The components of interest are:

• Point2dInt – an integer-based 2D point
• JtLoop – a closed polygon boundary loop
• JtLoops – a list of boundary loops
• JtBoundingBox2dInt – a bounding box for 2D integer points
• GeoSnoop – display a collection of curves in a .NET form
• Validation of results – reality check
• Next steps – where to go from here
• Download – try this yourself at home

Point2dInt – an Integer-based 2D Point

I introduced this class in the initial discussion on retrieving plan view room boundary polygon loops.

The main idea is to have a robust lightweight data container for passing 2D point information back and forth between my Revit add-in, the cloud and mobile devices.

The later development motivated the addition of a couple of convenience methods since the first publication:

/// <summary>
/// An integer-based 2D point class.
/// </summary>
class Point2dInt : IComparable<Point2dInt>
{
  public int X { get; set; }
  public int Y { get; set; }
 
  const double _feet_to_mm = 25.4 * 12;
 
  static int ConvertFeetToMillimetres( double d )
  {
    return (int) ( _feet_to_mm * d + 0.5 );
  }
 
  /// <summary>
  /// Convert a 3D Revit XYZ to a 2D millimetre 
  /// integer point by discarding the Z coordinate
  /// and scaling from feet to mm.
  /// </summary>
  public Point2dInt( int x, int y )
  {
    X = x;
    Y = y;
  }
 
  /// <summary>
  /// Convert a 3D Revit XYZ to a 2D millimetre 
  /// integer point by discarding the Z coordinate
  /// and scaling from feet to mm.
  /// </summary>
  public Point2dInt( XYZ p )
  {
    X = ConvertFeetToMillimetres( p.X );
    Y = ConvertFeetToMillimetres( p.Y );
  }
 
  /// <summary>
  /// Comparison with another point, important
  /// for dictionary lookup support.
  /// </summary>
  public int CompareTo( Point2dInt a )
  {
    int d = X - a.X;
 
    if( 0 == d )
    {
      d = Y - a.Y;
    }
    return d;
  }
 
  /// <summary>
  /// Display as a string.
  /// </summary>
  public override string ToString()
  {
    return string.Format( "({0},{1})", X, Y );
  }
 
  /// <summary>
  /// Add two points, i.e. treat one of 
  /// them as a translation vector.
  /// </summary>
  public static Point2dInt operator+(
    Point2dInt a,
    Point2dInt b )
  {
    return new Point2dInt(
      a.X + b.X, a.Y + b.Y );
  }
}

JtLoop – a Closed Polygon Boundary Loop

This class consists of a simple list of 2D integer points representing a closed boundary loop.

When a new point is added to the collection, it is compared to the last and ignored if they evaluate equal. This automatically suppresses too small boundary segment fragments.

/// <summary>
/// A closed polygon boundary loop.
/// </summary>
class JtLoop : List<Point2dInt>
{
  public JtLoop( int capacity )
    : base( capacity )
  {
  }
 
  /// <summary>
  /// Display as a string.
  /// </summary>
  public override string ToString()
  {
    return string.Join( ", ", this );
  }
 
  /// <summary>
  /// Add another point to the collection.
  /// If the new point is identical to the last,
  /// ignore it. This will automatically suppress
  /// really small boundary segment fragments.
  /// </summary>
  public new void Add( Point2dInt p )
  {
    if( 0 == Count
      || 0 != p.CompareTo( this[Count - 1] ) )
    {
      base.Add( p );
    }
  }
}

JtLoops – a List of Boundary Loops

Each room produces a collection of loops, since it may include holes. For the furniture and equipment, I am expecting to manage just one external boundary contour loop each. On the other hand, for the furniture, this class enables me to easily collect all the individual furniture loops together into one single object.

The addition operator + is used to unite the room and furniture loops into a single container to pass to the visualisation method.

The conversion to a list of Point instances is used to feed the System.Drawing.Drawing2D.GraphicsPath class AddLines method to display the loops in a form.

/// <summary>
/// A list of boundary loops.
/// </summary>
class JtLoops : List<JtLoop>
{
  public JtLoops( int capacity )
    : base( capacity )
  {
  }
 
  /// <summary>
  /// Unite two collections of boundary 
  /// loops into one single one.
  /// </summary>
  public static JtLoops operator+( JtLoops a, JtLoops b )
  {
    int na = a.Count;
    int nb = b.Count;
    JtLoops sum = new JtLoops( na + nb );
    sum.AddRange( a );
    sum.AddRange( b );
    return sum;
  }
 
  /// <summary>
  /// Return suitable input for the .NET 
  /// GraphicsPath.AddLines method to display the 
  /// loops in a form. Note that a closing segment 
  /// to connect the last point back to the first
  /// is added.
  /// </summary>
  public List<Point[]> GetGraphicsPathLines()
  {
    int i, n;
 
    List<Point[]> loops
      = new List<Point[]>( Count );
 
    foreach( JtLoop jloop in this )
    {
      n = jloop.Count;
      Point[] loop = new Point[n + 1];
      i = 0;
      foreach( Point2dInt p in jloop )
      {
        loop[i++] = new Point( p.X, p.Y );
      }
      loop[i] = loop[0];
      loops.Add( loop );
    }
    return loops;
  }
}

JtBoundingBox2dInt – a Bounding Box for 2D Integer Points

I discussed the 2D integer-based bounding box implementation last week.

As you can see there, it already includes a handy constructor taking a collection of loops to return their entire bounding box.

I now added properties to return the aspect ratio and a System.Drawing.Rectangle to easily define the visualisation target rectangle and coordinate system transformation:

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

GeoSnoop – Display a Collection of Curves in a .NET Form

Now comes the exciting part: extracting the loop information from my own data structures, setting up an appropriate .NET form and infrastructure, and passing the information across with a minimum of fuss.

I had some fiddling to do to set this up optimally, I can tell you.

I am very satisfied with the end result, though:

/// <summary>
/// Display a collection of loops in a .NET form.
/// </summary>
class GeoSnoop
{
  /// <summary>
  /// Pen size.
  /// </summary>
  const int _pen_size = 1;
 
  /// <summary>
  /// Pen colour.
  /// </summary>
  static Color _pen_color = Color.Black;
 
  /// <summary>
  /// Margin around graphics.
  /// </summary>
  const int _margin = 10;
 
  /// <summary>
  /// Draw loops on graphics with the specified
  /// transform and graphics attributes.
  /// </summary>
  static void DrawLoopsOnGraphics(
    Graphics graphics,
    List<Point[]> loops,
    Matrix transform )
  {
    Pen pen = new Pen( _pen_color, _pen_size );
 
    graphics.Clear( System.Drawing.Color.White );
 
    foreach( Point[] loop in loops )
    {
      GraphicsPath path = new GraphicsPath();
 
      transform.TransformPoints( loop );
 
      path.AddLines( loop );
 
      graphics.DrawPath( pen, path );
    }
  }
 
  /// <summary>
  /// Display loops in a temporary form generated
  /// on the fly.
  /// </summary>
  /// <param name="owner">Owner window</param>
  /// <param name="caption">Form caption</param>
  /// <param name="loops">Boundary loops</param>
  public static void DisplayLoops(
    IWin32Window owner,
    string caption,
    JtLoops loops )
  {
    JtBoundingBox2dInt bb
      = new JtBoundingBox2dInt( loops );
 
    // Adjust target rectangle height to the 
    // displayee loop height.
 
    int width = 400;
    int height = (int) (width * bb.AspectRatio + 0.5);
 
    // Specify transformation target rectangle 
    // including a margin.
 
    int bottom = height - (_margin + _margin);
 
    Point[] parallelogramPoints = new Point[] {
      new Point( _margin, bottom ), // upper left
      new Point( width - _margin, bottom ), // upper right
      new Point( _margin, _margin ) // lower left
    };
 
    // Transform from native loop coordinate system
    // to target display coordinates.
 
    Matrix transform = new Matrix(
      bb.Rectangle, parallelogramPoints );
 
    Bitmap bmp = new Bitmap( width, height );
    Graphics gr = Graphics.FromImage( bmp );
 
    DrawLoopsOnGraphics( gr,
      loops.GetGraphicsPathLines(), transform );
 
    Form form = new Form();
    form.Text = caption;
    form.Size = new Size( width + 7, height + 13 );
    form.FormBorderStyle = FormBorderStyle
      .FixedToolWindow;
 
    PictureBox pb = new PictureBox();
    pb.Location = new System.Drawing.Point( 0, 0 );
    pb.Dock = System.Windows.Forms.DockStyle.Fill;
    pb.Size = bmp.Size;
    pb.Parent = form;
    pb.Image = bmp;
 
    form.ShowDialog( owner );
  }
}

I bet you expected more than this, didn't you?

To quote Antoine de Saint-Exupéry: Il semble que la perfection soit atteinte non quand il n'y a plus rien à ajouter, mais quand il n'y a plus rien à retrancher (Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away).

Validation of Results

Actually, this is the really exciting part.

I mentioned that I was worried for a moment about the large number of loop vertices in the plan view of the desk. I was initially hoping for only four vertices, to represent a simple rectangle. After all, the plan view of a desk and chair looks like this in Revit:

In my visualisation, the same desk and chair loops are displayed like this instead:

The good news is:

• We have indeed produced closed loops.
• Their shape and location is correct.

Where do all those bumps come from, though?

The answer is easy and completely reassuring: the bumps are the desk drawer handles that stick out a little bit beyond the desktop surface. Looking at a 3D view in Revit from the top, the desk looks like this:

My results reproduce this exactly.

Looking at the chairs, I mentioned that some of the chair solids cause extrusion analyser failures, and I skip those. To be precise, I have two failures on each chair.

Comparing the chair 3D view from the top in Revit with my results shows that the armrests are the components causing trouble:

The rest matches up perfectly, once again validifying my approach. The bumps on the sides of the chairs are the armrest supports.

I also cleaned up the form generation as much as possible. Resizing, zooming and panning are not supported. The form aspect ratio is adjusted up front to adapt to the loops to display:

Once again, here is the same view in Revit:

Next Steps

Actually, the next steps are the really, really exciting part.

Now I can turn to the implementation of my data repository and the task of hosting it in the cloud.

I already discussed my tentative plans and high hopes for this. Let's see if I can live up to them.

Adventure! Who knows what will come, and where this will lead?

Download

To wrap this up for the moment, here is GeoSnoopLoops.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

Curve Following Face and Bounding Box Implementation

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

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

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

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

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

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

Use Curve Following Face

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

Now Bettina Zimmermann provided another idea:

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

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

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

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

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

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

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

Thank you very much Bettina for this valuable suggestion!

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

Bounding Box Determination for XYZ Points

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

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

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

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

  class JtBoundingBoxXyz : Tuple<XYZ, XYZ>

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

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

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

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

Bounding Box Determination for 2D Integer Points

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

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

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

Overview of Sweep Sample Code and Issue Resolutions

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

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

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

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

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

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

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

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

I hope this helps. Good luck!

Extrusion Analyser and Plan View Boundaries

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

I did not yet display the code driving the extrusion analyser, though, or discuss my experiences with that.

Those are the topics of today's post:

• Using the ExtrusionAnalyzer class
• Handling ExtrusionAnalyzer failures
• Testing the ExporterIFCUtils ValidateCurveLoops method
• First conclusion and capitulation
• Reimplementation with a Boolean union
• Conclusion, next steps and download
• New Revit Add-ins

Using the ExtrusionAnalyzer Class

Using the extrusion analyser is simple:

1. Retrieve and traverse the element geometry:

/// <summary>
/// Retrieve all plan view boundary loops from 
/// all solids of given element.
/// </summary>
JtLoops GetPlanViewBoundaryLoopsMultiple(
  Element e,
  ref int nFailures )
{
  Autodesk.Revit.Creation.Application creapp
    = e.Document.Application.Create;
 
  JtLoops loops = new JtLoops( 1 );
 
  Options opt = new Options();
 
  GeometryElement geo = e.get_Geometry( opt );
 
  if( null != geo )
  {
    Document doc = e.Document;
 
    if( e is FamilyInstance )
    {
      geo = geo.GetTransformed(
        Transform.Identity );
    }
 
    foreach( GeometryObject obj in geo )
    {
      AddLoops( creapp, loops, obj, ref nFailures );
    }
  }
  return loops;
}

2. For each solid, instantiate an ExtrusionAnalyzer, retrieve and process its resulting output curves:

/// <summary>
/// Add all plan view boundary loops from 
/// given solid to the list of loops.
/// The creation application argument is used to
/// reverse the extrusion analyser output curves
/// in case they are badly oriented.
/// </summary>
/// <returns>Number of loops added</returns>
int AddLoops(
  Autodesk.Revit.Creation.Application creapp,
  JtLoops loops,
  GeometryObject obj )
{
  int nAdded = 0;
 
  Solid solid = obj as Solid;
 
  if( null != solid
    && 0 < solid.Faces.Size )
  {
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    ExtrusionAnalyzer extrusionAnalyzer = null;
 
    extrusionAnalyzer = ExtrusionAnalyzer.Create(
      solid, plane, XYZ.BasisZ );
 
    Face face = extrusionAnalyzer
      .GetExtrusionBase();
 
    foreach( EdgeArray a in face.EdgeLoops )
    {
      int nEdges = a.Size;
 
      List<Curve> curves
        = new List<Curve>( nEdges );
 
      XYZ p0 = null; // loop start point
      XYZ p; // edge start point
      XYZ q = null; // edge end point
 
      foreach( Edge e in a )
      {
        Curve curve = e.AsCurve();
 
        if( _debug_output )
        {
          p = curve.get_EndPoint( 0 );
          q = curve.get_EndPoint( 1 );
          Debug.Print( "{0} --> {1}",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        curves.Add( curve );
      }
 
      CurveUtils.SortCurvesContiguous(
        creapp, curves, _debug_output );
 
      q = null;
 
      JtLoop loop = new JtLoop( nEdges );
 
      foreach( Curve curve in curves )
      {
        // Todo: handle non-linear curve.
        // Especially: if two long lines have a 
        // short arc in between them, skip the arc
        // and extend both lines.
 
        p = curve.get_EndPoint( 0 );
 
        loop.Add( new Point2dInt( p ) );
 
        Debug.Assert( null == q
          || q.IsAlmostEqualTo( p, 1e-05 ),
          string.Format(
            "expected last endpoint to equal current start point, not distance {0}",
            (null == q ? 0 : p.DistanceTo( q ))  ) );
 
        q = curve.get_EndPoint( 1 );
 
        if( _debug_output )
        {
          Debug.Print( "{0} --> {1}",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        if( null == p0 )
        {
          p0 = p; // save loop start point
        }
      }
      Debug.Assert( q.IsAlmostEqualTo( p0, 1e-05 ),
        string.Format(
          "expected last endpoint to equal current start point, not distance {0}",
          p0.DistanceTo( q ) ) );
 
      loops.Add( loop );
 
      ++nAdded;
    }
  }
  return nAdded;
}

Handling ExtrusionAnalyzer Failures

The desk solids are processed perfectly well by the extrusion analyser, but two of the chair solids produce failures. This is the standard Revit content 'Furniture Chair - Office' returning invalid solids.

Since I don't (yet?) know how to detect beforehand whether a solid will cause a failure or not, the only option I see is to encapsulate the extrusion analyser implementation in an exception handler. I also added code to report how many failures occur:

  ExtrusionAnalyzer extrusionAnalyzer = null;
 
  try
  {
    extrusionAnalyzer = ExtrusionAnalyzer.Create(
      solid, plane, XYZ.BasisZ );
  }
  catch( Autodesk.Revit.Exceptions
    .InvalidOperationException )
  {
    ++nExtrusionAnalysisFailures;
    return nAdded;
  }
 
  Face face = extrusionAnalyzer
    .GetExtrusionBase();

Testing the ExporterIFCUtils ValidateCurveLoops Method

Rudolf Honke added a very valid suggestion to my SortCurvesContiguous implementation: You may have a look at ExporterIFCUtils.ValidateCurveLoops method. RevitApi.chm says: "Does validity checks on a list of curve loops to ensure that they are all co-planar, closed, and properly oriented." I have never tested this method, but perhaps it prevents you from inventing the wheel another time...

I like that suggestion a lot and am interested to find out how useful this method might be.

It takes a list of curve loops and returns a new list of curve loops "properly oriented, if possible. If not, the return contains no loops."

I added code to test this method, passing in to it the output produced by the extrusion analyser:

  // Test ValidateCurveLoops
 
  CurveLoop loopIfc = new CurveLoop();
 
  foreach( Edge e in a )
  {
    Curve curve = e.AsCurve();
 
    if( _debug_output )
    {
      p = curve.get_EndPoint( 0 );
      q = curve.get_EndPoint( 1 );
      Debug.Print( "{0} --> {1}",
        Util.PointString( p ),
        Util.PointString( q ) );
    }
 
    curves.Add( curve );
 
    // Throws an exception saying "This curve 
    // will make the loop not contiguous. 
    // Parameter name: pCurve"
 
    loopIfc.Append( curve );
  }
 
  // We never reach this point:
 
  List<CurveLoop> loopsIfc
    = new List<CurveLoop>( 1 );
 
  loopsIfc.Add( loopIfc );
 
  IList<CurveLoop> loopsIfcOut = ExporterIFCUtils
    .ValidateCurveLoops( loopsIfc, XYZ.BasisZ );

Unfortunately, the CurveLoop Append method throws an exception saying "This curve will make the loop not contiguous. Parameter name: pCurve".

It obviously expects contiguous curves to be passed in and can therefore not be used to re-orient curves if they are oriented the wrong way.

So much for that suggestion. You got my hopes up there, Rudolf, but no luck this time.

First Conclusion and Capitulation

My first (erroneous) conclusion for the extrusion analyser was simple: the output I receive for a plan view is much too complex for my use.

I was expecting it to return the simplest possible contour to represent the shadow cast by the solid passed in. The results include lots of extraneous loops that do not contribute to the shadow of the object.

Oops.

Since I am passing in the multiple solids from the desk and the chair to the extrusion analyser one by one, individually, it is obviously returning a plan view boundary outline for each one of the solids, individually, as well.

At first glance I thought that this result is much too complicated for me to handle, since all I want is one single boundary for the whole object.

For a moment, I gave up on the whole idea of using the extrusion analyser and decided to switch to a 2D plan view instead, and ask for the view-specific family instance representation in that view. For the desk, that would simply give me the desired rectangular outline.

Capitulation.

Then I switched on my brain for a second again and realised the obvious fact that individual solids will generate individual outlines.

I decided to give the extrusion analyser another go, unite all the solids into one single one, then pass that in to a single call of the extrusion analyser.

Reimplementation with a Boolean Union

'Gesagt, getan', as the Germans say, 'No sooner said than done', 'a word and a blow'.

I united all the desk solids, passed the resulting union in to the extrusion analyser, and it produces a single closed loop.

I united all the chair solids, passed the resulting union in to the extrusion analyser, and it produces one single failure.

Oh no!

The individual chair solids causing a failure when passed in individually also cause a failure when united with the unproblematic ones.

Next idea:

• Extract the family instance solids from the geometry one by one.
• Test each solid by passing it in to the extrusion analyser on its own.
• If it causes a failure, discard it.
• If it does not, unite it with the others.
• Pass in the union of all non-failing solids to the extrusion analyser.
• Retrieve the resulting curves.
• Sort and re-orient the curves to form a contiguous closed loop.
• Convert the closed loop data to my integer-based 2D format.

Here is the final code for achieving this:

/// <summary>
/// Retrieve all plan view boundary loops from 
/// all solids of given element united together.
/// </summary>
JtLoops GetPlanViewBoundaryLoops(
  Element e,
  ref int nFailures )
{
  Autodesk.Revit.Creation.Application creapp
    = e.Document.Application.Create;
 
  JtLoops loops = new JtLoops( 1 );
 
  Options opt = new Options();
 
  GeometryElement geo = e.get_Geometry( opt );
 
  if( null != geo )
  {
    Document doc = e.Document;
 
    if( e is FamilyInstance )
    {
      geo = geo.GetTransformed(
        Transform.Identity );
    }
 
    Solid union = null;
 
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    foreach( GeometryObject obj in geo )
    {
      Solid solid = obj as Solid;
 
      if( null != solid
        && 0 < solid.Faces.Size )
      {
        // Some solids, e.g. in the standard 
        // content 'Furniture Chair - Office' 
        // cause an extrusion analyser failure,
        // so skip adding those.
 
        try
        {
          ExtrusionAnalyzer extrusionAnalyzer
            = ExtrusionAnalyzer.Create(
              solid, plane, XYZ.BasisZ );
        }
        catch( Autodesk.Revit.Exceptions
          .InvalidOperationException )
        {
          solid = null;
          ++nFailures;
        }
 
        if( null != solid )
        {
          if( null == union )
          {
            union = solid;
          }
          else
          {
            union = BooleanOperationsUtils
              .ExecuteBooleanOperation( union, solid,
                BooleanOperationsType.Union );
          }
        }
      }
    }
    AddLoops( creapp, loops, union, ref nFailures );
  }
  return loops;
}

This is the current result for my simple sample model (copy the text to see the truncated lines in full):

Room Rooms <212639 Room 1> has 2 loops:
  0: (2753,3087), (-4446,3087), (-4446,587), (-746,587), (-746,-1212), (2753,-1212)
  1: (298,-112), (298,587), (1698,587), (1698,-112)
FamilyInstance Furniture Desk <212646 1525 x 762mm> has 1 loop:
  0: (664,2561), (664,1761), (2227,1761), (2227,2561), (2056,2561), (2056,2580), (1954,2580), (1954,2561), (937,2561), (937,2580), (836,2580), (836,2561)
FamilyInstance Furniture Desk <212801 1525 x 762mm> has 1 loop:
  0: (-1200,2561), (-1200,1761), (362,1761), (362,2561), (191,2561), (191,2580), (89,2580), (89,2561), (-927,2561), (-927,2580), (-1028,2580), (-1028,2561)
FamilyInstance Furniture Desk <213000 1525 x 762mm> has 1 loop:
  0: (-4135,2561), (-4135,1761), (-2572,1761), (-2572,2561), (-2743,2561), (-2743,2580), (-2845,2580), (-2845,2561), (-3862,2561), (-3862,2580), (-3963,2580), (-3963,2561)
FamilyInstance Furniture Chair - Office <214027 Office Chair>: 2 extrusion analyser failures
FamilyInstance Furniture Chair - Office <214027 Office Chair> has 1 loop:
  0: (-3581,1142), (-3581,1162), (-3561,1162), (-3561,1502), (-3581,1502), (-3581,1542), (-3561,1542), (-3561,1577), (-3021,1577), (-3021,1542), (-3001,1542), (-3001,1502), (-3021,1502), (-3021,1162), (-3001,1162), (-3001,1142), (-3021,1142), (-3021,1108), (-3561,1108), (-3561,1142)
FamilyInstance Furniture Chair - Office <214138 Office Chair>: 2 extrusion analyser failures
FamilyInstance Furniture Chair - Office <214138 Office Chair> has 1 loop:
  0: (-636,1142), (-636,1162), (-616,1162), (-616,1502), (-636,1502), (-636,1542), (-616,1542), (-616,1577), (-76,1577), (-76,1542), (-56,1542), (-56,1502), (-76,1502), (-76,1162), (-56,1162), (-56,1142), (-76,1142), (-76,1108), (-616,1108), (-616,1142)
FamilyInstance Furniture Chair - Office <214409 Office Chair>: 2 extrusion analyser failures
FamilyInstance Furniture Chair - Office <214409 Office Chair> has 1 loop:
  0: (1263,1142), (1263,1162), (1283,1162), (1283,1502), (1263,1502), (1263,1542), (1283,1542), (1283,1577), (1823,1577), (1823,1542), (1843,1542), (1843,1502), (1823,1502), (1823,1162), (1843,1162), (1843,1142), (1823,1142), (1823,1108), (1283,1108), (1283,1142)

I have not really checked the validity of these loops yet.

The chairs have arcs in them, so maybe they have to be as complex as they appear.

The desk should actually be just one single simple rectangle, so maybe there is a possibility to clean up its loop, e.g. reduce the 12 vertices to just four, e.g. by identifying collinear segments or something.

I'll look at that in more detail anon.

As you can see, this is all very experimental work in progress.

I hope you can get some use out of it anyway, and am excited to see where this will lead me.

Conclusion, Next Steps and Download

It works so far, and I will still have hope of using this for my final project implementation.

The next step is to test the validity of the loops I retrieve. As said, the end goal is:

• Upload the boundary loop and other data to the cloud.
• Visualise and manipulate the loops in the room layout editor.

Alternatively, I could first implement a visualisation tool in .NET for local use and testing. I have had that on my list for a long time anyway.

Anyway, here is GetFurnitureLoops.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

New Revit Add-ins

Before closing, here are some new Revit add-ins pointed out by developers that have been active here on the blog:

Israel Rodriguez of icubY released his mYbox add-in providing an easy way to integrate families that are on our portal directly inside Revit, AutoCAD and SketchUp, and includes a WPF client using the Revit API to instantiate the families (video). The content is mainly in Brazilian Portuguese.

Fernando Malard of ofcdesk points out his ofctools, providing advanced maintenance commands to optimise and streamline work, e.g. creating, editing or deleting large numbers of elements.

Sort and Orient Curves to Form a Contiguous Loop

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I need to determine the boundary loop polygons to represent the furniture and equipment family instances for manipulation on the mobile device.

To display a polygon using SVG in the mobile device browser, I obviously need a set of contiguous and sorted curve elements forming a closed loop.

I mentioned using the Revit API ExtrusionAnalyzer class to determine the plan view boundary outline for the family instances. On testing that approach, I discovered that the results it returns are unsorted.

For instance, I analysed the ExtrusionAnalyzer output for the standard Revit furniture content 'Desk 1525 x 762mm'. In plan view, it can appear like this:

The desk includes lots of internal geometry that is not visible in plan view:

As a result, the information returned by the ExtrusionAnalyzer is much more complex than the simple rectangle one might expect. In fact, it returns ten separate closed loops, and the first one consists of eight curves.

To check whether they are contiguous and correctly sorted, here is a list of their end points:

  (2.74,8.38,0) --> (2.74,8.46,0)
  (2.74,8.38,0) --> (2.76,8.38,0)
  (2.76,8.38,0) --> (2.76,8.44,0)
  (2.76,8.44,0) --> (3.05,8.44,0)
  (3.05,8.44,0) --> (3.05,8.38,0)
  (3.05,8.38,0) --> (3.08,8.38,0)
  (3.08,8.46,0) --> (3.08,8.38,0)
  (2.74,8.46,0) --> (3.08,8.46,0)

You can see quite easily that they are not contiguous. For instance, the end point at (2.74,8.46) of the first curve equals the start point of the last.

If you look more carefully still, you will notice that some of the curves require reversing to connect to their neighbours.

These observations and considerations led to the implementation of the following curve sorting and orientation method.

Its end point matching comparison relies on the standard Revit precision, which is around one sixteenth of an inch. Since the built-in Revit database length unit is feet, I define the following fuzz factor for that:

  const double _inch = 1.0 / 12.0;
  const double _sixteenth = _inch / 16.0;

Further, the curve reversal is implemented by creating a completely new curve. Therefore, the creation application has to be provided for generating these:

/// <summary>
/// Create a new curve with the same 
/// geometry in the reverse direction.
/// </summary>
/// <param name="orig">The original curve.</param>
/// <returns>The reversed curve.</returns>
/// <throws cref="NotImplementedException">If the 
/// curve type is not supported by this utility.</throws>
static Curve CreateReversedCurve(
  Autodesk.Revit.Creation.Application creapp,
  Curve orig )
{
  if( !IsSupported( orig ) )
  {
    throw new NotImplementedException(
      "CreateReversedCurve for type "
      + orig.GetType().Name );
  }
 
  if( orig is Line )
  {
    return creapp.NewLineBound(
      orig.GetEndPoint( 1 ),
      orig.GetEndPoint( 0 ) );
  }
  else if( orig is Arc )
  {
    return creapp.NewArc( orig.GetEndPoint( 1 ),
      orig.GetEndPoint( 0 ),
      orig.Evaluate( 0.5, true ) );
  }
  else
  {
    throw new Exception(
      "CreateReversedCurve - Unreachable" );
  }
}

With this support in hand, we can go ahead and implement the SortCurvesContiguous method:

/// <summary>
/// Sort a list of curves to make them correctly 
/// ordered and oriented to form a closed loop.
/// </summary>
public static void SortCurvesContiguous(
  Autodesk.Revit.Creation.Application creapp,
  IList<Curve> curves,
  bool debug_output )
{
  int n = curves.Count;
 
  // Walk through each curve (after the first) 
  // to match up the curves in order
 
  for( int i = 0; i < n; ++i )
  {
    Curve curve = curves[i];
    XYZ endPoint = curve.GetEndPoint( 1 );
 
    if( debug_output )
    {
      Debug.Print( "{0} endPoint {1}", i,
        Util.PointString( endPoint ) );
    }
 
    XYZ p;
 
    // Find curve with start point = end point
 
    bool found = (i + 1 >= n);
 
    for( int j = i + 1; j < n; ++j )
    {
      p = curves[j].GetEndPoint( 0 );
 
      // If there is a match end->start, 
      // this is the next curve
 
      if( _sixteenth > p.DistanceTo( endPoint ) )
      {
        if( debug_output )
        {
          Debug.Print(
            "{0} start point, swap with {1}",
            j, i + 1 );
        }
 
        if( i + 1 != j )
        {
          Curve tmp = curves[i + 1];
          curves[i + 1] = curves[j];
          curves[j] = tmp;
        }
        found = true;
        break;
      }
 
      p = curves[j].GetEndPoint( 1 );
 
      // If there is a match end->end, 
      // reverse the next curve
 
      if( _sixteenth > p.DistanceTo( endPoint ) )
      {
        if( i + 1 == j )
        {
          if( debug_output )
          {
            Debug.Print(
              "{0} end point, reverse {1}",
              j, i + 1 );
          }
 
          curves[i + 1] = CreateReversedCurve(
            creapp, curves[j] );
        }
        else
        {
          if( debug_output )
          {
            Debug.Print(
              "{0} end point, swap with reverse {1}",
              j, i + 1 );
          }
 
          Curve tmp = curves[i + 1];
          curves[i + 1] = CreateReversedCurve(
            creapp, curves[j] );
          curves[j] = tmp;
        }
        found = true;
        break;
      }
    }
    if( !found )
    {
      throw new Exception( "SortCurvesContiguous:"
        + " non-contiguous input curves" );
    }
  }
}

This is obviously not the most effective sorting algorithm in the world, but it should do for the hopefully simple cases I expect to encounter.

This method includes an option for verbose logging to the Visual Studio debug output window. This is what it produces for the unsorted list of input points provided above:

  0 endPoint (2.74,8.46,0)
  7 start point, swap with 1
  1 endPoint (3.08,8.46,0)
  6 start point, swap with 2
  2 endPoint (3.08,8.38,0)
  5 end point, swap with reverse 3
  3 endPoint (3.05,8.38,0)
  4 end point, reverse 4
  4 endPoint (3.05,8.44,0)
  5 end point, reverse 5
  5 endPoint (2.76,8.44,0)
  6 end point, reverse 6
  6 endPoint (2.76,8.38,0)
  7 end point, reverse 7
  7 endPoint (2.74,8.38,0)

The complete output for the entire desk looks like this after sorting and rearranging all ten loops using the SortCurvesContiguous method and converting the results from Revit XYZ coordinates to my 2D integer-based loop representation in millimetres:

FamilyInstance Furniture Desk <212646 1525 x 762mm> has 10 loops:
  0: (836,2555), (836,2580), (937,2580), (937,2555), (931,2555), (931,2574), (842,2574), (842,2555)
  1: (1954,2580), (1954,2555), (1961,2555), (1961,2574), (2050,2574), (2050,2555), (2056,2555), (2056,2580)
  2: (683,2542), (683,1780), (2208,1780), (2208,2542), (1802,2542), (1802,1831), (1090,1831), (1090,2542)
  3: (664,2561), (664,1761), (2227,1761), (2227,2561)
  4: (683,2440), (785,2440), (785,2542), (683,2542)
  5: (785,1780), (785,1882), (683,1882), (683,1780)
  6: (2107,1882), (2107,1780), (2208,1780), (2208,1882)
  7: (2107,2542), (2107,2440), (2208,2440), (2208,2542)
  8: (702,2542), (702,2555), (1071,2555), (1071,2542)
  9: (1821,2542), (1821,2555), (2189,2555), (2189,2542)

I hope you can make good use of this method in your own add-ins as well.

Happy Easter!

Revit 2014 API and Plan View Room Boundary Loops

I am continuing the research and development for my cloud-based round-trip 2D Revit model editing project.

At the same time, Revit 2014 has been announced, and I am sure you are eager to hear more about that, especially from the API point of view, so let's have a look at that first.

The Revit 2014 API

It is impossible to cover everything, and I have to start somewhere.

Here are a couple of highlights:

• API access to the project browser and selected elements; API commands and macros are enabled.
• Copy and paste API supports copy within or between documents including view-specific elements.
• Full API support for the new non-rectangular crop regions.
• Schedule API now provides formatting control and read-write access to individual data items.
• Command API enables programmatic command launch including built-in Revit, external add-in and macro.
• Add-in API supports mid-session loading and execution.
• Displaced elements API enables exploded views.
• Join geometry API to create or remove a Boolean join and control join order.
• FreeForm element API enables modification of solid geometry imported from e.g. DWG or SAT.
• Site API enables editing of topography surface points and supports sub-regions.
• MEP calculations are moved to external services and can be replaced by add-ins.
• Structural reinforcement and rebar enhancements.
• Enhanced document open, save and worksharing API.
• Linked model API supports loading, unloading, path manipulation, link identification and creation.
• Linked model interaction enables tag creation for linked rooms, linked element selection, geometric reference conversion, etc.
• Import DXF markup, import and link SAT and SketchUp.
• Export to NavisWorks via add-in, access DWG, IFC and DGN layer, linetype, lineweight, font and pattern tables.
• Direct API access to rendering output pipeline including all geometry and material properties.
• Macro API provides support for Python and Ruby development plus List, create, delete and execute modules, macros and security settings.

How does that sound?

Rather a lot of new stuff, isn't there?

Rather a lot of really exciting new stuff, isn't there?

Joe Ye describes a few of these API features in a little more detail on the AEC DevBlog.

To round this off, here are the complete materials from the Revit 2014 DevDays presentations:

• Presentation
• Recording
• Sample code

We will have all the time in the world to explore this in more detail anon.

The material provided above should keep you occupied over the Easter weekend, however :-)

Enjoy!

Retrieving Plan View Room Boundary Polygon Loops

Returning to the cloud-based 2D model editing project, one of the first required components is an add-in that determines and uploads the room, furniture and equipment family instance boundary polygons to some globally accessible data repository for a simplified 2D plan view rendering on a mobile device.

As a first step in that direction, I revamped my code to retrieve and graphically display area boundary loops and combined it with the integer-based point class that I implemented for the OBJ model exporter.

The task I want to achieve for the first part of this first step is to retrieve the room boundary and store the 2D loops in a cloud-based data repository.

Since Revit does not support precision below one sixteenth of an inch, I might as well approximate all my data to something in that region.

For performance and efficiency reasons, it is also useful to move my calculations from floating point double numbers to integers.

Since I want to display my model on a mobile device with a limited resolution using SVG, integers also seem pretty appropriate.

Very handily, a millimetre is just a little bit less than a sixteenth of an inch.

That leads me to define the following integer-based 2D point class:

/// <summary>
/// An integer-based 2D point class.
/// </summary>
class Point2dInt : IComparable<Point2dInt>
{
  public int X { get; set; }
  public int Y { get; set; }
 
  const double _feet_to_mm = 25.4 * 12;
 
  static int ConvertFeetToMillimetres( double d )
  {
    return (int) ( _feet_to_mm * d + 0.5 );
  }
 
  /// <summary>
  /// Convert a 3D Revit XYZ to a 2D millimetre 
  /// integer point by discarding the Z coordinate
  /// and scaling from feet to mm.
  /// </summary>
  public Point2dInt( XYZ p )
  {
    X = ConvertFeetToMillimetres( p.X );
    Y = ConvertFeetToMillimetres( p.Y );
  }
 
  public int CompareTo( Point2dInt a )
  {
    int d = X - a.X;
 
    if( 0 == d )
    {
      d = Y - a.Y;
    }
    return d;
  }
 
  public override string ToString()
  {
    return string.Format( "({0},{1})", X, Y );
  }
}

A room boundary may include several loops, for instance if a room surrounds some other space such as an elevator, i.e. its outer boundary loop contains some interior loops representing 'holes'.

Therefore, the room GetBoundarySegments method returns a list of loops, and each loop as a list of boundary segments:

  IList<IList<BoundarySegment>> loops = room.
    GetBoundarySegments( opt );

I therefore define my own integer-based 2D loop and list of loops classes like this:

  class JtLoop : List<Point2dInt>
  {
    public JtLoop( int capacity )
      : base( capacity )
    {
    }
 
    public override string ToString()
    {
      return string.Join( ", ", this );
    }
  }
 
  class JtLoops : List<JtLoop>
  {
    public JtLoops( int capacity )
      : base( capacity )
    {
    }
  }

The code to retrieve the boundary segments and convert them to my own representation can be implemented as follows:

/// <summary>
/// Retrieve the room plan view boundary 
/// polygon loops and convert to 2D integer-based.
/// For optimisation and consistency reasons, 
/// convert all coordinates to integer values in
/// millimetres. Revit precision is limited to 
/// 1/16 of an inch, which is abaut 1.2 mm, anyway.
/// </summary>
JtLoops GetRoomLoops( Room room )
{
  SpatialElementBoundaryOptions opt
    = new SpatialElementBoundaryOptions();
 
  opt.SpatialElementBoundaryLocation =
    SpatialElementBoundaryLocation.Center; // loops closed
    //SpatialElementBoundaryLocation.Finish; // loops not closed
 
  IList<IList<BoundarySegment>> loops = room.
    GetBoundarySegments( opt );
 
  int nLoops = loops.Count;
 
  JtLoops jtloops = new JtLoops( nLoops );
 
  foreach( IList<BoundarySegment> loop in loops )
  {
    int nSegments = loop.Count;
 
    JtLoop jtloop = new JtLoop( nSegments );
 
    XYZ p0 = null; // loop start point
    XYZ p; // segment start point
    XYZ q = null; // segment end point
 
    foreach( BoundarySegment seg in loop )
    {
      p = seg.Curve.get_EndPoint( 0 );
 
      jtloop.Add( new Point2dInt( p ) );
 
      Debug.Assert( null == q || q.IsAlmostEqualTo( p ),
        "expected last endpoint to equal current start point" );
 
      q = seg.Curve.get_EndPoint( 1 );
 
      Debug.Print( "{0} --> {1}",
        Util.PointString( p.ToUv() ),
        Util.PointString( q.ToUv() ) );
 
      if( null == p0 )
      {
        p0 = p; // save loop start point
      }
    }
    Debug.Assert( q.IsAlmostEqualTo( p0 ),
      "expected last endpoint to equal loop start point" );
 
    jtloops.Add( jtloop );
  }
  return jtloops;
}

My external command mainline Execute method driving this method also implements some fancy pre- and post-selection support and reporting code listing the contents of my 2D integer-based loops in the Visual Studio debug output window:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  if( null == doc )
  {
    ErrorMsg( "Please run this command in a valid"
      + " Revit project document." );
    return Result.Failed;
  }
 
  // Iterate over all pre-selected rooms
 
  List<ElementId> ids = null;
 
  Selection sel = uidoc.Selection;
 
  if( 0 < sel.Elements.Size )
  {
    foreach( Element e in sel.Elements )
    {
      if( !( e is Room ) )
      {
        ErrorMsg( "Please pre-select only room"
          + " elements before running this command." );
        return Result.Failed;
      }
 
      if( null == ids )
      {
        ids = new List<ElementId>( 1 );
      }
 
      ids.Add( e.Id );
    }
  }
 
  // If no rooms were pre-selected, 
  // prompt for post-selection
 
  if( null == ids )
  {
    IList<Reference> refs = null;
 
    try
    {
      refs = sel.PickObjects( ObjectType.Element,
        new RoomSelectionFilter(),
        "Please select rooms." );
    }
    catch( Autodesk.Revit.Exceptions
      .OperationCanceledException )
    {
      return Result.Cancelled;
    }
    ids = new List<ElementId>(
      refs.Select<Reference, ElementId>(
        r => r.ElementId ) );
  }
 
  foreach( ElementId id in ids )
  {
    Element e = doc.GetElement( id );
 
    Debug.Assert( e is Room,
      "expected parts only" );
 
    JtLoops roomLoops = GetRoomLoops( e as Room );
 
    int nLoops = roomLoops.Count;
 
    Debug.Print( "{0} has {1} loop{2}{3}",
      Util.ElementDescription( e ), nLoops,
      Util.PluralSuffix( nLoops ),
      Util.DotOrColon( nLoops ) );
 
    int i = 0;
 
    foreach( JtLoop loop in roomLoops )
    {
      Debug.Print( "  {0}: {1}", i++, loop.ToString() );
    }
  }
  return Result.Succeeded;
}

I tested this on a simple sample room with one hole:

The original start and end points of the boundary segments for this room are reported as follows:

  (9.03,10.13,0) --> (-14.59,10.13,0)
  (-14.59,10.13,0) --> (-14.59,1.93,0)
  (-14.59,1.93,0) --> (-2.45,1.93,0)
  (-2.45,1.93,0) --> (-2.45,-3.98,0)
  (-2.45,-3.98,0) --> (9.03,-3.98,0)
  (9.03,-3.98,0) --> (9.03,10.13,0)
  (0.98,-0.37,0) --> (0.98,1.93,0)
  (0.98,1.93,0) --> (5.57,1.93,0)
  (5.57,1.93,0) --> (5.57,-0.37,0)
  (5.57,-0.37,0) --> (0.98,-0.37,0)

Converting these to my 2D integer-based loop classes and listing those generates the following debug output:

  Room Rooms <212639 Room 1> has 2 loops:
    0: (2753,3087), (-4446,3087), (-4446,587),
      (-746,587), (-746,-1212), (2753,-1212)
    1: (298,-112), (298,587), (1698,587), (1698,-112)

So far, so good.

As far as I can tell, all systems go.

My next step for this add-in is to implement code to determine 2D plan view boundary polygons for the furniture and equipment family instances contained within the selected room.

I am hoping to be able to make use of the ExtrusionAnalyzer class for this. As I mentioned, it is supplied a solid geometry, a plane, and a direction. From those, it calculates the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction.

At the same time, I am continuing to explore options for a cloud-based data repository.

And I have my day-to-day support tasks to attend to too...

Anyway, here is GetRoomLoops.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

Revit 2014 and Supporting Columns

Revit 2014 Announced

As you probably noticed by now, Revit 2014 has been announced. Here are the main product features:

• Design
  • Enhanced Autodesk Exchange
  • Dockable window framework
  • New stairs and railings
  • Temporary view templates to change view properties temporarily
  • Point cloud improvements improve appearance and controls of point clouds
  • Parameter variance for groups to vary the value of parameters assigned to groups
  • New air terminal on duct enables placement of air terminal device on duct face
  • New angle constraints to restrict angles for pipe, duct, and cable tray
  • Cap open ends of pipe or duct content quickly
  • CSV file removal project, embedding the data into families
  • New plumbing template
  • New rebar placement constraints customization
  • Reinforcement enhancements with more rebar options
• Documentation
  • Non-rectangular crop regions
  • Split elevations
  • Alternate dimensions
  • Improved rebar tagging to annotate multiple elements with a single tag
  • Improved positioning of beams and braces
  • Enhanced schedules providing greater control of schedule formatting
• Visualization
  • Displaced views enable creation of displaced or exploded building design views
  • Enhanced visualization
  • New rendering to reduce project costs with cloud-based rendering
• Analysis
  • New building element energy analysis
  • Enhanced structural analytical model
  • New duct and pipe calculations to API

Each and every one of these is really exciting in itself, and almost all include or are even based on enhanced API support. Some of the ones that seem most exciting to me are the non-rectangular crop regions, parameter variance for groups, enhanced schedules, displaced views... well, as said, they are really all very exciting.

And this is not even mentioning some of the new API features, such as the possibility to launch a Revit command and control copy and paste operations. I will get to all that real soon now.

As Harry puts it, the Revit 2014 API is going to blow your faces out :-)

Determining the Columns Supporting a Beam

Still, ignoring all that busy-ness for the moment, I chug along and return to a topic similar to my discussion on retrieving all touching beams.

In that post, I showed how to recursively traverse a collection of beams and detect the neighbouring ones at each end using an ElementIntersectsSolidFilter with a sphere.

Today I explore the task of determining the columns supporting a selected beam using various different methods.

• Columns supporting a selected beam
• Solid and element intersection
• Bounding box filter tolerance
• Moving the beam downwards in a temporary transaction
• GetGeneratingElementIds
• Cylinder Along Location Line Offset Downwards
• Find references via ray casting
• Sweep Along Location Curve Offset Downwards
• Conclusion and source code

Columns Supporting a Selected Beam

Here is a view of a simple sample model:

The task at hand is to pick the indicated beam and report the columns supporting it:

Simple, ain't it?

Solid and Element Intersection

Initially, I made some further attempts and experiments using the ElementIntersectsSolidFilter and ElementIntersectsElementFilter functionality.

The sample provided includes code exercising these tests and also the original bounding box implementation. It is enclosed in 'if' statements checking the setting of the following Boolean variables:

  bool useBoundingBox = false;
  bool useSolid = false;
  bool useElement = false;

That enables them to be switched on and off interactively in the debugger, if the need arises.

Unfortunately, as it turns out, they both do not work.

The beam solid is not quite big enough to intersect the columns, because the beam is cut back so that it does not actually intersect them.

The same problem also prevents use the element intersection filter.

It would be great if there was a possibility to grow the solid just slightly, e.g. offset all its faces outwards by an inch or two or define a tolerance before executing the intersection check, like for the bounding box. Unfortunately, growing or shrinking an arbitrary solid is much harder than a bounding box and therefore not implemented.

Bounding Box Filter Tolerance

The BoundingBoxIsInsideFilter can be instantiated with an optional double tolerance value that allows control over the match criteria by using the given tolerance in the geometry comparison.

By default, the tolerance is set to zero. If the tolerance is positive, the iterated element outline may extend the tolerance distance outside of the given outline in each coordinate to be a match. If the tolerance is negative, the iterated element outline must lie at least the tolerance distance inside the given outline in each coordinate to be a match.

This is exactly what I would need here for the solid and element intersection filters as well. Unfortunately, as said, such a tolerance is not supported by the solid or element intersection filters.

Moving the Beam Downwards in a Temporary Transaction

Lacking the tolerance option, I thought that maybe it would help to move the beam down a bit, and that it would intersect the supporting columns then. Unfortunately, that does not help either.

The problem is not only that the bottom face of the beam solid may be located above the end of the supporting columns, but also that the ends of the beam are cut back to avoid intersecting the columns, so their solids do not intersect even when the beam is moved slightly downwards.

This temporary movement forces a switch from read-only to manual transaction mode, of course, even though the model is not actually modify in any way in the end.

To make sure that the movement really is executed and the model updated before checking for an intersection, I followed the advice given by Arnošt Löbel on enhancing the temporary transaction trick and encapsulated the whole operation in a transaction group. The group is rolled rolled back at the end, but, before doing so, the encapsulated temporary transaction around the movement of the beam can be committed and the updated geometry evaluated.

By the way, these changes temporarily caused an error saying "Attempted to read or write protected memory. This is often an indication that other memory is corrupt." This was probably due to accessing the list of elements generated within the temporary transaction after the transaction group is rolled back. I handled that problem by storing the element ids instead of the live elements themselves inside the transaction, and then opening the elements via their id after rolling back the changes.

As said, the temporary downward translation still did not produce any intersections.

Time for another idea.

GetGeneratingElementIds

A colleague suggested that if the beam is cut back by the columns, you can iterate over the beam geometry faces and call the Element GetGeneratingElementIds method on each one, which might return the column element ids. In this example, you might also get faces generated by joins with other beams.

I tried this, encapsulating the code in the section if( useGeneratingIds ). Unfortunately, all the generating ids belong to the structural framing or floors categories, so that does not help to determine the columns either. No columns at all are returned by this method.

Cylinder Along Location Line Offset Downwards

I then realised that I could create a much simpler independent solid shape to intersect the columns by extruding a cylinder along the beam location line, offset downwards to just below the bottom face of the beam. It might require extending a little at each end. All supporting columns should be intersected by it.

I can use code similar to the sample presented to find 3D elements by intersection.

Yay! This works!

Find References via Ray Casting

A similar approach as the solid intersection with an offset cylinder could obviously also be implemented using the ray casting functionality provided by the FindReferencesByDirection and FindReferencesWithContextByDirection methods and the ReferenceIntersector wrapper class.

I did not implement any sample code demonstrating this, because I wanted to generalise the straight beam cylinder solution to a more general arbitrary curve case.

Sweep Along Location Curve Offset Downwards

Once I had the working solution using a cylinder defined by the straight beam location line offset downwards, I realised that it might be nice to use more generic sweep along curve functionality instead. After all, the beam location curve might not be straight, and a non-linear location curve can quite simply be used to generate a non-linear solid using the CreateSweptGeometry method instead of CreateExtrusionGeometry.

My first attempt caused the CreateSweptGeometry method to throw an exception saying that "The given attachment point don't lie in the plane of the Curve Loop. Parameter name: pathAttachmentCrvIdx & pathAttachmentParam". That was my fault, though, because I was providing zero for the parameter value, which is probably the normalised curve start point parameter. When providing the raw parameter value returned by curve.get_EndParameter( 0 ) instead, all works fine.

Here is a rather unrealistic sample spline beam that I used for testing:

The algorithm reports the following supporting columns for the spline beam:

All is well.

Conclusion and Source Code

Here is the complete source code of this command, including the test branches that are disabled by default. As said, they can be enabled and tested by modifying the Boolean switches interactively in the debugger.

[Transaction( TransactionMode.ReadOnly )]
public class Command : IExternalCommand
{
  const double _eps = 0.1e-9;
 
  double SignedDistanceTo( Plane plane, XYZ p )
  {
    XYZ v = plane.Normal;
    return v.DotProduct( p )
      - v.DotProduct( plane.Origin );
  }
 
  class BeamPickFilter : ISelectionFilter
  {
    public bool AllowElement( Element e )
    {
      return null != e.Category
        && e.Category.Id.IntegerValue.Equals(
          (int) BuiltInCategory.OST_StructuralFraming );
    }
 
    public bool AllowReference( Reference r, XYZ p )
    {
      return true;
    }
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
    Element beam = null;
 
    try
    {
      Selection sel = uidoc.Selection;
 
      Reference r = sel.PickObject(
        ObjectType.Element,
        new BeamPickFilter(),
        "Please select a beam" );
 
      beam = doc.GetElement( r );
    }
    catch( RvtOperationCanceledException )
    {
      return Result.Cancelled;
    }
 
    List<ElementId> columnIds = null;
 
    // Optionally switch between different tests
    // by modifying these values in the debugger
 
    bool useBoundingBox = false;
    bool useSolid = false;
    bool useElement = false;
    bool useGeneratingIds = false;
    bool useLocation = true;
 
    #region Obsolete previous attempts
    if( useBoundingBox )
    {
      BoundingBoxXYZ box = beam.get_BoundingBox( null );
 
      Outline outline = new Outline( box.Min, box.Max );
 
      ElementFilter bbfilter = new BoundingBoxIntersectsFilter(
        outline, 0.1 );
 
      FilteredElementCollector columns
        = new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( bbfilter );
    }
 
    if( useSolid )
    {
      Options opt = app.Create.NewGeometryOptions();
      GeometryElement geo = beam.get_Geometry( opt );
      Solid solid = null;
 
      foreach( GeometryObject obj in geo )
      {
        solid = obj as Solid;
 
        if( null != solid
          && 0 < solid.Faces.Size )
        {
          break;
        }
      }
 
      ElementFilter beamIntersectFilter
        = new ElementIntersectsSolidFilter( solid );
 
      FilteredElementCollector columns
        = new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( beamIntersectFilter );
    }
 
    if( useElement )
    {
      // Initially, no columns are found to 
      // intersect the beam. Maybe it will help to
      // move the beam down a bit?
 
      using( TransactionGroup txg = new TransactionGroup( doc ) )
      {
        txg.Start( "Find Columns Intersecting Beam" );
 
        using( Transaction tx = new Transaction( doc ) )
        {
          tx.Start( "Temporarily Move Beam Down a Little" );
 
          ElementTransformUtils.MoveElement(
            doc, beam.Id, -0.1 * XYZ.BasisZ );
 
          tx.Commit();
        }
 
        ElementFilter beamIntersectFilter
          = new ElementIntersectsElementFilter( beam );
 
        FilteredElementCollector columns
          = new FilteredElementCollector( doc )
            .WhereElementIsNotElementType()
            .OfCategory( BuiltInCategory.OST_StructuralColumns )
            .WherePasses( beamIntersectFilter );
 
        columnIds = new List<ElementId>(
          columns.ToElementIds() );
 
        // We do not commit the transaction group, 
        // because no modifications should be saved.
        // The transaction group is only created and 
        // started to encapsulate the transactions 
        // required by the IsolateElementTemporary 
        // method. Since the transaction group is not 
        // committed, the changes are automatically 
        // discarded.
 
        //txg.Commit();
      }
    }
 
    if( useGeneratingIds )
    {
      Options opt = app.Create.NewGeometryOptions();
      GeometryElement geo = beam.get_Geometry( opt );
 
      foreach( GeometryObject obj in geo )
      {
        Solid solid = obj as Solid;
 
        if( null != solid )
        {
          foreach( Face f in solid.Faces )
          {
            ICollection<ElementId> ids
              = beam.GetGeneratingElementIds( f );
 
            foreach( ElementId id in ids )
            {
              Element e = doc.GetElement( id );
              if( null != e.Category
                && e.Category.Id.IntegerValue.Equals(
                  (int) BuiltInCategory.OST_StructuralColumns ) )
              {
                columnIds.Add( id );
              }
            }
          }
        }
      }
    }
    #endregion // Obsolete previous attempts
 
    if( useLocation )
    {
      // Determine beam location curve for 
      // extrusion direction and length
 
      LocationCurve lc = beam.Location as LocationCurve;
 
      Curve curve = lc.Curve;
 
      Solid solid = null;
 
      // Handle generic curve parameters.
      // See below for simplified linear case.
 
      XYZ p = curve.get_EndPoint( 0 );
      double param = curve.get_EndParameter( 0 );
      Transform transform = curve.ComputeDerivatives( param, false );
      Debug.Assert( p.IsAlmostEqualTo( transform.Origin ),
        "expected derivative origin to equal evaluation curve point" );
      XYZ tangent = transform.BasisX;
 
      // Use bounding box to determine elevation of
      // bottom of beam and how far downwards to 
      // offset location line -- one inch below 
      // beam bottom.
 
      BoundingBoxXYZ bb = beam.get_BoundingBox( null );
 
      Debug.Assert( .001 > bb.Min.Z - bb.Max.Z,
        "expected horizontal beam" );
 
      double inch = 1.0 / 12.0;
      double beamBottom = bb.Min.Z;
 
      XYZ arcCenter = new XYZ( p.X, p.Y,
        beamBottom - inch );
 
      Plane plane = new Plane( tangent, arcCenter );
 
      CurveLoop profileLoop = new CurveLoop();
 
      Autodesk.Revit.Creation.Application creapp
        = app.Create;
 
      Arc arc1 = creapp.NewArc(
        plane, inch, 0, Math.PI );
 
      Arc arc2 = creapp.NewArc(
        plane, inch, Math.PI, 2 * Math.PI );
 
      profileLoop.Append( arc1 );
      profileLoop.Append( arc2 );
 
      List<CurveLoop> loops = new List<CurveLoop>( 1 );
      loops.Add( profileLoop );
 
      // Switch this on to handle a straight beam as 
      // a separate simplified case using 
      // CreateExtrusionGeometry instead of the 
      // generic CreateSweptGeometry solution.
 
      bool checkForLine = false;
 
      if( checkForLine && curve is Line )
      {
        XYZ q = curve.get_EndPoint( 1 );
        XYZ v = q - p;
 
        Debug.Assert( 0.01 > v.Z,
          "expected horizontal beam" );
 
        Debug.Assert( v.IsAlmostEqualTo( tangent ),
          "expected straight beam vector to equal start tangent" );
 
        solid = GeometryCreationUtilities
          .CreateExtrusionGeometry( loops, v, v.GetLength() );
      }
      else
      {
        // Offset location curve downward 
        // one inch  below beam bottom face
 
        XYZ offset = arcCenter - p;
 
        transform = Transform.get_Translation(
          offset );
 
        CurveLoop sweepPath = new CurveLoop();
 
        sweepPath.Append( curve.get_Transformed(
          transform ) );
 
        solid = GeometryCreationUtilities
          .CreateSweptGeometry(
            sweepPath, 0, param, loops );
      }
 
      ElementFilter beamIntersectFilter
        = new ElementIntersectsSolidFilter( solid );
 
      columnIds = new List<ElementId>(
        new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( beamIntersectFilter )
          .ToElementIds() );
    }
 
    int n = (null == columnIds)
      ? 0
      : columnIds.Count<ElementId>();
 
    string s1 = string.Format(
      "Selected beam is supported by {0} column{1}{2}",
      n,
      ( 1 == n ? "" : "s" ),
      ( 0 == n ? "." : ":" ) );
 
    string s2 = "<None>";
 
    if( 0 < n )
    {
      uidoc.Selection.Elements.Clear();
 
      foreach( ElementId id in columnIds )
      {
        Element e = doc.GetElement( id );
        uidoc.Selection.Elements.Add( e );
      }
 
      s2 = string.Join( ", ",
        columnIds.ConvertAll<string>(
          id => id.IntegerValue.ToString() ) );
    }
 
    TaskDialog.Show( s1, s2 );
 
    return Result.Succeeded;
  }
}

For your convenience, here is GetBeamColumns06.zip containing the complete source code, Visual Studio solution and add-in manifest of the GetBeamColumns external command.

I hope you find this both interesting and useful as a basis for your own variants.

Cloud & Mobile, Extensible Storage Data Use in Schedules

My topics for today are:

• Cloud and mobile topics I covered so far
• Cloud-based round-trip 2D Revit model editing on any mobile device using SVG
• Extensible storage data use in schedules

I am still meeting with my European DevTech colleagues here in Konk Leon, 'anse du Lèon', the cove of the lion, aka Le Conquet, Brittany.

Yesterday, one of our topics was work we have done so far for cloud and mobile applications. It was very interesting to hear about my peers' rich and varied experiences.

Cloud and Mobile Topics Covered so Far

I documented all my own experiences so far here on the blog, and was able to reuse that for my presentation quite spontaneously with no further preparation:

• Accessing a REST API web service from a Revit .NET add-in – Apollonian sphere packing and AVF.
• Thoughts on mobile indoor positioning, representing room polygons in SVG, the Azure SDK, ASP.NET MVC 4, and implementing a web service.
• An overview of the BIM 360 Glue viewer and REST API.
• BIM 360 Glue REST API authentication using Python.
• A room polygon and furniture picker in SVG.
• 2D SVG editing on mobile devices using the Raphaël JavaScript SVG library.

As I explained at the time, all of the explorations involving SVG are part of a larger master plan.

This plan has now matured to a certain extent and is forcing me to move ahead quite fast in the immediate future.

The main outcome so far is a presentation proposal that I submitted for the internal Autodesk technical summit taking place in June, and the fact that it was accepted.

My cloud and mobile roadmap is thus now clearly focused on implementing that proposal:

Cloud-based Round-trip 2D Revit Model Editing on any Mobile Device using SVG

I described the roadmap I envision in the discussion of my simple SVG editor. The main components include:

• A Revit add-in that determines room boundary and furniture and equipment family instance polygons for a simplified 2D plan view rendering.
• A cloud-based database repository managing the models, levels, rooms, furniture, equipment meta- and polygon data.
• The SVG editor running in a browser on any device, rendering the model and supporting some simple geometric modification.

Here is the actual wording of my technical summit proposal:

Proposal Abstract

This presentation demonstrates round-trip editing a 2D rendering of a Revit model on any mobile device with no need for installation of any additional software whatsoever beyond a browser. How can this be achieved? A Revit add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository. On the mobile device, the repository is queried and the data is rendered in a standard browser using JavaScript and SVG. The rendering supports modification, such as translation and rotation of the furniture and equipment, which is saved back to the cloud database. The Revit add-in picks up these changes and updates the Revit model.

Intended Audience and Prerequisites

Intended audience is programmers with interest in cloud-based and mobile computing, specifically interest in round-trip editing of a Revit model using a cloud-based data repository and editing a 2D model on an arbitrary mobile device with no additional software beyond a browser installed on it. 
Knowledge of .NET, JavaScript and REST programming is helpful but not required. Revit add-in experience is not a prerequisite.

Presentation Outline

• Show a Revit model.
• Export the model to a cloud-based data repository.
• Query and display the repository contents as 2D rendering on a mobile device.
• Edit the model in the browser on the mobile device, updating the data repository.
• Pick up and display the modified model in Revit.

Two of the important components whose implementation I plan to explore next are the polygon generation and data model:

Plan View Polygon Determination

The generation of the room boundary polygons is obvious, since the room has a boundary property.

For the furniture and equipment family instance, the solution is a less immediate. My current idea is to explore making use of the ExtrusionAnalyzer class. It is supplied a solid geometry, a plane, and a direction. From those, it calculates the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction. As far as I can tell, that should be exactly what I need.

Scott Conover mentioned this class in his session on the Geometry API, a continuation of his AU 2011 presentation CP4011 'Geometric Progression: Further Analysis of Geometry Using the Autodesk Revit 2012 API', enhanced for the Revit 2013 API.

As soon as I have the polygons determined, I want to implement functionality to render them easily. This will involve extent calculation, canvas definition, and coordinate system transformation. I will probably implement a simple .NET geometry viewer before moving on to the SVG rendering. I've been wanting to do that for a long time...

Cloud-based Data Repository

So far, my colleagues have been focusing on using the Amazon and Azure cloud hosting services, and many discussions on the cloud and mobile DevBlog deal with them.

I searched the Internet for other cloud-based database alternatives, and right now CouchDB looks pretty promising, so I might try a completely different approach using that instead.

There is a lot to do here as well: define the data model, set up the web service, define a format for saving the polygon data, etc. At the very least, I will need to manage:

• Model > metadata, rooms.
• Room > metadata, model, furniture, level, polygon.
• Furniture > metadata, room, polygon, transformation (initially identity).

Round tripping the information will be interesting, especially if I want the Revit model to update automatically when furniture positions are modified on the mobile device, which I certainly do, if only for the wow effect :-)

Stay tuned...

... Oh, and, yeah, wish me luck!

Extensible Storage Data Use in Schedules

Returning to the desktop again, here is a recent question from a developer on using estorage data in a schedule that leads to some general observations on that topic:

Question: I would like to display my extensible storage information in a schedule. I searched high and low, though, and was unable to find any samples or documentation on the subject. Can you help?

Answer: There is a good reason why you have not found anything: there is no such support.

The usage of extensible storage data is utterly and completely up to the add-in itself. The Revit API offers no support whatsoever for making use of estorage data in any way. The only support provided is for storage and retrieval, nothing else.

Well, one tiny little detail more: if an element id value is stored, and the element id is later modified by some worksharing operation, its value will be automatically updated.

On the other hand, there is currently no direct support for putting data into a schedule either.

I am no user interface expert, but I think that you can set up a schedule to be populated from certain parameter values via the user interface. You would have to talk with an application engineer or product support or explore this topic on the Internet to find out how that can be done.

Of course, there is nothing stopping you from extracting your data from extensible storage and transferring it into parameters set up to populate a schedule yourself.

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

Parameter DisplayUnitType, Bretagne and Decompilers

After looking at several performance enhancement possibilities last week, e.g. the sweep family performance enhancement and LoadFamily and collector iteration performance, here is another exciting and pretty sophisticated exploration of internal Revit API implementation details by Victor Chekalin that can be used to achieve a significant speed improvement when accessing large numbers of parameters and checking their DisplayUnitType property.

Brittany

Before getting to that, though, here is an update on my current whereabouts.

Yesterday I spent travelling to Brest and Le Conquet (Konk Leon in Breton) for a meeting with my European DevTech colleagues.

This is the western-most point of northern France, home of my boss Cyrille, and my first visit to the Bretagne.

The weather is exciting and challenging, and the views spectacular.

A quick rainfall in the east and simultaneous glorious evening sunlight from the west produced a beautiful double rainbow.

We have a meeting room in a converted chapel with a view straight out onto the Atlantic.

Parameter DisplayUnitType Enhancement and Research

Back to the DisplayUnitType enhancement, here is the description of the research leading up to it in Victor's own words:

Now I'm working with the element parameters again and I need to get all parameters of a lot of elements in the project including their DisplayUnitType.

The problem is that not all parameters have a display unit type. If I try to retrieve a display unit type for a parameter where it does not exist, an Autodesk.Revit.Exceptions.InvalidOperationException is thrown. Unfortunately, there is no direct way to determine beforehand whether a parameter has a DisplayUnitType defined or not, i.e. whether the call will succeed or fail.

The most obvious way would be to wrap the code where I retrieve the display unit type in a try... catch block. But throwing and catching an exception is a very expensive operation and greatly reduces the performance – exceptions should be exceptional.

I decided to go deeper and looked at the RevitAPI.dll using dotPeek – free .NET decompiler.

At first I went to the DisplayUnitType property of the Parameter class.

public DisplayUnitType DisplayUnitType
{
  get
  {
    Definition definition = this.Definition;
    ParamTypeSpec paramTypeSpec1;
    if ((ParamTypeEnum) *(int*)
      definition.getParamTypeSpec(&paramTypeSpec1)
      != (ParamTypeEnum) 15)
    {
      throw new Autodesk.Revit.Exceptions
        .InvalidOperationException(new FunctionId(
          "n:\\build\\2013_ship_x64_inst_20120221_2030\\source\\api\\revitapi\\objects\\parameters\\APIParameter.cpp",
          581, "Autodesk::Revit::DB::Parameter::DisplayUnitType::get"),
          string.Empty);
    }
    else
    {
      ParamTypeSpec paramTypeSpec2;
      return (DisplayUnitType)
        \u003CModule\u003E.FormatOptions\u002EgetDisplayUnits(
          \u003CModule\u003E.AUnits\u002EgetFormatOptions(
            \u003CModule\u003E.ADocument\u002EgetAUnits(
              (ADocument*) *(long*) this.m_pCDA),
                (UnitType.Enum) *(int*) ((IntPtr)
                definition.getParamTypeSpec(&paramTypeSpec2) + 8L)));
    }
  }
}

The most interesting thing here is 'if ((ParamTypeEnum) *(int*) definition.getParamTypeSpec(&paramTypeSpec1) != (ParamTypeEnum) 15)'. The first idea is to call this method via reflection. But getParamTypeSpec is an internal unsafe method. Unfortunately, I don't know how to use reflector with pointers and internal structures. So, I decided to go another way.

The next step is to look at the ParameterType property of the Definition class.

public override ParameterType ParameterType
{
  get
  {
    REVIT_MAINTAIN_STATE revitMaintainState;
    \u003CModule\u003E.REVIT_MAINTAIN_STATE\u002E\u007Bctor\u007D(
      &revitMaintainState);
 
    ParameterType parameterType;
    try
    {
      ParamDef* paramDefPtr = this.m_pParamDef;
      ParamTypeSpec paramTypeSpec;
      \u003CModule\u003E.paramDefToParamType(
        &paramTypeSpec, paramDefPtr);
      switch (^(int&) @paramTypeSpec)
      {
      case 1:
        parameterType = ParameterType.Text;
        break;
      case 6:
        parameterType = ParameterType.URL;
        break;
      case 9:
        parameterType = ParameterType.YesNo;
        break;
      case 11:
        parameterType = ParameterType.Integer;
        break;
      case 13:
        parameterType = ParameterType.Material;
        break;
      case 14:
        parameterType = ParameterType.FamilyType;
        break;
      case 15:
        switch (^(int&) ((IntPtr) &paramTypeSpec + 8))
        {
        case 0:
          parameterType = ParameterType.Length;
          break;
        case 1:
          parameterType = ParameterType.Area;
          break;
        case 2:
          parameterType = ParameterType.Volume;
          break;
        case 3:
          parameterType = ParameterType.Angle;
          break;
        case 4:
          parameterType = ParameterType.Number;
          break;
        case 26:
          parameterType = ParameterType.Force;
          break;
        case 27:
          parameterType = ParameterType.LinearForce;
          break;
        case 28:
          parameterType = ParameterType.AreaForce;
          break;
        case 29:
          parameterType = ParameterType.Moment;
          break;
        default:
          parameterType = (ParameterType) (
            ^(int&) ((IntPtr) &paramTypeSpec + 8) + 100);
          break;
        }
      case 16:
        parameterType = ParameterType.NumberOfPoles;
        break;
      case 24:
        parameterType = ParameterType.FixtureUnit;
        break;
      case 30:
        parameterType = ParameterType.LoadClassification;
        break;
      default:
        parameterType = ParameterType.Invalid;
        break;
      }
    }
    __fault
    {
      \u003CModule\u003E.___CxxCallUnwindDtor(
        (__FnPtr<void (void*)>) __methodptr(REVIT_MAINTAIN_STATE\u002E\u007Bdtor\u007D),
          (void*) &revitMaintainState);
    }
    \u003CModule\u003E.REVIT_MAINTAIN_STATE\u002E\u007Bdtor\u007D(
      &revitMaintainState);
    return parameterType;
    }
  }
}

Here we can see that a parameter will have a DisplayUnitType only if the ParameterType is Length, Area, etc.. So we can just check if the ParameterType is one of the Length, Area, etc. ones. If so, its parameter has a DisplayUnitType, otherwise not.

It is necessary to pay attention to the line

  default:
    parameterType = (ParameterType) (
      ^(int&) ((IntPtr) &paramTypeSpec + 8) + 100);
    break;

Looking at the ParameterType enumeration suggests that every parameter type whose integer value is greater than 100 belongs to paramTypeSpec = 15.

As a result, I created the following extension method for the Parameter class:

public static class ParameterExtensions
{
  public static bool HasDisplayUnitType(
    this Parameter parameter )
  {
    var parameterType =
        parameter.Definition.ParameterType;
 
    switch( parameterType )
    {
      case ParameterType.Length:
      case ParameterType.Area:
      case ParameterType.Volume:
      case ParameterType.Angle:
      case ParameterType.Number:
      case ParameterType.Force:
      case ParameterType.LinearForce:
      case ParameterType.AreaForce:
      case ParameterType.Moment:
        return true;
    }
 
    /* At the reflector I can see the following code
          default:
            parameterType = (ParameterType) 
              (^(int&) ((IntPtr) &paramTypeSpec 
              + 8) + 100);
            break;
        looking at the ParameterType enumeration 
        suggests that every parameter type whose 
        integer value is greater than 100 belongs 
        to paramTypeSpec = 15
    */
    return 100 < (int) parameterType;
  }
}

Comparison Benchmarking

To wrap this up, here is a little benchmark comparing the two methods.

The first one exercises the try... catch block:

  Reference r;
 
  try
  {
    r = uidoc.Selection.PickObject(
      ObjectType.Element );
  }
  catch( OperationCanceledException )
  {
    message = "Cancelled";
    return Result.Cancelled;
  }
 
  var e = doc.GetElement( r.ElementId );
 
  Stopwatch sw = Stopwatch.StartNew();
 
  foreach( Parameter parameter in e.Parameters )
  {
    try
    {
      DisplayUnitType dut =
          parameter.DisplayUnitType;
 
      Debug.Print( dut.ToString() );
    }
    catch( Autodesk.Revit.Exceptions
      .InvalidOperationException )
    {
    }
  }
  sw.Stop();
 
  TaskDialog.Show( "Benchmark result",
    sw.Elapsed.ToString() );

Pick an element. The result is 0.41 seconds.

Second measurement, with my new method:

  Reference r;
 
  try
  {
    r = uidoc.Selection.PickObject(
      ObjectType.Element );
  }
  catch( OperationCanceledException )
  {
 
    message = "Canceled";
    return Result.Cancelled;
  }
 
  var e = doc.GetElement( r.ElementId );
 
  Stopwatch sw = Stopwatch.StartNew();
 
  foreach( Parameter parameter in e.Parameters )
  {
    if( parameter.HasDisplayUnitType() )
    {
      DisplayUnitType dut =
          parameter.DisplayUnitType;
 
      Debug.Print( dut.ToString() );
    }
  }
  sw.Stop();
 
  TaskDialog.Show( "Benchmark result",
    sw.Elapsed.ToString() );

The result is 0.029 seconds for the same element!

You may say that 0.41 seconds is not so much, and users will not notice the difference between 0.41 seconds and 0.028. Of course the difference is not huge if you work with only one element. But note that the exception handling code works 15 times slower, repeatedly, ever single time it is called!

If you retrieve parameters for 100 elements, it takes 41 seconds using try... catch instead of just 3 seconds with my new method.

I hope this enhancement will be useful for other developers as well.

Many thanks to Victor for his very professional analysis and valuable result!

The best of luck to you in your new job, Victor, and congratulations on that achievement!

IL Decompilation

I talked about Reflector way back in the early days of the blog. It since became commercial.

Victor mentions using dotPeek for his explorations above.

When I brought this up with my colleagues, Adam added that he uses the ILSpy .NET Decompiler and is perfectly happy with that as well.

Determining Purgeable Elements

A question that crops up from time to time and is rather hard to answer exactly and exhaustively is on purgeable elements:

Question: What is the best way to get all of the elements that can be purged? I can use WhereElementIsElementType filter to return all types, and WhereElementISNotElementType to return instances, but comparing the two lists does not leave me with the purgeable result. I could compare individual lists of types (i.e. family symbol and family instance), but that seems prone to error. Is there any good way to get this information out of the model?

Answer: Yes, the Revit API does not currently provide any direct method to determine this.

Let's see what can be done about it anyway already.

When you say "all of the elements that can be purged", that can be a pretty huge task.

I would suggest breaking that down into individual sub-tasks for different types of purgeable elements, which will require pretty different handling.

For example, I implemented a method DeleteUnnamedNonHostingReferencePlanes to find and delete all reference planes not hosting any elements.

An explicit reference to the term purge is used in the post on removing unused text note types.

One way to determine whether a certain element A is required by another one B is to delete A and check the return value of the Delete method, which provides a list of deleted element ids. In some cases, B is deleted as well, and its element id is included the resulting list of deleted element ids. This is used by the object relationship analyser (VB).

The deletion can be made temporary by encapsulating it in a transaction that is later rolled back. Here is a discussion of the temporary transaction trick including a list of numerous usage examples, and later touched up slightly.

Unfortunately, of course, this method becomes extremely slow in a large model with each deletion taking place in its own transaction and then rolled back. Wrapping it all in one single transaction will essentially deleting the entire model, which causes other problems is also not very useful, so this idea may not really be very feasible for the task at hand.

When you do have access to a one-way relationship between two classes of objects, e.g. pointers from doors, windows and openings hosted in walls to their respective wall host elements, you can easily invert the relationship to determine the list of hosted object for each host. This is demonstrated in my discussion of the relationship inverter in one of the very first blog posts.

Taking a look at family types only, which is a small subset of the potentially purgeable elements, a similar one-way relationship as the one between hosted objects and their hosts is defined between non-element types and types, since the former provide a property named GetTypeId pointing to the type. You could make use of this in a similar manner to find all unused types as follows:

1. Determine all non-type elements using WhereElementISNotElementType
2. Iterate over all non-type elements. Determine the element id of each one, and build a dictionary D of the inverse relationship, mapping type element id to a list or the elements using that type.
3. Use WhereElementIsElementType to determine all element types. Iterate over them. For each type, check D to see how many elements are referencing it. If D has no entry for this type, it is not being used and can be deleted.

There is no guarantee that this will really work, though, since there may be any number of exceptional situations that need to be handled differently on a case-by-case base.

You can try it out, though, see whether you corrupt the database in any way, test thoroughly, possibly add handling of all special cases that you encounter, and maybe achieve your goal in the long run.

Unfortunately, there is currently no API access to the list of objects or categories searched by the built-in purge functionality, and the logic used for it is non-trivial.

Definitely, a number of special cases need to be handled, and there are some things that cannot be determined using the method described above.

For example, there are no instance placements of materials, so you have to search through instances placed in the model and for each element determine whether the material is used by it or not. This also leaves out materials that are set for type parameters on types that have not been used but are loaded into the model.

LoadFamily and Collector Iteration Performance

Since we are into the topic of family loading performance anyway, after yesterdays discussion on efficient sweep creation, here is another interesting discussion with some useful family loading and symbol filtering benchmarking results and observations by Thomas Jarzyna and an in-depth analysis of the effects of converting a filtered element collector to a .NET collection by Scott Conover:

Question: I need to load some family symbols into my project. I have a lot of different families and even more symbols, so to keep the projects small and clean I would prefer to load family symbols on demand only.

Therefore, whenever an instance of a family is to be created, I need to check first whether the family symbol is already loaded.

I can see two possible approaches to achieve this:

• Check whether the family symbol already exist by iterating through the database using a filtered element collector searching for family name and family symbol name.
• Not checking anything, and just always calling LoadFamilySymbol. It runs fine even if the family symbol is already loaded. One negative side effect of this approach is the "one time conversion" dialogue popping up for older families every time.

Which approach is better from a performance centred point of view, please?

Is there any other possible approach?

Answer: Both of your two approaches sound feasible.

I also find the "one time conversion" dialogue rather irritating and would not want my users to see it, especially not repeatedly.

If that is a serious problem for you, you could implement a system to ensure that it never occurs more than once. For instance, you could create different sub-directories for the different Revit versions of the same family, and check whether an updated version has already been generated before loading an older one.

However, I would expect the use of the filtered element collector to be much (very much!) more efficient.

However^2, it really depends on so many factors that it is impossible to say for sure.

The only way to really answer this with certainty for your particular system, workflow needs, and installation situation is to benchmark the different options.

I described a simple benchmarking system that I would use in a Revit add-in in lack of anything more sophisticated.

I cannot think of any other approach offhand.

The thought of calling LoadFamily without even checking beforehand actually never occurred to me :-)

Here are two different implementation examples checking whether a family has already been loaded, and loading it otherwise, for

• Creating and inserting an extrusion family
• Structural concrete setout points

I hope they fulfil your needs.

Response: Thank you for the answer.

I was hoping for a simple standard best practice, but I see it's not as easy as that.

In the meantime, I've done a little bit of benchmarking myself. Just basic, using a stopwatch:

And you are right, depending on the quantity of different Types (FamilySymbols) these approaches differ significantly.

For a scenario of creating 2000 family instances from one family (see attached sheet), this is my conclusion:

• If you expect less than a dozen different family symbols to load, just load them once via "LoadFamilySymbol" and don't care about iterating the element collection for the already loaded family symbols.
• Otherwise, iterating and finding the loaded family symbols first is better.
• Of course, this depends on the complexity of the family types and the environment (hardware & current load).
• A large number of different families is not considered yet.

I also noted the following interesting fact while iterating for "known" family symbols:

  var collector = new FilteredElementCollector( doc );

  IEnumerable<FamilySymbol> familySymbols = collector
    .OfClass( typeof( FamilySymbol ) )
    .ToElements()
    .OfType<FamilySymbol>();

The additional call to the ToElements method makes the search using the collector slightly less effective (some milliseconds slower) compared to:

  IEnumerable<FamilySymbol> familySymbols = collector
    .OfClass( typeof( FamilySymbol ) )
    .OfType<FamilySymbol>();

But in the long term, iterating over the family symbols is much faster when ToElements is called first.

For the 2000 instances it takes 14 seconds without ToElements vs. 9 seconds with.

I guess this has to do with the caching provided by possible multiple enumerations of IEnumerable.

What do you think?

Thank you, till next time.

Answer: Thank you for your very interesting results and observations, and congratulations on your first benchmarking results! They are already very interesting.

A call to ToElements definitely costs some performance, since it allocates an entirely new generic .NET collection and copies all the elements across from the Revit filtered element collector, as I mentioned discussing FindElement and collector optimisation.

I am surprised and interested (and was initially a little disappointed) to hear that the subsequent iteration over the .NET collection is measurably faster than the Revit collector, though.

Yes, the speed improvement is probably indeed related to the explanation you point to. In this case, the Revit element collector may be storing the elements in 'Revit memory' and eating cycles when marshalling them across to '.NET memory'. This marshalling effort may need to be performed anew on each repetition of the iteration.

Ah yes, with that explanation, I am perfectly happy with this observation, and not disappointed at all.

Thank you for these illuminating results.

Scott adds: I would expect the total time spent in FilteredElementCollector.ToElements and subsequent iteration to be longer than direct iteration of FilteredElementCollector, regardless of the number of elements that pass the filter.

Of course, once ToElements has run and you store the managed handles, iteration of this collection should be fast – you are not going back to the document to find the elements again or filter them or wrap them in managed handles.

If you are doing more than one iteration of a given filter criteria, the first one will always be faster than the second – because of the extra time taken to create the Elements collection. The other activities – traversing the database, applying and evaluating the filter, wrapping the elements that pass into managed code – happen on both.

If you know you need to have the same filtered set of elements more than once, saving them in the collection should be faster for the second and subsequent iterations. This assumes that you know the document hasn’t changed where there are new elements that pass the filter (or some of them are deleted). The second iteration over the managed collection should be faster than re-traversing the document. This is a pretty specialized approach. The other reasons for converting FilteredElementCollector to a collection (you want to store a list of elements or ids for later, you need such a list as input to another method, you want to delete anything you find, etc.) still apply.

If you are running multiple loops on the collector with no changes in between, the second will be consistently faster. Optimally, you might want to unroll the loop to just do everything in one shot.

The first might be faster than the second if the collector is returning a really large number of elements.

Mostly, you want to get a set of things once and just do things to it once. Normally, only certain specialized applications such as multiple data extractions or multiple permutations for design studies might require retrieval of the exact same data and then doing things to it repeatedly in the same code sequence.

Let’s use made up concrete numbers.

• It takes 100 ms to process the model and find elements that pass the filters, and to wrap each element into the API object.
• It takes 5 ms to build the .NET collection returned by ToElements.
• It takes 1 ms to traverse a .NET IEnumerable<Element>, which could be either the Revit collector or the .NET collection.

So with one group of elements processed once:

• With collection: 100 + 5 + 1 = 106 ms.
• Without collection: 100 + 1 = 101 ms.

With the same exact group of elements processed 10 times in the same code (where we know there is no chance new elements were added or elements deleted that we care about):

• With collection obtained once: 100 + 5 + 10 * 1 = 116 ms.
• Without collection: 100 * 10 + 10 * 1 = 1010 ms.

Make sense?

The key thing to understand is that FilteredElementCollector caches nothing (except the filters applied to it, of course). Caching data needed for multiple things will be better – always – but premature if there’s no need to have such a cache at all.

Note that the built-in collections on Document (.WallTypes, etc.) – which are becoming obsolete in future versions – use FilteredElementCollector as their base; there is no caching done there either, and no real advantage to them other than saving the coding effort of building the collector and filters.

Curve Evaluation and Song of the Gulls

Below, we take a look at one aspect of parametric NURB spline curve evaluation and an overview of recent AEC DevBlog posts.

First, however, another update on my vacation :-)

Marvels of the Song of the Gulls

I am winding up my vacation on the Island of Ischia that I first discovered three years back.

It is one of my favourite places in the world, where I visited natural wonders such as hot thermal springs of Sorgeto in Panza, where you can build your own bathtub to mix the hot spring water with the cold waves from the sea, and the antique natural roman bath of Cavascura on the Maronti Beach that includes a natural sauna in hewn rock that has been running uninterrupted for 3000 years.

On the way here, I first got off at the wrong ferry stop in Procida. That also proved very nice, with all the families taking their numerous kids for a Sunday walk, to chat and play in the main square.

From the ferry, I walked up to the Chiesa della Annunziata and on to the Piano Liguori and then explored the peninsula of San Pancrazio with its spectacular old church and caves. Here is the view from Piano Liguori back towards Procida and Naples.

I visited the Trani family restaurant, olives and vineyard. They even built their own staircase access to the sea, tunnelling through the almost vertical rock facing the water.

It was a huge pleasure chatting with one of the Trani sons and listening to his joy over the traditional agricultural work amidst the 'canto dei gabbiani', the song of the gulls, and the challenges of making it economically viable through some interaction with tourism.

I later saw this wonderful example of a scalable implementation and thinking outside the box:

Parametric NURB Spline Curve Evaluation

Question: I use the Curve.Evaluate method to obtain equally spaced points along a curve.

This works fine for most curve types, but not on a NURB Spline that I created.

When I evaluate with regularly incremented parameter values, e.g. 0, .2, .4, .6, .8 and 1, the distances of the resulting positions along the curve are not visually equal. Using the same curve to create a ruled surface shows the lines and points appearing where one would expect.

Here is an example with the green lines displayed where ruled lines on the face occur, and text letters at the locations returned by the evaluate function:

Answer: The parameterisation of a NURB spline is such that regions of strong curvature are 'longer' in the parameter space than the actual curve length.

The assumption that a parameter measures uniformly along its length can only be made for lines and arcs. For ellipses and splines the parameter does not typically follow this pattern, because of the mathematics involved.

This is mentioned in the Developer Guide description of the parameter used in curve parameterisation:

"A ‘normalized’ parameter. The start value of the parameter is 0.0, and the end value is 1.0. For some curve types, this makes evaluation of the curve along its extents very easy; for example, the midpoint of a line is at parameter 0.5. (Note that for more complex curve equations like Splines this assumption cannot always be made)."

It is also explained in more detail in the Wikihelp community article on points hosted on curve edges.

The Revit Geometry API currently does not offer the ability to measure by segment-length or normalized segment-length. If it did, a more iterative solution would be easy to describe.

Recent AEC DevBlog Overview

Here is an overview of some of the posts by my colleagues on the AEC DevBlog in the past few weeks:

• Bubble end and free end arguments: explores the detailed meaning of the two XYZ parameters bubbleEnd and freeEnd to the NewReferencePlane method.
• Regenerating the model: provides yet another example in the long list of situations requiring an extra regeneration or transaction.
• SQLite version conflict with a Revit add-in discusses methods to resolve a DLL version conflict.
• Hiding sections in ViewPlan presents sample code to filter out the plan views, filter the sections created on each one of them, and call HideElements to suppress them in the view.
• Determining if a family instance requires a host can be achieved using RevitLookup and the HOST parameter on the family itself.
• Retrieving paint material for walls uses the Face HasRegions property and GetRegions method.
• Disassociating a family parameter from an element parameter is possible using the FamilyManager AssociateElementParameterToFamilyParameter method.
• Accessing the material value of a panel uses the MATERIAL_ID_PARAM built-in parameter on the panel type referenced by the panel element.
• Using Rebar.CreateFromCurves with curves: if a Rebar shape includes any straight edges, then its first and last curves must be straight lines, unless it is completely made up of arcs.
• Revit API error in projects with web references can be fixed by changing the 'Generate Serialization Assembly' setting from 'Auto' to 'Off' in the Visual Studio project properties build tab.