What Is New with the Autodesk Revit 2012 API?

Transcription

1 Elizabeth Shulok Structural Integrators, LLC CP3870 Discover what is new in the Revit 2012 API. This class will introduce attendees to major new features in the API, such as extensible storage, worksharing, construction modeling, energy analysis, point clouds, and Performance Advisor, as well as major enhancements to existing functionality, including changes to the geometry, material, MEP, and analysis visualization framework APIs. Some minor changes and enhancements will be covered as well, along with information on how these changes may affect existing Revit add-ins being updated for Revit Learning Objectives At the end of this class, you will be able to: List the major enhancements to the Revit 2012 API List some of the minor enhancements to the Revit 2012 API Identify changes to the Revit API that may affect existing Revit add-in projects Define extensible storage and how it can be used List 5 new features of the geometry API About the Speaker Elizabeth is the founder and president of Structural Integrators, LLC, a software company based in Southern California that provides integration tools for the structural engineering industry. Prior to starting Structural Integrators in 2007, she spent nearly nine years as a software engineer at RAM International and Bentley Systems, specializing in interoperability issues. She has worked extensively with the Autodesk Revit API for nearly 7 years. shulok@structuralintegrators.com

2 Introduction Each new version of Revit brings an enormous amount of new features, enhancements and changes to the Revit API (Application Programming Interface) and Revit 2012 is no exception. There are more additions and changes to the API than can be covered in this class, but we will cover most of the new features. We ll start by examining the major new features that you may want to consider using in your Revit add-ins. Then we ll look at minor enhancements, updates which may require changes to your existing add-in code, and finally the extensive changes to the geometry portions of the API. Major New Features of the Revit 2012 API There are a number of major new features in the Revit 2012 API, some related to new features in Revit 2012, and some specific to the API. Worksharing Worksharing is a design method that allows multiple team members to work on the same project model at the same time. When worksharing is enabled, a Revit document can be subdivided into one or more worksets, which are subsets of elements in the project. Worksharing is not a new feature in Revit, but the addition of worksharing features in the API coincides with enhancements to the worksharing functionality in Revit, including new display modes. The Revit API now provides access to worksets, elements in worksets and visibility and display options related to worksharing. Worksets The Document class indicates whether worksharing is enabled for the document and provides access to the worksets if it is. Even if worksharing is not enabled, there will be one default workset for the document. The Workset class in the API provides information such as the name of the workset, the owner, the kind of workset, and whether it is editable. Worksets in the document can be filtered to retrieve a subset of worksets meeting certain criteria. Elements in Worksets Each element has a workset id to identify to which workset it belongs. You can obtain all of the elements in a given workset using filtering. The API also provides a worksharing utility class that can be used to get information such as checkout status of an element or whether the element is out of date with the central model. Visibility and Display The View class in the Revit API provides methods to get and set the visibility of worksets in that view. A workset s visibility is determined by default settings for the document, but its visibility can be overridden for a view to be visible or hidden. The default workset visibility settings for the document can also be set through the API. 2

3 In addition to setting the visibility for a view, you can also set the display mode for the view to display the checkout status for elements, the owner of each element, the worksets to which the elements belong, or model updates. And for each display mode, the graphics display settings (line color and fill color) can be set to configure how elements will be shown in different modes. These settings are common and shared by all users in the model. Point Clouds The ability to insert a point cloud file into a Revit model is a new feature in Revit The Revit API provides access to point clouds in two ways, via a Point Cloud Client API and a Point Cloud Engine API. The Client API allows you to create new point cloud instances, read and filter points, select subsets of the overall points, and select points to be highlighted or isolated. The Engine API allows you to create your own point cloud engine and process unsupported file formats (i.e. other than.pcg), providing points to Revit for the user to see. Figure 1: Imported point cloud file Client API Using the point cloud client API, you can create an instance of a point cloud in a document. The point cloud points will be served to the client from a point cloud engine. For a pcg file, this could be the built-in engine that comes with Revit. For other file formats, the point cloud client must 3

