The Building Coder

What I Do, Wall Layers and Open Transactions

One of my tasks today and tonight will be a minimal little contribution to an internal ADN meeting, where I was asked to explain briefly to my colleagues in just a couple of minutes what my job involves and what I have been up to for the last couple of months. Tonight, since we have a session each for the western and eastern hemisphere, and the eastern one will require me to set my alarm for 2:30 tomorrow morning.

I thought I might as well share the result here with you also, to provide a rough idea for all of what my everyday work looks like.

Further down I'll also mention two recent cases, dealing with:

• Determining wall layer materials, areas and volumes
• Determining whether a transaction is open
• The Application IsQuiescent property

What I Do

My spontaneous picture of my work life is that I never do anything at all except dealing with ADN cases and writing The Building Coder blog.

My main motivation is probably solving problems, but maybe even stronger than that an urge to help people in whatever manner possible.

Unfortunately for me, I seem to often find it more helpful just to shuffle information around that I receive from others, rather than performing my own research. I would love to spend more time programming and exploring new issues myself, rather than managing information provided by others.

I have a large number of other interests besides that, such as reading, languages, nature, sports, especially climbing, dancing, 5rhythms and dj-ing.

I also have four grown up kids who have left home by now and are out in the world doing their own things, such as composing their own music.

Job-wise, I recently switched from a Windows computer to a Mac and still enthusiastic about that, busy retraining my fingers and compiling open source software. I am a keyboard user and avoid touching the mouse or using the GUI whenever possible. It will take much longer to train my fingers to all the new shortcuts, but they are starting to adapt. I am overjoyed at having a Unix command console now again, after a couple of decades of cmd.exe.

When I offered to talk, I said that I would only be able to cover 30 seconds, since all I do is handle cases and blog, and that is quickly said.

Of course I also do some work creating presentations and conducting trainings at conferences and events such as AU (2, 3) or DevCamp (2, lab).

Jim suggested I could mention my visit to Australia.

Yes, indeed, I went there and gave a Revit API training, followed by a three-day DevLab. It really was a great learning experience and good fun. Some of the participants were extremely well versed in the Revit product usage, and the importance of knowing the product in depth before embarking on any add-in development plans was strongly reinforced.

In spite of that, I spent a while with one of the participants discussing how to implement a family and a command to toggle the family instance state between two conditions, until we discovered that we could save hundreds of lines of code, family complexity, workflow development and user training by just using the existing functionality already provided by Revit: define two different types for the two states, and let the user switch via the instance properties using standard built-in tools – a very impressive experience, cool.

What I Actually Did

That said, I do indeed spend almost all my time with cases and the blog. In 2012 ADN provided a couple of hands-on classroom trainings. The trend in some highly developed areas of the world seems to be going away from hands-on face-to-face trainings and meetings and moving towards virtual interactions and blogging instead.

So, to answer the question more precisely, I put together some statistics on the time I spent on various tasks in the year 2012 in per cent:

• 44% – ADN cases, special support cases, learning new Revit API features cases, newsletter articles
• 17% – Conferences: Autodesk University, DevCamp, DevDays, webcasts
• 14% – Admin including meetings and participating in trainings
• 13% – Blogging
• 6% – Providing hands-on Revit API training
• 6% – Other stuff, including cloud & mobile, plug-in development, Mac learning and setup

I was a bit surprised by some of these results and find them interesting. Maybe you do too.

The results are rather skewed, actually, since a lot of the work I do for the blog stems from case answering, trainings, and conference preparations, so maybe it would be more realistic to classify something between a fifth and a third of the case, conference and training work as blogging instead.

Basically, the intention of the blog is to eliminate the need for questions via ADN cases and discussion forum threads, and simultaneously the latter feed the former.

You could even go to the extreme of saying teat the blog is a filter for everything I do: if it is useful for the blog and can be shared in public, it is worthwhile doing; if not, not.

Therefore, let's return to the Revit API and present some notes on the two cases I mentioned above.

Determining Wall Layer Materials, Areas and Volumes

I recently started looking at foreign language cases as well as English ones, just for fun. I am very impressed by the advances in automatic translation. Here is a question on wall layers:

Question: 如何获取墙的材质厚度、名称等属性

我想请问下墙分层材料能够获取哪些信息？

我通过PickObject()获得墙（基本墙 外部 带砖与金属立筋龙骨复合墙）的Element， 再通过Element.Materials访问到MaterialSet，遍历得到各个Material信息，可得到墙的各个材质， 再根据Element.GetMaterialArea(Material)、Element.GetMaterialVolume(Material)获得该Material的体积和表面积。 单独墙体利用“体积/表面积”得到该Material的厚度是否正确？ 相交墙、曲面墙的情况呢？ 是否有API可以直接访问到该Material的厚度值？

Simply passing that though Google translate yields the following:

How to get the wall thickness of the material, the name and other attributes?

I would like to ask the next wall of layered materials able to get what information?

I PickObject wall (the wall externally with bricks and metal studs keel composite wall) Element. By Element.Materials access to MaterialSet, traverse various Material available wall material. According Element.GetMaterialArea (Material), Element.GetMaterialVolume (Material) to obtain the volume and surface area of the Material. Separate wall volume / surface area of the Material thickness is correct? Intersecting walls, curved wall? API can directly access to the thickness of the Material value?

Answer: Just as you say, the GetMaterialArea and GetMaterialVolume methods will return the volume and surface area of specific materials used within a wall.

This should work just fine for curved and intersecting walls as well.

You can also traverse the wall compound structure yourself to obtain more detailed information. Here is my very first discussion exploring wall compound layers.

Another exploration of this topic looks at extracting material volumes.

The access to the wall layers has been significantly enhanced since then, by the introduction of the new read-write compound layer structure access in Revit 2012, but the basic principles still apply just the same.

If you need more exact values than those returned by the built-in API methods, you can also split the wall into separate parts for a detailed analysis.

Here is a discussion describing such an approach used to determine the exact corner points of the various layers in the internal structure.

This apparently helped, at least to get started in further exploration of this topic.

Determining Whether a Transaction is Open

The other case was in English right from the start:

Question: My Revit add-in presents a modeless form to my users. How can I check from that context whether any other commands or transactions are open in Revit?

For example, the 'insert doors' command may be active.

If Revit is already waiting for user input, e.g. to insert a door, trying to start a transaction causes an error. It would be useful to be able to check whether a transaction is already in progress.

Answer: As you hopefully know, the implementation to handle the Idling event needs to be really clean and clear and is a little bit tricky.

Therefore, I strongly suggest basing anything you do on the ModelessForm_IdlingEvent and ModelessForm_ExternalEvent SDK samples introduced in Revit 2013.

If you implemented your Idling event handler in any other way in the past, it might be a good idea revisiting it now and comparing notes with those samples.

Also note that using an external event is often a little bit simpler and more appropriate than using an Idling event handler.

Please look at the implementation of my own tooltip for a more detailed explanation.

Basically, you never, ever, need to check for yourself whether a transaction is open at all.

Why? Because, to check whether a transaction is open, you need to use the Revit API. You cannot use the Revit API, though, unless you are in a valid Revit API context.

Mostly, when you are in a valid Revit API context, it is clear whether or not you can start a new transaction, since it depends to a large extent on the event handler that is currently being called.

Therefore, if your requirement is what I imagine it to be, I would simply suggest that you implement whatever you want to achieve based on the Revit SDK samples mentioned, and you will not need any further checks whether or not you can start a transaction, since it will be obvious: when your Idling event handler or external event Execute method is called, you can do what you like, and at all other times you can do nothing at all

Of course, in addition to being allowed to start a transaction at all, you may also have some restrictions due to read-only project documents etc., that also need to be gracefully dealt with.

Two methods are provided which may help with this: Document.IsModifiable andDocument.IsReadOnly. Look at the Revit API help file RevitAPI.chm for further oinformation on their application and usage.

The Application IsQuiescent Property

In addition to this, the Revit API does provide the Application.IsQuiescent property to check whether the application is quiescent. Unfortiunately, this method is not really useful for anything at all in the API right now.

Firstly, it is not at all related to transactions, thus one cannot make any assumption about starting a new transaction based on this. If any document in the current application is in editing mode or an in-place family is being edited, it returns false. Otherwise, true will be returned. That might correspond pretty well to what you are looking for. In reality, this property is by far not as useful as the two other ones mentioned above.

So, secondly, what it does tell you is whether you are currently in a command or edit mode or not. However, as pointed out above, as an API programmer, you already know that. For example, in your own external command, the method would return False, all the time. Ditto in many events and updaters. On the other hand, it should return True when called from Idling event, which again is obvious.

Just as a background information, this method was implemented in a very early attempt to mimic the AutoCAD API. However, due to significant differences, the quiescent state is not equally important in Revit, and thus the method ends up not actually being used in any Revit code.

Response: Thank you, that helped.

I'm making a 'Content Library' function as a modeless form in Revit. The form is intended to be open beside Revit when users work.

It provides content (RFA families) either by browsing by category or searching on family name, family type name, parameter name or parameter value on each of the family types.

The families are located by default on a website using REST. The database behind the website contains information about the family types, its parameters, and also thumbnails and a DWFX file of the RFA. For users with slow internet connections I made it possible to change provider to connect to content in a local database instead of the online website.

The above worked fine until I implemented SendKey Esc x 2 to cancel insert family in Revit.

When you mentioned the Idling event I looked through my code again and found the 'load family into Revit' function called from outside the Idling event. After moving this call into the Idling event handler all worked fine. :-)

Reload Add-in for Debug Without Restart

We explored and learned a lot of interesting areas during the DevLab at AU on Tuesday last week.

One recurring theme is how to effectively debug an add-in without having to restart Revit and reload the entire model each time a change is made to the source code.

A long, long time back, right in the beginning of the Revit .NET API, it was briefly possible to use the Visual Studio Edit and Continue feature for that. That was obviously an absolutely perfect solution. Alas, those times are past, and unlikely to return. I almost find it hard to believe I am not imagining things.

There are in fact several other known solutions to this problem, which I would classify as follows:

• Stupid: set up the Revit project and Visual Studio debug settings to bring you to the exact required debugging position and context in one F5 'start debugging' click. Every time a code modification is required, simply stop debugging, modify the code, recompile and restart Revit. That is the approach I use myself, since I can get by working in absolutely minimal test models.
• Cool: use an interactive scripting language such as Python or Ruby. In fact, the wish be able to modify the API code interactively without requiring the tedious recompile and reload cycle was one of the main motivating factors in implementing the latter. The use of this functionality is obviously just a side effect of the much larger main advantage of being able to play interactively with the code in complete freedom, since it is interpreted on the fly and no compilation at all is required.
• Effective and laborious: convert the code to be debugged to a macro and use the built-in SharpDevelop IDE. This means that you convert the part of your add-in that your are debugging and modifying to a macro. The rest can be left as a compiled DLL. The two components can communicate with each other. When finished debugging, you move the code out of the macro environment into the external DLL again.
• Efficient: use the AddInManager and attach to process to reload repeatedly, with compile and edit cycles.

I already described all three of the solutions not involving Python and Ruby in an earlier discussion on debugging an add-in without restarting Revit.

Melissa Manalac of S-frame was making such efficient use of the AddInManager approach at the DevLab that I asked her to document it for you once again.

She points out that James LeVieux already summarized the process in his comment on that discussion:

Here are the required steps:

1. Start Revit 2013.
2. Before coding, make sure all processes are detached.
3. After coding, rebuild your solution and attach to the Revit process.
4. In Revit, go to the Add-Ins tab > Add-In Manager and reload the desired add-in DLL.
5. Run desired external command.
6. Repeat steps 2 to 5.

You also need to be aware that the AddInManager requires the external commands it loads to use manual transaction mode. This is no significant restriction, since automatic transaction mode is not recommended anyway.

Here are some screen snapshots to further clarify these steps:

1. Start Revit 2013.

2. Before coding, make sure all processes are detached:

