Revit 2011 API: Exceptional Stuff…

(Part of our Revit API 2011 Series)
Forgive the bad pun of a title…

One of the new capabilities in the Revit 2011 API that I haven’t covered yet is some re-working of the way that Revit throws exceptions when you do something it doesn’t like… Whereas in the past, you would have gotten something pretty generic (in terms of the type of exception thrown), in 2011 Autodesk has introduced a variety of very specific Revit exceptions which are thrown. All of these inherit from Autodesk.Revit.Exceptions.ApplicationException:

• ApplicationException
  • ArgumentException
    • ArgumentNullException
    • ArgumentOutOfRangeException
    • ArgumentsInconsistentException
    • FileArgumentNotFoundException
    • InvalidPathArgumentException
  • InternalException
  • InvalidOperationException
    • AutoJoinFailedException
    • FamilyContextException
    • ForbiddenForDynamicUpdateException
    • InapplicableDataException
    • IncorrectProductException
    • InvalidLicenseException
    • InvalidObjectException
    • ModificationForbiddenException
    • ModificationOutsideTransactionException
    • ObjectAccessException
    • RegenerationFailedException
  • IOException
    • DirectoryNotFoundException
    • FileAccessException
    • FileNotFoundException
    • InvalidDataStreamException

So what, you say? An exception is an exception, you say? I disagree – historically it has been painful to try to figure out why something didn’t work in Revit – the exceptions and error messages were not always helpful. And if you wanted to trap specific exceptions, it was pretty weak.

I see this as a great investment on Autodesk’s part in making the Revit API “grow up” to a level of maturity that you can develop strong applications with it. Applications that are easier to control and to diagnose when something goes wrong.

And speaking of diagnosis, there’s one other hidden gem in all these exceptions: the FunctionId. A property on these exceptions which gives you:

• The Revit source code file
• The Revit source code function
• The Revit source code line number

where this particular exception occurred. This strikes me as a great help when I’m sending something in to Autodesk Developer Network… Telling them EXACTLY where in their code something is going bad (and to help me figure out why).

All in all, I appreciate that they took some time to implement this in 2011.

Obscure Developer TechNote:

One thing that I had not been expecting… If you use the “Debug + Exceptions + Thrown Exceptions” in Visual Studio… When a Revit Exception is first thrown, it shows up as an “SEHException” which I believe means an unmanaged C++ exception that is bubbling up. That said, when it actually arrives – it is one of the new types shown above. So you actually have to let it bubble all the way up before you get the benefit of the knowledge of what it is.

Revit API 2011: Ooh Ooh! Pick Me!

(Part of our Revit API 2011 Series)
The Revit 2011 API adds some new ways to interact with elements in the project – through picking. These are all available through the UIDocument.Selection class:

• PickObject (replaces PickOne – pick something in the active view – get back a reference)
• PickObjects – pick multiple objects, click “Finish” when done.
• PickElementsByRectangle – a replacement for “WindowSelect”
• PickPoint – return an XYZ coordinate based on picking on the active workplane

What’s Even Better?

All of the above except for PickPoint support a number of options that go deeper than what we had in Revit 2010 and prior (where you could only support picking full elements):

• Element (as before a whole element)
• Face (a specific face of an element)
• Edge (any model edge)
• PointOnElement (any point on any face or curve)

Further, the methods mentioned above also support a new concept as well – a Selection Filter interface: ISelectionFilter. You can implement ISelectionFilter on any class – it will get callbacks from the pick method to help you control what is allowed to be selected or not:

• a Pre-filter method at the element-level
• a Post-filter method at the reference-level

This lets you easily limit your selections to, for example, “walls” or “exterior walls” or “an inside horizontal top edge of an exterior wall” – the mind boggles.

But Wait, There’s More!

While PickPoint() does not support the options described above – it DOES support a different set of options – Object Snaps!

• Points - Snaps to site points.
• Quadrants - Snaps to quadrant points. For arcs, jump snaps are enabled.
• Tangents - Snaps tangent to an arc.
• Perpendicular - Snaps to perpendicular elements or components.
• Centers - Snaps to the center of an arc.
• Intersections - Snaps to intersections.
• WorkPlaneGrid - Snaps to a work plane grid.
• Nearest - Snaps to the nearest element or component.
• Midpoints - Snaps to the midpoint of an element or component.
• Endpoints - Snaps to the endpoint of an element or component.

Conclusion

The Pick mechanism in Revit has gone from paltry to an embarrassment of riches… I’m not aware of a better Pick API in any CAD system. While there are still a few usability oddities, it’s a vast improvement over 2010.

Revit API 2011: User Interface Changes/Improvements

(Part of our Revit API 2011 Series)
The 2011 API has a variety of interesting enhancements in the ribbon user interface – making it possible to build applications which more closely match the look, feel and capability of native Revit commands (aside from being relegated to the Add-Ins tab).

In 2010, the first Ribbon release, the API already had access to controls such as:

• RibbonPanel
• Pushbutton
• Stacked Pushbutton
• Pulldown Button

What is new in 2011 are a wide variety of new controls and constructs in the ribbon:

• Combo Box
• SplitButton (like a Pulldown button, but it has a default action)
• TextBox
• SlideOut

I created the following sample ExternalApplication which illustrates the different controls now possible:

Figure 1