4 specify the point cloud engine to be used. This would be a 3 rd party point cloud engine that has been registered with Revit. Once created, you can iterate through all the points in the point cloud instance and filter them based on a set of planar boundaries. Selected points may either be highlighted on screen or isolated, so that the other points in the cloud are not displayed. Engine API A custom point cloud engine can be implemented to supply cloud points to Revit. A point cloud engine can be file-based or non-file-based. A file-based implementation requires that each point cloud be mapped to a single file on disk. Revit will allow users to create new point cloud instances in a document directly by selecting point cloud files whose extension matches the engine identifier. These files are treated as external links in Revit and may be reloaded and remapped when necessary from the Manage Links dialog. A non-file-based engine implementation may obtain point clouds from anywhere (e.g. from a database, from a server, or from one part of a larger aggregate file). Because there is no file that the user may select, Revit's user interface will not allow a user to create a point cloud of this type. Instead, the engine provider supplies a custom command to create and place point clouds of this type. The Manage Links dialog will show the point clouds of this type, but since there is no file associated with the point cloud, the user cannot manage, reload or remap point clouds of this type. Construction Modeling The Revit API allows elements to be divided into sub-parts or collected into assemblies to support construction modeling workflows, much the same way as can now be done with the Revit user interface. Both parts and assemblies can be independently scheduled, tagged, filtered, and exported. You can also divide a part into smaller parts. After creating an assembly type, you can place additional instances in the project and generate isolated assembly views. Figure 2: Wall divided into parts 4

5 Extensible Storage Until now, shared parameters were the only way to store custom data with Revit elements. This data could be made visible to the user in the element properties table. One drawback to shared parameters is that they could only be applied to certain categories. Custom data could not be stored with materials, for example. The Extensible Storage feature is unique to the Revit API, unlike Shared Parameters which can be edited through the Revit user interface. Extensible Storage is a huge improvement on the ability to store custom data with Revit elements. Unlike shared parameters, extensible storage can be assigned to any element in the Revit model, regardless of category. And since most things in the Revit document derive from the Element class, this means you can assign your own data to nearly any object in the document. To use the extensible storage feature, you first define a schema, which consists of one or more fields to be assigned to an object. Field types can be any of the basic types such as int, bool, string, as well as a GUID, and some Autodesk types including ElementId, XYZ and UV. A field also has a unit type assigned to it as well as a name and documentation. When defining a schema, the read and write access can be set separately, so that you can allow 3 rd party applications to read your schema, but not edit it. Once a schema is defined, an entity can be created from it and then assigned to an element in the document. The entity is stored with the element and can be retrieved later by any application with read access for the schema. The data assigned to the element is not visible inside Revit. Analysis Visualization Framework Enhancements The Revit API provides a mechanism for external analysis applications to easily display the results of their computation in the Revit model, referred to as the analysis visualization framework. In Revit 2012, this framework was improved to support multiple analysis results shown in the same view at the same time. The portion of the Revit API related to analysis visualization was modified to support multiple results and to keep track of which are visible in the view. Two new types of analysis data and results display were also added. Analysis results can now be shown as diagrams or vectors. 5

6 Figure 3: Diagram analysis results display Figure 4: Vector analysis results display 6

7 Detailed Energy Analysis Model The Revit API provides the ability to obtain and analyze the contents of a project's detailed energy analysis model. The Export to gbxml and the Heating and Cooling Loads features produce an analytical thermal model from the physical model of a building. The analytical thermal model is composed of spaces, zones and planar surfaces that represent the actual volumetric elements of the building. After creating an energy analysis detail model, the API provides access to information on those spaces, zones, and surfaces. Conceptual Energy Analysis Elements and objects created by Revit to perform energy analyses on conceptual design models are available through the Revit API. The main class associated with conceptual energy analysis, MassEnergyAnalyticalModel, associates a mass instance with energy analytical model data and geometry. The API contains other related classes to provide access to the conceptual representation of an occupiable floor (Mass Floor) in a conceptual building model, conceptual representations of individually heated and cooled sub-volumes of a building, and data about a face in the MassEnergyAnalyticalModel element, such as the material value, and dimensions of auto-generated elements such as sill height, and skylight width. Performance Adviser The new performance adviser feature of the Revit API is designed to analyze a document and flag for the user any elements and/or settings that may cause performance degradation. The Performance Adviser command executes a set of rules and displays their result in a standard review warnings dialog. For an example of how this might be used, look at the PerformanceAdviserControl project in the Revit API SDK Samples folder, which demonstrates the implementation of a custom rule used to identify any doors in the document that are faceflipped. Customizing IFC Export The default IFC Export in Revit can now be customized by 3 rd party add-ins using the IExporterIFC interface which is registered with the Revit session. When a custom IFC exporter is registered with Revit, it will be used both when the user invokes an export to IFC from the user interface as well as from the API. When invoking an IFC export from the API, options similar to the export options available to the user from the Export IFC dialog box can be set programmatically. A custom IFC Export may be useful for regions that are developing their own flavors of IFC. A custom IFC export would be able to support those flavors by extracting the extra information out of the model and putting it into the IFC file. MEP API Enhancements A number of enhancements have been added concerning features specific to MEP. One important enhancement to the API is access to many of the Mechanical Settings found on this dialog box in Revit MEP: 7