3. After coding, rebuild the add-in solution and attach to Revit process.

Rebuild solution:

Attach to process:

Select the Revit.exe process:

4. In Revit, go to the Add-Ins tab > Add-In Manager and reload the desired add-in DLL.

Launch the Add-in Manager:

Load the add-in DLL:

5. Run the desired external command:

6. Repeat steps 2 to 5 as desired.

Many thanks to Melissa for the detailed up-to-date description!

Source Code Coloriser

As I mentioned quite a while back, I use the Visual Studio CopyToHtml plug-in to copy and paste colour coded C# and VB source code to HTML for my blog posts.

Harri Mattison of Boost Your BIM now pointed out that this utility obviously cannot be used in the built-in Revit SharpDevelop macro environment.

He found this online C# code coloriser tool by Pavel Vladov that is quite nice and can be used instead.

Oh, and I found another one myself, tohtml.com, that supports a huge number of different languages besides C#. Unfortunately, it does not escape all the HTML characters, e.g. '<' remains '<' instead of being converted to '&lt;'.

Extra Transaction or Regeneration Required

Whenever your add-in modifies the model in any way and you wish to query the Revit database, you need to pay careful attention to ensure that you do not retrieve stale or invalid data.

If anything unexpected whatsoever happens, one of the first things to consider is the possible need for a document regeneration or additional separate transactions between steps.

These kinds of issues arise frequently.

I discussed adding an extra transaction to modify beam parameters and add openings to it and to create an opening in a slab.

Sometimes a simple document regeneration is also sufficient, e.g. to set the width of a newly created TextNote.

Here are two more typical examples:

• Extra transaction required after loading tag
• Extra regeneration required to populate materials

Extra Transaction Required After Loading Tag

Here is an issue raised by Max, Maciej Szlek, who already contributed code to help distinguish MEP fitting shapes:

Question: I have a duct system and want to attach my tag to its elements, using the code to set a tag type. I tried something like this:

  doc.LoadFamilySymbol(
    [my_tag_family.rfa],
    [type_name],
    out tagType);

  IndependentTag tag = doc.Create.NewTag(
    doc.ActiveView,
    element,
    true,
    TagMode.TM_ADDBY_CATEGORY,
    TagOrientation.Horizontal,
    XYZ.Zero);

  tag.ChangeTypeId(tagType.Id);

This code works fine in some projects, whereas in others Revit throws an InvalidOperationException saying that there is no tag available in the call to the NewTag method. The behaviour seems to vary between different projects and on different elements.

How can that be?

Answer: Have you tried either regenerating the document or placing the tag symbol loading and the tag creation calls in separate transaction, committed individually?

Response: Problem solved. As it turns out, the Revit project needs to have some suitable tag type loaded before calling NewTag. Your transaction hint was very helpful. My earlier code was not enough as it stands. It actually requires separate transactions to load the tag type and add a new tag if there was no other tag loaded before. I did not previously know what Revit meant by 'there is no tag available'.

Furthermore, I was initially using automatic transaction mode for this command, thinking that would free me from worrying about any transaction handling myself at all. I now learned that the automatic transaction mode does not enclose each action in a separate transaction, but wraps all executed functions in the whole external command into one single one. In this case, such an approach is not usable at all.

Thank you for a very useful API lesson :))

Answer: Yes, I already mentioned that automatic transaction mode is unofficially deprecated, and manual mode is recommended for all cases nowadays. Automatic transaction mode is considered obsolete.

Arnošt Löbel's AU class on Core Frameworks in the Revit API provides more details on this topic.

Many thanks to Max for raising this issue and verifying that the solution works!

Extra Regeneration Required to Populate Materials

One of the issues we took a look at during the DevLab at AU last Tuesday was the list of materials attached to a newly duplicated symbol.

At first glance, it appeared that a duplicated family symbol had zero entries in its list of materials, whereas the original symbols material list was correctly populated.

On further exploration, we discovered that this is another case of retrieving stale data after a model modification.

The behaviour is easily rectified by a call to regenerate the model after the symbol duplication.

Here is the final implementation of the external command implementing to test the issue. It expects a structural steel column to be pre-selected, which is a family instance whose associated symbol has exactly one entry in its materials list. We duplicate the symbol. This requires defining a new name. To simplify repeated testing, we generate a new name by simply appending the clock tick counter to the original one. Directly after the call to Duplicate, the new symbol's material list has zero entries, which makes no sense for this kind of symbol. A call to Regenerate fixes that:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  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;
    Selection sel = uidoc.Selection;
    FamilyInstance inst = null;
 
    if( 1 == sel.Elements.Size )
    {
      foreach( Element e in sel.Elements )
      {
        inst = e as FamilyInstance;
 
        break;
      }
    }
 
    if( null == inst )
    {
      message = "Please select one "
        + "single structural column";
 
      return Result.Failed;
    }
 
    using( Transaction tx 
      = new Transaction( doc ) )
    {
      tx.Start( "Duplicate Symbol" );
 
      FamilySymbol symbol = inst.Symbol;
 
      string name = symbol.Name 
        + DateTime.Now.Ticks.ToString();
 
      int nMaterialsBefore 
        = symbol.Materials.Size;
 
      symbol = inst.Symbol.Duplicate( name ) 
        as FamilySymbol;
 
      // The model is in a temporary state that does 
      // not make sense. Regenerate to clean this up.
 
      int nMaterialsAfter 
        = symbol.Materials.Size;
 
      doc.Regenerate();
 
      nMaterialsAfter = symbol.Materials.Size;
 
      Debug.Assert( 
        nMaterialsAfter.Equals( nMaterialsBefore ),
        "why does the material get lost, please?" );
 
      tx.Commit();
    }
    return Result.Succeeded;
  }
}

For completeness' sake, here is DuplicatedSymbolLosesMaterial.zip containing the complete source code, Visual Studio solution and add-in manifest of this little test command.

AU Classes on Python, UI, Server and Framework APIs

Thursday was another very full and fruitful day at AU. I gave my third and last class, the most exciting one in my eyes, on some UI and integration aspects. I was unable to attend Iffat May's class introducing Python and using it in Revit and Vasari via RevitPythonShell, but I love her material so much I am including it anyway. Adam Nagy presented a class addressing cloud and mobile development and the Revit Server API. Finally, Arnošt Löbel provided a peek behind the scenes and into the depths of the fundamental frameworks underlying the Revit API.

Here they are in chronological order:

1. CP3837-L Scripting with RevitPythonShell in Vasari by Iffat May.
2. CP4107 Let's Face It: New Revit 2013 User Interface API Functionality by Jeremy Tammik.
3. CP3093 My First Cloud/Mobile App with Revit Server by Adam Nagy.
4. CP3426 Core Frameworks in the Revit API by Arnošt Löbel.

I am including the class materials below, for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

1. CP3837-L RevitPythonShell in Vasari

Iffat provides an entire introductory tutorial to the Python programming language, and then shows how to apply it to solve a number of useful tasks in Revit and Vasari. She makes use of Daren Thomas' Revit Python shell, originally implemented for Revit 2010, then for Vasari, Revit 2012 and Vasari 2.1, and now available for Revit 2013.

RevitPythonShell introduces interactive scripting ability to Revit and Project Vasari. Designers now have the ability to interactively design and manipulate Revit elements using algorithms and computational logic. The class explores the Python structures, variables, data types, and flow control, and shows how to use them to create scripts to control Revit elements dynamically.

• Handout
• Presentation
• Sample code and models

2. CP4107 Revit 2013 User Interface API

This class takes a deeper look at the new user interface and add-in integration functionality provided by the Autodesk Revit 2013 API. It covers 2013 features including Options dialogue custom extensions using WPF components, subscription to Revit progress bar notifications, embedding and controlling a Revit view inside an add-in dialogue for preview purposes, the new drag and drop API, and the UIView. This class is complementary to and expands on CP3272, a Snapshot of the Revit UI API:

• Document management and View API
• Revit progress bar notifications
• Options dialogue WPF custom extensions
• Embedding and controlling a Revit view
• UIView and Windows coordinates
• Drag and drop

From my point of view, one of the most exciting new features provided by the Revit 2013 UI API is the possibility to correlate between Windows screen device coordinates and Revit model coordinates provided by the UIView class, which I used to examine and implement my own Revit tooltip, which also makes use of the new ReferenceIntersector class and Idling event. This has never previously been possible. Now you can do anything you like using the Windows API and connect that intelligently with the underlying Revit model.

• Handout
• Presentation
• Sample code

3. CP3093 Cloud/Mobile App with Revit Server

This class has two objectives: to introduce you to the Revit Server REST API and to introduce you to cloud and mobile programming.

Autodesk Revit Server is a server-based file storage system that we can use to store Revit files. It has a public API that uses simple HTTP known as REST (or Representational State Transfer). REST is a "style" for designing network applications, and it is used to communicate between the server and a client machine. REST is simple, yet powerful enough. You can use it from anywhere where HTTP programming is available: from a desktop, a mobile device or a server-side application. In this class, we discuss what REST is, using the context of Revit Server.

We then go one step further and show you how to create your own REST service in .NET. We implement it as a notification system in the cloud and demonstrate with an Apple iPad/iPhone application in Apple iOS. At the end of this class, you will be able to:

• Use HTTP requests to interact with a REST API
• Programmatically access and modify data available on Revit Server
• Create basic iOS applications in Xcode
• Create a basic REST service in .NET
• Use Apple Push Notification

Here is the detailed handout document:

• Handout

4. CP3426 Core Frameworks in the Revit API

A good understanding of core frameworks in the Revit API is a prerequisite for developing well behaved Revit add-ins. Among the most important ones, the following frameworks play key roles in most applications:

• External applications, commands, and events
• Transactions phases
• Regeneration and transaction modes
• Updaters and other call-backs
• Scoped objects and element validity

These concepts have been around for many releases, yet there are still facts about them that may not be completely understood. This class summarizes the necessary basics, and also sheds some light on the behaviour that is normally hidden 'under the hood'. Knowledge acquired during this class will help Revit developers to build more efficient, safer, and robust applications.

• Paper
• Presentation

By the time you read this, I will be sitting in the plane heading back to Europe.

Take care, and walk in beauty.

AU Classes on the View, MEP and Link APIs

Wednesday was my first normal and full AU day, after completing the developer conference and DevLab activities. I was able to attend two interesting classes held by Revit API developers Steven Mycynek and Arnošt Löbel, and present my own Revit MEP API one. Here they are in chronological order:

• CP3133 Using the Revit Schedule and View APIs by Steven Mycynek
• CP4108 Revit MEP Programming: All Systems Go by Jeremy Tammik
• CP3455 Managing Revit Links with the Revit API by Arnošt Löbel

I am including the class materials below, both for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

Schedule and View APIs

Revit 2013 includes a major expansion of the Schedule and View APIs. This class introduces the API for Schedule and Elevation views as well as many methods and properties that apply to all views. Learn how to create and modify these views to help document and display your Revit model.

• Handout
• Presentation
• Sample code
• Sample models

This class should really resolve all those recurring questions associated with the creation of different views once and for all! Take a special deep look at Steve's multitude of useful utility classes in the sample code.

Revit MEP Programming

This class shows how to work programmatically with Revit MEP models. It provides an overview of the entire Revit MEP API with specific focus on the major enhancements in Revit 2013. The most important 2013 feature is the routing preference functionality. An overview of the available samples is provided. All MEP domains including HVAC, electrical, and plumbing are addressed. It shows how to analyse existing systems and create new MEP models from scratch; covers mechanical and electrical system traversal; display of system hierarchies in a tree view; components such as circuits, ducts, pipes, fittings, connectors, cable trays, and conduits; and automatic calculation and sizing based on room and space requirements.

• Handout
• Presentation
• Sample code

Managing Revit Links

This class explains common pitfalls working with links and how to avoid them. It details the creation of Revit link types and instances, and recommends how to easily check or modify the parameters of links. Material describing ways to inquire for data about the various types of external files, including Revit links, is included. It concludes with an overview of a larger Revit link API application – the eTransmit add-in, which enables users to move an entire package of Revit files while maintaining relationships with all linked files.