If the user has added a SlideOut to the RibbonPanel, any additional controls will be only available on the SlideOut panel – available when you click the down-arrow to the right of the Ribbon Panel name.

Figure 2

Note that the slide out is “pinnable” to keep it open. That, combined with the ability to “tear off” the panel (also available in 2010) – makes for some interesting capabilities.

Going Deeper

Beyond the new controls, there are some new capabilities a level deeper:

• Images on Pulldown buttons
• Tooltips and Long Descriptions – to provide more detail on how to run your command.
• Tooltip Images – to provide a graphic for your command – a picture is worth a thousand words

General Availability

Another new feature in 2011 is the ability to have an interface (IExternalCommandAvailability) which implements a check for whether your command should be enabled or disabled.

This is useful if your command should only be available in a 3D View, or only if the user has filled out the setup/preferences dialog, or only if they user has pre-selected a certain category of elements. The command will be automatically enabled/disabled as appropriate.

The TaskDialog

One of the new core capabilities of Windows (starting in Vista) is an upgrade for the venerable MessageBox – called the TaskDialog. Revit now provides the TaskDialog on a platform-independent basis. The TaskDialog has all of the capabilities of the old MessageBox, but also has new and interesting capabilities like:

• Expanded Content (visible when the user expands it)
• As many or few buttons as you’d like (Yes/No/Close/Retry/About/etc).
• Up to 4 Command Link buttons with supporting text.
• Checkbox with verification text
• Footer text

Here’s an example showing a bit of everything:

The code required to do a TaskDialog is pretty straightforward:

TaskDialog td = new TaskDialog("Hello World"); td.MainContent = "This is main content"; td.ExtendedContent = “This is shown on demand”; td.Show(); // or, alternatively – you can use a static method, if you only need the basics: TaskDialog.Show("The Title", "The Main Instruction");

Conclusion

Revit 2011 provides a good number of new controls and capabilities – it’s nice to be able to make applications that have the feel of native Revit commands.

Revit API 2011: The New UI vs. Database Split

(Part of our Revit API 2011 Series)
One interesting development in the Revit 2011 API is the splitting of the single Revit API into two – a Revit User-Interface DLL and a core Revit database DLL.

The “RevitAPI.dll” continues to cover the core database, while the new “RevitAPIUI.dll” covers the user-interface integration. This split extends to the core of the object model as well – while in the past the two primary classes in the API were Application and Document. Now, these classes have been split into:

• UIApplication and Application
• UIDocument and Document

UIApplication has picked up the classes and methods defining the RibbonPanels, the loaded applications, and some UI-oriented events like view changes and dialog boxes. The Application class retains the rest of the core application capability.

UIDocument picks up some of the UI-oriented aspects of the document, like selection, showing elements, and refreshing the active view.

The IExternalCommand and IExternalApplication interfaces live in the RevitAPIUI.dll, so all Add-In DLLs will have to reference the new DLL.

What does it all mean?

I don’t know this for certain, but I’m hopeful that this signals a shift towards an ability to access the Revit model outside of the user interface (similar to ObjectDBX/RealDWG on the AutoCAD side). I’m sure this is a hard feature for the factory to pursue – but here’s hoping that we might see it in a release or two.

What’s New in the Revit 2011 API: New Deployment Methods

(Part of our Revit API 2011 Series)
Deploying commands and applications in Revit up until now has required a mental visit back to the 90’s… You had to create or edit sections within the Revit.INI file – keywords and values (and ugly ones at that). And developing installers which would programmatically add and remove things? Ugh!

Autodesk has heard and finally answered the call on this issue – new in 2011 are XML-based “add-in” files. These new files (typically one for each program) also address some of the issues with permissions – particularly in Vista and Windows 7:

The locations are:

• For “All Users”:
  • Windows XP: C:\Documents and Settings\All Users\Application Data\Autodesk\Revit\Addins\2011\
  • Windows Vista/Windows 7: C:\ProgramData\Autodesk\Revit\Addins\2011\
• For “User-Specific”:
  • Windows XP: C:\Documents and Settings\<user>\Application Data\Autodesk\Revit\Addins\2011\
  • Windows Vista/Windows 7: C:\Users\<user>\AppData\Roaming\Autodesk\Revit\Addins\2011\

For .NET programmers, I would recommend using the Environment.GetFolder() method, where you can specify:

• All Users: Environment.SpecialFolder.CommonApplicationData
• Current User: Environment.SpecialFolder.ApplicationData

A basic Command sample might look like:

<?xml version="1.0" encoding="utf-16" standalone="no"?>
<RevitAddIn>
<AddIn Type="Command">
<Assembly>C:\MyDirectory\MyCommand.DLL</Assembly>
<ClientId>64end01a-5d66-4243-b4544-31429ecae9ed</ClientId>
<FullClassName>Avatech.RoomRenumber</FullClassName>
<Text>Room Renumber</Text>
<VisibilityMode>NotVisibleInFamily</VisibilityMode>
<VisibilityMode>NotVisibleInMEP</VisibilityMode>
<AccessibilityClassName></AccessibilityClassName>
</AddIn>
</RevitAddIn>

I’ll write more about some of the capabilities implied here – but as you can see it represents a big step forward versus the REVIT.INI file (which still works).

More Deployment Help Still… For Installers.

As mentioned above – writing installers for Revit in the olden-days was no picnic. While it’s no picnic in 2011, beyond the new file format, Autodesk has also provided an all-new redistributable DLL – specifically to help developers do installations in .NET.