8 Figure 5: Mechanical Settings Settings under Pipe Settings, Sizes, and Slopes are all available to read and write via the Revit API. Another useful feature in the API is the ability to put placeholder elements into a system when the exact design of the layout is not yet know. Using placeholder ducts and pipes can allow for a well-connected system while the design is still unknown. Placeholder ducts and pipes can later be converted to actual ducts and pipes via the API. The last major new feature of the MEP portion of the Revit API is the ability to access and create duct and pipe insulation and lining as separate objects associated with ducts and pipes. Minor Changes to the API Many minor changes and enhancements were added to the Revit API for the 2012 release. Although not as extensive as the major changes, some of these minor enhancements are quite significant. Custom Ribbon Tab Previously, ribbon panels and controls could only be added to the Add-Ins or Analyze tab. With Revit 2012, you can now add new ribbon tabs. To ensure that the standard Revit ribbon tabs remain visible, only 20 custom ribbon tabs can be added to a Revit session. Figure 6: New Ribbon Tab with one Panel and some simple Controls 8

9 DB-Level Applications Starting with Revit 2012, you can now create database-level add-ins that do not add anything to the Revit user interface. A db-level add-in can respond to the OnStartup and OnShutdown events for Revit, at which time they can register events or updaters for the Revit session. Document and View enhancements Several enhancements have been made to both the Document and View classes in the API. A document can now be opened and made the active document via the API. And the preview image settings of a document can now be accessed programmatically. For the first time, the active view can be set from the API, although it must be a view of the active document and cannot be inside a transaction. And it is now also possible to control the initial view settings when a model is opened. Linked Files The Revit API can now determine which elements in Revit are references to external files ("linked files") and can make some modifications to how Revit loads external files. Specifically, you can get the path to external files as well as the file type. You can also determine if the file was loaded, unloaded, or not found the last time the main Revit document was opened. The TransmissionData class allows you to examine the external file data in a closed Revit document and to modify the path and load-state information for that data. Although you can modify the path from which to open the external file and change the state from loaded to unloaded (and vice-versa), you cannot use this class to add or remove links from the document. 2-click Pick Option for Selection A new option has been added to allow the user to specify a rectangular area of the screen. Unlike the existing option to allow the user to pick elements in a rectangle, this new method, PickBox() does not return the set of selected elements. Instead, it returns a class that contains the two XYZ points the user selected on screen. One example of a use for this option is to use the picked points to determine a set of point cloud points to select for highlighting on screen. Dynamic Update Framework Changes The dynamic update framework has been updated to allow a registered Updater to be optional. Previously, if an Updater had been associated with a document and that document was opened when the updater was no longer available (on another computer, for example, where the add-in that registered the Updater is not installed), the user would receive a warning. Optional Updaters will not trigger such a warning. The user will still receive this warning if a document is modified by a non-optional Updater and later opened with the Updater is not available. 9

