Friday, March 23, 2007

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).


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"...


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).


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).


Adrian Uifalean said...

About the geometric objects, i look over the RevitAPI Help. I found some geometry operation methods for 2d geometry like intersection, projection, but i found no suport for 3d geometry object like solids. It is possible to make solids intersection, union and other geometric operations between solids and other solids or 2d geometric objects?

Kiki said...

Hi Matt,

unfortunately FromRoom.Name/ToRoom.Name will NOT be actualized if the door is FacingFlipped.

Similar to "From Room: Name" in standard door schedules.

Even the FromRoom.Name includes the Name and the Id.

There are still space for corrections.

(Revit Architecture 2008, build: 20070607_1700)

Kiki said...

RoomTo, roomFrom not updating

Matt Mason said...


Yes - I've experienced this as well - although I'm not sure that FacingFlipped has anything specifically to do with it.

I can't recall what I figured out in detail working with one of our AEs. I feel like we figured that the To/From room might have been set by the original placement of the door and the room, but it does not get updated when the door is flipped.

However, FacingFlipped doesn't mean that it has been interactively flipped... It means that the orientation of the door is opposite to the orientation of the hosted wall.

At the end of the day, I wound up resorting to geometric tricks looking at the door orientation and room geometry to come up with a heuristically accurate approach.

Duncan McGregor said...

Hi Matt,

I'm having a look at the

Duncan McGregor said...

Hi Matt,

I'm having a look at the
method in the Revit 2008 API, i am trying to work out what the parameter value is.

What I am trying to do is work out if the center point of an Arc is contained within the bounds of the arc.

This is to extract the curves to then be redrawn to an image for viewing on the web.

If you have a better idea of how to extract wall curves from the drawing.



Matt Mason said...

I'm not sure what your mechanism is for drawing on the web... my approach to problems like that, historically, has been to tessellate curves into roughly equivalent line segments.

In looking at the API - it looks like Edges have a Tessellate method, but "mathematical curves" do not.

I presume though, that if you can use the EndParameter of each end of the Curve to generate a number of points in between.

Would that work?

I'm not sure what you're doing with IsInside()...

Samuli said...

Dear Matt,
I have spent a lot time trying to figure out how to get a door schedule done so that it would give me the swing direction ie left/right -hand value so that I can still use the flip control. No success. Is it possible to call value for this flipHand parameter inside family formulas?
I can't do API.

Samuli said...

Dear Matt,
Door swing ie left/right handed -issue.
Is there a way to get it to the door schedule? And maintain the ability to use flip control.

Matt Mason said...

I'm not aware of any way to get at the Hand/Flip information in a schedule.

At the moment, the API seems the only way to go.

Best Regards,