The “RevitAddInUtility.DLL” can:

1. Provide you information about which versions of Revit 2011 are installed (no much reverse engineering 6+ uninstall registry keys!).
2. Get all existing addins, and manifest.

All in all, there are a variety of new features, capabilities and tools which bring more power and professionalism to Revit AddIn deployment in 2011.

The Revit API – 2011 Edition – What’s New?

For the past few years, I’ve done a series of posts describing what’s new and possible in the latest version of Revit and it’s Application Programming Interface (API). For the uninitiated, the API is the series of mechanisms that Autodesk provides to be able to drive or analyze Revit through programming.

2011 represents a watershed year in the ongoing development of the Revit API. Autodesk has taken the opportunity to re-work the API to better match how Revit works internally – and at the same time to do some amazing new things.

Over the following series of posts, I hope to cover topics such as:

1. Upgrading Existing Revit API commands/applications
2. New Deployment Methods
3. The New UI vs. Database split.
4. New Ribbon Capabilities
5. Element Iteration Changes
6. Ooh-ooh Pick Me! New Selection Methods
7. Dynamic Model Update
8. Event Model Changes
9. RevitLookup: The New RevitMgdDbg
10. Revit AddIn Manager: Almost Edit & Continue
11. What’s New in Element Creation?
12. Exceptional Stuff
13. What Kinds of Applications are Possible Now?
14. And More…

What Type of Element is this? It depends...

(Sorry for the long interruption in blogging - project work was just too heavy to devote time to blogging).





I ran into something interesting yesterday that I had not seen before, and I figured it was worthy of a quick blog post. When doing Revit-oriented development, there are a lot of times when you check the type of an element, and have logic in place to handle that element based on the type.





I was running an application that I had tested before in the past - but it was no longer working - why? And then I stumbled upon an interesting quirk about Revit Architecture versus Revit MEP - something that I had never encountered before:



For certain types such as Pipe, when you ask Revit what type it is - the answer depends on which flavor of Revit you are using. In the sample above, I was interrogating a pipe element. In Revit MEP, it tells you it is a Pipe. BUT - with the same model in Revit Architecture - it tells you that it is an "Element" (Revit's code word for generic elements that don't have any special definition).

The element's category is consistently reported as "Pipes" - but this is just the first time I've ever noticed the type of object being different based on which flavor of Revit you're in. It makes sense that Revit behaves this way - if it did not, you would be exposing a variety of properties and methods for this type of object which should only be available in MEP.