• Presentation
• Sample code and models

Implementing a BIM Business Transformation

Unrelated to any direct programming topic, here is a white paper on implementing a BIM business transformation that is of interest to visionaries and decision makers and neatly complements the recently released BIM for Infrastructure one.

The Champions Roundtable at AU

Tuesday we held a DevLab at AU successfully exploring and resolving a bunch of interesting issues. I hope to get around to documenting and sharing some of them soon, before being overwhelmed by other new exciting stuff. The most pressing priority first, though: sharing the notes from the Revit API roundtable session.

My first session at AU was a very pleasant, comfortable and fun one, being a roundtable providing a free-for-all exchange of questions, views and feedback between the audience and a bunch of Autodesk employees. The Autodesk side included developers creating the Revit API, ADN developer supporters supporting people in making use of it, and consultants who actually use it themselves. The audience was you guys.

We tried to keep the questions and answers short and to the point, and I tried to take notes of everything said. They are provided below, only very slightly edited for readability, and possibly cryptic for those of you who did not attend the session. I wish you some enjoyable head-scratching trying to decipher what we actually meant.

Before we dive into the notes, here are its AU catalogue entry and a very few slides listing the goal of this meeting and the panellists answering the questions:

CP4109 – Revit API Round Table: Meet the Champions

Class Summary

• Interact with a panel of Autodesk Revit API experts
• Ask questions and discuss topics of your choice
• Get to know the people who shape the APIs you work with better
• Explain your views, ideas and problems directly face to face

Learning Objectives

At the end of this class, you will have

• Interacted with a panel of Autodesk Revit API experts
• Asked questions and discussed topics of your choice
• Got to know the people who shape the APIs you work with better
• Explained your views, ideas and problems directly face to face

Panellists

• Arnošt Löbel, Revit Developer
• Augusto Gonçalves, ADN
• Jeremy Tammik, ADN
• Miroslav Schonauer, Consulting
• Saikat Bhattacharya, ADN
• Steven Mycynek, Revit API Engineer

Learning More

• Revit Developer Center: DevTV and My First Plugin Introduction, SDK, Samples, API Help
• Developer Guide and Online Help
• API trainings, webcasts and archives > Revit API
• Discussion groups > Revit Architecture > Revit API
• API training classes
• ADN AEC DevBlog
• The Building Coder Revit API Blog
• ADN and ADN Open, The Autodesk Developer Network
• DevHelp Online for ADN members

Almost Unedited Notes from the Session

Here are my session notes in a rough and almost verbatim Q&A format:

What is coming up in future versions? We cannot talk about that here. Please join ADN for more info, sign an NDA agreement.

Why are you guys using Macs? No Autodesk or Revit-specific reason.

What are some common themes or requests for API app development? Hard to say, depends on company; high level: getting data from Revit, enterprise wide integration, setting up a BIM enterprise structure, company specific needs...

How can I effectively run a batch operation to open successive work shared Revit files and run an external command on them? Keep track of the processes; expect to handle failure and recovery. What do you want to achieve? You can use journaling, but not recommended. Open file, close file. No problem in theory. We are not leaking any memory. Managed stuff gets garbage collected eventually. To launch command automatically, install an external application and register for the OnDocumentOpenend event. Lots of communication pipelines available, various messaging mechanisms. What do you want to achieve? Export data to SQL, for example. One app doing this in a batch process, download file from Revit server. Ensure that the app provides feedback on what it is doing, log the events, be able to study log file. Maybe 1000 files process well and one of them fails. Saikat created a plug-in of the month which batch processes RVT files to upgrade them to a newer version doing SaveAs; it also logs all events and writes to text file. You can also look at the progress notification introduced in Revit 2013, that provides more feedback

General organisation of elements inside Revit: family dictates behaviour, categories, etc. this limits some things, pretty strict structure. Will this change? No, not significantly. We can take this as feedback.

External RealDWG application creates 3D drawing using Revit API? Develop Revit external application which queries external data source, query it regularly to write feedback... Revit threading model does not allow for directly attaching, need to use some kind of messaging model. An external program cannot directly access the Revit API.

AutoCAD provides the command console allowing data access without GUI... is anything similar coming for Revit? That would be a nice enhancement. Originally there was no API for Revit, it was highly user focused, and the thought was it would never need an API.

It is currently not possible to access the Revit database without opening Revit. What is the reason for that? You are always opening an application to access its complex internal data structures. It may be happening in the background, invisibly. We should be able to provide some kind of RealDWG-like access sometime in the future to RVT as well.

We would like to parametrically change the model to run different energy simulations on it; changing one parameter affects many other ones, creating a new model to export, but I do not want to see the changes, just change the model without visual feedback. How can this be achieved? The Revit model is parametric, you cannot even query it without regeneration, and it is in an invalid state until regeneration, e.g. transaction committed, half-baked until then. You can open documents in the background, then they are not visualised. Call OpenDocumentFile, it opens in the database but not in the UI. Later we added OpenAndActivate, which does both. Regeneration is smart. Revit updates only the minimal set requiring it. If you regenerate twice in a row, the second call does nothing.

Do I need to commit the transaction to ensure the model is correctly updated? Technically yes, but sometimes no. Sometimes the transaction needs to be committed to propagate the changes fully, sometimes simply regenerating is sufficient.

The API is great at customising the ribbon, but a more important aspect of Revit is its parameters, and there is little help there for users. Is there any way to improve this? We looked at putting a real API around parameters. Talk with the product managers, they need to balance requirements. Parameters could definitely be easier to use.

Managing large numbers of large Revit project files, it is difficult to keep everything up to date. Some people create a new local file every day, even update the central file. How stable is the program? Do I need to do anything to protect my model? We only create small test models. Some people create huge files. Stability is getting better all the time; regression tests improve all the time. Best practices improve. Most Revit problems have to do with not following best practice. The Revit API and every add-in always needs to respect best practice, not fight it. Completely different from other CAD systems. Big investment, understand the product and best practice.

Managing Revit server effectively? What are the best practices? It may be ok to update users every year, but painful to do so for servers, it is painful to update servers every year like Revit users. Is Revit server on the same release cycle as the Revit product? What would the alternative be? The file format should not change every release.

Can we edit a group in the API? No, you have to ungroup and regroup. There are some blog posts on this. If multiple instances of the group exist, you have to replace all the instances.

The dynamic updater framework can display a missing updater warning. Can I suppress that? There is an option to suppress that screen. When you register the updater you can set it as optional, so the end user is not bothered by the message if it is missing. Before that option appeared, you could just open the file without the updater, choose to ignore the missing updater, and save the file before sending it to someone else. Now you can control it as the updater implementer.

Some families have options for how they look in different views. Can I make other categories do the thing? Some families will only allow plan view. Can you achieve this from the UI? No. In that case you cannot do it programmatically either. Now I have to go and tag every damper in the section. The aim is to provide API access to everything available in the UI.

Issues with shared families. A family with no instances placed creates an instance of its geometry even if it is not placed. If an instance is placed which conflicts with the geometry, it can cause a 'cannot make type' error. How can this be worked around? This is a regeneration issue. Query noted.

How can I check what Revit is doing? Use the progress notification, which tells you all the sub-steps happening during transactions. You might have to do some primitive benchmarking.

Are processes that occur during regen behind the scenes documented in the journal file? Some stuff is, it is up to the individual programmer. They can check a journal coming back from a customer. The content may be cryptic and does not explain. Sometimes debugging significantly impacts performance, of course.

When I open a transaction on a work shared model, should I verify that all elements can be modified before committing the transaction? I don't think you can check whether an individual element is modifiable. There was a plan, maybe, for that. This kind of feature has been requested. Currently the transaction will be rolled back. Actually you can check this somehow, maybe.

DesignScript is now integrated in AutoCAD. Are there any plans for providing this in Revit as well? We would like to create parametric masses. DesignScript looks as if it is open enough to be integrated into Revit. No new language integration is simple, but it looks as if it might fit and be useful.

What are the most prominent issues you run across, the most common things that pops up? Install RevitLookup, explore the model. Driving from external process, use Idling event. Daily requests: multithreading, 100% API coverage of worksharing functionality, integration and speed. When we get several similar requests, we blog about them, either on The Building Coder or the ADN AEC DevBlog. Why do you ask this, actually? Just for sharing and discussing here together. Also we keep receiving recurring issues. It helps to know the real good solution. Another common issue: how to get data from Revit and export to Excel or Access, and reimport. It is easy, but customers face many challenges, lots of countrification needs. People coming from other CAD systems and used to the sketch plane modelling and create feature are a bit surprised by Revit family editor and constraints and dimensions etc. It is possible to create a dimensioned family and make it parametric through the API. That is not intuitive, that is a challenge. Take a few steps back, look at how Revit does things, and then reproduce that relationship programmatically. Revit is not mechanical engineering. Understand the UI first, and then move on to API.

Do you follow the Autodesk discussion forums? Yes.

Can I use formulas to establish parametric relations between different families, e.g. if I want the width of family A to be driven by the height of family B? Good question, not currently supported.

Can I access the document warnings? There is the failure API, but no access to the warnings. There are ways to get rid of failures. Install the failure processor at application level. You get called when transaction ends and if there are failures your processor is called and you can decide how to handle them. I get a model and it has 300 warnings in it. Can I get that list? The failure processor does not give you that list? No, probably not. If you go to look at warnings in Revit, you can export that list to a text file. It would be nice to be able to fix warnings such as the 'line off axis', provide tools and options to fix this, or an option to leave it as it is.

Every column I touch is part of a phase and design option. Currently the phase mapping is not part of the Revit API. I run into problems trying to match phases when they differ between linked and host model. We have a link API in 2013 and a list of additions, I think something more will be coming in that area. The goal for the API is to provide 100% access to all end user features. Right now all new features are automatically exposed to the API as well.

C# versus VB? It all goes to the same place. It all compiles to IL and can be decompiled as well.

Dispose is inherited through the class hierarchy from APIObject. Do we need to dispose of all the objects we use? It is probably good practice. It happens eventually through the GC. We have scoped objects, everything with a start and an end, e.g. transaction. If you dispose that, it is automatically ended. The easiest way is to use a 'using' block. You must call Commit, Rollback or Dispose. APIObject is only a very thin wrapper. Dispose does not actually do anything. If you need to clean up memory and access a lot of data from Revit, you may want to call Dispose yourself in between loop iterations, e.g. If you do not call Dispose, Revit will hold on to the object even if GC is called. If you call Dispose, then we let go. When the command ends, everything is disposed. Revit elements can have an unpredictable lifetime. It is always safer to hold on to an element id rather than an element. Native pointers are invalidated. You can test whether an element is invalid. You can modify an element, then delete it, undo the deletion, and the element pointer will go from valid to null and back to valid again. You do not have to refetch the element, actually, Revit handles its validity. The API creates a managed wrapper around the native pointer.

Error reporting. When a user has an error and we do not have all the info. Is there a central file location where more error reporting is available? Beside the journal there is something worksharing related log file, extension 'slog', monitoring activity between local and central, meant for programmers, not customers, that might provide some hints. Same folder as central file.

Insight into eTransmit? Visit Arnošt's AU session on Wednesday.

Unique id? Working with linked files, the unique id can actually be the same for different files. Looking for a view n a linked file, the view in link and host has the same unique id. Element id yes, of course, they only work within the session, and might change due to worksharing session, but unique id should be stable and unique. If you see a duplicate unique id, please report it to us.

What are the coolest projects you have seen? The ruby scripting plugin and its installer. ZoomToAwesome, which basically consists of one single line of code.

