Revit Structure API & VSTA Overview

Revit Structure provides an Application Programming Interface (API) that allows you to extend the functionality of the product. Starting with Revit Structure 2009, you can use the API to define macros that can be saved with the application or project. For example, you might define a macro to add a grid to your project, to rotate a selected object, or to collect information about the square footage of all the rooms in your structure. Other general examples include:

• Locating and extracting Revit content to external files
• Changing geometry or parameters
• Creating elements
• Importing/exporting external file formats

Macro support is provided by the Revit VSTA plug-in, which you can install in conjunction with your existing Revit installation.

First, let's answer the question: “what are macros, and why would you use them”? Macros are programs that are designed to help you save time, by automating repetitive tasks. Each macro performs a series of pre-defined steps to accomplish a particular task. The steps should be repeatable and the actions predictable.

Revit provides an Application Programming Interface (API) that allows you to extend the functionality of the product. Experienced developers and Autodesk partners may already know that the Revit API lets them add customized commands to the Tools > External Commands menu, or add new menus and toolbars.

In addition to those API extensions, starting in the Revit 2009 release you can use the API to define macros that run in Revit. Unlike external commands and external applications, the macro functionality is available to Revit after you install an “add-in” called Revit VSTA. We will explain the API differences later in this topic, but for experienced developers, note that you do not need to register the macros in Revit.ini, or add RevitAPI.dll as a reference.

VSTA is an acronym for Visual Studio Tools for Applications. It is a Microsoft technology that provides the .NET framework for creating macros in C# and VB.NET based on specific applications. VSTA is the next evolution of Visual Basic for Applications (VBA) that appears in several existing Autodesk applications.

Expect API Changes

It is very likely that the Revit API will change in subsequent product releases. This means that after installing the next Revit release, you will need to edit and rebuild your macros to reflect the API changes.

Revit VSTA Components

To create macros, you must install Revit VSTA on top of your existing Revit installation. The Revit product and Revit VSTA versions must be the same.

You can use the Revit VSTA macro features in all Revit products: Revit Architecture, Revit Structure, and Revit MEP. However, a separate Revit VSTA install, described in this topic, is required for each Revit product in which you want to run macros. In this topic, we refer to any of these products generically as “Revit” without a further qualifier.

Once installed, Revit VSTA provides:

• New items on the toolbar’s Tools menu:
• Tools > Macros > Macros
• Tools > Macros > Launch VSTA IDE
• Macro Manager, a user interface launched by the Tools > Macros > Macros menu option. Macro Manager presents a list of macros you built previously that you can run, edit, or debug (StepInto). Macro Manager also provides options to create new macros using different types of templates.
• An Integrated Development Environment (IDE) built into the product, the Revit VSTA IDE. You can launch it several ways:
• Tools > Macros > Launch VSTA IDE
• From the Macro Manager, by selecting the New, Edit, or StepInto buttons
• Full access to the Revit API.

Workflow Overview: Initial Steps with Macros

The following diagram illustrates the initial steps with Revit VSTA and macro development:

{Revit Structure 2009 User's Guide}

Some New Project Settings

There have been some improvements in the area of project settings. Nothing to call the Vatican about, but still nice improvements.

Suppressing Trailing Zeros and Spaces

You can format project units to suppress trailing zeros (for example, 123.400 displays as 123.4) and suppress spaces (for example, 1’ - 2” displays as 1’-2”).

• Click Settings menu>Project Units, or type the keyboard shortcut UN.
• In the Project Units dialog, select the discipline.
• Click the value in the Format column to change the display value for that unit type. The Format dialog displays.
• Specify Units, if necessary.
• For Rounding, select an appropriate value.If you select Custom, enter a value in the Rounding increment text box.
• For Unit symbol, select an appropriate option from the list.
• Optionally select:

Suppress trailing 0’s :: When selected, trailing zeros do not display (for example, 123.400 displays as 123.4).
Suppress 0 feet :: When selected, does not display the 0 foot value (for example, 0’ - 4” displays as 4”).This option is available for Length and Slope units.
Show + for positive values :: Do I really need to explain this one?
Use digit grouping :: When selected, the Decimal symbol/digit grouping option specified in the Project Units dialog is applied to the unit value.
Suppress spaces :: When selected, suppresses spaces around feet and fractional inches (for example, 1’ - 2” displays as 1’-2”). This option is available for Length and Slope units.

• Click OK.

Decimal Display and Digit Grouping

The decimal display option for project units has changed. When you select the decimal display type, you can also select how to group the digits in the unit value.

1. Click Settings menu>Project Units, or type the keyboard shortcut UN.
2. In the Project Units dialog, select a value from the Decimal symbol/digit grouping list.
3. In the Format column, click the button for the unit you want to use this setting.
4. In the Format dialog, select Use digit grouping.
5. Click OK 2 times.

{Revit Structure 2009 User's Guide}

Rendering Enhancements in Revit Structure 2009

In Revit Structure 2009, the AccuRender® rendering engine has been replaced with the Mental Ray® rendering engine. With this change, Revit Structure 2009 provides an overall higher quality of rendering. Improved lighting effects and more accurate render appearances for materials result in more photorealistic rendered images.

Rendering Workflow Enhancements

The user interface for rendering images has been completely redesigned. Fewer dialogs, a simplified workflow, improved defaults, and clear terminology make it easier for users to generate realistic images with a minimum of effort, even if they have limited rendering experience.

For more experienced users, Revit Structure 2009 offers control over advanced settings to refine a rendered image and achieve the desired result.

Render Appearance Enhancements for Materials

In Revit 2008 and previous releases, the software provided default materials, many of which used AccuRender definitions for render appearances. When you rendered a 3D view of a building model, these AccuRender definitions were used to provide a realistic representation of the model elements.

In Revit Structure 2009, new render appearances provide more accurate results in rendered images. A dynamic user interface presents different properties for each type of render appearance, allowing more control over textures and visual effects. When working with materials, you can enter search text to locate the desired material or render appearance quickly, based on its name, description, keywords, or other information.

Material definitions are stored as part of the project file. Render appearances are stored in a local, read-only library. If you change settings for render appearances, many changes are stored as part of the project. If you specify image files for render appearances (for example, for custom colors or textures), you can store the image files in a directory, and point Revit Structure to that directory. To share custom render appearances with team members, you use File > Transfer Project Standards. Also send the directory containing the image files.

Lighting Enhancements
Lighting fixtures are now photometric and can be described by IES files. (Many manufacturers provide IES files for their lighting fixtures, which you can download from their Web sites.) When you render an image, Revit Structure uses information in the IES file to determine the intensity of light at various points in space. If you do not use an IES file to describe the light source, you can specify real-world lighting variables based on manufacturer information. These improvements provide more accurate, realistic lighting in the rendered image.

During the rendering process, daylighting is performed automatically. For advanced lighting quality in interior views, you can enable daylight portals, if needed.

Enhancements for Export to 3ds Max

When you export a 3D view to Autodesk® 3ds Max® to use its higher-level rendering capabilities, Revit Structure 2009 passes rendering settings to 3ds Max. The information includes render appearances (material assignments), lights, and related settings defined in the project. By preserving this information during the export process, Revit Structure 2009 maintains a high degree of fidelity and reduces the amount of work you must perform in 3ds Max.

{Revit Structure 2009 User's Guide}

On the dotted line...

We have finally committed to our Revit Structure Implementation with ..... (drum roll, please)
Avatech Solutions

Project kick-off will commence around the middle of May, with the classroom training phase to begin on June 10th and coincide with the beginning of our first production project. To make this as helpful as possible to other newcomers to RST, I plan on logging our progress: the good stuff and some things to avoid.
If you're lucky, you might just witness a meltdown or two along the way.
If I'm lucky, I'll survive to fight another day.

In the meantime, I will be trying to post some articles & helpful items. This blog may be a little slow to get going, but I'm hoping to pick up some momentum here soon.

If anyone knows of any more helpful links/blogs, please speak up! I have some good ones in my list, but...