In any case - just be aware - the code that you have that works perfectly one way in MEP could work completely differently in Revit Architecture (and I'm sure this is not the only scenario).

Avatech Utilities for Revit

We finally got our Avatech Utilities for Revit launched a month or so ago. We've added to the list of utilities as well:

• Room Renumber
• Change Case
• Space Update (New)
• Grid Select (New)
• Door Mark Update
• RevitCity Content Browser
• Earth Connector
• Room Phase Copy (New)

Unfortunately - we came to a hard decision... because of the amount of effort it takes to produce, support and update these utilities on an ongoing basis - we have to start charging money for them.

Because we didn't really give any warning on this - we wanted to make this as fair as possible for the 2010 release.

As such, we did the following:

• Avatech Utilities for Revit LITE - this will continue to be free (it's made up of the top four utilities above).
• Avatech Utilities for Revit - will be offered for $395 USD / seat

To take care of all of the people who had previously downloaded the software- we've put in a one-time program to give previous downloaders 5 standalone seats of the software (this was sent via e-mail to the address which was registered during the download). You should have received the second and final notice of this program today (so if you're thinking "where was that?" you might want to check your junk mail folder or something like that).

Finally, there will be other special offers for customers who purchase their Revit software through Avatech (which I realize is only a fraction of the total audience - sorry!).

While this has been a bit tough for us to work through - I'm looking forward to what this means - we should be able to do a better job growing and releasing more utilities in the future.

-Matt

Getting back into the swing of things

I apologize! I've committed the cardinal sin of blogging - not doing it once you got started.

But you know how it is - work gets busy, yadda, yadda, yadda.

In any case - I think it's back to a level where I can blog occasionally... and I'm looking forward to it. Now if I can just remember all the ideas I had while I've been "away".

Autodesk University 2009 Voting

Hi there, readers...

Today is the last day of public voting for the Autodesk University 2009 conference...

I've submitted three classes and I'd REALLY appreciate your vote:

• Deep Dive on the Revit API: Advanced Topics
• The Power of Creation in the Revit API
• Check It! Building Check Plugins for BIMreview

You can vote at:

AU Session Selection

Thanks!

What’s New in the Revit 2010 API: Geometry

(Part of the What’s New in the Revit 2010 API series)

The Geometry area of the Revit API has a few interesting and helpful enhancements in the 2010 version.

Probably the most obvious of the enhancements were made to support Revit’s new conceptual massing capabilities.

HermiteSpline

While there was previously a HermiteFace class to represent the surface – we now have a HermiteSpline element for the splines that can be created (which will probably result in many more HermiteFaces as well – since it only takes one button to go from spline to face).

The HermiteSpline exposes its control points and tangent vectors (nice touch). WARNING: For those of you who have been using Tessellation – like we have on our Earth Connector application – be prepared for an explosion of points as Revit Users start using splines. The 5-point spline shown above tessellated into 287 points… (I probably have to start investing some mental energy in a “reduce” function – because that’s pretty heavy!).

Point

As I joked about in one of the previous posts – Autodesk has finally broken down and added the Point concept to Revit (yes, yes – the XYZ class was there before – but Points are now first class geometric objects).

The reference points in the picture above are part of the spline, but it is possible to create standalone ReferencePoint elements – and the geometry extracted for the reference point is a Geometry point.

I have not yet figured out why it’s important to have a point in the geometry class (since you can get the location directly from the element) – but I’m sure that there is a good reason (consistency, if nothing else, I suppose).

Making Life a Little Easier for You

Historically if you dealt with geometry in the Revit API, you had to brush up on your linear algebra in order to deal with Transformation matrices… For example, a chair might be modeled within a family centered on the 0,0,0 point – but then it gets placed 100 times into a project way out in space. Every instance has a transformation matrix that gets you from the “internal” geometry locations – also known as the “SymbolGeometry” – out to the actual geometry location in the project.

It was even worse when items are nested a few levels deep… I know that, for example, stairs have railings and railings have balusters – and balusters gave me fits for quite some time, being a good number of levels deep.

Autodesk started making this better a couple of releases ago – making it easier to get the transformed version of things – and they’ve taken it another step now.

• Instance.GetInstanceGeometry()
• Instance.GetSymbolGeometry()

(Instance is the Geometry class which represents things like FamilyInstances, and other elements where you need to dig into the definition of things). Both of these methods can optionally take a transform matrix to transform – or just give you the easy answer.

The Hit Reference

I mentioned in “Very Spatial APIs” that the Reference class has been upgraded, mainly to provide the additional information retrieved when shooting rays through elements. The new properties:

• ProximityParameter (how close the hit is to the origin)
• Element (the element that was hit)
• ElementReferenceType:
• MESH
• CUT_EDGE
• INSTANCE
• FOREIGN (from the docs: “The reference is to geometry or elements in linked Revit file.”)
• SURFACE
• LINEAR (curve or edge)
• GeometryObject (the geometry intersected)
• Transform (of an instance, if that’s what was hit)
• UVPoint (U,V parameters of the face, if that’s what was hit)

Summary

This is yet another area with modest but solid improvement in the API in 2010.

What’s New in the Revit 2010 API: Events

(Part of the What’s New in the Revit 2010 API series)

The Event section of the API is one area that I believe developers have been hoping for years to see more… In 2010, Autodesk re-writes a bunch of what is there, adds a few more interesting events – but probably leaves out what you were hoping for…

Before and After

The biggest change, both for the re-written events and the new events is that they can receive callbacks either “before” the action or “after” – which is a very nice, mature feature for events. The “before” events enable you to either (1) fix the model before it is saved/printed/etc OR (2) stop the process and ask the user to do something before the action can be performed.

NOTE: for those of you who are thinking immediately about having “alternative interfaces” for something like Document.SaveAs – I think you’ll be disappointed. So far as I can see all of the “before” events are still fired after the user has completed the dialog (i.e. chosen the new SaveAs target file) – but before it actually happens.

User-Driven and API-Driven

I’m not sure that this was the case in the past – but there are notes with the 2010 release that indicate that the events will fire not just when triggered by interactive usage – but also when triggered by the API. I’m not 100% sure if I love that (once we developers all start using them at the same time) – but we’ll see.

Re-written Events

The following events have been re-implemented:

• Document Creation
• Document Opening
• Document Saving
• Document Save As
• Document Closing
• DialogBox showing (Revit 2010 generally uses the newer style “TaskDialog” from WPF, rather than the old-school “MessageBox” of the last 15 years)

The New Events

The new events are:

• File Export
• File Import
• View Printing
• Document Printing
• View Activating
• Document Save to Central

The last one, saving a document to the central file – has some interesting options – including being able to see the exact properties that have been used for the operation, including:

• Compact Central File
• Relinquish Borrowed Elements
• Relinquish Family Worksets
• Relinquish Project Standard Worksets
• Relinquish User Created Worksets
• Save Local File

That said, alas, they are read-only.

In Summary

I know you were hoping for an element-level event. Autodesk knows that you’d like to have it – but there are apparently some complexities and pitfalls to giving us this power (not the least of which is that we could probably cause never-ending cascading update loops).

All in all, though – the events took a good step forward in terms of the maturity of the API. They’re better thought out than before, and they’ll get more usage.

What’s New in the Revit 2010 API: Import/Export

(Part of the What’s New in the Revit 2010 API series)

Revit 2010 introduces a number of nice enhancements to Importing and Exporting in general – and best of all (for developers, at least) – all of the new capabilities are also available through the API.

The ADSK File Format

One of the new exciting capabilities in 2010 product line revolves around a new file format called an ADSK file (Autodesk Exchange File). This is essentially a zip file, but it contains all the geometry and data that are needed to support DIFFERENT intra-Autodesk software workflows (including, for example – Revit to Civil3D and Inventor to Revit).

Export BuildingSite

The BuildingSite export gathers a wide variety of information useful primarily to Civil3D users, and puts it together in a package that’s easy to transfer.

The content includes:

• dwg files for the footprint, building shell, site plan and property lines.
• Data such as:
• Gross Building Area (based on a selected AreaPlan)
• Building Model data (doors, floors, roofs, etc)
• Project Information, including:
• Location information
• Building Type
• Total Occupancy
• Area per person
• Preview Images

All in all, the amount of XML data is significant in there – so I think we’re just hitting the highlights of what is potentially transferred here…

The API export gives a few options, and I think between what it picks up automatically from the model and what you can specify, you have access to pretty much everything.

Import from Inventor

Import from Inventor is another incredibly important workflow in the greater scheme of things – particularly for the MEP side of things. The ability for manufacturers to model their content in Inventor (with as much detail as they want) – but then to easily produce lower-detail models for use in Revit (including MEP connectors) – that’s powerful.

I haven’t gotten Inventor 2010 installed yet – so I haven’t tried out the export side. The import side seems to be pretty minimal (both in the UI and in code). But the capability is there.

(NOTE: I can’t recall if these are DWG or ACIS solids – but I’m pretty sure it’s not a “new” method of exchange – it’s a better-controlled, better-wrapped version, which includes additional properties and the MEP connectors – but the geometry is probably on the “heavy” side compared to native Revit).

Export to DGN

New with Revit 2010: export to Microstation DGN format. The export options include:

• Export Solids (ACIS or Polymesh)
• Layer Mapping (a layer setting or file)
• DGN Template File

Extract PartAtom

This is equivalent to the new “Publish –> Share with Autodesk Seek” capability. The capability in the UI packages up a piece of content, along with XML to fully describe the types, the parameters, etc – all a part of the PartAtom specification used by Autodesk Seek.

The API version of this only produces the XML file – you’ll have to do the rest yourself. NOTE: This method, ExtractPartAtomFromFamilyFile is on the Application class (not the Document or Family class).

Export GBXML

The GBXML export is much improved in the 2010 User Interface (shown below).

The most important new capability to note here is the “Export Complexity” option. This option will control how much detail is exported to the GBXML model from your Revit model – ranging from only the basics, to how “shading surfaces” are handled, to whether curtain wall mullions are counted as shading surfaces.

The capability for the API to export GBXML was introduced in the prior version – but this has been updated to include the all-important complexity option.

NOTE: This is technically not a change to the “Export” method for GBXML, but a change to the GBXMLparamElement which defines the export options.

Import GBXML

This is a fascinating new addition to the Revit MEP package – the ability to read GBXML back into Revit. While I’m sure that there is probably more workflows that I haven’t quite grasped yet, just being able to use Revit as a GBXML viewer (or see what went out the door as GBXML) seems very useful.

The API exists for import, however, there are currently no options.

New DWF Export Options

The API has been restructured a little around DWF export – shaping up for more robust options in the future (for example, there’s now separate options classes for DWF2D, DWFX2D, DWF3D and DWFX3D) – although they’re mostly the same between DWF and DWFX at present.

In the 2D DWF/DWFx export, they’ve added support for controlling:

• Image Format (compression level)
• ImageQuality
• PaperFormat (size)
• Paper Orientation (portrait or layout)

These additions will help fine tune the DWFs you can create.

Most of the Export Options (DWF and FBX) also now include a “StopOnError” option, so that it won’t keep going if it runs into a problem… sounds like a good idea! :)