A plugin can bring down Revit. This should not happen. Revit builds in protection in the external command framework that should shield Revit and the end user from all misbehaviour. Dynamic updaters as well. App can cause exception within exception, very hard to protect against. We make it as robust as possible, and still try to open up wide and give you all the options. Example: call a command, do something bad, invalid geometry, try to commit transaction, failure handling, try to resolve, you have a failure resolver, this causes another exception, things can get really bad. A point about add-ins, which is a limitation of .NET and Windows: if your add-in uses COM interop and dereferences an invalid pointer, we cannot protect against that. Unsafe code and p/invoke cannot be protected completely.

Reload the keynotes text file from the API. Not supported, sorry.

Building is data. Can we tap into that without dB link? Direct query?

Thank you for a very interesting discussion with numerous insights on both sides! Have fun using the Revit API!

Grand Canyon and AU Arrival

I always try to arrive early in Las Vegas to acclimatise and recover from jetlag before the conferences begin.

I bring my sleeping bag and sleep in the desert. Sleeping in the cold dry winter desert under starlight, watching the sunset, the slow progress of the moon across the sky, the stars rotating over me, is the best acclimatisation I can imagine. I was blessed with some shooting stars during the last night as well.

In previous years, I went climbing in Red Rock during the day.

I always wanted to visit the Grand Canyon, though. After all, it is considered one of the seven natural wonders of the world.

I was loath to face the five-hour drive, though, in the past.

Now I finally did, and it was well worth it. I kept comparing it to a Swiss mountaineering tour. This is like an upside down mountain.

It is very beautiful, huge, overwhelming, spectacular.

I went down the South Kaibab trail, 2213 metres, and up the Bright Angel one, 2093 metres. I slept at the Indian Garden, halfway up again. I carried all my water, with no need to refill or top up at the bottom. I had some left over when I returned to the top again.

Mule trails, autobahn-like trails. Steps. Muscle pain in my calves from the stair-like stepping-stones for days afterwards. Natural formations, stones, unevenness, like in Swiss mountains give you variety; on these mule paths you can just plod on, monotonously, like a New York staircase marathon outdoors. The advantage is that you can enjoy the landscape much better instead of staring at your feet all the time. I did imagine and wonder whether I could do it blindfolded.

I found a penny, from 1968:

A new lucky penny. I wonder how long it has been lying there? It was really hard to see, earth-coloured.

After the long drive back to Las Vegas, I entered the Mandalay Bay hotel for the Autodesk University conference.

I was upgraded to a penthouse suite on the 62^nd floor. It must be at least a hundred square metres in surface, with separate kitchen, sitting room, bedroom, bathroom and two toilets. Four TV screens, two of them over a metre wide. A private lift for the top three floors. All I want to do is sleep, actually.

Unfortunately, that is not so easy, since it is equipped with ubiquitous noise, like on an ocean liner, just like all the other rooms I have ever had here, due to the air conditioning and possibly other machinery as well. I'll need earplugs to be able to sleep here. Luckily I come prepared and have them with me already. I wish at least the conference facilities were a bit quieter, but apparently the art of calculating air conditioning systems to avoid noise has not yet reached these foreign shores.

Oh, I also have a double size bathtub with whirlpool functionality in here. All of me fits in. Judicious folding of legs even allows knee submersion. I lay in it this morning and sang myself a couple of different Happy Birthday songs.

I tried out the whirlpool. It is incredibly noisy. I should probably wear earplugs in the bathtub as well. Felt like being inside some kind of huge roadwork machine.

Anyway, I had a wonderful dinner last night with all my colleagues. It is such a joy to see everybody again. Now we are all raring to go dive into this year's AU adventure. I'll try to keep you posted.

Moving to the Mac

I have been quiet for a whole week now, busy setting up my Mac, learning new functionality, techniques, keyboard shortcuts, editors, you name it.

Under Windows, I was already using quite a number of batch files and command line Unix-style tools, so I am very happy to have a real Unix shell to play with now.

On the other hand, each batch file needs some fixes applied to convert it to a shell script, and every keystroke needs some additional neutrons firing to switch from the Windows habits to new Mac conventions.

Several of my colleagues are also using Macs nowadays, although they seem to be mostly remaining inside a Windows environment and using Parallels to run it on the Mac. I am going native :-)

I installed the Xcode environment to have access to standard development tools like make and gcc, the Komodo text editor, TrueCrypt to manage all my secret stuff, Firefox, Skype, Office, Parallels, and much more.

Some of my own command line tools are in C, others in Python. Everything works fine, so far, many things required some tweaks or cleanup, and much remains to be done.

AU Material Submitted

I managed to keep the deadline yesterday for submission of the Autodesk University material.

For your delectation and the pleasure of online search engines, here is a reproduction of it in its current state.

I may and probably will update it a bit more before the final event, but this should give you a rough idea of everything:

• CP4109 Revit API Round Table: Meet the Champions
  • Tuesday, Nov 27, 5:30 PM - 7:00 PM
  • Handout
  • Presentation
• CP4108 Revit MEP Programming: All Systems Go
  • Wednesday, Nov 28, 1:00 PM - 2:30 PM
  • Handout
  • Presentation
  • Material
• CP4107 Let's face it: New Autodesk Revit 2013 UI API Functionality
  • Thursday, Nov 29, 1:00 PM - 2:30 PM
  • Handout
  • Presentation
  • Material

All done on the Mac :-)

Meanwhile, Joe and Saikat brought a case to my attention and asked me to publish a quick note on it, since the answer is apparently not completely trivial to find:

Determine Whether Project Document is Workshared or Not

Question: I'm creating a utility to copy central (workshared) RVT files to a specific folders on the user laptop to make a local copy, then open it in Revit.

How can I determine whether the RVT file is a central file (workshared) or stand-alone before copying it?

If stand-alone, it would not require copying; it could just be opened in Revit.

It could be opened in memory first, but that would increase the time to eventually open and activate it for work.

I looked into the TransmissionData, but I can find no solution. Is there one?

Answer from Joe: I think BasicFileInfo.IsWorkshared property is what you are looking for.

The BasicFileInfo class can retrieve some metadata file information without fully opening the RVT file in Revit.

This was briefly mentioned between the lines when recently discussing how to detach and discard worksets. I hope it helps to highlight this fact for itself as well.

Create Radial Dimension

Saikat published another example on the AEC DevBlog, showing how to access the sketch of a circular extrusion in a family document and make a call to NewRadialDimension to create a radial dimension.

There, my first blog post completed and published on a Mac.

Now to get back to real work again, gradually, at least for a short period before sinking into the gory mess of conference time.

The Temporary Transaction Trick for Gross Slab Data

Last week I provided an updated version of the CmdSlabBoundary external command to determine a floor slab boundary.

Here is a follow-up to that issue:

Question: The solution provided to retrieve the slab boundary works fine for me if no openings are cut out.

I have a situation where my slabs are cut by openings, however, and I need to retrieve the original uncut gross slab boundary.

Here is an example with two slabs A and B and an opening cutting out part of both of them:

The solution provided retrieves the cut out net slab boundary:

How can I obtain the following original gross uncut slab boundary?

Answer: One way to obtain the unmodified geometry of the slab is to use the temporary transaction trick to temporarily eliminate all openings and other elements affecting its shape.

This technique was used to determine gross material quantities of floors, walls and roofs in the material quantities sample from Scott Conover's Autodesk University 2009 class on analysing building geometry, which was later add to the Revit SDK as the MaterialQuantities sample.

It shows how the transaction handling for the temporary operation can be simply and cleanly encapsulated.

It analyses the material quantities of walls, floors, and roofs, and outputs the result to Excel by implementing the following steps:

1. Collect all roof elements
2. Iterate through each material found in each roof element
3. Find the net volume and area of the material
4. Store the material quantities
5. Write the results to the output file
6. Find the gross material quantities
   1. Start a new transaction
   2. Delete the elements that cut the host (doors, windows, openings)
   3. Find the volume and area for each material
   4. Store the material quantities
   5. Write the results to the output file
   6. Rollback the transaction
7. Repeat the above steps for walls and floors
8. Open the output file in Microsoft Excel

To determine the boundary lines of the floor slab with all opening removed, you could proceed in the same fashion as described in step 6 for obtaining the gross material quantities.

Temporarily delete then openings in a separate transaction, retrieve the original slab geometry, and abort the transaction to restore the original state.

This technique is easy to implement. We reused this method for many different purposes a number of times, e.g.

• Determine host reference
• Material quantity extraction
• Unmodified element geometry
• Object relationships (VB)
• Retrieve all model elements via a temporary 3D view
• Access to sketch and sketch plane
• Retrieve unjoined wall geometry
• Retrieving detailed wall layer geometry
• Unit conversion and display string formatting
• Determine Revit demo mode

Addendum: Arnošt Löbel pointed out that this will not always work. Some modifications require the transaction to be committed before they take full effect. The workaround for that is to enclose it within a transaction group and roll back the group at the end.

Apphack @ AU

Do you have an interesting AutoCAD app you would like to publish?

Will you attend Autodesk University 2012 and would you like to win an attractive prize?

If so, take a look at the APPHACK @ AU Hackathon:

The official rules list some great prizes. Unfortunately, they also restrict the participation to AutoCAD apps, so Revit add-ins are not permissible.

Kean Walmsley provides a a few more details.

PowerPoint Slide Deck Text Extractor Ppt2txt

Here is another longish post that is not directly related to the Revit API, but rather Microsoft Office programming, more specifically PowerPoint. However, the sample material I present at the end is very directly related to Revit programming, so rest assured that all is well and hopefully interesting.

Contents:

1. Slide deck and handout document
2. Slide deck comparison and text extraction
3. Alternative comparison method
4. Ppt2txt usage
5. Ppt2txt implementation
6. Ppt2txt download
7. Formatting in Word
8. Sample run

Slide Deck and Handout Document

The Autodesk University class materials will be due one of these days. The deadline is not exactly looming yet, but definitely and inexorably creeping up.

I still need to finish off the handout for my class CP4107 on the new Revit 2013 UI API functionality, probably the most exciting one of my three AU sessions.

I have the sample code for it assembled, both from the DevCamp presentation in June and the brand new UIView, Windows coordinates, ReferenceIntersector and tooltip discussion.

Normally, I think the handout should be finished before I start creating the slide deck. I think the recommended steps for preparing a class should look like this:

1. Gather experience.
2. Know what you have to share.
3. Create compelling illustrative samples.
4. Summarise the presentation content in a handout document.
5. Create a slide deck to illustrate.

For some reason, however, I sometimes find myself with an existing slide deck in hand, and no handout document yet created.

In that case, I often use the slide deck to create a skeleton handout document by exporting the pure text content of the slide deck and converting that to a document and outline.

In this case, of course, I am aided and abetted in doing this dirty deed by the fact that I already have the finished slide deck from the precursor session at DevCamp.

Slide Deck Comparison and Text Extraction

Another important reason for extracting pure text content from a slide deck is for comparison purposes.

Working on presentations, especially as a group project, I regularly want to find out exactly what changed between one version and another of a given set of PowerPoint slides.

Differences in graphics are often easy to spot, but small changes in the text may also be really important and harder to identify.

Given the pure text content, it is trivial to find and pinpoint them using text comparison tools such as Unix diff and Visual Studio Windiff, of course.

Enter ppt2txt, my very own PowerPoint slide deck text extractor.

I implemented it back in 2007 and have been using it happily ever since.

The thought of sharing it with you guys crossed my mind, so here it is.

Alternative Comparison Method

My colleague Marat Mirgaleev mentioned another way to compare similar slide decks without extracting the text.

The PowerPoint slide deck PPTX format is one of the Microsoft Office Open XML formats, which basically consist of a ZIP compressed archive containing a bunch of XML files and folders.

One of the subfolders contains the slides. Within that folder, each individual slide is represented by a separate XML file. A simple slide by slide comparison of the deck can be performed by comparing the date associated with each one.

Anyway, back to my Ppt2txt text extractor.

Ppt2txt Usage

Usage is simple: you feed it a PPT file, it extracts all the text on all the slides and spits it out in a pure ASCII text file.

By default, the output file path is determined from the input PPT, just replacing the extension. You can use the '-f' option to specify a different output filename or '-' to redirect the output to stdout.

