Revit 2008 API: New Creation Capabilities, Newly promoted Objects

In any new release of an API like Revit, it seems like everyone's first question is "what can it create now? can it create everything that I want/need? can it create everything that is in the interactive Revit product?". I however, am too mature to care too dearly about that :)

New Application Object Creation
In the application area, the following can now be created. Most of these are "mathematical" objects which are later used to create actual geometry.

• Ellipse
• NurbSpline
• Select Element Set
• Parameter List Item Array (apparently used in conjunction with some kind of external parameter item list).

New Document Object Creation
In the document element creation, the following objects can now be created:

• Annotation Symbol
• Area Reinforcement
• Beam System
• Detail Curve
• Foundation Slab
• Opening
• Path Reinforcement
• Room
• Tag
• Text Note
• View Plan

Elements Promoted to Concrete Objects
If you've ever scanned a Revit model programmatically, you know that there are probably 30,000 elements in a very modestly sized model. If you look at their types, you know that a large number of those elements show up as "Autodesk.Revit.Element" - meaning that they are an abstract type with only limited information provided about them.

In 2008, a variety of Element types got promoted so that they are represented by full classes. This typically means that you can inquire about more detailed information on these types:

• Blend
• Extrusion
• Sweep
• Revolution
• gbxmlElement
• LinearArray
• RadialArray
• ProjectInfo
• ProjectUnit
• Sketch
• SpotDimension
• TextNote
• ViewPlan
• ViewSection
• ViewSheet
• Leader, LeaderArray