Summary

Many of the enhancements to import/export are driven by the core 2010 product enhancements. But it’s so nice to see that they’re investing in keeping the API up with what’s new, rather than lagging a year or more behind.

What’s New in the Revit 2010 API: Very Spatial APIs

One of the most exciting areas of potential API development is checking the building… Whether trying to determine if the egresses are short enough, or whether there is a nurses station close enough to each room, or just understanding how buildings, floors and rooms are modeled – there are a lot of things to check for. Historically, these things have been hard to check for – it was far easier to just look at a drawing than to try and figure it out.

But all that is beginning to change with some neat new APIs in 2010, which give you some tools to help understand the building and spatial relationships between objects.

Shooting Rays

One of the classic CAD solutions to these kinds of problems is “shooting rays” through your model… That is, set a point and a vector, then see what that “ray” hits. This was kind of possible with some creative math prior to 2010 – but it’s both better and easier now in 2010.

The new mechanism:

ReferenceArray =
Document.FindReferencesByDirection( origin, direction, View3D)

The new method returns back an array of references – and the reference class has been upgraded to include:

• Element
• Type of Reference (Surface hit, Element hit, Edge, Foreign, Mesh)
• GeometryObject of the hit
• XYZ location of the hit
• Distance of the hit from the origin (“Proximity Parameter”), UV location of the hit on a surface (if appropriate)

Important Note: The View3d that you specify controls a few things – first, if you’ve got elements or categories hidden, those do not seem to be “hit”… Also, remember that if you’ve got model phases, the ray will follow the phase of the view.

Still, it’s a great new feature for those who are trying to use the API for any kind of building analysis.

Where am I?

The other enhancements in the category of spatial awareness relate to being inside a particular architectural room or MEP space. If you want to test if a given point is in a known room or space, you now have:

• Room.IsPointInRoom( xyz )
• Space.IsPointInSpace( xyz )

Conversely – if you don’t know where a particular XYZ point is at all, you can ask:

• Document.GetRoomAtPoint (xyz)
• Document.GetSpaceAtPoint (xyz)

I think these enhancements are also critical… while FamilyInstances have long known which room they were in – these API enhancements give a great variety of additional power for analyzing buildings.