By default, a prefix string 'Title: ' is added in front of each slide title, making it easy to identify and e.g. search and replace the paragraph style of all titles in one fell swoop. If you prefer no such prefix, use the '-t' option to suppress it.

Here is the usage message explaining this a bit more succinctly (copy to a text editor to see the truncated lines in full):

ppt2txt 2.0 * PowerPoint Slide Deck Text Extractor
  (C) 2007-2012 Jeremy Tammik Autodesk Inc.
usage:  ppt2txt [-f textfilename] [-t] pptfilename
  -t: skip adding prefix 'Title: ' to each slide title
  -f: write output to textfilename.txt
      default: pptfilename.txt
      -f-: stdout

Ppt2txt Implementation

Here is the code implementing this:

#region Namespaces
using System;
using System.IO;
using Microsoft.Office.Core;
using Ppt = Microsoft.Office.Interop.PowerPoint;
using PptType = Microsoft.Office.Interop.PowerPoint.PpPlaceholderType;
#endregion // Namespaces
 
namespace ppt2txt
{
  class Program
  {
    /// <summary>
    /// Usage prompt.
    /// </summary>
    static string[] _usage = new string[] {
      "ppt2txt 2.0 * Powerpoint Slide Deck Text Extractor",
      "  (C) 2007-2012 Jeremy Tammik Autodesk Inc.",
      "usage:  ppt2txt [-f textfilename] [-t] pptfilename",
      "  -t: skip adding prefix 'Title: ' to each slide title",
      "  -f: write output to textfilename.txt",
      "      default: pptfilename.txt",
      "      -f-: stdout"
    };
 
    /// <summary>
    /// Constant representing 'True' in Powerpoint API.
    /// </summary>
    const MsoTriState _t = MsoTriState.msoTrue;
 
    /// <summary>
    /// Windows carriage return + linefeed combination.
    /// </summary>
    const string _crlf = "\r\n";
 
    /// <summary>
    /// Prepend a linefeed to every 
    /// non-empty input string.
    /// </summary>
    static string PrependLinefeed( string s )
    {
      return 0 == s.Length ? string.Empty : _crlf + s;
    }
 
    /// <summary>
    /// Append a new paragraph p to the given text s
    /// with a linefeed separator in between if s is
    /// not empty.
    /// </summary>
    static string AppendParagraph( string s, string p )
    {
      if( 0 < s.Length )
      {
        s += _crlf;
      }
      return s + p;
    }
 
    #region Escape unpleasant Powerpoint characters
    //static Encoding _ascii = Encoding.ASCII;
 
    /// <summary>
    /// Remove unpleasant non-ascii characters 
    /// that crop up in powerpoint.
    /// </summary>
    static string normalise_string( string s )
    {
      s = s.Replace( "…", "..." );
      s = s.Replace( '–', '-' );
      s = s.Replace( '‘', '\'' ); // backward apostrophe from powerpoint
      s = s.Replace( '’', '\'' ); // forward apostrophe from powerpoint
      s = s.Replace( ' ', ' ' ); // strange space char from powerpoint
      //
      // quote:
      //
      s = s.Replace( '\u0060', '\'' ); // grave accent   
      s = s.Replace( '\u00b4', '\'' ); // acute accent   
      s = s.Replace( '\u2018', '\'' ); // left single quotation mark      
      s = s.Replace( '\u2019', '\'' ); // right single quotation mark 
      s = s.Replace( '\u201C', '"' );  // left double quotation mark      
      s = s.Replace( '\u201D', '"' );  // right double quotation mark   
      //
      // space:
      //
      s = s.Replace( '\x0b', '\n' ); // vertical tab
      s = s.Replace( '\u0020', ' ' ); // space basic latin
      s = s.Replace( '\u00a0', ' ' ); // no-break space latin-1 supplement
      s = s.Replace( '\u1680', ' ' ); // ogham space mark ogham
      s = s.Replace( '\u180e', ' ' ); // mongolian vowel separator mongolian
      s = s.Replace( '\u2000', ' ' ); // en quad general punctuation
      s = s.Replace( '\u2001', ' ' ); // em quad 
      s = s.Replace( '\u2002', ' ' ); // en space 
      s = s.Replace( '\u2003', ' ' ); // em space 
      s = s.Replace( '\u2004', ' ' ); // three-per-em space 
      s = s.Replace( '\u2005', ' ' ); // four-per-em space 
      s = s.Replace( '\u2006', ' ' ); // six-per-em space 
      s = s.Replace( '\u2007', ' ' ); // figure space 
      s = s.Replace( '\u2008', ' ' ); // punctuation space 
      s = s.Replace( '\u2009', ' ' ); // thin space 
      s = s.Replace( '\u200a', ' ' ); // hair space 
      s = s.Replace( '\u202f', ' ' ); // narrow no-break space 
      s = s.Replace( '\u205f', ' ' ); // medium mathematical space 
      s = s.Replace( '\u3000', ' ' ); // ideographic space
 
      return s;
 
      //using System.Globalization;
      //using System.Text;
      //System.Globalization.UnicodeCategory.
      //s = s.Replace( "", "-->" ); // right arrow
      //s = s.Replace( '', '\'' ); // backquote Unicode characters
      //return Encoding.ASCII.GetBytes( s ).ToString();
      //return _ascii.GetString( _ascii.GetBytes( s ) );
    }
    #endregion // Escape unpleasant Powerpoint characters
 
    /// <summary>
    /// Get all the text from a given Ppt 
    /// shape, delimited by _crlf.
    /// </summary>
    static string GetShapeText( Ppt.Shape shape )
    {
      string s = null;
 
      if( _t == shape.HasTextFrame
        && _t == shape.TextFrame.HasText )
      {
        s = shape.TextFrame.TextRange.Text.Trim();
 
        string[] a = s.Split(
          new char[] { '\r', '\n' } );
 
        s = string.Empty;
 
        foreach( string s2 in a )
        {
          s += PrependLinefeed( s2.Trim() );
        }
        s = s.Trim();
 
        if( 0 == s.Length )
        {
          s = null;
        }
      }
      return s;
    }
 
    static int Main( string[] args )
    {
      // Command line argument values.
 
      string filename_in = null;
      string filename_out = string.Empty;
      bool title_prefix = true;
 
      // Process command line arguments.
 
      int n = args.Length;
      int i = 0;
 
      while( i < n )
      {
        string a = args[i];
 
        if( '-' == a[0] )
        {
          if( 't' == a[1] )
          {
            title_prefix = !title_prefix;
          }
          else if( 'f' == a[1] )
          {
            filename_out = a.Substring( 2 );
 
            if( 0 == filename_out.Length )
            {
              ++i;
              if( i >= n )
              {
                Console.Error.WriteLine(
                  "-f option lacks output filename" );
 
                break;
              }
              filename_out = args[i];
            }
          }
          else
          {
            Console.Error.WriteLine(
              string.Format( "invalid option '{0}'",
                a ) );
 
            break;
          }
        }
        else if( null == filename_in )
        {
          filename_in = a;
 
          if( !File.Exists( filename_in ) )
          {
            if( File.Exists( filename_in + ".ppt" ) )
            {
              filename_in = filename_in + ".ppt";
            }
            else if( File.Exists(
              filename_in + ".pptx" ) )
            {
              filename_in = filename_in + ".pptx";
            }
          }
          if( !File.Exists( filename_in ) )
          {
            Console.Error.WriteLine(
              string.Format(
                "unable to open input file '{0}'",
                filename_in ) );
 
            break;
          }
        }
        else
        {
          Console.Error.WriteLine(
            string.Format( "invalid argument '{0}'",
              a ) );
 
          break;
        }
        ++i;
      }
 
      if( null == filename_in
        || !File.Exists( filename_in ) )
      {
        foreach( string s in _usage )
        {
          Console.Error.WriteLine( s );
        }
        return 1;
      }
 
      // Determine full input and output filenames.
 
      filename_in = Path.GetFullPath( filename_in );
 
      string ext = "txt";
 
      if( 0 == filename_out.Length )
      {
        filename_out = Path.ChangeExtension(
          filename_in, ext );
      }
      else if( !filename_out.Equals( "-" ) )
      {
        filename_out = Path.Combine(
          Path.GetDirectoryName( filename_in ),
          filename_out + "." + ext );
      }
 
      // Open output file and process ppt input.
 
      using( StreamWriter sw
        = filename_out.Equals( "-" )
          ? new StreamWriter( Console.OpenStandardOutput() )
          : new StreamWriter( filename_out ) )
      {
        if( null == sw )
        {
          Console.Error.WriteLine(
            string.Format(
              "unable to write to output file '{0}'",
                filename_out ) );
        }
        else
        {
          string s, title, subtitle, body, notes;
 
          Ppt.Application app = new Ppt.Application();
 
          app.Visible = _t;
 
          Ppt._Presentation p = app.Presentations.Open(
            filename_in, _t, _t, _t );
 
          foreach( Ppt._Slide slide in p.Slides )
          {
            title = subtitle = body = string.Empty;
 
            foreach( Ppt.Shape shape in slide.Shapes )
            {
              s = GetShapeText( shape );
 
              if( null != s )
              {
                if( MsoShapeType.msoPlaceholder
                  == shape.Type )
                {
                  switch( shape.PlaceholderFormat.Type )
                  {
                    case PptType.ppPlaceholderTitle:
                    case PptType.ppPlaceholderCenterTitle:
                      title = AppendParagraph(
                        title, s );
                      break;
 
                    case PptType.ppPlaceholderSubtitle:
                      subtitle = AppendParagraph(
                        subtitle, s );
                      break;
 
                    case PptType.ppPlaceholderBody:
                    default: // e.g., ppPlaceholderObject
                      body = AppendParagraph(
                        body, s );
                      break;
                  }
                }
                else
                {
                  body = AppendParagraph(
                    body, s );
                }
              }
            }
 
            // Retrieve notes text.
 
            notes = string.Empty;
 
            foreach( Ppt.Shape shape
              in slide.NotesPage.Shapes )
            {
              s = GetShapeText( shape );
 
              if( null != s )
              {
                if( slide.SlideIndex.ToString() != s )
                {
                  notes = AppendParagraph(
                    notes, s );
                }
              }
            }
 
            // Write output for current slide.
 
            if( 0 < ( title.Length + subtitle.Length
              + body.Length + notes.Length ) )
            {
              s = ( ( 0 == title.Length )
                  ? ( _crlf + "Slide " + slide.SlideIndex.ToString() )
                  : ( _crlf + ( title_prefix ? "Title: " : "" ) + title ) )
                + PrependLinefeed( subtitle )
                + PrependLinefeed( body )
                + PrependLinefeed( notes );
 
              sw.WriteLine(
                normalise_string(
                  s.Replace( "\n", _crlf ) ) );
            }
          }
          p.Close();
          sw.Close();
        }
      }
      return 0;
    }
  }
}

I reformatted it to minimise the number of truncated overlong lines. Look at the source download below or copy to a text editor to see all the lines in full.

Ppt2txt Download

Here is ppt2txt_2.zip containing the full source code and Visual Studio solution for this utility.

I hope you find it as useful as I do.

Comments and suggestions for improvement are appreciated, as always.

Formatting in Word

One of the ppt2txt options I mentioned above was to turn off the 'Title: ' prefix.

The question is why to implement and turn it on in the first place.

Well, it prefixes each slide heading with a string saying 'Title: '.

Assuming none of my existing text already contains that exact string, I can then search and replace it globally.

In Word, I can event use search and replace to set a specific paragraph style by selecting Home > Replace > Find what: Title: > Replace with: > More>> > Format > Style... > Heading 3 > Replace All:

Next, I replace the same search string by an empty string with no formatting to remove all the prefixes.

I also replace duplicate paragraph end markers by single ones using the search string "^p^p" and the replacement "^p".

Sample Run

Here is the draft material that I am working on for my AU class CP4107 on the Revit 2013 UI API, including source pptx, intermediate txt, target docx and pdf renderings:

• PPTX PowerPoint slide deck.
• PDF rendering of the slide deck.
• TXT pure extracted text.
• DOCX resulting skeleton handout document.
• PDF rendering of the handout, which is what I submit as the final handout for AU participants.

The handout document already contained some boilerplate text at the beginning and end before inserting the slide deck text. I replaced the 'Title: ' prefixes first by the Heading 3 paragraph style and then by empty strings to remove them. I removed all duplicate paragraph markers. That's it.

The PDF renderings of the slide deck and handout document were generated using eDocPrintPro.

My next step is obvious: add some artificial intelligence with domain knowledge, linguistic skills and good taste to create a completely finished handout fully automatically.

Enjoy, please.

Porting an AutoCAD Application

AutoCAD and Revit are very different animals, as we already pointed out a couple of times in the past.

Exaggerating just a little, you might say that Revit manages a BIM and ensures its consistency at all times, so there are no exceptions to anything ever, meaning nothing can be overridden. Moreover, almost all Revit geometry is parametrically driven, so there is no way to tweak the model geometry either, except of course by changing the official parameter values.

This is obviously a challenge to developers with existing AutoCAD applications. Here is another example of some typical considerations of an application developer with an existing full-blown AutoCAD application, wondering whether there is any way to start supporting Revit as well:

Question: We have customers using our software and asking if we could port our AutoCAD.NET application to Revit.

In our current implementation, we override line functionality to display special walls. We need to modify subcomponents individually, manipulate grip points, split them, add more components, etc.

Intersections between walls affect neighbouring walls and their subcomponents.

We have therefore currently overridden grip points, snap points, graphics, properties, a custom ribbon is regenerated then an object is selected and so on.

Is it possible to implement something similar with Revit? I guess we probably need to customize the functionality of some wall type? What is best place to start if this is possible?

Answer: I am afraid that the answer is definitely not that you can simply port your existing application.

The Revit API is completely different from the AutoCAD one.

More than this, the entire underlying principles, workflows and paradigms are utterly different and almost beyond comparison.

In fact, one of the biggest stumbling blocks to learning the Revit API is being caught up in preconceptions coming from AutoCAD or other non-BIM APIs.

In Revit, almost all the functionality you list above cannot be overridden, because Revit manages a building information model, BIM, and ensures that it remains consistent at all times.

The proper approach in Revit would probably be to define an appropriate family and family types.

I am not at all a product expert, though, so I cannot advise you at all about how best to implement your specific model in Revit. You need to consult with application engineers and product experts about that, and above all understand the existing Revit functionality in depth before you even start considering creating an add-in application, which may easily end up reproducing or even fighting against the recommended Revit paradigms and workflows.

What I can tell you with a hundred percent certainty is that your existing AutoCAD application cannot simply be ported to Revit, and that your best approach will almost certainly require reconsidering the whole implementation from scratch.

What I can also say with conviction is that it will probably be well worth your while in the long run to start learning and understanding the Revit BIM concepts and researching how a useful add-in for that domain might look, to enable you to start work on a BIM-compatible implementation, in which you will certainly be able to reuse a lot of your existing know-how and continue supporting your customers as they gradually migrate to BIM usage.

If you have customers knowledgeable in Revit who are interested in cooperating with you to drive such a project, I would take that opportunity with great gratitude if I were you.

Best place to start? Learn the product functionality, and do your best to forget AutoCAD for a moment.

Response: Thank you for a great answer!

I think at this point we have to stick with AutoCAD due the limitations or the concept of Revit. The main interest of our customer in using Revit was using IFC for integration with thermal calculation applications.

Of course Revit would also save us having to implement a number of additional objects like openings, roofs etc. that are not available in AutoCAD.

I believe we will continue implementing the functionality on top of AutoCAD but still continue to research Revit at the same time. Perhaps at some point we could implement some kind of separate editor for our model, maybe using a WPF dialogue user interface that plays with normal walls in Revit. If I read the API documentation correctly, we can still store additional info to wall objects.

Answer: Your approach sounds very feasible and sensible to me.

Implementing additional functionality in a separate WPF dialogue interacting with Revit would work fine.

Please be aware that you can also maintain your existing AutoCAD functionality and access that in the background, invisibly to the user, from your Revit add-in.

For example, you can read the relevant data from the Revit model, process it in the background using your existing application, and display useful results in your own WPF dialogue in a way that supports an efficient Revit workflow. That might enable you to achieve a near perfect solution with little effort.

And yes, absolutely, you can store any additional data you like on walls and any other elements using the extensible storage functionality.

Importing SAT into Revit

People now and then ask about programmatically importing a SAT file into Revit.

You can export a SAT file using the API and import an SAT file from the user interface, simply by going through Insert > Import > Import CAD > ACIS SAT Files.

However, the Revit API Import methods only take options for DGN, DWG/DXF, gbXML, and images.

One obvious workaround is to implement an intermediate step to generate a DWG file from the SAT one.

This can be achieved either using RealDwg or AutoCAD itself, if it happens to be installed on the same machine.

In either case, the description of implementing ACISIN and ACISOUT in .NET might come in handy to achieve this.

ElementTransformUtils and Family Instance Creation May Force Regeneration

If you are facing performance problems generating or manipulation largish models, please be aware that you need to watch out a bit with the ElementTransformUtils class. Some of its methods contain built-in regeneration at the end, which is executed regardless of your other regeneration actions. Family instance creation can also force regeneration at times. As always, some research and lots of benchmarking is advisable.

AU Registration Savings End October 14

The end is near!

Oct 14 is the last chance to save $500 on the Autodesk University 2012 registration.

Prepare thyself and register now.

Hope to see you there!

UIView, Windows Coordinates, ReferenceIntersector and My Own Tooltip

Here is my well-meant contribution to making this the most exciting Wednesday of your entire week.

For the first time in history, the Revit 2013 UIView class provides a possibility to convert back and forth between Revit model coordinates and Windows device screen points.

I imagined making use of that right away when I read about the UIView class, and mentioned it when discussing UIView and Windows device coordinates.

I am still a bit surprised that I have not yet received any questions about these exciting possibilities. Well, anyway, that gives me a chance to finally dive into this exploration free of preconceptions.

Another Revit 2013 topic that I wanted to talk about for a long time is the new ReferenceIntersector class. My previous attempts at publishing anything on it were thwarted by running into some unintended features which have meanwhile been attended to.

Now I can combine both of these topics into a single nice example, presenting my very own tooltips displaying any information I like based on the cursor location in the Revit BIM.

Does that sound cool, or what?

To give you an idea of what I am talking about, here is a two-minute video depicting a sample run demonstrating the final result, with the normal Revit tooltips and my own specialised ones displayed side by side.

To run the demo, I open up the basic architectural sample project, switch away from the perspective view, since add-ins are disabled there, select Level 2, turn on my own tooltips, hover around different elements to compare the Revit tooltip with my own one, and turn off my tooltips again:

Table of Contents

To display a useful tooltip, the user needs to be free to play around in the model.

Simultaneously, my add-in needs to be able to access the Windows cursor location, determine the corresponding Revit model coordinates from it, and query the Revit BIM to determine the information I would like to display.

This calls for an Idling event handler, adding a third topic to the two already mentioned above.

We thus end up with the following list, including hints on the respective approaches, solutions, and helper methods:

• Top-level form and Idling event management: ModelessForm_IdlingEvent.
• Helper methods: GetActiveUiView, GetView3d, ElementDescription.
• Idling event handler:
  • Access Windows cursor location: System.Windows.Forms.Cursor.Position.
  • Determine Revit model coordinates: UIView.
  • Query Revit BIM for information: ReferenceIntersector.
  • Display tooltip: JtTooltipForm.
  • Entire implementation.
• Toggle tooltip on and off commands.
• Conclusion and download.

Before closing, I also mention Saikat's new posts on multi-image naming conventions and text file TaskDialog command links, DesignScript availability on Autodesk Labs, and a nice video of my friend Falk on the Schafberg.

Top-level Form and Idling Event Management

As you hopefully know by now, the implementation to handle the Idling event needs to be really clean and clear and is a little bit tricky.

I strongly suggest basing anything you do on the ModelessForm_IdlingEvent SDK sample.

If you implemented your Idling event handler in any other way in the past, it might be a good idea revisiting it now and comparing notes with that sample.

I based my WinTooltip external application on it, anyway.

It handles all the modeless form interaction in the external application implementation.

In my case, the modeless form is either a Visual Studio designer generated JtTooltipForm or a hand-built JtTooltipForm2.

The external application is instantiated as a singleton instance, and provides public access to that instance so that external commands can access it and use its functionality to show and hide the modeless form.