10 Figure 7: Missing Third Party (Non-optional) Updater Allow/Disallow Wall End Joins Whether a wall allows or disallows end joins is now accessible via the API. If joins exist at the end of a wall and joins are disallowed, the walls will become disjoint. If joins are disallowed for the end of the wall, and then the setting is changed to allow the joins, the wall will automatically join to its neighbors, if there are any. Pin/Unpin Elements Previously, an element s pinned status was read-only. Now, an element can be set to pinned or unpinned via the API. Filtering Enhancements Several enhancements have been made to the element filtering capabilities in the Revit API. There is now an option to check if a specific element passes a filter, which can be useful if you have an element and want to know if it meets certain conditions. New types of filters have been added. A multi-category filter which allows you to find elements whose category matches any of a given set of categories and a multi-class filter which allows you find elements whose class type matches any of a given set of classes. Two geometric filters have been added as well that allow you to filter elements by intersection. One finds all elements that intersect a given element while another will find all elements that intersect a given solid. For example, you could create a cylinder centered at the end of a wall to find other walls in close proximity, even if the walls are not joined. 10

11 Changes that may affect existing add-ins There are several changes that impact existing functionality in the Revit API. Some of these changes will prevent an existing add-in from compiling once you reference the new API. Some may not be apparent until you run your code..net 4.0 The Revit API now runs with the.net 4.0 runtime. This requires your add-ins to be targeted to.net 3.5 or.net 4.0 and to be run in Visual Studio 2010 in order to debug them. Add-ins compiled with Visual Studio 2008 will run normally outside of the debugging environment. Regeneration Mode Automatic regeneration mode is no longer an option. This means you no longer have to include the RegenerationMode attribute on your add-ins. The result is that add-ins must use manual regeneration when necessary by calling the Document.Regenerate() method. Since this call can be time-consuming, it is best to only call it when necessary. Once case is when accessing the geometric representation of an element. Attempting to access Element.Geometry for a newly created or modified element will throw an exception if the element has not been regenerated first by performing a manual regeneration on the document. VendorID The.addin manifest file now requires a vendor ID property. The VendorId is a string conforming to the Autodesk vendor ID standards. Prior to using a VendorID, you must register your vendor id string with Autodesk at An error will be shown if the addin manifest file does not contain this required property for an add-in entry. An optional vendor description property has also been added, which can be used to list the vendor s legal name or any other relevant information about the vendor. Event changes There have been some minor changes related to events. Some event properties have been replaced with methods or the type of the property has changed. For some of the UI Events, the sender has changed from ControlledApplication to UIControlledApplication or from Application to UIApplication. If your add-ins subscribe to events, you ll want to look more closely at these changes. JournalData and Library Paths These are minor changes, but if you access the journal data or the paths to library content, you will need to update your code. The property ExternalCommandData.Data has been replaced with ExternalCommandData.JournalData and is now an IDictionary<String, String> rather than a StringStringMap class. The Application.LibraryPaths property is also obsolete. It has been replaced with get and set methods and the returned value is now of type IDictionary<String, String>. 11

12 Material Changes and Property Sets The Revit 2012 changes related to materials impacts the API as well. When compiling a project that works with materials for the first time in Revit 2012, the first thing you will find is that material specific classes such as MaterialSteel or MaterialWood, which were derived from the Material class, are now obsolete. Material-specific classes such as MaterialSteel, had class properties to access certain material properties, such as minimum yield stress. Now these properties must be retrieved using built in parameters on the base Material class. Another significant change is that materials can now reuse property sets which can be referenced by more than one material. When reading material information for an element, you must now first determine if the material properties are by property set or have been set independently. If they are by property set, the individual material properties must be retrieved from the property set; otherwise they can still be retrieved from the material itself. This change will not be trigger a compiler error, but when running an add-in that hasn t been updated to consider property sets, you will get undesirable results if accessing a material using a property set. Below is some code to read in some steel material properties using the Revit 2011 API: Figure 8: Material code using Revit 2011 API To accomplish the same thing using the Revit 2012 API, the code is: 12

13 Figure 9: Material code using Revit 2012 API CompoundStructure The CompoundStructure class, which describes the internal structure of a wall, floor, roof or ceiling, has been replaced. Previously, this class was read-only and did not provide support for the settings related to vertical regions, sweeps, and reveals. The new CompoundStructure class supports read and modification of all of the structure information including vertical regions, sweeps, and reveals. The CompoundStructureLayer class has been replaced for similar reasons. Since these classes have been replaced, not simply updated with certain properties and methods, any add-in that used these classes will fail to compile. In many cases, the changes are easy to identify and accommodate in the code. For example, some properties in CompoundStructure have been replaced with get and set methods. AnalyticalModel The AnalyticalModel class is now derived from the Element class. This change requires a regeneration before the AnalyticalModel of a newly created structural element can be obtained. You may also have noticed in the Revit Structure user interface, that analytical properties for structural elements are now accessed from a drop down box on the properties window. 13