Copyright (C) 2006-2009, Matt Mason Content provided here does not necessarily reflect the views of Avatech Solutions, Inc.

What’s New in the Revit 2010 API: Element Enhancements

(Part of the What’s New in the Revit 2010 API series)

As with each release of the Revit API, there are a ton of enhancements to the “Elements” area of the Revit API. Whether it’s new capabilities on existing elements, or new Element classes to make Revit elements more identifiable and understandable – enhancements here are a big deal.

Elements and Materials

One of the features I’m most excited about is the new Element/Material part of the API. In the past, trying to do material take-offs with the API was tough – especially if the designers were using Split Faces (which almost everyone does). You pretty much had to export out to ODBC or schedules to Excel in order to extract what you needed. But no more.

This room floor has been divided by a split face – with one of the sides being carpet and the other tile.

In Revit 2010, every Element has a Materials property to show all the materials associated with an element. Further, you can call Element.GetMaterialArea( Material ) or
Element.GetMaterialVolume (Material)

to get the area or volume of material for that element. With this, people trying to do material take-offs through the API should be in far better shape!

Element Hiding

For a number of releases, Revit has supported the hiding of individual elements on a view-specific basis. While great for designers, it did pose occasional challenges for developers. Now, the API offers up:

Element.CanBeHidden ( View v )
Element.IsHidden( View v )
as well as:
View.Hide( Element e)
View.UnHide( Element e)

This should give developers powers similar to what you can do in Revit interactively (that fairness which every CAD developer yearns for :) ).

Family Enhancements

There are few enhancements with Family and FamilyInstance elements:

• Family.IsInPlace (this was possible heuristically in previous releases – but it’s always better to make it obvious)
• Family.IsCurtainPanelFamily (because of the special additional properties – it’s good to know this directly)
• FamilyInstance.IsSlantedColumn (another situation where there are special additional properties)
• FamilyInstance.Space  (similar to familyInstances knowing which Room they reside in, now they know which space they reside in – very useful for MEP families!)

New Element Classes

The following classes are new in 2010:

• Alignment
• AreaScheme (see below)
• BasePoint
• Control
• CurveByPoints
• CurveElement
• DividedSurface (with an amazing amount of depth!)
• Form (representing all of the Family solid content, and also with a huge amount of depth)
• ImportInstance (used for DWG imports, etc)
• ModelText
• PointOnEdge
• PointOnEdgeEdgeIntersection (I think you might need to have a PhD or be Russian to understand this :) ).
• PointOnEdgeFaceIntersection
• PointOnFace
• PointOnPlane
• ReferencePoint
• ReferencePointArray
• SpacingRule (structure and grids)
• SweptBlend
• SymbolicCurve
• TopographySurface (with an “AddPoints” method, no less)

Areas

There appear to be a few enhancements to Area elements that are of note:

• New AreaScheme element (this typically is set for “Rentable”, “Gross” but also apparently has some new BOMA settings for facilities management people)
• Areas have a link to their scheme
• ViewPlans have a link to the AreaScheme (where appropriate)

Dimensioning

Dimensions also seem to have some upgrades in 2010. In particular:

• Dimensions have DimensionSegments
• The “Locked” property (read/write) has been added

Other Miscellaneous Enhancements

A few others that I couldn’t categorize:

• Blends now have access to Profiles, Offsets and VertexConnections.
• CurtainGridLines now have ExistingSegmentCurves
• Grid.ExtendToAllLevels method
• GridNodes
• GBXMLParamElement now has an ExportComplexity object associated with it which contains all sorts of things to control how GBXML is exported (including, for example, how to handle Shading Surfaces).
• ModelCurve now exposes:
• IsReferenceLine
• SubCategory
• TrussCurveType
• Visibility
• Mullion.LocationCurve
• Opening exposes IsTransparentIn3D and IsTransparentInElevation.
• Path3D.AllCurveLoops

Two that I’ll be writing about a little later:

• Room.IsPointInRoom (XYZ)
• Space.IsPointInSpace( XYZ )

A few items seem targeted at making it easier to get geometry references and planes:

• Level now exposes a PlaneReference (to make things easier)
• ReferencePlane.Reference
• SketchPlane exposes:
• Reference
• IsSuitableForModelElements
• View.SketchPlane

Wow. Again – there’s enough in these enhancements, new classes and more to keep us busy for quite some time.

What’s New in the Revit 2010 API: Element Creation

(Part of the What’s New in the Revit 2010 API series)

For some people, the measure of a CAD API is always how many different types of elements it can create. Revit got off to a slow start in this category, but it continues to get stronger.

In this release, the new Revit API capabilities seem divided into:

• A significant amount of new MEP element creation
• A little bit of new Structure / Rebar options
• A significant amount of new capabilities around family content creation.
• A few very interesting things around the new freeform geometry and divided surface modeling in Revit 2010.

All in all, Revit can now create 70-100 different types of elements (depending on how you count the family content-related things).

What’s New for MEP Creation?

Here are the new MEP-oriented creation capabilities:

• Duct
• Elbow
• ElectricalSystem
• FlexDuct
• FlexPipe
• MechanicalSystem
• Pipe
• PipingSystem
• Cross Fitting
• TakeOffFitting
• TeeFitting
• UnionFitting
• Wire

(not being very MEP-savvy myself, I can’t add any real commentary to them other than to say it looks like an impressive list).