It implements an internal CloseForm method, public methods ShowForm and HideForm, called by the external commands, and the standard interface methods OnStartup and OnShutdown, like this:

  /// <summary>
  /// Singleton external application class instance.
  /// </summary>
  internal static App _app = null;
 
  /// <summary>
  /// Provide access to singleton class instance.
  /// </summary>
  public static App Instance
  {
    get { return _app; }
  }
 
  /// <summary>
  /// The tooltip form to display.
  /// </summary>
  internal static JtTooltipForm2 _form = null;
 
  /// <summary>
  /// Dispose and null out form.
  /// Return true if it was previously not disposed.
  /// </summary>
  static bool CloseForm()
  {
    bool rc = _form != null;
 
    if( rc )
    {
      if( !_form.IsDisposed )
      {
        _form.Dispose();
      }
      _form = null;
    }
    return rc;
  }
 
  /// <summary>
  /// Create and show the form, 
  /// unless it already exists.
  /// </summary>
  /// <remarks>
  /// The external command invokes 
  /// this on end-user request.
  /// </remarks>
  public void ShowForm( UIApplication uiapp )
  {
    // If we do not have a form yet, create and show it
 
    if( _form == null || _form.IsDisposed )
    {
      // Instantiate JtTooltipForm to use 
      // the designer generated form.
 
      _form = new JtTooltipForm2();
 
      _form.Show();
 
      // If we have a form, we need Idling too
 
      uiapp.Idling += IdlingHandler;
    }
  }
 
  /// <summary>
  /// Hide the form.
  /// </summary>
  /// <remarks>
  /// The external command invokes 
  /// this on end-user request.
  /// </remarks>
  public void HideForm( UIApplication uiapp )
  {
    if( CloseForm() )
    {
      // If the form was showing, we had subscribed
 
      uiapp.Idling -= IdlingHandler;
    }
  }
 
  public Result OnStartup( UIControlledApplication a )
  {
    _app = this;
    _form = null;
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown( UIControlledApplication a )
  {
    if( CloseForm() )
    {
      a.Idling -= IdlingHandler;
    }
    return Result.Succeeded;
  }

Helper Methods

Apart from the top-level management, the Idling event handler does all the rest of the work.

Before we get to the event handler itself, I'll present the three helper methods it uses:

• GetActiveUiView: retrieve the active UIView.
• GetView3d: retrieve the 3D view named "{3D}".
• ElementDescription: return a descriptive text for a given Revit element.

We can get the active document view directly, but need some additional coding to determine the associated UIView, for example like this:

/// <summary>
/// Return currently active UIView or null.
/// </summary>
static UIView GetActiveUiView( 
  UIDocument uidoc )
{
  Document doc = uidoc.Document;
  View view = doc.ActiveView;
  IList<UIView> uiviews = uidoc.GetOpenUIViews();
  UIView uiview = null;
 
  foreach( UIView uv in uiviews )
  {
    if( uv.ViewId.Equals( view.Id ) )
    {
      uiview = uv;
      break;
    }
  }
  return uiview;
}

The ReferenceIntersector constructor requires a 3D view argument in which the ray tracing takes place. In this sample, I assume that a suitable 3D view named "{3D}" is available and retrieve that using one single line of filtered element and LINQ driven code:

/// <summary>
/// Return the 3D view named "{3D}".
/// </summary>
View3D GetView3d( Document doc )
{
  return new FilteredElementCollector( doc )
    .OfClass( typeof( View3D ) )
    .Cast<View3D>()
    .FirstOrDefault<View3D>( 
      v => v.Name.Equals( "{3D}" ) );
}

You can obviously modify this in any way you like and set up a suitable 3D view to suit your specific view setting, sectioning and filtering needs.

The location dependent BIM information displayed in the tooltip can be determined completely freely. In my case, I simply detect what element the cursor is hovering over and use the ElementDescription method to put together a descriptive text for it:

/// <summary>
/// Return a string describing the given element:
/// .NET type name,
/// category name,
/// family and symbol name for a family instance,
/// element id and element name.
/// </summary>
static string ElementDescription(
  Element e )
{
  if( null == e )
  {
    return "<null>";
  }
 
  // For a wall, the element name equals the
  // wall type name, which is equivalent to the
  // family name ...
 
  FamilyInstance fi = e as FamilyInstance;
 
  string typeName = e.GetType().Name;
 
  string categoryName = ( null == e.Category )
    ? string.Empty
    : e.Category.Name + " ";
 
  string familyName = ( null == fi )
    ? string.Empty
    : fi.Symbol.Family.Name + " ";
 
  string symbolName = ( null == fi
    || e.Name.Equals( fi.Symbol.Name ) )
      ? string.Empty
      : fi.Symbol.Name + " ";
 
  return string.Format( "{0} {1}{2}{3}<{4} {5}>",
    typeName, categoryName, familyName,
    symbolName, e.Id.IntegerValue, e.Name );
}

This is somewhat similar to and yet does not exactly match the information displayed by the standard Revit tooltip and other parts of the user interface, as you might have noticed in the video recording.

Idling Event Handler

The Idling event handler implements the following steps, which we first discuss one by one before presenting the entire code in context:

• Access Windows cursor location: System.Windows.Forms.Cursor.Position.
• Determine Revit model coordinates: UIView.
• Query Revit BIM for information: ReferenceIntersector.
• Display tooltip: JtTooltipForm.
• Entire implementation.

Access Windows Cursor Location

Converting from the cursor position retrieved in Windows device coordinates to Revit model coordinates is possible by calculating the relative position in the UIView.

Here is an illustration assuming a screen resolution of 1600 x 1200 with a Revit view located at the rectangle 800,150 to 1500,650, displaying a plan view of part of the Revit model, with model coordinates ranging from 10,40,0 to 220,120,0. The current cursor location is represented by the green spot:

The Windows device coordinate origin 0,0 is at the upper left, and Y values increase downwards, whereas the Revit model coordinate Y values increase upwards.

You can easily query the cursor position in device coordinates on the Windows screen from .NET framework at any time using the System.Windows.Forms.Cursor.Position property:

  Point p = System.Windows.Forms.Cursor.Position;

Determine Revit Model Coordinates

The cursor location is obviously returned in Windows device coordinates, stored in the point (or vector) variable 'p'.

The aim is to determine the location indicated by this point in Revit model coordinates, for example by determining the vector v from the lower left corner of the Revit view to that location.

We can easily determine the relative position of p between the two corners of the UIView in Windows device coordinates by subtracting the lower left hand corner and dividing by the total width and height to obtain the relative width and height location values dx and dy like this:

  UIView uiview = GetActiveUiView( uidoc );
 
  Rectangle rect = uiview.GetWindowRectangle();
 
  Point p = System.Windows.Forms.Cursor.Position;
 
  double dx = (double) ( p.X - rect.Left )
    / ( rect.Right - rect.Left );
 
  double dy = (double) ( p.Y - rect.Bottom )
    / ( rect.Top - rect.Bottom );

From the UIView, we can also determine model coordinates of the view corners. They are stored in a and b, respectively.

Now it is easy to calculate the cursor point 'q' in model coordinates from the two relative values like this:

  IList<XYZ> corners = uiview.GetZoomCorners();
  XYZ a = corners[0];
  XYZ b = corners[1];
  XYZ v = b - a;
 
  XYZ q = a
    + dx * v.X * XYZ.BasisX
    + dy * v.Y * XYZ.BasisY;

Query Revit BIM for Information using ReferenceIntersector Ray Casting

Once we have the model space cursor location 'q', we can calculate a point beyond the model extents (hopefully) from which one can picture the user looking into the model.

The first element intersected by a ray cast from that point in the view direction should be the one we are interested in displaying information about.

Initially, the sample run was a bit boring, because the only element encountered when looking from straight above was always the roof.

I tweaked that to make the example more interesting, not by modifying the model itself – I use the standard architectural basic sample project rac_basic_sample_project.rvt – but by adding a filter to remove all roof category elements from the reference intersector results instead. The exact elements of interest and information to display are entirely up to you and your needs to determine, of course.

The ray casting requires a 3D view to operate in. In this case, I simply pick the one named "{3D}" returned by the GetView3d helper method. You can set up your own view with specific graphics properties, section cuts, and only certain elements visible, if that better suits your requirements.

Here is the code determining the view, view direction and ray origin, setting up the intersector, determining the target element, and defining the tooltip text to display in the variable 's':

  View3D view3d = GetView3d( doc );
 
  XYZ viewdir = view.ViewDirection;
 
  XYZ origin = q + 1000 * viewdir;
 
  // Find all elements:
 
  //ReferenceIntersector ri
  //  = new ReferenceIntersector( view3d );
 
  // Find all elements except roofs:
 
  ElementFilter f = new ElementCategoryFilter( 
    BuiltInCategory.OST_Roofs, true );
 
  ReferenceIntersector ri 
    = new ReferenceIntersector( f, 
      FindReferenceTarget.Element, view3d );
 
  ReferenceWithContext rc
    = ri.FindNearest( origin, -viewdir );
 
  string s = "Element not found";
 
  if( null != rc )
  {
    Reference r = rc.GetReference();
 
    Element e = doc.GetElement( r );
 
    s = ElementDescription( e );
  }

Display Tooltip and the JtTooltipForm class

I originally used the Visual Studio designer to create a simple tooltip form named JtTooltipForm for me, then tweaked that auto-generated code to create one named JtTooltipForm2 myself programmatically from scratch.

Besides the constructor setting up the form and the Label object to display the tooltip text, it also manages an offset from the cursor position at which to display itself, provides a method to set the tooltip text, and overrides the OnShown and OnVisibleChanged methods to react appropriately to position changes:

/// <summary>
/// A tooltip window designed to move 
/// around with the cursor position.
/// </summary>
class JtTooltipForm2 : Form
{
  /// <summary>
  /// The offset from the mouse pointer 
  /// at which to show the form.
  /// </summary>
  public Point Offset { get; set; }
 
  /// <summary>
  /// Tooltip text.
  /// </summary>
  Label _label;
 
  /// <summary>
  /// Set the tooltip text.
  /// </summary>
  public void SetText( string s )
  {
    _label.Text = s;
  }
 
  /// <summary>
  /// Move the window to an offset of mouse pointer.
  /// </summary>
  protected override void OnShown( EventArgs e )
  {
    base.OnShown( e );
 
    Location = new Point(
      MousePosition.X + Offset.X,
      MousePosition.Y + Offset.Y );
  }
 
  /// <summary>
  /// Move the window to an offset of mouse pointer.
  /// </summary>
  protected override void OnVisibleChanged(
    EventArgs e )
  {
    base.OnVisibleChanged( e );
 
    if( Visible )
    {
      Location = new Point(
        MousePosition.X + Offset.X,
        MousePosition.Y + Offset.Y );
    }
  }
 
  public JtTooltipForm2()
  {
    Size = new Size( 200, 20 );
 
    _label = new Label();
 
    SuspendLayout();
 
    _label.AutoSize = false; // the label will not change its height automatically, only width, so switch off AutoSize to wrap text
    _label.CausesValidation = false;
    _label.Dock = DockStyle.Fill;
    _label.Location = new Point( 0, 0 );
    _label.Size = new Size( 35, 13 );
    _label.Parent = this;
 
    AutoScaleDimensions = new SizeF( 6F, 13F );
    AutoScaleMode = AutoScaleMode.Font;
    BackColor = SystemColors.Info;
    ClientSize = new Size( 200, 12 );
    Controls.Add( _label );
    FormBorderStyle = FormBorderStyle.None;
    Name = "JtTooltipForm";
    Opacity = 0.8D;
    ShowInTaskbar = false;
    TopMost = true;
    TransparencyKey = Color.White;
 
    ResumeLayout( false );
    PerformLayout();
 
    Offset = new Point( 10, 0 );
  }
}

You may note that I switched off the AutoSize property. Setting it to true enables the label to automatically expand, and that just means getting wider to fit the text length. The label will not change its height automatically, only width.

A neat trick to wrap text before putting it into the label that I spotted and did not make use of employs a regular expression to do the job:

  WrappedMessage := RegExReplace( 
    LongMessage, "(.{50}\s)", "$1`n" );

Controlling the text and position from the Idling event handler is a trivial two-liner:

  // Move tooltip to current cursor 
  // location and set tooltip text.
 
  _form.Location = p + new Size( _form.Offset );
  _form.SetText( s );

Entire Idling Event Handler Implementation

For better readability, here is the entire Idling event handler implementation in all its glory.

It even includes one slight improvement that is not demonstrated by the ModelessForm_IdlingEvent SDK sample implementation:

If the Revit project is closed while the Idling event is still subscribed to, the UI document may be null. One needs to add a check for that situation as well in the Idling handler, in case the hander relies on an open document.

/// <summary>
/// Idling event handler.
/// </summary>
/// <remarks>
/// We keep the handler very simple. First check
/// if we still have the form. If not, unsubscribe 
/// from Idling, for we no longer need it and it 
/// makes Revit speedier. If the form is around, 
/// check if it has a request ready and process 
/// it accordingly.
/// </remarks>
public void IdlingHandler( 
  object sender, 
  IdlingEventArgs args )
{
  UIApplication uiapp = sender as UIApplication;
  UIDocument uidoc = uiapp.ActiveUIDocument;
 
  if( null == uidoc || _form.IsDisposed )
  {
    uiapp.Idling -= IdlingHandler;
  }
  else // form still exists
  {
    Document doc = uidoc.Document;
    View view = doc.ActiveView;
 
    UIView uiview = GetActiveUiView( uidoc );
 
    Rectangle rect = uiview.GetWindowRectangle();
 
    Point p = System.Windows.Forms.Cursor.Position;
 
    double dx = (double) ( p.X - rect.Left )
      / ( rect.Right - rect.Left );
 
    double dy = (double) ( p.Y - rect.Bottom )
      / ( rect.Top - rect.Bottom );
 
    IList<XYZ> corners = uiview.GetZoomCorners();
    XYZ a = corners[0];
    XYZ b = corners[1];
    XYZ v = b - a;
 
    XYZ q = a
      + dx * v.X * XYZ.BasisX
      + dy * v.Y * XYZ.BasisY;
 
    // If the current view happens to be a 3D view, 
    // we could simply use it right away. In 
    // general we have to find a different one to 
    // run the ReferenceIntersector in.
 
    View3D view3d = GetView3d( doc );
 
    XYZ viewdir = view.ViewDirection;
 
    XYZ origin = q + 1000 * viewdir;
 
    // Find all elements:
 
    //ReferenceIntersector ri
    //  = new ReferenceIntersector( view3d );
 
    // Find all elements except roofs:
 
    ElementFilter f = new ElementCategoryFilter( 
      BuiltInCategory.OST_Roofs, true );
 
    ReferenceIntersector ri 
      = new ReferenceIntersector( f, 
        FindReferenceTarget.Element, view3d );
 
    ReferenceWithContext rc
      = ri.FindNearest( origin, -viewdir );
 
    string s = "Element not found";
 
    if( null != rc )
    {
      Reference r = rc.GetReference();
 
      Element e = doc.GetElement( r );
 
      s = ElementDescription( e );
    }
 
    // Move tooltip to current cursor 
    // location and set tooltip text.
 
    _form.Location = p + new Size( _form.Offset );
    _form.SetText( s );
  }
}

Toggle Tooltip On and Off Commands

To simplify the usage and cooperation with other add-ins, I implemented two trivial read-only external commands calling the external application ShowForm and HideForm methods to toggle my personal tooltips on and off:

[Transaction( TransactionMode.ReadOnly )]
public class CmdTooltipOn : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.ShowForm( 
      commandData.Application );
 
    return Result.Succeeded;
  }
}
 