14 Figure 10: Analytical properties of a column Properties only visible when viewing the analytical properties of a structural element are now available from the structural element s AnalyticalModel. For example, the end releases for beams, columns, and braces, used to be retrieved as built-in parameters from the FamilyInstance class. Now, you must retrieve the end releases from the AnalyticalModel class. Because the data is retrieved using built-in parameters rather than class properties, this change would not be apparent at compile time, but would show up at run time if not addressed. Rebar Changes Many changes have been made related to rebar to simplify this part of the API and to make it more consistent with the user interface. RebarShape is no longer modifiable. Instead of changing a RebarShape, you can create a new one based on the existing one. This change has resulting in several changes to the API, including new methods and methods that have been deprecated. Hook angle, hook orientation, and style can no longer be set except at creation. There are several other changes, mostly related to creation of rebar. LinePattern and FillPattern The LinePattern and FillPattern classes have been replaced. The old classes represented not only the line pattern or fill pattern itself, but also the element that contained it. The LinePattern class now represents the line pattern only, while LinePatternElement represents the element containing the line pattern. This LinePattern class provides access to the pattern name and the list of segments that make up the pattern. The line segments define a repeating pattern of dashes and dots for the line pattern. Settings.LinePatterns has been removed. You can now use filtering on the class LinePatternElement. 14

15 Similarly, the FillPattern class now represents the fill pattern only, while FillPatternElement represents the element containing the fill pattern. The FillPattern class provides access to the pattern name and the set of grids that make up the pattern. There is also a FillGrid class that represents a grid line in a fill pattern. Settings.FillPatterns has been removed. And similar to with LinePatterns, FillPatterns can be obtained by filtering on the FillPatternElement class. Save and Close API Changes The behavior of closing or saving a document has changed. Previously, it would prompt the user to pick a target path name if the document's path name was not already set, or if the target file was read-only. Now it will throw an exception if the document's path name is not yet set, or if the saving target file is read-only. A new Save method has been added to allow you to specify a temporary id to use to generate the file preview. The behavior of performing a save as of the document has changed. Previously, it would prompt the user before overwriting another file. Now an exception will be thrown in that situation. A new SaveAs method has been added to the Document class that allows you to save a document, and encapsulates the options to rename the document in session, overwrite an existing file (if it exists), and temporarily assign a view id to use to generate the file preview. Some save methods have been added to the UIDocument as well. Unlike the save or close methods in the Document class, these do provide a means for interacting with the user. A SaveAs method has been added to the UIDocument class that saves the document to a file name and path obtained from the Revit user (via the "Save As" dialog). And a SaveAndClose method has been added that closes the document after saving it. If the document's path name has not been set the "Save As" dialog will be shown to the Revit user to set its name and location. Reference class The Reference class has been renovated to be more closely aligned with the native Revit class it wraps. Because of this change, References will no longer carry information on the document, element, or geometry object from which it was obtained. Some properties of the Reference class are now obsolete and alternate methods are available to retrieve the information. The method Document.FindReferencesByDirection(), which was used to populate the now obsolete Transform and ProximityParameter properties of Reference, should be replaced with Document.FindReferencesWithContextByDirection(). This new method returns a list of ReferenceWithContext objects. Each ReferenceWithContext has a Proximity property and a GetInstanceTransform() method to replace the obsolete properties of the Reference class. 15