What’s New in Family Content Creation?

This whole area is new and exciting…

• Solid Forms
• Blend
• Extrusion
• ExtrusionForm
• Form By Cap
• Form By ThickenSingleSurface
• Loft
• Revolution
• SweptBlend
• Supporting Elements
• Angular Dimension
• ArcLength Dimension
• Linear Dimension
• Radial Dimension
• Symbolic Curve
• Control
• Alignment (this looks interesting)
• Vertex Index Pair (this is a construct which defines how different profiles in a blend link together, I believe)
• Family Symbol Profile
• More Elements
• Openings
• Model Text
• Freeform Modeling / Surfacing
• Curve By Points
• Divided Surface
• Reference Point

A Brief Story on Reference Points

A year or so ago I pinged Emile Kfouri, the Revit Platform Product Manager about why there were no “Points” in Revit (I can’t recall why I needed them – but I do know how old-time CAD people’s heads look like they’re going to explode when I say that they don’t exist). He said “Points are not BIM” – and I came to agree with the statement, in general (not that Lines are BIM – and they were prevalent in Revit still). In any case – while they’re not BIM, they are quite handy for building things – and it’s nice to see them in there.

A Few More…

Finally, there are a couple last additions and changes…

• Rebars defined by RebarShapes
• Hermite Splines (these are one of the building blocks of the new freeform modeling capabilities)
• Plane from Curves
• Topography Surface (Now this looks very interesting – just pass in an array of XYZ points and get back a surface? I haven’t had a chance to try it out yet – but it should be cool!)

Image: a spline-controlled surface with control points that can be dragged/modified.

Summary

All in all, this release presents a great deal of new capabilities around Element creation… certainly enough to keep most of us busy for the next year until Revit 2011 comes out!

What's New in the Revit 2010 API: User Interface

From the (What's New in Revit 2010 API series).

As you may know, Revit 2010 brings the Ribbon-style User-Interface to the world of Revit. Similar to bringing the Ribbon to Microsoft Office or AutoCAD - this has far-reaching effects on how users will navigate Revit.

For better or worse, ExternalCommands and ExternalApplications will be shoe-horned into the new Ribbon concept.

How it Works

First, if you have any "Add-ins" of any kind, the "Add-in" tab is visible in Revit.

Second, any ExternalCommands which previously were on the Tools > External Tools menu are now on the Add-Ins menu under the "External Tools" pulldown-button.

Third, there are a number of "constructs" for how you can customize the ribbon. Unlike AutoCAD's WPF Ribbon UI, you are limited to just a couple of UI elements.

The key elements are:

• RibbonPanel - creating an "area" to contain your application


• Pushbutton - a single Pushbutton command


• PulldownButton - a button which drops down a list of commands


• Separator - basic separation

Both Pushbuttons and PulldownButtons can have large (32x32) icons and small (16x16) icons (not shown above). The large icon is always displayed on the button, while the small icon is only shown if the user adds the button to the "Quick Access Toolbar" - which is always available.

Autodesk also released a 29-page document describing how icons should be created to fit in with Revit (who knew it could be so complicated? :) ).

Existing Applications

The existing APIs that applications use to create both top-level menus or toolbars have disappeared - so you MUST migrate to this approach.

Summary Opinion

While I think that it's great that the Ribbon has come to Revit - I really like it... The UI straightjacket that we've been put in with the UI is a little tight... It would be nice if we could at least do stacked buttons like the rest of Revit.

(Editors Note: Stacked buttons, 2 or 3 high - was added in the API after this was written)

It's also a little unfortunate that everything external is confined to the "AddIns" tab - both because we used to be able to have "top-level" menus, but also because if you have a lot of applications loaded, the real-estate may get crowded.

What's New in the Revit 2010 API: Finally Families!

(Part of the What's New in Revit 2010 API series)





Probably the biggest single improvement to the Revit API in 2010 is a wide variety of enhancements to supporting Revit Families - and it's been a long time coming.


Until now, the support for families has been spotty - for example, you could open family files as documents - but you couldn't see the types inside them - or really do anything with them.

Autodesk has implemented a dizzying amount of capabilities to help with:

• Analyzing Families


• Creating new Families (geometry, parametrics and all!)


• Reading and Writing Family Types, parameters, and even formulas


• Ability to examine Families embedded in projects


• Read/Write Family Element Visibility


• Control the loading behavior of families
  

Personally, after doing a number of Family manipulation projects which had to be done with Journal Files - I'm excited to be back dealing with the API!

Enhanced Document class
The core concept of working with families in the Revit 2010 API is the improved "Document" class. The Document class still represents both Project and Family documents, but it has been enhanced with the following properties and methods:

• EditFamily( family) - similar to context-menu Edit Family command


• FamilyManager (provides access to the types, parameters, and formulas related to the family)


• OwnerFamily - to deal with nested family components
  

The Family Manager is able to do a wide variety of tasks, including full control of adding, removing and renaming types, adding and removing parameters, and setting values and formulas.

Creating Solids

Creation of elements will be covered in more depth in another post - but suffice it to say there is an impressive list of things that you can programmatically create through the new APIs, including:

• Extrusions


• Blends


• Sweeps


• Loft


• Model Text


• Openings


• Revolutions


• Dimensions


• and much more

Visibility Settings

For those of you who are not familiar with content building, one of the most critical topics to "get right" when building content is the visibilty settings:




Each element in a family has visibility settings - both which levels of detail it appears in as well as whether it appears in different types of views. These options are critical to building good content. For example, if you have intricate details in your family, consider if they should only be shown in "Fine" detail views. Also, if you have 3D solid content, one alternative is to NOT show the 3D solid in Plan views - instead, you would use 2D linework in Plan View. These approaches can make a SUBSTANTIAL difference in the performance of Revit - particularly as your building model grows.

While there had been undocumented parameter access to this information before, the new FamilyElementVisibility class makes this information easy to access for each element in a family.

Loading Control
If you've ever written an application that loads families into a project, you may have run into the problem of what happens when the family already exists in the project (particularly if you're using shared families). While the "DialogBox" event controls used to give a poor-but-workable method to suppress Revit's pop-up dialog boxes, the new loading methods give far better control over what happens.