(In this series of postings, I'll continue to provide short commentary on what's new in the Revit 2008 API, and why I think it's interesting).

Revit 2008 API: The Hidden Features

This is probably my favorite topic... the enhancements to the Revit 2008 API which are not obvious - that we've figured out by inspecting behavior rather than inspecting documentation. For those of us trying to accomplish some goal with the API, and improvement in this category is worth just as much as any other feature enhancement...

Rooms and Family Instances
I think a variety of us had tried to do programmatically what Revit did so nicely - keep track of what room a particular family instance was related to. The API and the scheduling guide seemed to have everything we needed: parameters for Room, ToRoom and FromRoom... BUT - they sort of, well, didn't work.

I'm happy to say that as of Revit 2008, everything that I've tried relating to Family Instances and Rooms DOES work:

• Family Instances now have a "first class" "ToRoom" and "FromRoom" property (not just buried in the parameter list). So you can now understand the connection between rooms based on the information in Doors and Windows - NICE!
• Family Instances now have a Room Parameter that works - ie furniture knows what room it resides in (can you say "Asset Management application?").

A couple of additional notes:

• Room objects seem to have many more Parameters than before - I'd estimate 75 parameters on every room, most of them Revit Systems oriented.
• Door Oddity: External Doors have a FROM but no TO room.
• Window Oddity: External Windows have a TO but no FROM room.
• The FamilyInstance/Room relationship is PHASE-AWARE... So if a phase means that the instance is now in another room in a later phase, it can handle that. Wow!

Other FamilyInstance Enhancements

Beyond the myriad of Room-oriented enhancements, there are a number of interactively-oriented enhancements to FamilyInstances, including:

• Properties for CanFlipFacing, FacingFlipped, and a method to actually do the Flip
• Properties for CanFlipHand, HandFlipped, and a method to do the Flip
• Properties and Methods for mirroring and rotating
• A property for "SimilarObjectTypes" - making it far easier to figure out the types that this instance could swap to.
• This is a little out of place, but if you get from the FamilyInstance to the Family, you now have access to deeper Family information such as Solid and Void feature information (I haven't figured out what to do with it yet).

TextNote

While it's a very nice thing that TextNotes can be created in Revit 2008, an API always should be measured on both its ability to create data as well as its ability to read existing data. While the TEXT_TEXT builtin Parameter had been in existence since the beginning - it never worked until now... With the Revit 2008, you can get the text associated with a given note using the TEXT_TEXT parameter, as well as the coordinates of each note through a property. All in all, TextNotes have become very functional!

OK, the next two topics don't really go to the level of hidden in behavior - but they are not well publicized by the "what's new"...

View

Some small but, I think, incredibly important changes were made to the View object (at least if you've tried to work with it before).

• CategoryVisibility - the ability to control category visibility within your view
• Print - print a given view
• Type - the type of view
• GenLevel - very important: the level which generated this view (I think that this is incredibly important for queries... it lets you easily figure out which elements are logically associated to the current view, for example).

Geometric Objects
The geometry objects have been upgraded with a variety of enhanced properties and methods to help with mathematical analysis:

• Curves: Properties like ApproximateLength, isCyclic, Period, etc.
• Curves: Methods like ComputeDerivatives, Distance, Evaluate, Intersect, IsInside, Project
• Faces: Properties like isCyclic, Period
• Faces: Methods like ComputeDerivatives, Evaluate, Intersect, Project, IsInside

These enhancements are critical when you have a geometry-intense application (and you'd rather not re-invent the geometry wheel in your own code).

Summary

I'm sure that this list is far from complete - it's just what we came up with based on some exploration (and in particular reviewing some of our pains from the past). Understanding undocumented behaviors is an important step to mastering the possibilities of the Revit API - and a challenging topic learn. It would be nice if we could come up with a way to share our experiences - perhaps a Wiki or other collaborative solution.

(In this series of postings, I'll continue to provide short commentary on what's new in the Revit 2008 API, and why I think it's interesting).

Revit 2008 API: Working at the Application Level

(stretch) We are finally out of the box!

Prior to Revit 2008, Revit developers were kept in a fairly narrow box... You could only be added to the Tools + External Tools menu, and you could only be run when Revit was in "Modify mode" in the context of a document. The straightjacket was on!

As of Revit 2008, that's now gone... and while you don't have complete carte blanche to work in the application level, there are a variety of critical steps:

ExternalApplication
There is now the concept of External Applications, which are started when Revit starts (and shutdown when Revit shuts down). There are also now application level events for keeping tracking of when documents are created, opened, saved (which are important for a wide variety of applications which try to synchronize BIM data).

User Interface
External Applications can add both menus and toolbars. Menus can be added to the top level, or wherever you would like within Revit.

Document Control
From the application, you're now able to do several key things which were previously impossible:

• Open a specific Revit file
• Start a New Project from a Template (can you say "configurator"!?)
• Start a New Family Document
• Start a New Template

Also at the application level, event trapping is available for things like "OnNewDocument" "OnSaveDocument", "OnCloseDocument"...

(In this series of postings, I'll continue to provide short commentary on what's new in the Revit 2008 API, and why I think it's interesting).

Revit 2008 API: Import/Export of DWG/DWF/Image

One of the things that always seemed like a missing capability of any "end-to-end" kind of automation of Revit was that there was no good way to save your work - or better, save it back to DWG so that the AutoCAD crowd could see your work. I know that we worked with a variety of companies to explore how to do "batch save as DWG" on a nightly basis!

Well - I'm quite happy to say that Autodesk has added Import/Export of both DWG and DWF, as well as import of Image files. I suspect that the Image file import is to help tie Revit to various survey or aerial photo applications (whether it's Google Earth or otherwise).

All of the Import/Export tools come with a wide variety of options setting as well - so you get the sense that the processes have been well thought out.

(The wheels are churning in my mind of all the fun things that are now possible).

(In this series of postings, I'll continue to provide short commentary on what's new in the Revit 2008 API, and why I think it's interesting).

Revit 2008 API: Pick/Select

Oh, how long were we made to suffer? well, perhaps just the 2 years that the API existed - but it was painful! It was impossible to do what seemed most trivial in any other API... to be able to interactively pick something! Nope, not in Revit - if you wanted something picked, you better have had it picked in advance!

But no more! Finally we have two methods which bring a little bit of interactivity to your Revit application:

• Pick (single element)
• WindowSelect()

These methods will give control back to the user to do what they need to do, and add any selected elements to the "SelectedElementsSet". It's limited in that you can't pick a location on the screen - only an element - so while there is still more growth needed here, this represents a good first step.

I think it will also lead to more interactive Revit applications (rather than simple tools) - prior to now you could only work with the pre-selected element set. While this didn't completely preclude multiple pick application scenarios, it certainly made them more awkward.

(In this series of postings, I'll continue to provide short commentary on what's new in the Revit 2008 API, and why I think it's interesting).

Revit 2008 API: What's New

OK, the cuffs are finally off... we're allowed to talk about the Revit 2008 API...
There's so much that's new, I'm going to tackle it in a few different postings, just to spread things out a little bit.

Until now, most developers would have characterized the Revit API as "immature" - but Autodesk has taken a variety of important steps to change my view of the API in this release. The door has been opened for Revit to perform a wide variety of new, more interesting tasks.

Some of the enhancements to the Revit API that I'll cover include:

• Interactive Element Pick/Select
• DWG/DWF/Image Import/Export
• Working at the Application Level
• Printing and Saving
• New Element Creation
• Elements Promoted to concrete classes
• More access to parameter and other data within elements

Anyone who has developed Revit applications or has been thinking about it should be excited at all of the new capabilities to work with in Revit 2008...

Vault 2008 and WSE 3.0

I wrote this post some time ago - when I wasn't sure where the embargo on Vault stood... Now I think I'm in the clear, since at least Productstream has been officially released.

Warning: This is a pretty obscure post - so if you're not involved in Vault development, you might want to pass on this one!

The next version of Vault (2008) is catching up to the latest in Web Standards from Microsoft - Web Services Enhancements 3.0. This will be nice, because WSE 3.0 is the only version that plays nicely with Visual Studio 2005 (leaving developers to jump through some hoops to make things work).

Along the way, I found out about a few issues that make Vault development a little more challenging...

1. Ticket changes
The behavior of the SecurityHeader ticket has been improved... Prior to now it tended to be the same for a long time (I'm not sure if I have it figured out, but you could restart the webserver, and your ticket would still be valid). Now, if you try restarting the webserver, your client's ticket is no longer valid, and you get a SoapException #300.

Working around this scenario means implementing either partial classes or derived classes to be able to store the userID and password, then do a "try/catch" around the actual invoking of the Web Services method... If you get a 300, then you need to try to re-login and then re-Invoke...

2. Download file changes
The signature for the file download has changed - instead of using DIME attachments, the routine just passes back a byte array... However, it's important to note that there is a client config setting called "MTOM" which should be turned on in order to have efficient transfers (if you don't, files will transfer in base-64 ascii mode rather than as binary - making them perhaps 30% less efficient).





3. Time is of the essence
Maybe it was the DST debacle - or maybe either WSE 3.0 or Vault 2008 is more sensitive about time differences between client and server. I know that while doing some wide-area testing, my machine clock was out-of-sync with the Vault 2008 server by about 10-15 minutes - and it would not let me work (buried down deep in the exception was a very clear message about the time tolerance setting). In particular I think it doesn't like it if the SecurityHeader looks like it was generated in the future.


Well - I hope that this was useful to Vault developers out there...