16 The obsolete properties and methods have simply been marked obsolete in the API and will not prevent existing add-ins from compiling or running in Revit But they will be removed in a future version at which point your add-ins should be updated. Move, Mirror, Rotate, Array Some Document methods to modify elements have been replaced. Move(), Rotate(), Array() and Mirror() are obsolete. An ElementTransformUtils class is now provided with overloaded methods that can move, rotate, mirror and array elements in the document. The array methods are broken down into some for linear arrays and some for radial arrays. The new utility class also has an overloaded Copy method that allows you to copy and translate one or more physical elements and place the newly copied elements by applying the given translation vector. Changes to the Geometry API The Geometry API refers to the aspects of the Revit API that are geometry-related. There isn t a geometry class or namespace, but the Revit API contains many classes related to geometry and graphic-related types used to describe the graphical representation in the API which are collectively referred to as the Geometry API. Many of the enhancements are the addition of utility classes for various geometric applications. Analysis of Room and Space Geometry The Revit API now provides access to 3D spatial elements like rooms and spaces. You can use the API to calculate the geometry of a spatial element and obtain the relationships between the geometry and the element's boundary elements. You can obtain the sub-faces related to the room bounding elements that define the spatial element face from the results of calculating the geometry. Extrusion Analysis of a Solid A new utility class called ExtrusionAnalyzer allows you to attempt to fit a given piece of geometry into the shape of an extrusion. The utility class can be used to calculate the base profile of the extruded solid aligned to the input plane. You can also identify all faces from the original geometry which do and do not align with the faces of the calculated extrusion. This could be useful to figure out if a wall, for example, has a slanted join at the top as would be the case if there is a join with a roof. If a face is unaligned, something is joined to the geometry that is affecting it. In the case of a non-aligned face, you can use the ExtrusionAnalyzer to determine the element that produced the non-aligned face. Boolean Operations A new BooleanOperationsUtils utility class provides methods for combining a pair of solid geometry objects. This class can be used to either take a copy of the input solids and produce a new solid as a result or to perform the boolean operation directly on the first input solid. In either case, you have the option to perform a Union, Difference, or Intersect of the two solids. 16

17 GeometryCreationUtilities The Revit API now has a GeometryCreationUtilities class that allows you to create solid geometry from input curves, such as: Extrusion Revolution Sweep Blend SweptBlend The resulting geometry is not added to the document as a part of any element. However, you may use the created Solid, and its constituent faces and edges, in several ways: As the input face(s) to the methods in the Analysis Visualization framework As the input solid to finding 3D elements by intersection using filtering As one or more of the inputs to a Boolean operation As a part of a geometric calculation FaceSplitter A FaceSplitter class has been added to the Revit API, representing the element produced by a Split Face operation. Use this class to identify the element whose face was split by the element. You can also access the faces created by the split. Getting Faces The new HostObjectUtils utility class provides methods to quickly locate the faces of a given roof, floor, or wall which act as the exterior or interior boundary of the object's CompoundStructure. Top and bottom faces are applicable to roofs and floors. Side faces are applicable to walls. Get Original Geometry The FamilyInstance class, which represents beams, column, braces and footings, now has a method called GetOriginalGeometry() which will return the geometry of the member before it is modified by joins, cuts, coping, extensions, or other post-processing. PolyLine A new geometry object called a PolyLine is exposed through the API. The PolyLine represents a set of coordinate points forming contiguous line segments. Typically this type of geometry would be seen in geometry imported from other formats (such as DWG). 17

18 Resources There are a number of great resources to help you work with the Revit API. Revit Software Development Kit The Revit SDK should be your first resource for information on the Revit API. You can install the Revit SDK from the Revit 2012 installer. Figure 11: Install Revit SDK from Revit installer Once installed, you will find a RevitAPI.chm file in the main folder. Be sure to read through the What s New section of the Revit API Help file. The SDK also includes numerous sample projects, usually including major new features if you need ideas on how to use them. Revit API Dev Guide The Revit API Dev Guide used to be provided with the Revit SDK as a pdf file. The Revit API Dev Guide is now on the Autodesk WikiHelp website at: 18

19 Figure 12: API Dev Guide on WikiHelp The Building Coder Jeremy Tammik s blog The Building Coder is all about the Revit API. Jeremy is a member of the AEC workgroup of the Autodesk Developer Network ADN DevTech team who, among other things, provides developer support to ADN members. When he gets interesting or technical questions, he posts them to his blog along with the solution. He also posts information on changes to the API for new versions of Revit, so it is a good place to go when learning about new features of the API. 19