The new LoadFamily method signature:

Family = Document.LoadFamily( string path, IFamilyLoadOptions options );
or
Family = Document.LoadFamily( Document familyDocument, IFamilyLoadOptions options);

The IFamilyLoadOptions, as implemented by the RevitUIFamilyLoad class, give you events for family loading as well as specific behavior control for whether to update the family, and whether to override parameters.


What Can You Do With All This?

There are a variety of capabilities that these features open to you... First of all, I suspect that a variety of new content tools will become available to better manage your content. If you manage a great deal of content, and need to make large-scale changes to content, these features will make it happen.

It IS possible now to extract project families back to RFAs - as well as doing better comparisons than previously possible between "embedded" families and standalone families.

Another big step for Autodesk - they now allow you to use the API insert a DWG file into a family. This had previously been deliberately disabled.

Hypothetically speaking, this means that you could possibly crank out thousands of families based on existing DWGs. But before you consider doing this - let me be among the voices saying - DON'T. Our research indicates that families created using DWG files are fundamentally terrible - they are "heavy", "slow", and "dumb". Almost all firms using Revit have discovered this - and are systematically removing these families from their library. Doing content correctly would be a great other post - and the API now gives you the tools to do things right... Please try to do the right thing!

-Matt

What's New in the Revit 2010 API: General Changes

(Part of the What's New in Revit 2010 API series)
In this post, we'll cover a few quick topics about general changes to the Revit 2010 API.

.NET 3.5 and Visual Studio 2008 SP1

First, the 2010 release has a new platform requirement for developing Visual Studio solutions - .NET 3.5 for users and Visual Studio 2008 SP1 for developers. What does this mean? Several things:

• First, every user of Revit 2010 will have the .NET 3.5 Framework pre-installed, taking care of the pre-requisite issue.


• We can leverage the new technologies available in .NET 3.5, including: Windows Presentation Foundation (WPF) for new look-and-feel, Language Integrated Query (LINQ) for easy access to data from databases, XML or the Revit model.


• Potentially improved deployment options with .NET 3.5 SP1, which resolves some issues that made it difficult to put Revit Plugin DLLs in a centralized network location.

As a developer, I also appreciate the ability to take advantage of the newer features of Visual Studio, including the built-in Unit Testing framework and language features like the new "var" keyword - where Visual Studio figures out variable types for you!

Compatibility with Previous Versions

The nature of the changes to the RevitAPI makes it likely that old applications will be broken in 2010, and will require re-compiling and some changes to make them work with 2010.

It is possible, if your ExternalCommand does not make use of any objects or properties that have changed, that the existing DLL will work - but I'd say that any ExternalCommand of any complexity is unlikely to work without changes.

VSTA 2.0

We will talk about VSTA (Visual Studio Tools for Applications - Microsoft's replacement for VBA - Visual Basic for Applications) and Revit separately - but this version of Revit includes the 2.0 version of VSTA.

What's in a Name?

I've historically been curious about the directory that Revit gets installed in, i.e. "C:\Program Files\Revit Architecture 2009". It always seemed like Revit has held onto the "Revit" folder name while the other Autodesk products were all being standardized to be called "Autodesk _____".

So whether they just finally got around to it, or whether there's deeper intrigue - as of Beta 1, the product is now called "Autodesk Revit Architecture 2010", with the folder name to match.

Ok, this post was a little dry and boring - but I felt like these things had to be said up front... I promise it will get better from here :).

What's New in the Revit 2010 API

One of my favorite blog topics of the year is here - the "What's New" posts, describing the new capabilities of the API (application programming interface) for Revit.


In this series of posts, I'll try to lay out both what's new and what it might mean for you.


Since introducing a small .NET API in Revit 8, the API has doubled in size for each release. Obviously, that's not sustainable the bigger the API gets - and while I'm not sure of the "actual" size increase of the 2010 release, I can say that it's impressive in both size and thoughtfulness.


There is so much new, that we will break up the posts as follows

• General Changes in 2010
  
• User Interface
  
• Finally Families!
  
• Element Creation
  
• Element Enhancements
  
• Spatial Awareness
  
• Import and Export
  
• Events
  
• MEP Enhancements
  
• Geometry Enhancements
  
• Potpourri
  
• What's Still Missing?

Whew! Even breaking it up into this many pieces, these are still going to be some large topics. I'd better get started.

Copyright (C) 2006-2009, Matt Mason Content provided here does not necessarily reflect the views of Avatech Solutions, Inc.