[Transaction( TransactionMode.ReadOnly )]
public class CmdTooltipOff : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.HideForm(
      commandData.Application );
 
    return Result.Succeeded;
  }
}

Conclusion and Download

I hope you find this as useful as I imagine it might become, and look forward to your feedback.

By the way, I will be talking about this sample and the possibilities it demonstrates along with many other topics in my Autodesk University presentation CP4107 on the new Revit 2013 UI API functionality, probably making this the most exciting one of my three AU sessions.

Here is a current snapshot of the entire source code, Visual Studio solution and add-in manifest of the WinTooltip sample application, together the rest of my CP4107 sample material. The latter is based on my DevCamp Revit 2013 UI API samples.

Here are a couple of other items of interest before I wrap up, related to the Revit API, technology and purely human interst.

DWG and Image Export Naming Convention

Saikat Bhattacharya points out that the naming convention for exporting multiple images follows the one used for DWG export: [FileName]-[ViewType]-[ViewName].[image format].

Displaying a Text File from a TaskDialog Command Link

I recently mentioned the order of TaskDialog command links.

Now Saikat Bhattacharya picked up a related issue, on how to define a TaskDialog command link to open up a text file in the local system.

URLs and local system HTML links work fine out of the box. A text file, however, needs special processing. One way to launch it is by using the Process.Start method in the .NET System.Diagnostics namespace. Saikat provides the source.

DesignScript

A very exciting new technology is now publicly available on Autodesk Labs: DesignScript:

• A powerful scripting language for exploratory programming.
• Managing and distinguishing between a generative description of a design (as a script) and the resulting generated model.
• A language to help designers build and analyze complex geometric models that would be difficult to model with interactive techniques.
• Integrated into a host geometry application (currently AutoCAD).

The designer no longer directly models the resulting design: instead she develops a script whose execution generates the model. This enables a completely different kind of design model to be created. The design process is also different. An apparently minor edit to the script can have a profound effect on the generated model, enabling the exploration of a vast array of alternatives, with much less effort than manual interactive modeling. Here is a five-minute video explanation of Design Computation by Robert Aish for Autodesk University last year:

Kean Walmsley provides a very nice explanation and description of the DesignScript sample he implemented for it together with Robert in 2008 for the Design Computation Symposium and AU mainstage presentation.

Now you can try it for yourself. Unfortunately, DesignScript is not yet available for Revit...

Falk on Schafberg

For something completely unrelated to any technology at all, here is a nice little video of my friend Falk recently when we hiked over the Wildhauser Schafberg (sheep mountain) together, clearly illustrating some basic and sympathetic human and ovine commonalities :-)

AU Registration and ADN Open

Preparations for Autodesk University 2012 on November 27-29 at the Mandalay Bay hotel in Las Vegas are moving along as usual. Registration is now open, and, following Kean's suit, I just registered as well. I already mentioned the classes I will be presenting. More details on these have emerged, since the time plan has been settled and the AU class catalogue is now available:

• CP4107 Let's face it: New Autodesk Revit 2013 UI API Functionality
  Thursday, Nov 29, 1:00 PM - 2:30 PM
• CP4108 Revit MEP Programming: All Systems Go
  Wednesday, Nov 28, 1:00 PM - 2:30 PM
• CP4109 Revit API Round Table: Meet the Champions
  Tuesday, Nov 27, 5:30 PM - 7:00 PM

Before the beginning of the conference proper, I will obviously be attending the ADN conference at AU (6302) on Monday with its AEC breakout session in the afternoon, and happily the late afternoon round table timing on Tuesday will also allow me to spend almost all that day at the DevLab, which is always one of the very most interesting chances to interact directly with developers and their issues.

Autodesk Developer Network Open

Something else that just opened up wide, besides the AU registration, is the Autodesk Developer Network ADN.

In the past, this was reserved for members only, to a certain extent.

As you probably noticed, we recently opened up significantly by launching numerous ADN DevBlogs publishing programming and customisation solutions.

Certain members-only areas remain, such as free access to Autodesk software, preview releases, and direct support.

We are making a large effort to simplify access to the basic knowledgebase content, though, and to support discussion forums.

One goal is that a simple Google search should bring up all available information on Autodesk API questions, and to strongly encourage peer-to-peer support in discussion groups.

Stephen Preston published an announcement introducing ADN Open describing the whole scenario in full, and Kean Walmsley's description adds additional background.

Last and definititely not least, if you just want to jump straight in to the real thing with no further ado, here is the official link to Autodesk Developer Network Open:

www.autodesk.com/adnopen

Updated Revit MEP 2013 Material

I presented the Revit MEP API at the AEC DevCamp in June. In preparation for that, I provided a quick Revit 2013 MEP API overview and migrated and more fully described the AdnRme sample application. I will be presenting on this topic again at Autodesk University in November, so I revisited the material and fleshed out the description of the Revit 2013 changes a bit more. Here is the completed overview:

The Revit MEP 2013 API

The information provided in this section is based on the Revit API help file RevitAPI.chm 'What's New' section. The help file is available as part of the Revit SDK from the Revit developer page (cf. Further Reading at the end).

One of the main Revit MEP 2013 product features is the support for routing preferences. Previously, you could only define one single default elbow, tee, etc. The routing preferences support multiple settings for different materials and sizes.

Routing Preferences

The routing preferences enable you to select your preferred pipe and duct fitting types for various materials and sizes. It can be used to set routing preference policies for end users and query fittings and segments used for given size criteria.

The RoutingPreferenceManager class is used to manage routing preference rules for segments and fittings or query the fitting or segment chosen by Revit for a given size condition. The MEPCurveType class now provides a RoutingPreferenceManager property to access the main routing preferences object for that type. This is currently only support by the derived PipeType and DuctType classes.

Routing preferences choose the first symbol in a rule list matching the given criteria. To ensure that a certain symbol is chosen for a given scenario, you can either set appropriate size criteria, or temporarily re-order the rules using the RemoveRule and AddRule methods.

Programmatic use of routing preferences is demonstrated by RoutingPreferenceTools SDK sample.

Flow Analysis Sections

The MEPSection base class has been introduced to represent duct and pipe sections, i.e. a series of connected elements, mainly for pressure loss calculation. A section includes ducts or pipes, fittings, terminals and accessories, where all section members have same the flow analysis properties, e.g. Flow, Size, Velocity, Friction and Roughness. An element can belong to multiple sections. For example, a tee fitting with three connectors usually belongs to three sections, and a tap will divide a duct or pipe segment into two sections.

Fluid Viscosity and Density

Revit MEP 2013 provides support for more precise temperature dependant friction calculation via the new FluidTemperature class, which can represent viscosity and density properties at a given temperature. The FluidType class has been extended to provide read and write access to a collection of FluidTemperature objects representing the fluid properties at various different temperatures. This collection can be accessed and manipulated using the new AddTemperature, GetTemperature, RemoveTemperature and GetFluidTemperatureSetIteratormethods.

Thermal Properties

Thermal properties have been enhanced in several areas. New properties are provided on the ThermalProperties class, e.g. Absorptance, HeatTransferCoefficient, Roughness, ThermalMass, ThermalResistance. These are available on BIM elements such as wall, floor, ceiling, roof, door, window, etc.

The new ThermalAsset class is provided, representing the properties of a material pertinent to energy analysis. It is specified using the PropertySetElement and SetMaterialAspectByPropertySet classes.

The gbXML export provides more precise control of thermal properties of BIM types. They can be set to use calculated values or pre-defined values from Constructions.xml using the MEPBuildingConstruction methods GetBuildingConstructionOverride and SetBuildingConstructionOverride. The EnergyDataSettings.IncludeThermalProperties flag determines whether thermal information from model assemblies and components is included in the gbXML export.

More Revit MEP API News

Other enhancements include read and write access to spare circuit values, retrieval of more of the localised user-visible display strings for enumeration values.

ConnectorProfileType and PartType enumeration changes, ConnectorElement changes and new static creation methods, more LabelUtils access to localised user-visible display strings, access to panel schedule spare circuit values, a light and light group API,

The new ReferenceIntersector class provides a simpler access to geometric ray-tracing analysis.

Finally, a new external services framework has been put into place. It wraps external service functionality, which can be used to enable encapsulation and replacement of various calculation and analysis workflows, providing a basis for future MEP calculations and structural code checking. It is already in place and fully functional, but not yet used, so no examples are yet provided.

For completeness' sake, here is a draft preview of my AU presentation and handout document.

Update API Assembly References and Wizards

I finally completed my disk clean-up and managed to install the Autodesk Building Design Suite Ultimate 2013. Phew.

Update API Assembly References

That requires me to update the Revit API references in the projects I am working on accordingly.

In order to easily compile all the SDK samples, I always create copies of the Revit API assemblies in the default installation locations for Revit Architecture, MEP and Structure.

Here is the batch file cprvtapi.bat that I used to achieve this after installing the onebox version of Revit 2013:

@echo off
set a=C:\Program Files\Autodesk
set b=Revit 2013\Program

set c=Revit Architecture 2013\Program

copy "%a%\%b%\RevitAPI.dll" "%a%\%c%"
copy "%a%\%b%\RevitAPIUI.dll" "%a%\%c%"
copy "%a%\%b%\RevitAddInUtility.dll" "%a%\%c%"

set c=Revit MEP 2013\Program

copy "%a%\%b%\RevitAPI.dll" "%a%\%c%"
copy "%a%\%b%\RevitAPIUI.dll" "%a%\%c%"

set c=Revit Structure 2013\Program

copy "%a%\%b%\RevitAPI.dll" "%a%\%c%"
copy "%a%\%b%\RevitAPIUI.dll" "%a%\%c%"

set a=
set b=
set c=

Autodesk University Proposals Confirmed and Requested

I was notified yesterday that my AU proposals were accepted, so now I know where I will be spending my next birthday again.

I will be presenting two lectures and participating in one panel with members of the Revit API development team and ADN DevTech AEC workgroup:

• CP4107 Let's face it: New Autodesk Revit 2013 UI API Functionality
• CP4108 Revit MEP Programming: All Systems Go
• CP4109 Revit API Round Table: Meet the Champions

One advantage of these two lectures is that the AEC DevCamp class material can be reused for preparing them:

• 1-4 Revit 2013 UI API enhancements
• 2-7 Revit MEP API

Another advantage is that they have consecutive numbers, making them easier to remember for me :-)

Whereas the live AU proposals have been submitted and processed by now, the Autodesk University Virtual call for proposals just opened and we are eagerly awaiting your submissions.

Updated Revit Add-in Wizards for C# and VB

After finally installing the official release of Revit, I updated my Revit add-in wizard and also re-implemented the VB one.

Basically, all that needed doing was to replace all occurrences of "Revit Quasar RP" by "Revit 2013" in the *.csproj and *.vbproj project files. They occur in the StartProgram and HintPath tags.

The boiler-place code now creates a 'using' statement around the dummy transaction, and I changed the default version strings in the assembly properties from "1.0.0.0" to "1.0.*" to take advantage of the automatically generated build numbers.

For the full description of the wizards, please refer to these previous posts:

• Original introduction, benefits, and usage example for C# and VB.
• Personalised minimal C# version for Revit 2011.
• A short additional usage note.
• 64 bit versions for C# and VB.
• Revit 2012 C# and VB version.
• Updated C# and VB versions placing assembly DLL alongside add-in manifest and including other changes.
• Revit 2013 wizard for C# only.

To install, simply copy the appropriate zip file to the Visual Studio C# or VB project template folder in your local file system:

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