The Building Coder

What's New in the Revit 2014 API

Here is one post that I prepared well for in advance, by publishing the previous 'What's New in the API' sections two months back:

• What's New in the Revit 2010 API
• What's New in the Revit 2011 API
• What's New in the Revit 2012 API
• What's New in the Revit 2013 API

The information provided here is extracted from the document 'Revit Platform API Changes and Additions.docx' provided with the Revit SDK. It is also included in the 'What's New' section in the Revit API help file RevitAPI.chm.

The reason for copying it here on-line as well is to ensure that the valuable information provided is picked up by web searches. More and more people, myself included, perform a web search straight away, first thing, before even looking at the API documentation.

For more detailed information on the pointers provided below, please refer to the complete API documentation and developer's guide.

For a short summary of the main highlights, please refer to the Revit 2014 API overview, which also points to the complete materials from the Revit 2014 DevDays presentations:

• Presentation
• Recording
• Sample code

This document consists of three main sections:

• Major changes and renovations
• Major enhancements to the Revit API
• Small enhancements & interface changes

I hope this proves useful to you and you find the new API features as useful and exciting as I do!

Major Changes and Renovations

Document APIs

Document.Save()

Several modifications have been made to the Document.Save() methods.

• The methods now return void instead of boolean.
• Failures are signaled with specified documented exceptions.
• The new property SaveOptions.Compact allows the caller to specify if the OS should eliminate all dead data from the file on disk.

Document.SaveAs()

Several modifications have been made to the Document.SaveAs() functions.

• The methods now return void instead of boolean.
• Failures are signaled with specified documented exceptions.
• The new property SaveAsOptions.MaximumBackups identifies the maximum number of backups to keep on disk.
• The new property SaveAsOptions.Compact allows the caller to specify if the OS should eliminate all dead data from the file on disk.
• The new property SaveAsOptions.WorksharingOptions offers options specific to workshared files:
• WorksharingSaveAsOptions.SaveAsCentral
• WorksharingSaveAsOptions.OpenWorksetsDefault
• WorksharingSaveAsOptions.ClearTransmitted
• The property SaveAsOptions.Rename has been obsoleted.  The property previously had no effect, use of SaveAs will always modify the document in memory.

In addition, a new version of SaveAs() taking a ModelPath and SaveAsOptions has been introduced.  This offers capabilities similar in behavior to SaveAs(string, SaveAsOptions).

OpenOptions

New options are available in this class:

• OpenOptions.Audit

This Boolean option specifies whether to expand all elements, to check for corruption.  Defaults to false.

• OpenOptions.AllowOpeningLocalByWrongUser

This boolean option specifies whether a local file is allowed to be opened ReadOnly by a user other than its owner.

• OpenOptions.GetOpenWorksetsConfiguration()
• OpenOptions.SetOpenWorksetsConfiguration()

These methods access the WorksetConfiguration.   This class specifies which user-created worksets should be opened/closed when the document is opened.  Once an instance of this class is created, it can be further modified by calling available methods in any order.  It is a specification of a setting for model open; the methods of this class just adjust the specification, and do not themselves open or close worksets.

Only user-created worksets can be specified to be opened or closed.  All system worksets are automatically open.  An open workset allows its elements can be expanded and displayed. For a closed workset, Revit tries to not expand its elements, and to that end, does not display them. This is intended to help with performance by reducing Revit's memory footprint.

An application can determine how to populate this class by looking at workset information from a closed document.  This is done by calling

• WorksharingUtil.GetUserWorksetInfo()

This method returns a collection of WorksetPreview classes containing the workset id, unique id, owner, name and whether or not the workset is default.

Application.OpenDocumentFile(ModelPath, OpenOptions)

This method has been reimplemented.  While the signature has not changed, there are new options available to be set in OpenOptions. 

Failures are now signaled with specific documented exceptions.

Application.OpenDocumentFile(String)

This method has been reimplemented.  While the signature has not changed, failures are now signaled with specific documented exceptions.

UIApplication.OpenAndActivateDocument(ModelPath, OpenOptionsForUI)

The signature and the implementation of this method has changed.

• The class OpenOptionsForUI has been removed.
• The new signature is (ModelPath, OpenOptions, Boolean detachAndPrompt). 

If you wish to let the user answer interactively the prompt of whether to preserve or discard worksets when opening the documented detached from central, set the following values:

• OpenOptions.DetachFromCentralOption = DoNotDetach
• Boolean argument "detachAndPrompt" = true.

Failures are now signaled with specific documented exceptions.

UIApplication.OpenAndActivateDocument(String)

This method has been reimplemented.  Failures are now signaled with specific documented exceptions.

FilteredElementCollector

Iteration and element deletion

When an element is deleted active iterations over the document (via FilteredElementCollector) are now stopped. A new InvalidOperationException is thrown.  The iterator cannot proceed due to changes made to the Element table in Revit's database (typically, this can be the result of an Element deletion). This affects the use of FilteredElementIterator, FilteredElementIdIterator, and foreach loops over a FilteredElementCollector.

The exception can be triggered by direct calls to Document.Delete(), but also by other Revit APIs which change the document resulting in an element being deleted. In general it is best not to make any changes to the document while an iterator is running over the document.

The simplest workaround to fix existing code which encounters this error is to use one of:

• FilteredElementCollector.ToElements()
• FilteredElementCollector.ToElementIds()
• FilteredElementCollector.ToList<Type>() (LINQ method)

to get a standalone collection, then iterate that collection.  Even if elements are deleted from the document, the iteration of the already fetched collection can proceed.

Geometry APIs

Curve creation

New curve creation methods have been added as statics on the associated curve type:

• Curve.CreateTransformed()
• Line.CreateBound()
• Line.CreateUnbound()
• Arc.Create()
• Ellipse.Create()
• NurbSpline.Create()
• HermiteSpline.Create()

The older curve creation properties and methods are now obsolete:

• Curve.Transformed
• Line.Bound
• Line.Unbound
• Autodesk.Revit.Creation.Application.NewLine()
• Autodesk.Revit.Creation.Application.NewLineBound()
• Autodesk.Revit.Creation.Application.NewLineUnbound()
• Autodesk.Revit.Creation.Application.NewArc()
• Autodesk.Revit.Creation.Application.NewEllipse()
• Autodesk.Revit.Creation.Application.NewNurbSpline()
• Autodesk.Revit.Creation.Application.NewHermiteSpline()

Both the old and new curve creation routines are updated to consistently prevent creation of curves smaller than Revit's tolerance. This value is now exposed via:

• Application.ShortCurveTolerance

Some other adjustments have been made to the validation on specific curve creation routines, consult the documentation for details.

Curve utilities

The new methods:

• GetEndPoint()
• GetEndParameter()
• GetEndPointReference()

replace the indexed property utilities on Curve:

• EndPoint
• EndParameter
• EndPointReference

The setter for EndParameter is deprecated and code should be adjusted to call MakeBound(double, double) instead.

Edge utilities

The new methods:

• Edge.GetFace()
• Edge.GetEndPointReference()

replace:

• Edge.Face (property)
• Edge.EndPointReference (property)

Transform initialization

The new methods:

• Transform.CreateTranslation()
• Transform.CreateRotation()
• Transform.CreateRotationAtPoint()
• Transform.CreateReflection()

replace:

• Transform.Translation (property)
• Transform.Rotation (property)
• Transform.Reflection (property)

SketchPlane creation

The SketchPlane creation methods of Autodesk.Revit.Creation.ItemFactoryBase have been replaced.

• SketchPlane.Create(Document, Plane) replaces ItemFactoryBase.NewSketchPlane(Plane)
• SketchPlane.Create(Document, Reference) replaces ItemFactoryBase.NewSketchPlane(Reference)
• Either method may be appropriate to replace calls to ItemFactoryBase.NewSketchPlane(PlanarFace), depending on whether the goal is a sketch plane tied to a Revit geometric reference, or a sketch plane fixed in space to a given plane.

A new SketchPlane creation has been added:

• SketchPlane.Create(ElementId)

This creates a SketchPlane from a grid, reference plane, or level.

SketchPlane also now has two more methods to get related properties of the SketchPlane element.

• SketchPlane.GetPlane() Returns the corresponding Plane.
• SketchPlane.GetPlaneReference()  Returns a reference to this element as a plane.

BeamSystem creation

The BeamSystem creation methods of Autodesk.Revit.Creation.Document have been replaced:

• BeamSystem.Create(Document, IList<Curve>, SketchPlane, int) replaces Document.NewBeamSystem(CurveArray, SketchPlane)
• BeamSystem.Create(Document, IList<Curve>, SketchPlane, XYZ, bool) replaces Document.NewBeamSystem(CurveArray, SketchPlane, XYZ, bool)
• BeamSystem.Create(Document, IList<Curve>, Level, int, bool) replaces Document.NewBeamSystem(CurveArray, Level)
• BeamSystem.Create(Document, IList<Curve>, Level, XYZ, bool) replaces Document.NewBeamSystem(CurveArray, Level, XYZ, bool)

Truss creation

The Truss creation method of Autodesk.Revit.Creation.Document have been replaced.

• Truss.Create(Document, ElementId, ElementId, Curve) replaces Document.NewTruss(TrussType, SketchPlane, Curve)

Family Symbol API

Family symbols that are not used in the document are now inactive until they are used.  A symbol's geometry will be empty and should not be accessed until it is active.  To test if a symbol is active, use

• FamilySymbol.IsActive()

To activate an inactive family symbol, use

• FamilySymbol.Activate()

Units API

The API for Units in Revit has been expanded and changed. The methods

• Document.GetUnits()
• Document.SetUnits()

allow interaction with the units of a document.  The Units class provides access to data such as

• DecimalSymbol
• DigitGroupingAmount
• DigitGroupingSymbol
• FormatOptions

The FormatOptions class provides access to data including:

• Rounding
• Accuracy
• DisplayUnits
• SuppressLeadingZeros
• SuppressTrailingZeros
• SuppressSpaces

LabelUtils.GetLabelFor() has been enhanced so that it can now return the user-visible name for a UnitSymbolType.

Unit Formatting and Parsing

The methods:

• UnitFormatUtils.FormatValueToString()
• UnitFormatUtils.TryParse()

provide the ability to format a value into a string based on formatting options and to parse a formatted string (including units) into a value if possible.

Unit Conversion

The new class UnitUtils contains methods to convert between unit types:

• UnitUtils.Convert() – Converts a value from one unit type to another, such as square feet to square meters.
• UnitUtils.ConvertFromInternalUnits() – Converts a value from Revit's internal unit type.
• UnitUtils.ConvertToInternalUnits() – Converts a value to Revit's internal unit type.

View API changes

Viewport.Create behavioral change

The method

• Viewport.Create()

previously did not consistently align the center of the Viewport with the point supplied.  This has been changed, and now the center will be aligned with the input point.  This should allow easier alignment of multiple viewports on the same sheet.

View.ViewName obsolete

The property

• View.ViewName

is now obsolete.  View.Name can be used.

View.SetVisibility()

The name of this method has now been correctly capitalized.

ViewSchedule changes

ViewSchedule is now a child of TableView.   All previously existing ViewSchedule API is still valid, but TableView also brings in a set of APIs related to:

• Table sections (header and body)
• Table formatting
• The contents of individual table cells

There are methods on TableView (and its constituent TableData and TableSectionData class) that are useful for Electrical Panel Schedules and some varieties of specialized schedules but forbidden for use with standard Revit tabular schedules generated from Revit content (e.g. InsertRow(), RemoveRow()).   Use of these functions on standard Revit schedules will result in an exception.

Some new members were introduced on schedule related classes:

• ScheduleField.SetStyle()
• ScheduleField.GetStyle()
• ScheduleField.IsOverridden
• ScheduleField.ResetOverrides()
• ScheduleField.GetFormatOptions()
• ScheduleField.SetFormatOptions()

relate to the style and formatting applied to schedule columns, and:

• ScheduleField.IsCalculatedField
• ScheduleField.IsCombinedParameterField
• ScheduleField.HasSchedulableField

relate to information about the type of a field.

The new members:

• ViewSchedule.GetFontId()
• ViewSchedule.AddFontId()

provide access to fonts stored in the table and applied to cells.

The new members:

• ViewSchedule.GroupHeaders()
• ViewSchedule.UngroupHeaders()
• ViewSchedule.CanGroupHeaders()
• ViewSchedule.CanUngroupHeaders()

affect header grouping in the schedule.

The new method:

• ViewSchedule.GetTableData()

returns the object which provides access to the sections of the table.

Materials API changes

Applying visual materials

The method

• Material.SetRenderAppearance()

has been deprecated.  The Render appearance properties should be set via the related ApperanceAssetElement. 

Use the new property:

• Material.AppearanceAssetId

to assign the element to the material.

AppearanceAssetElements can be found via element filtering – they expose the following members:

• AppearanceAssetElement.Create() – creates a new asset element for a given rendering Asset and name.
• AppearanceAssetElement.GetAppearanceAssetElementByName() – gets an asset element handle given the name.
• AppearanceAssetElement.SetRenderingAsset() – Sets the rendering Asset to the element

AssetProperty changes

AssetProperty no longer inherits from APIObject. 

New subclasses of AssetProperty are exposed:

• AssetPropertyList – a property consisting of a list of AssetProperty members. 
• AssetPropertyFloatArray – a property consisting of an array of float values.
• AssetPropertyUInt64 – a property of UInt64 value.
• AssetPropertyInt64 – a property of Int64 value.

Some of the return values of AssetProperty.GetTypeName() have been changed as shown here listing input argument, old return and new return:

• APT_Double – "Double1" – "Double"
• APT_DoubleArray2d – "Double2" – "DoubleArray2d"
• APT_DoubleArray3d – "Double3" – "DoubleArray3d"
• APT_DoubleArray4d – "Double4" – "DoubleArray4d"
• APT_Asset – "RenderingAsset" – "Asset"
• APT_FloatArray – "Float3" – "FloatArray"

UI API changes

External commands now supported from Project Browser as active view

API commands and macros are now enabled when the Revit active view is the Project Browser.  

• If there are actively selected elements in the Project Browser, these will be returned from UIDocument.Selection
• However, add-ins cannot prompt for interactive selection when the Project Browser is the active view.
• The enumerated type ViewType now has separate entries for ProjectBrowser and SystemBrowser to allow applications to deal with situations where the Project Browser is active.  These view types used to be returned as ViewType.Internal, so code which keys of off ViewType.Internal may need to be updated to also deal with these new types.

Note that API commands are still disabled when the active view is the MEP system browser. 

Beam and Brace Parameters changes

Revit 2014 includes several changes to control the position of structural framing members like beams and braces.  These changes do not affect the API members but can be accessed via parameters. 

Start/End Extension & Cutback

There are new extension and cutback parameters assigned to Beam and Brace elements.

• BuiltInParameter.START_EXTENSION
• BuiltInParameter.END_EXTENSION
• BuiltInParameter.START_JOIN_CUTBACK
• BuiltInParameter.END_JOIN_CUTBACK

Note: In some families “Start Extension” and “End Extension” family parameters may also exist but it is recommended to use instead new the new built-in parameters.

These parameters work as follows:

• If the Beam or Brace element end doesn’t belong to a join Revit uses the new parameters “Start Extension" or "End Extension”.  Assigning positive values to these parameters lengthens the element).
• If the Beam or Brace element belongs to a join Revit uses the parameters “Start Join Cutback" or "End Join Cutback”.  Assigning positive values to these parameters shortens the element).

In certain cases it may be difficult to detect if an element node belongs to join or not. Therefore, it may be advisable to set both groups of parameters via the API. With both groups of parameters will be set for element, Revit automatically detects which should be applied to the structural element.

Justifications

There are new justification parameters assigned to Beam and Brace elements. The new set of parameters provides more options to manipulate the physical element in relation to its analytical curve.

Here is a list of parameters and the permitted values for each:

• BuiltInParameter.YZ_JUSTIFICATION – YZJustificationOption.Uniform, YZJustificationOption.Independent
• BuiltInParameter.Y_JUSTIFICATION – YJustification.Left, YJustification.Center, YJustification.Origin, YJustification.Right
• BuiltInParameter.Y_OFFSET_VALUE – double
• BuiltInParameter.Z_JUSTIFICATION – ZJustification.Top, ZJustification.Center, ZJustification.Origin, ZJustification.Bottom
• BuiltInParameter.Z_OFFSET_VALUE – double
• BuiltInParameter.START_Y_JUSTIFICATION – YJustification.Left, YJustification.Center, YJustification.Origin, YJustification.Right
• BuiltInParameter.START_Y_OFFSET_VALUE – double
• BuiltInParameter.START_Z_JUSTIFICATION – ZJustification.Top, ZJustification.Center, ZJustification.Origin, ZJustification.Bottom
• BuiltInParameter.START_Z_OFFSET_VALUE – double
• BuiltInParameter.END_Y_JUSTIFICATION – YJustification.Left, YJustification.Center, YJustification.Origin, YJustification.Right
• BuiltInParameter.END_Y_OFFSET_VALUE – double
• BuiltInParameter.END_Z_JUSTIFICATION – ZJustification.Top, ZJustification.Center, ZJustification.Origin, ZJustification.Bottom
• BuiltInParameter.END_Z_OFFSET_VALUE – double

Previously only Beam elements had any justification parameters.

In Revit 2014, Beams as well as Braces share this set of built-in justification parameters.

The following list shows a mapping from old deprecated justification parameters to new ones:

• BEAM_H_JUSTIFICATION – Y_JUSTIFICATION
• BEAM_V_JUSTIFICATION – Z_JUSTIFICATION
• BEAM_V_JUSTIFICATION_OTHER_VALUE (valid only for Other value set to BEAM_V_JUSTIFICATION) – Z_OFFSET_VALUE (valid for all Z_JUSTIFICATION values)

Old beam parameters can still be used.  When set, they will be used to recalculate the new parameters.  It is strongly recommended to use new justification parameters instead of old ones, because in some cases the old parameters may be not sufficient to correctly describe the element position (for example, when justification is set independently on either end of the member).

Divided surface changes

Divided Surface API

The class DividedSurfaceData and the associated method Element.GetDividedSurfaceData() have been replaced.  The new methods to access DividedSurfaces applied to elements are:

• DividedSurface.GetReferencesWithDividedSurface()
• DividedSurface.GetDividedSurfaceForReference()

The method:

• Autodesk.Revit.Creation.Document.NewDividedSurface()

has been replaced by:

• DividedSurface.Create()

Point clouds

Revit 2014 includes a new point cloud engine.  This new engine supports .rcp and .rcs file formats.  The introduction of this new engine has led to several changes in the client API around Point Cloud elements.

PointCloudType.Create()

The method

• PointCloudType.Create()

no longer supports input of .pcg files to directly create a new PointCloudType.  .pcg files can be indexed to create matching .rcs files, but this does not happen automatically when using this method.

This method does support creation of PointCloudTypes from .rcp or .rcs files, or from custom formats supplied by the Point Cloud Engine API.

PointCloudInstance.GetPoints()

The method

• PointCloudInstance.GetPoints(PointCloudFilter filter, int numPoints)

has been deprecated and replaced by

• PointCloudInstance.GetPoints(PointCloudFilter filter, double averageDistance, int numPoints)

The new averageDistance argument is the desired average distance between "adjacent" cloud points (in Revit units of length).  The smaller the averageDistance the larger number of points will be returned up to the numPoints limit.  Specifying this parameter makes the actual number of points returned for a given filter independent of the density of coverage produced by the scanner. This average distance parameter is only used when extracting points from .rcs or .rcp point clouds, and is not used when extracting from .pcg point clouds or custom point clouds from the Point Cloud Engine API.

Point cloud overrides

The classes

• PointCloudOverrides
• PointCloudOverrideSettings
• PointCloudColorSettings

allow read and write access to point cloud override settings assigned to a given view.  Overrides can be applied to an entire point cloud instance, or to specific scans within that instance. Options for the overrides include making the cloud non-visible, setting it to a fixed color, or to color gradients based on elevation, normals, or intensity.

The property

• PointCloudInstance.SupportsOverrides

identifies point clouds which support override settings (clouds which are based on .rcp or .rcs files).

Point cloud scans

The method

• PointCloudInstance.GetScans()

returns a list of scans contained within the .rcp point cloud.  Scan names can be used to set visibility and fixed color overrides independently for each scan in the PointCloudInstance.

IFC API changes

IFC export now External Service

The capability to override IFC export is now managed as an External Service.  As such, the explicit interfaces in ExporterIFCRegistry are no longer needed and have been marked obsolete.  It is now possible to register more than one external IFC export implementation in the same session, and manage the active implementation using the methods of the SingleServerService wrapper to IFC export.

IFC APIs moved to new assembly

Most IFC API classes have been moved from RevitAPI.dll to a new assembly: RevitAPIIFC.dll. The classes moved include all members of the Autodesk.Revit.DB.IFC namespace which enable development of a custom IFC exporter.

Any Add-In using any of the migrated APIs needs to reference the new DLL and rebuild to work in Revit 2014.

Note that the APIs to invoke an IFC export and import:

• Document.Export(String, String, IFCExportOptions)
• Application.OpenIFCDocument(String)

and the related options class have not moved. Applications which export or import IFC files but do not provide custom implementations do not need to make changes.

PrintParameters

The property HideUnreferencedViewTages was renamed to HideUnreferencedViewTags. 

Obsolete API Removal

API classes and methods previously marked Obsolete in Revit 2013 or earlier have been removed from the API.

Classes removed

• CurtainCellSetIterator and CurtainCellSet – Use generic .NET collection classes instead.
• PipeMaterialType – replaced by Material
• Batch creation argument class types – batch creation is not needed with changes to Revit API regeneration
• ProfiledWallCreationData
• RectangularWallCreationData
• RoomCreationData
• TextNoteCreationData
• Subclasses of ConnectorElement have been removed, access these elements through the parent class
• ElectricalConnector
• ElectricalConnector.SystemType – query the parameter RBS_ELEC_CIRCUIT_TYPE on ConnectorElement and cast to ElectricalSystemType
• DuctConnector
• DuctConnector.LinkedConnector – replaced by ConnectorElement.GetLinkedConnectorElement() and ConnectorElement.SetLinkedConnectorElement()
• DuctConnector.SystemType – query the parameter RBS_DUCT_CONNECTOR_SYSTEM_CLASSIFICATION_PARAM on ConnectorElement and cast to DuctSystemType
• PipeConnector
• PipeConnector.LinkedConnector replaced by ConnectorElement.GetLinkedConnectorElement() and ConnectorElement.SetLinkedConnectorElement()
• PipeConnector.SystemType – query the parameter RBS_PIPE_CONNECTOR_SYSTEM_CLASSIFICATION_PARAM on ConnectorElement and cast to PipeSystemType

Methods and Properties removed

Autodesk.Revit.Creation namespace

Application

• NewMaterialSet() – replaced by .net Generic collection classes
• NewElementArray() – replaced by .net Generic collection classes

Document

• NewAnnotationSymbol(XYZ ,AnnotationSymbolType ,View) – replaced by NewFamilyInstance(XYZ, FamilySymbol, View)
• NewAreaViewPlan(String,Level,AreaElemType) – replaced by ViewPlan.CreateAreaPlan()
• NewCurtainSystem(ReferenceArray,CurtainSystemType) – replaced by NewCurtainSystem2(ReferenceArray, CurtainSystemType)
• NewElectricalSystem(ElementSet,ElectricalSystemType) – replaced by NewElectricalSystem(ICollection<ElementId>, ElectricalSystemType)
• NewFamilyInstances(List<FamilyInstanceCreationData>) – replaced by NewFamilyInstances2(List<FamilyInstanceCreationData>)
• NewGroup(ElementSet) – replaced by NewGroup(System.Collections.Generic.ICollection<Autodesk.Revit.DB.ElementId>)
• NewRooms(Phase, Int32) – replaced by NewRooms2(Phase, Int32)
• NewRooms(Level,Phase) – replaced by NewRooms2(Level, Phase)
• NewRooms(Level) – replaced by NewRooms2(Level)
• NewRooms(List<RoomCreationData>) – there is no single equivalent that creates multiple rooms, this is not needed with Revit API control over regeneration
• NewSpaces(Phase,Int32) – replaced by NewSpaces2(Phase, Int32)
• NewSpaces(Level,Phase,View) – replaced by NewSpaces2(Level, Phase, View)
• NewTextNotes(List<TextNoteCreationData>) – replaced by NewTextNote()
• NewViewPlan(String,Level,ViewPlanType) – replaced by ViewPlan.Create(Document, ElementId, ElementId)
• NewView3D(XYZ) – replaced by View3D.CreateIsometric(Document, ElementId)
• NewViewSection(BoundingBoxXYZ) – replaced by ViewSection.CreateDetail()
• All Wall creation methods replaced by equivalent Wall.Create() methods:
• NewWall(CurveArray,WallType,Level,Boolean,XYZ)
• NewWall(CurveArray,WallType,Level,Boolean)
• NewWall(CurveArray,Boolean)
• NewWall(Curve,WallType,Level,Double,Double,Boolean,Boolean)
• NewWall(Curve,Level,Boolean)
• NewWalls(List<ProfiledWallCreationData> dataList) – there is no single equivalent that creates multiple walls, this is not needed with Revit API control over regeneration
• NewWalls(List<RectangularWallCreationData> dataList) – there is no single equivalent that creates multiple walls, this is not needed with Revit API control over regeneration

FamilyItemFactory

• NewDuctConnector(Reference,DuctSystemType) – replaced by ConnectorElement.CreateDuctConnector()
• NewPipeConnector(Reference,PipeSystemType) – replaced by ConnectorElement.CreatePipeConnector()
• NewElectricalConnector(Reference,ElectricalSystemType) – replaced by ConnectorElement.CreateElectricalConnector()

Autodesk.Revit.DB namespace

BaseArray

• CopyMembers – replaced by GetCopiedMemberIds()
• OrigMembers – replaced by GetOriginalMemberIds()

CurtainGrid

• UnlockedMullions – replaced by GetUnlockedMullionIds()
• Mullions – replaced by GetMullionIds()
• Cells – replaced by GetCurtainCells()
• UnlockedPanels – replaced by GetUnlockedPanelIds()
• Panels – replaced by GetPanelIds()
• VGridLines – replaced by GetVGridLineIds()
• UGridLines – replaced by GetUGridLineIds()

CurveElement

• LineStyles – replaced by GetLineStyleIds()

Document

• Delete(ElementSet elements) – replaced by Delete(System.Collections.Generic.ICollection<Autodesk.Revit.DB.ElementId> elementIds)
• WorksharingCentralFilename – replaced by ModelPathUtils.ConvertModelPathToUserVisiblePath(Document.GetWorksharingCentralModelPath())
• PrintSettings – replaced by GetPrintSettingIds()
• Element/get_Element – replaced by GetElement method

Element

• PhaseDemolished – replaced by DemolishedPhaseId
• PhaseCreated – replaced by CreatedPhaseId

FamilyInstance

• GetCopings() – replaced by GetCopingIds()
• SetCopings(ElementSet) – replaced by SetCopingIds(ICollection<ElementId> cutters)
• SubComponents – replaced by GetSubComponentIds()

Floor

• SpanDirectionSymbols – replaced by GetSpanDirectionSymbolIds()

GeometryElement

• Objects – replaced by GetEnumerator()

Group

• Ungroup() – replaced by UngroupMembers()
• Members – replaced by GetMemberIds()

LinearArray

• CopyMembers – replaced by GetCopiedMemberIds()
• OrigMembers – replaced by GetOriginalMemberIds()

Material

• GetMaterialAspectPropertySet(MaterialAspect) – replaced by GetStructuralAssetId() and GetThermalAssetId()
• SetMaterialAspect(MaterialAspect,ElementId,Boolean) – replaced by SetStructuralAssetId() and SetThermalAssetId()
• SetMaterialAspectToIndependent(MaterialAspect) – replaced by SetStructuralAssetId() and SetThermalAssetId()

MEPSystem

• Remove(ElementSet) – replaced by Remove(ICollection<ElementId>)

Part

• ParentDividedElementId – no replacement, concept is removed from Revit
• OriginalDividedElementId – no replacement, concept is removed from Revit
• GetDividedParents() – no replacement, concept is removed from Revit

PartMaker

• IsElementDivided(ElementId elemId) – replaced by IsSourceElement(ElementId)
• GetDividedElementIds() – replaced by GetSourceElementIds()
• SetDividedElementIds(ICollection<ElementId>) – replaced by SetSourceElementIds(ICollection<ElementId>)

PartUtils

• AreElementsValidForDivide(Document, ICollection<ElementId>) – replaced by ArePartsValidForDivide(Document, ICollection<ElementId>)
• AreElementsValidIntersectingReferences(Document, ICollection<ElementId>) – replaced by PartMakerMethodToDivideVolumes.AreElementsValidIntersectingReferences(Document, ICollection<ElementId>)
• IsValidSketchPlane(Document, ElementId) – replaced by PartMakerMethodToDivideVolumes.IsValidSketchPlane(Document, ElementId)
• SetOffsetForIntersectingReference() – replaced by PartMakerMethodToDivideVolumes.SetOffsetForIntersectingReference()
• GetOffsetForIntersectingReference() – replaced by PartMakerMethodToDivideVolumes.GetOffsetForIntersectingReference()
• PartMakerUsesReference() – replaced by PartMakerMethodToDivideVolumes.PartMakerUsesReference()
• IsMaxDivisionDepthReached(Document, ElementId) – no replacement, concept is removed from Revit
• GetDividedParents(Part) – no replacement, concept is removed from Revit
• PlanTopology
• Rooms – replaced by GetRoomIds()

PropertySetElement

• Create(Document, MaterialAspect) – replaced by Create(Document, StructuralAsset)

RadialArray

• CopyMembers – replaced by GetCopiedMemberIds()
• OrigMembers – replaced by GetOriginalMemberIds()

SpatialFieldManager

• UpdateSpatialFieldPrimitive(Int32,FieldDomainPoints,FieldValues) – replaced by UpdateSpatialFieldPrimitive(Int32, FieldDomainPoints, FieldValues, Int32)
• SetUnits(IList<string>, IList<double>) – replaced by AnalysisResultSchema.SetUnits() and SetResultSchema()

View

• ApplyTemplate(View viewTemplate) – replaced by ViewTemplateId/ApplyViewTemplateParameters(View viewTemplate)
• Hide(ElementSet elemSet) – replaced by HideElements(System::Collections::Generic::ICollection<Autodesk::Revit::DB::ElementId^>^ elementIdSet)
• Unhide(ElementSet elemSet) – replaced by UnhideElements(System::Collections::Generic::ICollection<Autodesk::Revit::DB::ElementId^>^ elementIdSet)

View3D

• EyePosition – replaced by ViewOrientation3D.EyePosition/View.Origin
• ViewSheet
• AddView(View,UV) – replaced by Viewport.Create(Document, ElementId, ElementId, XYZ)

Autodesk.Revit.DB.Plumbing namespace

PipeType

• Roughness – replaced by Segment.Roughness
• Material – replaced by PipeSegment.MaterialId

Autodesk.Revit.DB.Structure namespace

AnalyticalModel

• CanDisable() – no replacement, concept removed from Revit
• IsValidAnalyticalProjectionType(AnalyticalDirection,AnalyticalProjectionType) – replaced by IsValidProjectionType(AnalyticalElementSelector, AnalyticalDirection, AnalyticalProjectionType)

AreaReinforcement

• NumBarDescriptions – replaced by GetRebarInSystemIds()
• BarDescription – replaced GetRebarInSystemIds()
• Curves – replaced by GetCurveElementIds()

BeamSystem

• GetAllBeams() – replaced by GetBeamIds()

PathReinforcement

• BarDescription – replaced by GetRebarInSystemIds()
• Curves – replaced by GetCurveElementIds()

Rebar

• GetCenterlineCurves(Boolean) – replaced by GetCenterlineCurves(Boolean,Boolean,Boolean)
• DistributionPath – replaced by GetDistributionPath()
• RebarShape – replaced by RebarShapeId
• Host – replaced by Rebar.GetHostId() and SetHostId(Document, ElementId)
• BarType – replaced by Element.GetTypeId() and Element.ChangeTypeId(ElementId)

Major Enhancements to the Revit API

Worksharing API enhancements

Reload Latest

The method:

• Document.ReloadLatest()

Fetches changes from central (due to one or more synchronizations with central and merges them into the current session. After this call finishes, use

• Document.HasAllChangesFromCentral()

to confirm that there were no Synchronizations with Central performed during execution of ReloadLatest.

Synchronize with Central

The method:

• Document.SynchronizeWithCentral()

performs a reload latest until the model in the current session is up to date and then saves changes back to central.  A save to central is performed even if no changes were made.

Element ownership

The following methods affect element and workset ownership:

• WorksharingUtils.CheckoutElements – Obtains ownership for the current user of as many specified elements as possible.
• WorksharingUtils.CheckoutWorksets – Obtains ownership for the current user of as many specified worksets as possible.
• WorksharingUtils.RelinquishOwnership – Relinquishes ownership by the current user of as many specified elements and worksets as possible, and grants element ownership requested by other users on a first come, first served basis.

Create new local

The new method:

• WorksharingUtil.CreateNewLocal()

takes a path to a central model and copies the model into a new local file for the current user.

Enable Worksharing

The new method Document.EnableWorksharing will enable worksharing in a project.

Enhancements to interactions with links

Several improvements have been made to increase API functionality when working with RVT links.

Identifying links

The property:

• Document.IsLinked

identifies if a document is in session because it is a linked Revit file.

Obtaining linked documents

The method:

• RevitLinkInstance.GetLinkedDocument()

gets the document that corresponds to an Revit Link instance.

Link creation

Two functions have been added to RevitLinkOptions, used to specify options for RevitLinkType.Create. 

• RevitLinkOptions.GetWorksetConfiguration()
• RevitLinkOptions.SetWorksetConfiguration()

This allows the user to specify which worksets should be opened when creating and loading a new Revit link.

Link load and unload

The methods

• RevitLinkType.Load()
• RevitLinkType.LoadFrom()
• RevitLinkType.Unload()

allow a link to be loaded or unloaded, or to be loaded from a new location.   These methods regenerate the document.  The document's Undo history will be cleared by these methods.  As a result, this function and others executed before it cannot be undone.  All transaction phases (e.g. transactions, transaction groups and sub-transactions) that were explicitly started must be finished prior to calling this method.

Link shared coordinates

The methods:

• RevitLinkType.SavePositions()
• RevitLinkType.HasSharedCoordinatesChanges()

support save of shared coordinates changes back to the linked document. While this operation does not clear the document's undo history, you will not be able to undo this specific action, since it saves the link's shared coordinates changes to disk.

Link path type

The property:

• RevitLinkType.PathType

allows read and modification of the path type associated with a link. 

Conversion of geometric references

The new APIs:

• Reference.LinkedElementId
• Reference.CreateLinkReference(RevitLinkInstance)
• Reference.CreateReferenceInLink()

allow conversion between Reference objects which reference only the contents of the link and Reference objects which reference the host. This allows an application, for example, to look at the geometry in the link, find the needed face, and convert the reference to that face into a reference in the host suitable for use to place a face-based instance. Also, they would allow you to obtain a reference in the host (e.g. from a dimension or family) and convert it to a reference in the link, suitable for use in Element.GetGeometryObjectFromReference().

Room tag creation from linked rooms

The new method:

• NewRoomTag(LinkElementId roomId, UV point, ElementId viewId)

can create room tags in Revit Links.

Picking in links

PickObject() and PickObjects() now allow selection of elements in RVT Links.

Views & Display

Graphic Display options

These new members expose read and write of graphic display options:

• View.GetBackground()
• View.SetBackground()
• View.ShadowIntensity
• View.SunlightIntensity
• View.SurfaceTransparency
• View.ShowEdges
• View.ShowSilhouettes
• View.SilhouetteLineStyleId

Category classes override

Display of category classes may be overridden by the user.  The new properties:

• View.AreModelCategoriesHidden
• View.AreAnnotationCategoriesHidden
• View.AreAnalyticalModelCategoriesHidden
• View.AreImportCategoriesHidden

allow an application to determine if a class of categories has been completely hidden.  Note that Category.Visible[View] and View.GetVisibility(Category) does not look to the category classes when it returns the individual visibility status.

Category override

Display of categories can be overridden. This can be done with the new class OverrideGraphicSettings and the new View methods:

• SetCategoryOverrides
• GetCategoryOverrides
• IsOverrideValidForCategory
• IsCategoryOverridable

Element Override

Display of elements can be overridden with the new methods:

• View.GetElementOverrides
• View.SetElementOverrides.

View Filters

A new set of methods on the View class allow getting, setting, adding, and removing filters. Filters can be created using the ParameterFilterElement class and its Create method which existed in previous versions of the Revit API.

Non-rectangular crop region

Views can now be assigned a crop region which is non-rectangular.  The new View members:

• View.GetCropRegionShapeManager()
• View.GetCropRegionShapeManagerForReferenceCallout()
• View.GetReferenceCallouts()

provide access to a ViewCropRegionShapeManager for the view or for a displayed reference callout.

This class allows access and modification of the crop region shape:

• ViewCropRegionShapeManager.GetCropRegionShape()
• ViewCropRegionShapeManager.SetCropRegionShape()
• ViewCropRegionShapeManager.IsCropRegionShapeValid()
• ViewCropRegionShapeManager.RemoveCropRegionShape()
• ViewCropRegionShapeManager.ShapeSet
• ViewCropRegionShapeManager.Valid

The properties:

• View.CropBoxActive
• View.CropBoxVisible

also apply to non-rectangular crop regions which may be assigned to a given view.

Viewport

The new property

• Viewport.Rotation

controls the rotation of the viewport on the sheet.

The new method

• Viewport.MoveCenterTo() 

moves the viewport so that the center of the box outline (excluding the viewport label) is at a given point.

The new method

• Viewport.GetBoxCenter()

returns the center of the outline of the viewport on the sheet, excluding the viewport label.

Exploded Views

The new DisplacementElement class can be used to cause elements to appear displaced from their actual location to create views such as this one where the roof has been moved in the positive Z direction. The DisplacementPath class creates an annotation that depicts the movement of the element from its actual location to its displaced location.

Revisions on sheets

The new methods:

• ViewSheet.GetAllProjectRevisionIds()
• ViewSheet.GetAdditionalProjectRevisionIds()
• ViewSheet.SetAdditionalProjectRevisionIds()

provide access to the ids of project revision elements associated to a particular sheet.  GetAllProjectRevisionIds() returns project revisions ordered from lowest to highest by project revision sequence number.  The results include revisions associated to a revision cloud visible on the sheet and revisions that have been additionally included using the Revisions On Sheet parameter.   GetAdditionalProjectRevisionIds() and SetAdditionalProjectRevisionIds() access specifically the additional revisions added using the Revisions On Sheet parameter.

Note that there is no special class for project revision elements, but that they can be accessed as Elements by filtering on category BuiltInCategory.OST_Revisions.

User interface customization

UIView

Zoom operations

The new methods:

• UIView.ZoomToFit()
• UIView.ZoomSheetSize()
• UIView.Zoom(double zoomFactor)

provide shortcuts to quickly adjust the zoom of the graphical view window.

Close view

The new method:

• UIView.Close()

closes a visible view window. Note that the last open view for a given document cannot be closed by this method.

PreviewControl

The new property:

• PreviewControl.UIView

returns a UIView handle to the preview view. This allows an application to manipulate the zoom and pan settings of the preview view.

The new property:

• PreviewControl.ScrollbarVisibility

accesses the visibility setting for the preview view scrollbars.

Command API

Command event

The event

• AddInCommand.BeforeExecuted

occurs before the command associated with an AddInCommandBinding executes.  This event is read-only, an application can react to this event but cannot make changes to documents, or affect the invocation of the command in any way.

Command posting

The method

• UIApplication.PostCommand()

posts a command to Revit.  Revit will invoke it when control returns from the current API context.   Only certain commands can be posted using this method:

1. Commands listed in the Autodesk.Revit.UI.PostableCommand enumerated type
2. External commands created by any add-in

This restriction prevents posting of contextual commands (because Revit's command framework cannot directly access the accessibility of some contextual commands).

Note that only one command may be posted to Revit at a given time.  If a second command is posted from any API application, the method throws an InvalidOperationException.

The command must be accessible to be executed.  This is determined only at the point where Revit returns from the API context, and therefore a failure to execute the command because the command is not currently accessible will not be reported directly back to the application that posted the command.

To use this API, the application must obtain a RevitCommandId handle for the command.  This can be done using either

• RevitAddInCommand.LookupCommandId(String)
• RevitAddInCommand.LookupPostableCommandId(PostableCommand)

The method

• UIApplication.CanPostCommand

identifies if the given command can ever be posted (that is, it is a member of PostableCommand or an external command).  It does not identify the command can be posted at the given timeframe (that is, it will not attempt to determine if the command is currently accessible). 

Dockable Dialog Panes

Revit now allows addins to register WPF dialogs to dock into the top, left, right, and bottom of the main Revit window, as well as to be added as a tab to an existing system pane, such as the project browser.  Dialogs can be registered with UIApplication.RegisterDockablePane and a user-implementation of the IDockablePaneProvider interface.  Dockable panes can later be retrieved, shown, and hidden through UIApplication.GetDockablePane() and DockablePane.Show() and Hide().

Dimensions & annotations API

Multi-reference annotations for rebar

Revit now supports annotations pointing to more than one reference, consisting of a dimension and associated tag These annotations can be used to label and dimension Rebar elements, and are labeled in the user interface as “Multi-rebar annotations.”

The API exposes this through:

• MultiReferenceAnnotation – the annotation object instance. This class includes a reference to the associated dimension and tag element.
• MultiReferenceAnnotationType – the annotation type.  The type specifies the tag and dimension types to be used in the multi-reference annotation, as well as associated display settings.
• MultiReferenceAnnotationOptions – an options class used to create a new MultiReferenceAnnotation, including specification of the associated elements and options for the dimension and tag placement.
• IndependentTag.MultiReferenceAnnotationId  – returns the ElementId of the MultiReferenceAnnotation that owns a tag.
• Dimension.MultiReferenceAnnotationId – returns the ElementId of the MultiReferenceAnnotation that owns a dimension.

Dimension alternate units

New properties of DimensionStyle provide access to alternate units settings:

• DimensionStyle.AlternateUnits
• DimensionStyle.GetAlternateUnitsFormatOptions()
• DimensionStyle.SetAlternateUnitsFormatOptions()
• DimensionStyle.AlternateUnitsPrefix
• DimensionStyle.AlternateUnitsSuffix

Dimension unit type

The property:

• DimensionStyle.UnitType

returns the type of units supported by this dimension style (length, angle, or slope).

Add-ins and macros

Automatic load of add-ins without restarting Revit

Revit now automatically loads addins from newly added .addin manifest files without restarting Revit.  

After placing a new .addin manifest file into one of the dedicated addins folders, the running Revit session will attempt to load the corresponding addin.  Loaded ExternalCommands will be added to the External Tools pulldown menu.  ExternalApplication and ExternalDBApplication OnStartup methods will be executed upon loading.  An addin's installer may leverage this feature – but it must do so by creating the new .addin file at the end of installation to the dedicated Revit addin folders (the installer must ensure that the addin's assembly is already deployed to the target machine and the assembly path can be resolved in the add-in manifest file). 

Add-ins may decline the ability for Revit to load the .addin in the middle of a session.  To decline this options, add an tag (set to “NO”) in the add-in manifest file. 

Note that when Revit starts an add-in in the middle of the session, some add-in logic may not function identically because of the different interactions with the session.  Specifically:

• If the application's goal is to prevent something from happening, the application may not be able to handle the fact that this activity has already happened in the existing session.
• If the application's goal is to manage external information in synch with documents loaded in the session, the application may not be able to handle documents that were loaded before the application started.
• If the application's logic depends on the ApplicationInitialized event, this event has already been called before the add-in was loaded.

Also, some add-ins may not be able to fully initialize when loading in the middle of the session.  This is because some activities must take place at the start of the Revit session:

• Creation of custom failure definitions
• Establishment of a system-wide IFailureProcessor to handle all failures.
• Registering ExternalServices.

Revit also offers a new UI API method

• UIApplication.LoadAddIn()

to programmatically load the add-in(s) listed in the provided add-in manifest file.   Typically, this API would not be needed because Revit is already loading new .addin files automatically.

MacroManager API

Revit now support an API for listing, creating, removing, editing, debugging, and running macros through several supporting classes and enums

• MacroManager
• Available at the DB.Document or ApplicationServices.Application level; manages the querying, creation, and removal of macro modules
• UIMacroManager
• Available at the UIDocument or UIAppliciation level, manages adding, removing, and editing UI-level modules.
• MacroModule
• Manages the querying, creation, removal, and running of specific macro methods
• ModuleSettings
• A collection of top-level properties of a MacroModule
• Macro
• Represents a single, runnable macro method.
• UIDocumentMacroOptions
• Represents security options for UIDocument-level macros.
• DocumentMacroOptions
• Represents security options for DB.Document-level macros.
• ApplicationMacroOptions
• Represents security options for Application-level macros
• MacroLanguageType
• Represents the language of a given macro, C#, VB.NET, Ruby, or Python
• MacroLevel
• Represents whether a macro is associated with a document the Revit application
• ModuleStatus
• Represents the compiled, loaded, or built status of a MacroModule.

The MacroManager APIs are all in the Autodesk.Revit.DB.Macros namespace and are available in RevitAPIMacros.dll and RevitAPIUIMacros.dll

Macro Attributes

The attributes  

• Autodesk.Revit.UI.Macros.AddinAttribute
• Autodesk.Revit.UI.Macros.VendorIdAttribute

and the interface 

• Autodesk.Revit.UI.Macros.IEntryPoint

have been moved to the namespace Autodesk.Revit.DB.Macros.

Parameters

Shared parameter – create with specified GUID

The new method

• Definitions.Create(String, ParameterType, bool, GUID)

supports creation of new ExternalDefinition objects (shared parameter definitions) which use the designated GUID instead of a random GUID. This allows an application to programmatically create consistent definitions for shared parameters without a shared parameter file or copying elements from one project to another.

Dimension.Label

The property

• Dimension.Label

Has been replaced by a new property

• Dimension.FamilyLabel

As this label applies only to dimension in families and their corresponding family parameter.

Family Parameters

The new property

• FamilyParameter.IsShared

identifies if the family parameter is a shared parameter.

Geometry APIs

JoinGeometryUtils

Revit now supports APIs for joining, unjoining, querying join state, and changing join order of elements in a model through the JoinGeometryUtils class.

Extensible Storage

ExtensibleStorage API changes

The method

• Element.GetEntitySchemaGuids()

returns the Schema Guids of any Entities present on an Element.

The methods

• Schema.GetField()
• Schema.ListFields()

are now restricted based on the read permission defined in the Schema.

ExtensibleStorageFilter

An ExtensibleStorageFilter is a new ElementQuickFilter for finding elements that contain an extensible storage entity of a given Schema Guid.

Translation

Export to Navisworks

The new function:

• Document.Export(String, String, NavisworksExportOptions)

exports a Revit project to the Navisworks .nwc format.  Note that in order to use this function,you must have a compatible Navisworks exporter add-in registered with your session of Revit.  If there is no compatible exporter registered, the function will throw OptionalFunctionalityNotAvailableException.  Use

• OptionalFunctionalityUtils.IsNavisworksExporterAvailable()

to check if there is an exporter registered.

Import/Link SAT

The functions:

• Document.Import(String, SATImportOptions, View)
• Document.Link(String, SATImportOptions, View)

import or link an SAT file into the document.

Import/Link SketchUp

The functions:

• Document.Import(String, SKPImportOptions, View)
• Document.Link(String, SKPImportOptions, View)

import or link an SKP file into the document.

Import DWF Markups

The function:

• Document.Import(String, DWFImportOptions)

imports DWF markups into the document.

Export tables

The new classes

• ExportLayerTable
• ExportLinetypeTable
• ExportPatternTable
• ExportFontTable
• ExportLineweightTable

expose read and write access to the tables used for mapping on export to various formats such as DWG, IFC and DGN.

Site

Editing a TopographySurface

Editing the points in a TopographySurface now requires establishment of an edit scope. The class

• TopographyEditScope

allows an application to create and maintain an editing session for a TopographySurface. Start and end of a TopographyEditScope will also start and end a transaction group. After the TopographyEditScope is started, an application can start transactions and edit the topography surface. Individual transactions the application creates inside TopographyEditScope will not appear in the undo menu.  All transactions committed during the edit mode will be merged into a single one which will bear the given name passed into TopographyEditScope constructor.

The method:

• TopographySurface.AddPoints()

has been modified to operate with the edit scope, and thus cannot be called outside of an edit scope.  The function no longer regenerates the document.

The new methods:

• TopographySurface.DeletePoints()
• TopographySurface.MovePoint()
• TopographySurface.MovePoints()
• TopographySurface.ChangePointElevation()
• TopographySurface.ChangePointsElevation()

provide the ability to modify and delete existing points in the TopographySurface.  Multiple calls to these functions can be included in the same edit scope.

Reading points from a TopographySurface

The new method:

• TopographySurface.ReadPoints()

returns a list of the points stored in the surface.

The method:

• TopographySurface.FindPoints()

filters and returns only the points of the topography surface which lie within the input bounding box.

The method:

• TopographySurface.ContainsPoint()

identifies if the input point is found in points stored in the surface.

The methods:

• TopographySurface.GetBoundaryPoints()
• TopographySurface.IsBoundaryPoint()

identify points which are a part of the boundary of the surface.

Validation

Several new validation methods have been added to the TopographySurface class:

• IsValidRegion() – Identifies whether the points can construct a valid region for a topography surface.
• ArePointsDistinct() – Identifies whether the input points are distinct in XY location.

These methods are newly used in AddPoints() to prevent problematic inputs from causing issues.

SiteSubRegion

The class SiteSubRegion represents a proxy class exposing the interfaces needed to access details of a subregion.   In the Revit database, both TopographySurface elements and subregion elements are represented by the same TopographySurface element subclass, however, in the Revit API, this SiteSubRegion class exists to separate the interfaces for subregions from those of topography surfaces.  The SiteSubRegion class offers these APIs:

• SiteSubRegion.Create() – creates a new subregion given a boundary consisting of one or more curve loops.
• SiteSubRegion.IsValidBoundary() – validates the input boundary for a new subregion
• SiteSubRegion.GetBoundary() – returns the boundary curves
• SiteSubRegion.SetBoundary() – sets the boundary for the subregion
• SiteSubRegion.TopographySurface – the TopographySurface element which this subregion represents
• SiteSubRegion.HostId – the identifier of the topography surface hosting this subregion

BuildingPad

The class BuildingPad represents a building pad element in Revit.  It inherits from CeilingAndFloor and thus offers inherited capabilities from HostObject as well. The API exposes the following specific capabilities around BuildingPads:

• BuildingPad.Create() – Creates a new BuildingPad given a boundary, type and level.
• BuildingPad.GetBoundary() – Returns the sketched boundary curves.
• BuildingPad.SetBoundary() – Assigns a new boundary to the BuildingPad.
• BuildingPad.HostId – The element id of the topography surface hosting this BuildingPad.

The type of the building pad is represented by BuildingPadType.  This inherits from HostObjAttributes and offers inherited capabilities from this parent, including access to the CompoundStructure of the type.  The API exposes these new capabilities for BuildingPadTypes:

• BuildingPadType.CreateDefault() – Creates a new default BuildingPadType in the document.

MEP

Externalized Calculations

Several new interfaces and classes based on external services are supported for pipe and duct calculations.

• Several new interfaces deriving from IExternalServer to support friction, flow, and pressure drop for pipes and ducts have been added.
• IPipePlumbingFixtureFlowServer
• IPipePressureDropServer
• IDuctPressureDropServer
• IDuctFittingAndAccessoryPressureDropServer
• IPipeFittingAndAccessoryPressureDropServer
• IDuctFittingAndAccessoryPressureDropUIServer
• IPipeFittingAndAccessoryPressureDropUIServer
• Several new classes implementing IExternalData to support friction, flow, and pressure drop for pipes and ducts have been added.
• PipePlumbingFixtureFlowData
• PipePressureDropData
• DuctPressureDropData
• DuctFittingAndAccessoryConnectorData
• PipeFittingAndAccessoryConnectorData  
• Several new classes implementing ISingleServerService to support friction, flow, and pressure drop for pipes and ducts have been added.
• PipePlumbingFixtureFlowService
• PipePressureDropService
• DuctPressureDropService
• DuctFittingAndAccessoryPressureDropService
• PipeFittingAndAccessoryPressureDropService
• DuctFittingAndAccessoryPressureDropUIService
• PipeFittingAndAccessoryPressureDropUIService

ElectricalLoadClassificationData

ElectricalLoadClassificationData has several new string properties corresponding to the load classification section of the electrical panel schedule.

• LoadSummaryDemandFactorLabel
• PanelConnectedLabel
• PanelEstimatedLabel
• PanelConnectedCurrentLabel
• PanelEstimatedCurrentLabel
• ActualElecricalLoadNameLabel

CSV Fitting Parameter Removal

Because CSV files are no longer used to drive MEP fitting parameters, Revit supports a new set of APIs to manage fitting parameters through several classes

• FamilySizeTableManager – manages importing and exporting of legacy CSV data and size tables.
• FamilySizeTable – manages specific sizes of fittings.
• FamilySizeTableColumn – manages a specific dimension of a given size in a size table
• FamilySizeTableErrorInfo – reports any errors when importing an file with CSV size table into a FamilySizeTable

Fitting Angle Settings

The members:

• DuctSettings.FittingAngleUsage
• DuctSettings.GetSpecificFittingAngles()
• DuctSettings.GetSpecificFittingAngleStatus()
• DuctSettings.SetSpecificFittingAngleStatus()
• PipeSettings.FittingAngleUsage
• PipeSettings.GetSpecificFittingAngles()
• PipeSettings.GetSpecificFittingAngleStatus()
• PipeSettings.SetSpecificFittingAngleStatus()
• ElectricalSetting.FittingAngleUsage
• ElectricalSetting.GetSpecificFittingAngles()
• ElectricalSetting.GetSpecificFittingAngleStatus()
• ElectricalSetting.SetSpecificFittingAngleStatus()

provide access to fitting angle usage settings for ducts, pipes, cable trays and conduits.

Duct Settings

Duct settings for size prefixes and suffixes, annotations, and  air density and viscosity may now be set through the DuctSettings class.

Curve Creation

Pipes, Ducts,  FlexPipes, and FlexDucts can now be created with a  Pipe, Duct, FlexPipe, or FlexDuct SystemTypeId as a parameter on their respective static Create() methods.

ConnectorElement

The methods

• ConnectorElement.CreatePipeConnector(Document, Document, PipeSystemType, Reference, Edge)
• ConnectorElement.CreateDuctConnector(Document, DuctSystemType, ConnectorProfileType, Reference, Edge)
• ConnectorElement.CreateElectricalConnector(Document, ElectricalSystemType, Reference, Edge)
• ConnectorElement.CreateConduitConnector(Document, Reference, Edge)
• ConnectorElement.CreateCableTrayConnector(Document, Reference, Edge)

allow creation of connector elements in families on centered on internal loops of a given face.

The property

• ConnectorElement.SystemType

accesses the MEPSystemType of the connector

The members:

• ConnectorElement.Direction
• ConnectorElement.FlipDirection()

access the direction of the connector.

Connect Air Terminal to Duct

The new method:

• MechanicalUtils.ConnectAirTerminalOnDuct()

connects an air terminal to a duct directly (without the need for a tee or takeoff). The current location of the air terminal will be projected to the duct centerline, and if the point can be successfully projected, the air terminal will be placed on the most suitable face of the duct. 

General

• CableTray.CurveNormal returns the "up" direction vector of a cable tray segment.
• RoutingPreferenceGroup now supports a new rule type for Cap fittings.
• Caps can be automatically be placed on all open connections of a pipe with PlumbingUtils.PlaceCapOnOpenEnds(Document, ElementId, ElementId)

Reinforcement API 

There are many new reinforcement and rebar-related methods and classes in Revit 2014.

AreaReinforcement

AreaReinforcement has several new methods and properties.

• AreaReinforcement.Create – creates a new AreaReinforcement object from curves.
• AreaReinforcement.IsUnobscuredInView – checks if Area Reinforcement is shown unobscured in a view.
• AreaReinforcement.SetUnobscuredInView – sets Area Reinforcement to be shown unobscured in a view.

PathReinforcement 

PathReinforcement has several new methods and properties.

• PathReinforcement .Create – creates a new PathReinforcement object from curves.
• PathReinforcement .AdditionalOffset - gets and sets length offset.
• PathReinforcement .IsUnobscuredInView – checks if PathReinforcement is shown unobscured in a view.
• PathReinforcement .SetUnobscuredInView – sets PathReinforcement to be shown unobscured in a view.

FabricArea 

FabricArea has several new methods and properties.

• FabricArea.Create – now supports an origin point of direction parameter.
• FabricArea.GetReinforcementRoundingManager – returns an object for managing reinforcement rounding override settings.

FabricSheet 

FabricSheet has several new methods and properties.

• FabricSheet.Create() – new static factory method for creation.
• FabricSheet.GetLocalCoordinateSystem()
• FabricSheet.SetLocalCoordinateSystem()
• FabricSheet.PlaceInHost()
• FabricSheet.GetReinforcementRoundingManager() – returns an object for managing reinforcement rounding override settings.
• FabricSheet.HostId
• FabricSheet.FabricLocation – the FabricSheet location in the host.
• FabricSheet.CoverOffset – the additional cover offset of the FabricSheet.
• FabricSheet.IsCoverOffsetValid() – identifies if the specified value is valid for use as a cover offset.

FabricSheetType 

• FabricSheetType.GetReinforcementRoundingManager() – returns an object for managing reinforcement rounding override settings.

Rebar

Rebar has several new methods and properties.

• Rebar.ComputeDrivingCurves() – compute the driving curves.
• Rebar.GetRebarConstraintsManager() – returns an object for managing the external constraints on the Rebar element.
• Rebar.GetReinforcementRoundingManager() – returns an object for managing reinforcement rounding override settings.
• Rebar.HookAngleMatchesRebarShapeDefinition() – checks that the hook angle of the specified RebarHookType matches the hook angle used in the Rebar's RebarShape at the specified end of the bar.
• Rebar.CanUseHookType – checks if the specified RebarHookType id is of a valid RebarHookType for the Rebar's RebarBarType.
• Rebar.ConstraintsCanBeEdited – returns true, if the Rebar element's external constraints are available for editing.
• Rebar.GetHookOrientation() – returns the orientation of the hook plane at the start or at the end of the rebar with respect to the orientation of the first or the last curve and the plane normal.
• Rebar.SetHookOrientation() – defines the orientation of the hook plane at the start or at the end of the rebar with respect to the orientation of the first or the last curve and the plane normal.

RebarType has several new methods and properties.

• RebarType.SetHookTangentLength() – identifies the hook tangent length for a hook type.
• RebarType.GetReinforcementRoundingManager() – returns an object for managing reinforcement rounding override settings.
• RebarBendData – new constructor to specify hook orientation.

RebarHandleType – a new enum to represent  the various types of handles on a Rebar instance that can be joined to References.

RebarConstrainedHandle – a new class to represent a handle on a Rebar that can be joined to a reference.

RebarConstraintType – a new enum to represent the various types of constraints that can be applied to a RebarConstrainedHandle.

RebarConstraintTargetHostFaceType – a new enum  to identify the individual face on a host element to which a Rebar handle is constrained.

RebarConstraint – a new class representing a constraint on the position of a Rebar Element or one of its handles.

RebarConstraintsManager – a  new class used to obtain information about the constrained shape handles (RebarConstrainedHandles) on a Rebar element.

RebarDeformationType – new enum representing the type of deformation of rebar.

RebarHookType.HookAngleInDegrees – a new property representing the angle of a rebar hook.

RebarInSystem

• RebarInSystem.getReinforcementRoundingManager – returns an object for managing reinforcement rounding override settings.
• RebarInSystem.setUnobscuredInView - sets the element to be shown unobscured in a view.

RebarShape

• RebarShape.GetDefaultHookAngle – get the hook angle, expressed as an integral number of degrees (common values are 0, 90, 135, and 180).
• RebarShape.GetDefaultHookOrientation – gets the default rebar hook orientation.

ReinforcementRoundingSource – a new enum listing the possible sources for reinforcement rounding overrides.

ReinforcementRoundingManager – a new class providing access to reinforcement rounding overrides for structural elements.

RebarRoundingManager – new class providing access to element reinforcement roundings overrides.

FabricRoundingManager – a new class providing access to element reinforcement roundings overrides.

ReinforcementSettings

• ReinforcementSettings.GetRebarRoundingManager – returns an object for managing reinforcement rounding override settings used by RebarBarTypes, Rebar and RebarInSystem elements.
• ReinforcementSettings.GetFabricRoundingManager – returns an object for managing reinforcement rounding override settings used by FabricSheetType and FabricSheet elements. 

Custom Export

The Custom Export API provides access to the rendering output pipeline through which Revit sends a processed model (its graphics 3D representation) to an output device. In the case of Custom Export, the "device" is represented by a context object that could be any kind of a device, even a file (in the most common case, actually.) A client of Custom Export provides a context and invokes rendering of a model, upon which Revit starts processing the model and sends graphic data out via methods of the context. The data describes the model exactly as it would have appeared in Revit when the model is rendered. The data includes all geometry and material properties.

The following classes have been made available so far:

CustomExporter

A class that allows exporting 3D views via a custom export context. The Export method of this class triggers standard rendering process in Revit, but instead of displaying the result on screen or printer, the output is channeled through the given custom context that handles processing the geometric as well as non-geometric information.

IExportContext

An interface of which interface is used in a custom export of a Revit model. The instance of this class is passed in as a parameter of a CustomExporter. The methods are then called by Revit at times of exporting entities of the model.

Render Node Classes

Classes of which instance are sent to an export context during a custom export.

• RenderNode – base class for all output nodes
• ViewNode – represents a View
• GroupNode – base class for family and link instances
• InstanceNode – represents an instance of a family
• LinkNode – represents an external link
• ContentNode – base class from RPC, Light, and Daylight nodes
• RPCNode – represents an RPC object
• DaylightPortalNode – represents a daylight portal
• LightNode – represents a light
• MaterialNode – represents a material change

CameraInfo

A class that describes information about projection mapping of a 3D view to a rendered image. An instance of this class can be obtained via a property of ViewNode.

Paint API

The paint tool is now supported in the API

• Document.Paint
• Document.RemovePaint
• Document.IsPainted
• Document.GetPaintedMaterial

Component repeater API

Component repeaters can be used to replicate (repeat) elements hosted on repeating references. The result of the repeating operation is a collection of slots. Each slot contains one repeated component. The ComponentRepeater class provides the repeating functionality and access to the slots.

Each repeating reference is capable of hosting one point of an adaptive component. An initial pattern can be created by populating one or more repeating references with such points. Component repeaters can then be used to replicate the pattern to fill the rest of the repeating references in the particular repeating reference source.

The repeating references in repeating reference source are arranged in one or two dimensional arrays, allowing for different kinds of repeating:

• One dimensional source allows for repeating along a path.
• Two dimensional source allows for repeating across a grid.
• It is also possible to host a point on a zero dimensional reference (a point). This point will be shared by all slots. A zero dimensional source allows for repeating around a single point. It should not be used alone, but together with at least one other repeating reference source (typically one dimensional.) The point hosted on the zero dimensional source serves as a central point around which other points can be repeated on their respective repeating reference sources.

Multiple adaptive components may be hosted on one repeating reference source, and different points of one adaptive component may be hosted on different repeating reference sources, effectively allowing different points of an adaptive component to be repeated using different patterns.

The following classes provide access to the functionality of Component repeaters:

• Autodesk.Revit.DB.RepeatingReferenceSource
• Autodesk.Revit.DB.RepeaterBounds
• Autodesk.Revit.DB.RepeaterCoordinates
• Autodesk.Revit.DB.ComponentRepeater
• Autodesk.Revit.DB.ComponentRepeaterSlot

Small Enhancements & Interface Changes

API validation

No transactions from outside threads

Calling into the Revit API from outside threads and outside modeless dialogs has never been supported, but it was not strictly prohibited, meaning there would be no immediate exceptions when someone tries to modify model from outside of the supported API workflows. That has been changed. It is no longer possible to start a transaction unless the caller is inside a legitimate API call, such as an external command, event, updater, call-back, etc. An exception will be thrown if such attempt is made.

IsValidObject property

If a Revit native object contained within an API wrapper is destroyed, or creation of the corresponding native object is undone, the managed API object containing it is no longer valid. API methods cannot be called on invalidated wrapper objects. The property IsValidObject (added to many API classes) can be used to identify if the corresponding native object has gone out of scope.

Enumerated type validation

Automatic validation has been introduced for enumerated type inputs to API methods and properties. If an value is improperly cast to an enum and is not a valid member of that enum, an ArgumentOutOfRangeException will be thrown.

Elements

Copy & paste elements

The new methods:

• ElementTransformUtils.CopyElements(Document, ICollection<ElementId>, Document, Transform)
• ElementTransformUtils.CopyElements(View, ICollection<ElementId>, View, Transform)
• Transform ElementTransformUtils.GetTransformFromViewToView(View, View)

support copy and paste of arbitrary elements.  The first overload supports copy within documents, or from document to document.  The second overload also support copying within one document or between two documents, but specifically supports copy and paste of view-specific elements.

Materials

Materials applied with the Paint tool and their areas can be found by specifying "true" for the 'usePaintMaterial' argumement in Element.GetMaterialIds and Element.GetMaterialArea

Geometry

FreeForm element

A FreeFormElement is a form sub-type that contains non-parametric geometry created from an input solid outline. The element can be added to families, and can participate in joins and void cuts with other combinable elements.  Planar faces of the element can be offset interactively and programmatically in the face normal direction.

• FreeFormElement.Create() – creates a new FreeForm element.
• FreeFormElement.SetFaceOffset() – offsets a planar face a certain distance in the face normal direction.

Solid & curve intersection

The new method

• Solid.IntersectWithCurve()

calculates the intersection between a closed volume Solid and a curve. There is an option to return details about the segments inside the volume, or outside. Both the curve segments and the parameters of the segments are available in the results.

Face/Face Intersection

The method

• Face.Intersect()

calculates the intersection of the input face with this face and returns the intersection results.  The method can output the intersection geometry if the intersection consists of a single curve.

ReferenceIntersector & RVT Links

The new option findReferencesInRevitLinks allows ReferenceIntersector to find geometry in RVT links.

Rulings of RuledFace

The new method

• RuledFace.RulingsAreParallel

determines if the rulings of the ruled surface are parallel.

Detail elements

Detail element draw order

The class

• DetailElementOrderUtils

now includes routines to BringToFront, BringForward, SendToBack, SendBackward multiple detail members.  The draw order of the members does not change relative to one another.

Stairs

StairsRunJustification

New values LeftExterior and RightExterior have been added to this enum to support jusitification to the left and right supports.

StairsLanding

The new members:

• CreateAutomaticLanding(Document, ElementId, ElementId)
• CanCreateAutomaticLanding(Document, ElementId, ElementId)

provide automatic landing(s) creation and creation validation between two stairs runs.

StairsRun

The new properties:

• StairsRun.ExtensionBelowRiserBase
• StairsRun.ExtensionBelowTreadBase

represent the extension/trim value for the run, depending upon whether the run begins with a riser or tread.

These replace the deprecated property:

• StairsRun.ExtensionBelowBase

which now accesses whichever property listed above depending on the run's configuration.

StairsComponentConnection

The new methods:

• StairsRun.GetConnections()
• StairsLanding.GetConnections()

provide information about connections among stairs components (run to run, or run to landing).

Parameters & filters

Parameter.AsValueString()

This method previously was implemented for only Integer and Double values. It now can also be used with Enums and ElementIds. Optionally it can accept a FormatOptions object to specify units formatting of the returned string.

Parameter.Definition.UnitType

This new property provides access to the UnitType of a parameter definition.

Parameter variance among group instances

The new members:

• InternalDefinition.VariesAmongGroups
• InternalDefinition.SetVariesAmongGroups(Document)

support read and write to the option that the parameter value can vary across groups.  This can be changed only for non-built-in parameters.

FilterCategoryRule

The new class FilterCategoryRule can be used in the definition of a ParameterFilterElement.   It represents a filter rule that matches elements of a set of categories.

The related method:

• ParameterFilterElement.AllCategoriesFilterable()

has been replaced by

• FilterCategoryRule.AllCategoriesFilterable()

Miscellaneous

ThermalAsset.SpecificHeat

This new property provides the specific heat value of a thermal asset in feet per Kelvin, squared-second.

AreaVolumeSettings

This new class provides access to settings related to volume and area computations. The old VolumeCalculationSetting class is obsolete. 

Document.Delete()

This method previously returned null if the element or elements could not be deleted. It now will throw an exception in this situation.

Document level updaters

The new methods:

• UpdaterRegistry.IsUpdaterRegister(UpdaterId, Document)
• UpdaterRegistry.UnregisterUpdater(UpdaterId, Document)

provide the ability to inquire about and to unregister updaters that are associated to specific documents. 

UIThemeManager

The static properties of UIThemeManager provide access to the current UI theme and the default theme.

Families & content

Family category

The property

• FamilyBase.FamilyCategory

can now be set.  This allows the category of an family being edited to be changed.

SpatialElementCalculationLocation

The class SpatialElementCalculationLocation is used to specify the room or space where an element should be considered as placed.

This is a base class with currently subtypes of calculation location:

• SpatialElementCalculationPoint
• SpatialElementFromToCalculationPoints

A SpatialElementCalculationLocation can be added to the family by turning on the family's ROOM_CALCULATION_POINT parameter.   Once the location has been added, you can access the marker position using the MarkerPosition property. 

Note that the MarkerPosition property is no longer settable – this position is determined automatically.

SpatialElementFromToCalculationPoints

SpatialElementFromToCalculationPoints is a subclass of SpatialElementCalculationLocation used to specify the search points for a family instance that connects two rooms or spaces, such as a door or window. The points determine which room or space is considered the "from" and which is considered the "to".    The properties ToPosition and FromPosition govern the coordinates for these points.

Arc through points

The method

• CurveByPointsUtils.CreateArcThroughPoints()

creates an arc curve through three input ReferencePoints.

Events

DocumentChangedEventArgs

For the methods GetAddedElementIds()/GetModifiedElementIds() – internal Revit element ids that are not visible to UI and API are now excluded from the return set.

GetAddElementIds(ElementFilter)/GetModifiedElementIds(ElementFilter)

The new methods:

• DocumentChangedEventArgs.GetAddedElementIds(ElementFilter)
• DocumentChangedEventArgs.GetModifiedElementIds(ElementFilter)

only return ElementIds that pass the input element filter. This helps applications detect only specific changes of interest.

Reinforcement API

Reinforcement Length Tolerance

The new classes:

• RebarRoundingManager
• FabricRoundingManager

contain settings for rounding tolerance for rebar and fabric reinforcement elements.  They can be assigned at the element instance level (Rebar, RebarInSystem, FabricArea, FabricSheet), at the type level (RebarType, FabricSheetType), or at the ReinforcementSettings level.   Lower level settings override the setting of higher levels. 

I hope this is enough for you :-)

Cool, huh?

Revit 2014 API and Plan View Room Boundary Loops

I am continuing the research and development for my cloud-based round-trip 2D Revit model editing project.

At the same time, Revit 2014 has been announced, and I am sure you are eager to hear more about that, especially from the API point of view, so let's have a look at that first.

The Revit 2014 API

It is impossible to cover everything, and I have to start somewhere.

Here are a couple of highlights:

• API access to the project browser and selected elements; API commands and macros are enabled.
• Copy and paste API supports copy within or between documents including view-specific elements.
• Full API support for the new non-rectangular crop regions.
• Schedule API now provides formatting control and read-write access to individual data items.
• Command API enables programmatic command launch including built-in Revit, external add-in and macro.
• Add-in API supports mid-session loading and execution.
• Displaced elements API enables exploded views.
• Join geometry API to create or remove a Boolean join and control join order.
• FreeForm element API enables modification of solid geometry imported from e.g. DWG or SAT.
• Site API enables editing of topography surface points and supports sub-regions.
• MEP calculations are moved to external services and can be replaced by add-ins.
• Structural reinforcement and rebar enhancements.
• Enhanced document open, save and worksharing API.
• Linked model API supports loading, unloading, path manipulation, link identification and creation.
• Linked model interaction enables tag creation for linked rooms, linked element selection, geometric reference conversion, etc.
• Import DXF markup, import and link SAT and SketchUp.
• Export to NavisWorks via add-in, access DWG, IFC and DGN layer, linetype, lineweight, font and pattern tables.
• Direct API access to rendering output pipeline including all geometry and material properties.
• Macro API provides support for Python and Ruby development plus List, create, delete and execute modules, macros and security settings.

How does that sound?

Rather a lot of new stuff, isn't there?

Rather a lot of really exciting new stuff, isn't there?

Joe Ye describes a few of these API features in a little more detail on the AEC DevBlog.

To round this off, here are the complete materials from the Revit 2014 DevDays presentations:

• Presentation
• Recording
• Sample code

We will have all the time in the world to explore this in more detail anon.

The material provided above should keep you occupied over the Easter weekend, however :-)

Enjoy!

Retrieving Plan View Room Boundary Polygon Loops

Returning to the cloud-based 2D model editing project, one of the first required components is an add-in that determines and uploads the room, furniture and equipment family instance boundary polygons to some globally accessible data repository for a simplified 2D plan view rendering on a mobile device.

As a first step in that direction, I revamped my code to retrieve and graphically display area boundary loops and combined it with the integer-based point class that I implemented for the OBJ model exporter.

The task I want to achieve for the first part of this first step is to retrieve the room boundary and store the 2D loops in a cloud-based data repository.

Since Revit does not support precision below one sixteenth of an inch, I might as well approximate all my data to something in that region.

For performance and efficiency reasons, it is also useful to move my calculations from floating point double numbers to integers.

Since I want to display my model on a mobile device with a limited resolution using SVG, integers also seem pretty appropriate.

Very handily, a millimetre is just a little bit less than a sixteenth of an inch.

That leads me to define the following integer-based 2D point class:

/// <summary>
/// An integer-based 2D point class.
/// </summary>
class Point2dInt : IComparable<Point2dInt>
{
  public int X { get; set; }
  public int Y { get; set; }
 
  const double _feet_to_mm = 25.4 * 12;
 
  static int ConvertFeetToMillimetres( double d )
  {
    return (int) ( _feet_to_mm * d + 0.5 );
  }
 
  /// <summary>
  /// Convert a 3D Revit XYZ to a 2D millimetre 
  /// integer point by discarding the Z coordinate
  /// and scaling from feet to mm.
  /// </summary>
  public Point2dInt( XYZ p )
  {
    X = ConvertFeetToMillimetres( p.X );
    Y = ConvertFeetToMillimetres( p.Y );
  }
 
  public int CompareTo( Point2dInt a )
  {
    int d = X - a.X;
 
    if( 0 == d )
    {
      d = Y - a.Y;
    }
    return d;
  }
 
  public override string ToString()
  {
    return string.Format( "({0},{1})", X, Y );
  }
}

A room boundary may include several loops, for instance if a room surrounds some other space such as an elevator, i.e. its outer boundary loop contains some interior loops representing 'holes'.

Therefore, the room GetBoundarySegments method returns a list of loops, and each loop as a list of boundary segments:

  IList<IList<BoundarySegment>> loops = room.
    GetBoundarySegments( opt );

I therefore define my own integer-based 2D loop and list of loops classes like this:

  class JtLoop : List<Point2dInt>
  {
    public JtLoop( int capacity )
      : base( capacity )
    {
    }
 
    public override string ToString()
    {
      return string.Join( ", ", this );
    }
  }
 
  class JtLoops : List<JtLoop>
  {
    public JtLoops( int capacity )
      : base( capacity )
    {
    }
  }

The code to retrieve the boundary segments and convert them to my own representation can be implemented as follows:

/// <summary>
/// Retrieve the room plan view boundary 
/// polygon loops and convert to 2D integer-based.
/// For optimisation and consistency reasons, 
/// convert all coordinates to integer values in
/// millimetres. Revit precision is limited to 
/// 1/16 of an inch, which is abaut 1.2 mm, anyway.
/// </summary>
JtLoops GetRoomLoops( Room room )
{
  SpatialElementBoundaryOptions opt
    = new SpatialElementBoundaryOptions();
 
  opt.SpatialElementBoundaryLocation =
    SpatialElementBoundaryLocation.Center; // loops closed
    //SpatialElementBoundaryLocation.Finish; // loops not closed
 
  IList<IList<BoundarySegment>> loops = room.
    GetBoundarySegments( opt );
 
  int nLoops = loops.Count;
 
  JtLoops jtloops = new JtLoops( nLoops );
 
  foreach( IList<BoundarySegment> loop in loops )
  {
    int nSegments = loop.Count;
 
    JtLoop jtloop = new JtLoop( nSegments );
 
    XYZ p0 = null; // loop start point
    XYZ p; // segment start point
    XYZ q = null; // segment end point
 
    foreach( BoundarySegment seg in loop )
    {
      p = seg.Curve.get_EndPoint( 0 );
 
      jtloop.Add( new Point2dInt( p ) );
 
      Debug.Assert( null == q || q.IsAlmostEqualTo( p ),
        "expected last endpoint to equal current start point" );
 
      q = seg.Curve.get_EndPoint( 1 );
 
      Debug.Print( "{0} --> {1}",
        Util.PointString( p.ToUv() ),
        Util.PointString( q.ToUv() ) );
 
      if( null == p0 )
      {
        p0 = p; // save loop start point
      }
    }
    Debug.Assert( q.IsAlmostEqualTo( p0 ),
      "expected last endpoint to equal loop start point" );
 
    jtloops.Add( jtloop );
  }
  return jtloops;
}

My external command mainline Execute method driving this method also implements some fancy pre- and post-selection support and reporting code listing the contents of my 2D integer-based loops in the Visual Studio debug output window:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  if( null == doc )
  {
    ErrorMsg( "Please run this command in a valid"
      + " Revit project document." );
    return Result.Failed;
  }
 
  // Iterate over all pre-selected rooms
 
  List<ElementId> ids = null;
 
  Selection sel = uidoc.Selection;
 
  if( 0 < sel.Elements.Size )
  {
    foreach( Element e in sel.Elements )
    {
      if( !( e is Room ) )
      {
        ErrorMsg( "Please pre-select only room"
          + " elements before running this command." );
        return Result.Failed;
      }
 
      if( null == ids )
      {
        ids = new List<ElementId>( 1 );
      }
 
      ids.Add( e.Id );
    }
  }
 
  // If no rooms were pre-selected, 
  // prompt for post-selection
 
  if( null == ids )
  {
    IList<Reference> refs = null;
 
    try
    {
      refs = sel.PickObjects( ObjectType.Element,
        new RoomSelectionFilter(),
        "Please select rooms." );
    }
    catch( Autodesk.Revit.Exceptions
      .OperationCanceledException )
    {
      return Result.Cancelled;
    }
    ids = new List<ElementId>(
      refs.Select<Reference, ElementId>(
        r => r.ElementId ) );
  }
 
  foreach( ElementId id in ids )
  {
    Element e = doc.GetElement( id );
 
    Debug.Assert( e is Room,
      "expected parts only" );
 
    JtLoops roomLoops = GetRoomLoops( e as Room );
 
    int nLoops = roomLoops.Count;
 
    Debug.Print( "{0} has {1} loop{2}{3}",
      Util.ElementDescription( e ), nLoops,
      Util.PluralSuffix( nLoops ),
      Util.DotOrColon( nLoops ) );
 
    int i = 0;
 
    foreach( JtLoop loop in roomLoops )
    {
      Debug.Print( "  {0}: {1}", i++, loop.ToString() );
    }
  }
  return Result.Succeeded;
}

I tested this on a simple sample room with one hole:

The original start and end points of the boundary segments for this room are reported as follows:

  (9.03,10.13,0) --> (-14.59,10.13,0)
  (-14.59,10.13,0) --> (-14.59,1.93,0)
  (-14.59,1.93,0) --> (-2.45,1.93,0)
  (-2.45,1.93,0) --> (-2.45,-3.98,0)
  (-2.45,-3.98,0) --> (9.03,-3.98,0)
  (9.03,-3.98,0) --> (9.03,10.13,0)
  (0.98,-0.37,0) --> (0.98,1.93,0)
  (0.98,1.93,0) --> (5.57,1.93,0)
  (5.57,1.93,0) --> (5.57,-0.37,0)
  (5.57,-0.37,0) --> (0.98,-0.37,0)

Converting these to my 2D integer-based loop classes and listing those generates the following debug output:

  Room Rooms <212639 Room 1> has 2 loops:
    0: (2753,3087), (-4446,3087), (-4446,587),
      (-746,587), (-746,-1212), (2753,-1212)
    1: (298,-112), (298,587), (1698,587), (1698,-112)

So far, so good.

As far as I can tell, all systems go.

My next step for this add-in is to implement code to determine 2D plan view boundary polygons for the furniture and equipment family instances contained within the selected room.

I am hoping to be able to make use of the ExtrusionAnalyzer class for this. As I mentioned, it is supplied a solid geometry, a plane, and a direction. From those, it calculates the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction.

At the same time, I am continuing to explore options for a cloud-based data repository.

And I have my day-to-day support tasks to attend to too...

Anyway, here is GetRoomLoops.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

Revit 2014 and Supporting Columns

Revit 2014 Announced

As you probably noticed by now, Revit 2014 has been announced. Here are the main product features:

• Design
  • Enhanced Autodesk Exchange
  • Dockable window framework
  • New stairs and railings
  • Temporary view templates to change view properties temporarily
  • Point cloud improvements improve appearance and controls of point clouds
  • Parameter variance for groups to vary the value of parameters assigned to groups
  • New air terminal on duct enables placement of air terminal device on duct face
  • New angle constraints to restrict angles for pipe, duct, and cable tray
  • Cap open ends of pipe or duct content quickly
  • CSV file removal project, embedding the data into families
  • New plumbing template
  • New rebar placement constraints customization
  • Reinforcement enhancements with more rebar options
• Documentation
  • Non-rectangular crop regions
  • Split elevations
  • Alternate dimensions
  • Improved rebar tagging to annotate multiple elements with a single tag
  • Improved positioning of beams and braces
  • Enhanced schedules providing greater control of schedule formatting
• Visualization
  • Displaced views enable creation of displaced or exploded building design views
  • Enhanced visualization
  • New rendering to reduce project costs with cloud-based rendering
• Analysis
  • New building element energy analysis
  • Enhanced structural analytical model
  • New duct and pipe calculations to API

Each and every one of these is really exciting in itself, and almost all include or are even based on enhanced API support. Some of the ones that seem most exciting to me are the non-rectangular crop regions, parameter variance for groups, enhanced schedules, displaced views... well, as said, they are really all very exciting.

And this is not even mentioning some of the new API features, such as the possibility to launch a Revit command and control copy and paste operations. I will get to all that real soon now.

As Harry puts it, the Revit 2014 API is going to blow your faces out :-)

Determining the Columns Supporting a Beam

Still, ignoring all that busy-ness for the moment, I chug along and return to a topic similar to my discussion on retrieving all touching beams.

In that post, I showed how to recursively traverse a collection of beams and detect the neighbouring ones at each end using an ElementIntersectsSolidFilter with a sphere.

Today I explore the task of determining the columns supporting a selected beam using various different methods.

• Columns supporting a selected beam
• Solid and element intersection
• Bounding box filter tolerance
• Moving the beam downwards in a temporary transaction
• GetGeneratingElementIds
• Cylinder Along Location Line Offset Downwards
• Find references via ray casting
• Sweep Along Location Curve Offset Downwards
• Conclusion and source code

Columns Supporting a Selected Beam

Here is a view of a simple sample model:

The task at hand is to pick the indicated beam and report the columns supporting it:

Simple, ain't it?

Solid and Element Intersection

Initially, I made some further attempts and experiments using the ElementIntersectsSolidFilter and ElementIntersectsElementFilter functionality.

The sample provided includes code exercising these tests and also the original bounding box implementation. It is enclosed in 'if' statements checking the setting of the following Boolean variables:

  bool useBoundingBox = false;
  bool useSolid = false;
  bool useElement = false;

That enables them to be switched on and off interactively in the debugger, if the need arises.

Unfortunately, as it turns out, they both do not work.

The beam solid is not quite big enough to intersect the columns, because the beam is cut back so that it does not actually intersect them.

The same problem also prevents use the element intersection filter.

It would be great if there was a possibility to grow the solid just slightly, e.g. offset all its faces outwards by an inch or two or define a tolerance before executing the intersection check, like for the bounding box. Unfortunately, growing or shrinking an arbitrary solid is much harder than a bounding box and therefore not implemented.

Bounding Box Filter Tolerance

The BoundingBoxIsInsideFilter can be instantiated with an optional double tolerance value that allows control over the match criteria by using the given tolerance in the geometry comparison.

By default, the tolerance is set to zero. If the tolerance is positive, the iterated element outline may extend the tolerance distance outside of the given outline in each coordinate to be a match. If the tolerance is negative, the iterated element outline must lie at least the tolerance distance inside the given outline in each coordinate to be a match.

This is exactly what I would need here for the solid and element intersection filters as well. Unfortunately, as said, such a tolerance is not supported by the solid or element intersection filters.

Moving the Beam Downwards in a Temporary Transaction

Lacking the tolerance option, I thought that maybe it would help to move the beam down a bit, and that it would intersect the supporting columns then. Unfortunately, that does not help either.

The problem is not only that the bottom face of the beam solid may be located above the end of the supporting columns, but also that the ends of the beam are cut back to avoid intersecting the columns, so their solids do not intersect even when the beam is moved slightly downwards.

This temporary movement forces a switch from read-only to manual transaction mode, of course, even though the model is not actually modify in any way in the end.

To make sure that the movement really is executed and the model updated before checking for an intersection, I followed the advice given by Arnošt Löbel on enhancing the temporary transaction trick and encapsulated the whole operation in a transaction group. The group is rolled rolled back at the end, but, before doing so, the encapsulated temporary transaction around the movement of the beam can be committed and the updated geometry evaluated.

By the way, these changes temporarily caused an error saying "Attempted to read or write protected memory. This is often an indication that other memory is corrupt." This was probably due to accessing the list of elements generated within the temporary transaction after the transaction group is rolled back. I handled that problem by storing the element ids instead of the live elements themselves inside the transaction, and then opening the elements via their id after rolling back the changes.

As said, the temporary downward translation still did not produce any intersections.

Time for another idea.

GetGeneratingElementIds

A colleague suggested that if the beam is cut back by the columns, you can iterate over the beam geometry faces and call the Element GetGeneratingElementIds method on each one, which might return the column element ids. In this example, you might also get faces generated by joins with other beams.

I tried this, encapsulating the code in the section if( useGeneratingIds ). Unfortunately, all the generating ids belong to the structural framing or floors categories, so that does not help to determine the columns either. No columns at all are returned by this method.

Cylinder Along Location Line Offset Downwards

I then realised that I could create a much simpler independent solid shape to intersect the columns by extruding a cylinder along the beam location line, offset downwards to just below the bottom face of the beam. It might require extending a little at each end. All supporting columns should be intersected by it.

I can use code similar to the sample presented to find 3D elements by intersection.

Yay! This works!

Find References via Ray Casting

A similar approach as the solid intersection with an offset cylinder could obviously also be implemented using the ray casting functionality provided by the FindReferencesByDirection and FindReferencesWithContextByDirection methods and the ReferenceIntersector wrapper class.

I did not implement any sample code demonstrating this, because I wanted to generalise the straight beam cylinder solution to a more general arbitrary curve case.

Sweep Along Location Curve Offset Downwards

Once I had the working solution using a cylinder defined by the straight beam location line offset downwards, I realised that it might be nice to use more generic sweep along curve functionality instead. After all, the beam location curve might not be straight, and a non-linear location curve can quite simply be used to generate a non-linear solid using the CreateSweptGeometry method instead of CreateExtrusionGeometry.

My first attempt caused the CreateSweptGeometry method to throw an exception saying that "The given attachment point don't lie in the plane of the Curve Loop. Parameter name: pathAttachmentCrvIdx & pathAttachmentParam". That was my fault, though, because I was providing zero for the parameter value, which is probably the normalised curve start point parameter. When providing the raw parameter value returned by curve.get_EndParameter( 0 ) instead, all works fine.

Here is a rather unrealistic sample spline beam that I used for testing:

The algorithm reports the following supporting columns for the spline beam:

All is well.

Conclusion and Source Code

Here is the complete source code of this command, including the test branches that are disabled by default. As said, they can be enabled and tested by modifying the Boolean switches interactively in the debugger.

[Transaction( TransactionMode.ReadOnly )]
public class Command : IExternalCommand
{
  const double _eps = 0.1e-9;
 
  double SignedDistanceTo( Plane plane, XYZ p )
  {
    XYZ v = plane.Normal;
    return v.DotProduct( p )
      - v.DotProduct( plane.Origin );
  }
 
  class BeamPickFilter : ISelectionFilter
  {
    public bool AllowElement( Element e )
    {
      return null != e.Category
        && e.Category.Id.IntegerValue.Equals(
          (int) BuiltInCategory.OST_StructuralFraming );
    }
 
    public bool AllowReference( Reference r, XYZ p )
    {
      return true;
    }
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
    Element beam = null;
 
    try
    {
      Selection sel = uidoc.Selection;
 
      Reference r = sel.PickObject(
        ObjectType.Element,
        new BeamPickFilter(),
        "Please select a beam" );
 
      beam = doc.GetElement( r );
    }
    catch( RvtOperationCanceledException )
    {
      return Result.Cancelled;
    }
 
    List<ElementId> columnIds = null;
 
    // Optionally switch between different tests
    // by modifying these values in the debugger
 
    bool useBoundingBox = false;
    bool useSolid = false;
    bool useElement = false;
    bool useGeneratingIds = false;
    bool useLocation = true;
 
    #region Obsolete previous attempts
    if( useBoundingBox )
    {
      BoundingBoxXYZ box = beam.get_BoundingBox( null );
 
      Outline outline = new Outline( box.Min, box.Max );
 
      ElementFilter bbfilter = new BoundingBoxIntersectsFilter(
        outline, 0.1 );
 
      FilteredElementCollector columns
        = new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( bbfilter );
    }
 
    if( useSolid )
    {
      Options opt = app.Create.NewGeometryOptions();
      GeometryElement geo = beam.get_Geometry( opt );
      Solid solid = null;
 
      foreach( GeometryObject obj in geo )
      {
        solid = obj as Solid;
 
        if( null != solid
          && 0 < solid.Faces.Size )
        {
          break;
        }
      }
 
      ElementFilter beamIntersectFilter
        = new ElementIntersectsSolidFilter( solid );
 
      FilteredElementCollector columns
        = new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( beamIntersectFilter );
    }
 
    if( useElement )
    {
      // Initially, no columns are found to 
      // intersect the beam. Maybe it will help to
      // move the beam down a bit?
 
      using( TransactionGroup txg = new TransactionGroup( doc ) )
      {
        txg.Start( "Find Columns Intersecting Beam" );
 
        using( Transaction tx = new Transaction( doc ) )
        {
          tx.Start( "Temporarily Move Beam Down a Little" );
 
          ElementTransformUtils.MoveElement(
            doc, beam.Id, -0.1 * XYZ.BasisZ );
 
          tx.Commit();
        }
 
        ElementFilter beamIntersectFilter
          = new ElementIntersectsElementFilter( beam );
 
        FilteredElementCollector columns
          = new FilteredElementCollector( doc )
            .WhereElementIsNotElementType()
            .OfCategory( BuiltInCategory.OST_StructuralColumns )
            .WherePasses( beamIntersectFilter );
 
        columnIds = new List<ElementId>(
          columns.ToElementIds() );
 
        // We do not commit the transaction group, 
        // because no modifications should be saved.
        // The transaction group is only created and 
        // started to encapsulate the transactions 
        // required by the IsolateElementTemporary 
        // method. Since the transaction group is not 
        // committed, the changes are automatically 
        // discarded.
 
        //txg.Commit();
      }
    }
 
    if( useGeneratingIds )
    {
      Options opt = app.Create.NewGeometryOptions();
      GeometryElement geo = beam.get_Geometry( opt );
 
      foreach( GeometryObject obj in geo )
      {
        Solid solid = obj as Solid;
 
        if( null != solid )
        {
          foreach( Face f in solid.Faces )
          {
            ICollection<ElementId> ids
              = beam.GetGeneratingElementIds( f );
 
            foreach( ElementId id in ids )
            {
              Element e = doc.GetElement( id );
              if( null != e.Category
                && e.Category.Id.IntegerValue.Equals(
                  (int) BuiltInCategory.OST_StructuralColumns ) )
              {
                columnIds.Add( id );
              }
            }
          }
        }
      }
    }
    #endregion // Obsolete previous attempts
 
    if( useLocation )
    {
      // Determine beam location curve for 
      // extrusion direction and length
 
      LocationCurve lc = beam.Location as LocationCurve;
 
      Curve curve = lc.Curve;
 
      Solid solid = null;
 
      // Handle generic curve parameters.
      // See below for simplified linear case.
 
      XYZ p = curve.get_EndPoint( 0 );
      double param = curve.get_EndParameter( 0 );
      Transform transform = curve.ComputeDerivatives( param, false );
      Debug.Assert( p.IsAlmostEqualTo( transform.Origin ),
        "expected derivative origin to equal evaluation curve point" );
      XYZ tangent = transform.BasisX;
 
      // Use bounding box to determine elevation of
      // bottom of beam and how far downwards to 
      // offset location line -- one inch below 
      // beam bottom.
 
      BoundingBoxXYZ bb = beam.get_BoundingBox( null );
 
      Debug.Assert( .001 > bb.Min.Z - bb.Max.Z,
        "expected horizontal beam" );
 
      double inch = 1.0 / 12.0;
      double beamBottom = bb.Min.Z;
 
      XYZ arcCenter = new XYZ( p.X, p.Y,
        beamBottom - inch );
 
      Plane plane = new Plane( tangent, arcCenter );
 
      CurveLoop profileLoop = new CurveLoop();
 
      Autodesk.Revit.Creation.Application creapp
        = app.Create;
 
      Arc arc1 = creapp.NewArc(
        plane, inch, 0, Math.PI );
 
      Arc arc2 = creapp.NewArc(
        plane, inch, Math.PI, 2 * Math.PI );
 
      profileLoop.Append( arc1 );
      profileLoop.Append( arc2 );
 
      List<CurveLoop> loops = new List<CurveLoop>( 1 );
      loops.Add( profileLoop );
 
      // Switch this on to handle a straight beam as 
      // a separate simplified case using 
      // CreateExtrusionGeometry instead of the 
      // generic CreateSweptGeometry solution.
 
      bool checkForLine = false;
 
      if( checkForLine && curve is Line )
      {
        XYZ q = curve.get_EndPoint( 1 );
        XYZ v = q - p;
 
        Debug.Assert( 0.01 > v.Z,
          "expected horizontal beam" );
 
        Debug.Assert( v.IsAlmostEqualTo( tangent ),
          "expected straight beam vector to equal start tangent" );
 
        solid = GeometryCreationUtilities
          .CreateExtrusionGeometry( loops, v, v.GetLength() );
      }
      else
      {
        // Offset location curve downward 
        // one inch  below beam bottom face
 
        XYZ offset = arcCenter - p;
 
        transform = Transform.get_Translation(
          offset );
 
        CurveLoop sweepPath = new CurveLoop();
 
        sweepPath.Append( curve.get_Transformed(
          transform ) );
 
        solid = GeometryCreationUtilities
          .CreateSweptGeometry(
            sweepPath, 0, param, loops );
      }
 
      ElementFilter beamIntersectFilter
        = new ElementIntersectsSolidFilter( solid );
 
      columnIds = new List<ElementId>(
        new FilteredElementCollector( doc )
          .WhereElementIsNotElementType()
          .OfCategory( BuiltInCategory.OST_StructuralColumns )
          .WherePasses( beamIntersectFilter )
          .ToElementIds() );
    }
 
    int n = (null == columnIds)
      ? 0
      : columnIds.Count<ElementId>();
 
    string s1 = string.Format(
      "Selected beam is supported by {0} column{1}{2}",
      n,
      ( 1 == n ? "" : "s" ),
      ( 0 == n ? "." : ":" ) );
 
    string s2 = "<None>";
 
    if( 0 < n )
    {
      uidoc.Selection.Elements.Clear();
 
      foreach( ElementId id in columnIds )
      {
        Element e = doc.GetElement( id );
        uidoc.Selection.Elements.Add( e );
      }
 
      s2 = string.Join( ", ",
        columnIds.ConvertAll<string>(
          id => id.IntegerValue.ToString() ) );
    }
 
    TaskDialog.Show( s1, s2 );
 
    return Result.Succeeded;
  }
}

For your convenience, here is GetBeamColumns06.zip containing the complete source code, Visual Studio solution and add-in manifest of the GetBeamColumns external command.

I hope you find this both interesting and useful as a basis for your own variants.

Cloud & Mobile, Extensible Storage Data Use in Schedules

My topics for today are:

• Cloud and mobile topics I covered so far
• Cloud-based round-trip 2D Revit model editing on any mobile device using SVG
• Extensible storage data use in schedules

I am still meeting with my European DevTech colleagues here in Konk Leon, 'anse du Lèon', the cove of the lion, aka Le Conquet, Brittany.

Yesterday, one of our topics was work we have done so far for cloud and mobile applications. It was very interesting to hear about my peers' rich and varied experiences.

Cloud and Mobile Topics Covered so Far

I documented all my own experiences so far here on the blog, and was able to reuse that for my presentation quite spontaneously with no further preparation:

• Accessing a REST API web service from a Revit .NET add-in – Apollonian sphere packing and AVF.
• Thoughts on mobile indoor positioning, representing room polygons in SVG, the Azure SDK, ASP.NET MVC 4, and implementing a web service.
• An overview of the BIM 360 Glue viewer and REST API.
• BIM 360 Glue REST API authentication using Python.
• A room polygon and furniture picker in SVG.
• 2D SVG editing on mobile devices using the Raphaël JavaScript SVG library.

As I explained at the time, all of the explorations involving SVG are part of a larger master plan.

This plan has now matured to a certain extent and is forcing me to move ahead quite fast in the immediate future.

The main outcome so far is a presentation proposal that I submitted for the internal Autodesk technical summit taking place in June, and the fact that it was accepted.

My cloud and mobile roadmap is thus now clearly focused on implementing that proposal:

Cloud-based Round-trip 2D Revit Model Editing on any Mobile Device using SVG

I described the roadmap I envision in the discussion of my simple SVG editor. The main components include:

• A Revit add-in that determines room boundary and furniture and equipment family instance polygons for a simplified 2D plan view rendering.
• A cloud-based database repository managing the models, levels, rooms, furniture, equipment meta- and polygon data.
• The SVG editor running in a browser on any device, rendering the model and supporting some simple geometric modification.

Here is the actual wording of my technical summit proposal:

Proposal Abstract

This presentation demonstrates round-trip editing a 2D rendering of a Revit model on any mobile device with no need for installation of any additional software whatsoever beyond a browser. How can this be achieved? A Revit add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository. On the mobile device, the repository is queried and the data is rendered in a standard browser using JavaScript and SVG. The rendering supports modification, such as translation and rotation of the furniture and equipment, which is saved back to the cloud database. The Revit add-in picks up these changes and updates the Revit model.

Intended Audience and Prerequisites

Intended audience is programmers with interest in cloud-based and mobile computing, specifically interest in round-trip editing of a Revit model using a cloud-based data repository and editing a 2D model on an arbitrary mobile device with no additional software beyond a browser installed on it. 
Knowledge of .NET, JavaScript and REST programming is helpful but not required. Revit add-in experience is not a prerequisite.

Presentation Outline

• Show a Revit model.
• Export the model to a cloud-based data repository.
• Query and display the repository contents as 2D rendering on a mobile device.
• Edit the model in the browser on the mobile device, updating the data repository.
• Pick up and display the modified model in Revit.

Two of the important components whose implementation I plan to explore next are the polygon generation and data model:

Plan View Polygon Determination

The generation of the room boundary polygons is obvious, since the room has a boundary property.

For the furniture and equipment family instance, the solution is a less immediate. My current idea is to explore making use of the ExtrusionAnalyzer class. It is supplied a solid geometry, a plane, and a direction. From those, it calculates the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction. As far as I can tell, that should be exactly what I need.

Scott Conover mentioned this class in his session on the Geometry API, a continuation of his AU 2011 presentation CP4011 'Geometric Progression: Further Analysis of Geometry Using the Autodesk Revit 2012 API', enhanced for the Revit 2013 API.

As soon as I have the polygons determined, I want to implement functionality to render them easily. This will involve extent calculation, canvas definition, and coordinate system transformation. I will probably implement a simple .NET geometry viewer before moving on to the SVG rendering. I've been wanting to do that for a long time...

Cloud-based Data Repository

So far, my colleagues have been focusing on using the Amazon and Azure cloud hosting services, and many discussions on the cloud and mobile DevBlog deal with them.

I searched the Internet for other cloud-based database alternatives, and right now CouchDB looks pretty promising, so I might try a completely different approach using that instead.

There is a lot to do here as well: define the data model, set up the web service, define a format for saving the polygon data, etc. At the very least, I will need to manage:

• Model > metadata, rooms.
• Room > metadata, model, furniture, level, polygon.
• Furniture > metadata, room, polygon, transformation (initially identity).

Round tripping the information will be interesting, especially if I want the Revit model to update automatically when furniture positions are modified on the mobile device, which I certainly do, if only for the wow effect :-)

Stay tuned...

... Oh, and, yeah, wish me luck!

Extensible Storage Data Use in Schedules

Returning to the desktop again, here is a recent question from a developer on using estorage data in a schedule that leads to some general observations on that topic:

Question: I would like to display my extensible storage information in a schedule. I searched high and low, though, and was unable to find any samples or documentation on the subject. Can you help?

Answer: There is a good reason why you have not found anything: there is no such support.

The usage of extensible storage data is utterly and completely up to the add-in itself. The Revit API offers no support whatsoever for making use of estorage data in any way. The only support provided is for storage and retrieval, nothing else.

Well, one tiny little detail more: if an element id value is stored, and the element id is later modified by some worksharing operation, its value will be automatically updated.

On the other hand, there is currently no direct support for putting data into a schedule either.

I am no user interface expert, but I think that you can set up a schedule to be populated from certain parameter values via the user interface. You would have to talk with an application engineer or product support or explore this topic on the Internet to find out how that can be done.

Of course, there is nothing stopping you from extracting your data from extensible storage and transferring it into parameters set up to populate a schedule yourself.

I hope that answers your question and helps you get started successfully.

Curve Evaluation and Song of the Gulls

Below, we take a look at one aspect of parametric NURB spline curve evaluation and an overview of recent AEC DevBlog posts.

First, however, another update on my vacation :-)

Marvels of the Song of the Gulls

I am winding up my vacation on the Island of Ischia that I first discovered three years back.

It is one of my favourite places in the world, where I visited natural wonders such as hot thermal springs of Sorgeto in Panza, where you can build your own bathtub to mix the hot spring water with the cold waves from the sea, and the antique natural roman bath of Cavascura on the Maronti Beach that includes a natural sauna in hewn rock that has been running uninterrupted for 3000 years.

On the way here, I first got off at the wrong ferry stop in Procida. That also proved very nice, with all the families taking their numerous kids for a Sunday walk, to chat and play in the main square.

From the ferry, I walked up to the Chiesa della Annunziata and on to the Piano Liguori and then explored the peninsula of San Pancrazio with its spectacular old church and caves. Here is the view from Piano Liguori back towards Procida and Naples.

I visited the Trani family restaurant, olives and vineyard. They even built their own staircase access to the sea, tunnelling through the almost vertical rock facing the water.

It was a huge pleasure chatting with one of the Trani sons and listening to his joy over the traditional agricultural work amidst the 'canto dei gabbiani', the song of the gulls, and the challenges of making it economically viable through some interaction with tourism.

I later saw this wonderful example of a scalable implementation and thinking outside the box:

Parametric NURB Spline Curve Evaluation

Question: I use the Curve.Evaluate method to obtain equally spaced points along a curve.

This works fine for most curve types, but not on a NURB Spline that I created.

When I evaluate with regularly incremented parameter values, e.g. 0, .2, .4, .6, .8 and 1, the distances of the resulting positions along the curve are not visually equal. Using the same curve to create a ruled surface shows the lines and points appearing where one would expect.

Here is an example with the green lines displayed where ruled lines on the face occur, and text letters at the locations returned by the evaluate function:

Answer: The parameterisation of a NURB spline is such that regions of strong curvature are 'longer' in the parameter space than the actual curve length.

The assumption that a parameter measures uniformly along its length can only be made for lines and arcs. For ellipses and splines the parameter does not typically follow this pattern, because of the mathematics involved.

This is mentioned in the Developer Guide description of the parameter used in curve parameterisation:

"A ‘normalized’ parameter. The start value of the parameter is 0.0, and the end value is 1.0. For some curve types, this makes evaluation of the curve along its extents very easy; for example, the midpoint of a line is at parameter 0.5. (Note that for more complex curve equations like Splines this assumption cannot always be made)."

It is also explained in more detail in the Wikihelp community article on points hosted on curve edges.

The Revit Geometry API currently does not offer the ability to measure by segment-length or normalized segment-length. If it did, a more iterative solution would be easy to describe.

Recent AEC DevBlog Overview

Here is an overview of some of the posts by my colleagues on the AEC DevBlog in the past few weeks:

• Bubble end and free end arguments: explores the detailed meaning of the two XYZ parameters bubbleEnd and freeEnd to the NewReferencePlane method.
• Regenerating the model: provides yet another example in the long list of situations requiring an extra regeneration or transaction.
• SQLite version conflict with a Revit add-in discusses methods to resolve a DLL version conflict.
• Hiding sections in ViewPlan presents sample code to filter out the plan views, filter the sections created on each one of them, and call HideElements to suppress them in the view.
• Determining if a family instance requires a host can be achieved using RevitLookup and the HOST parameter on the family itself.
• Retrieving paint material for walls uses the Face HasRegions property and GetRegions method.
• Disassociating a family parameter from an element parameter is possible using the FamilyManager AssociateElementParameterToFamilyParameter method.
• Accessing the material value of a panel uses the MATERIAL_ID_PARAM built-in parameter on the panel type referenced by the panel element.
• Using Rebar.CreateFromCurves with curves: if a Rebar shape includes any straight edges, then its first and last curves must be straight lines, unless it is completely made up of arcs.
• Revit API error in projects with web references can be fixed by changing the 'Generate Serialization Assembly' setting from 'Auto' to 'Off' in the Visual Studio project properties build tab.

What's New in the Revit 2013 API

This is the fourth and last instalment of a series publishing the information provided in the 'What's New' sections of the past few Revit API releases help file RevitAPI.chm.

The first instalment covering What's New in the Revit 2010 API explains my motivation for this and provides an overview of the other releases.

We now move on to the Revit 2013 API, looking at:

• Major changes and renovations
• Major enhancements
• Small enhancements & API interface changes

First, however, another update on my vacation.

Turning North Again

I am still on holiday in Italy, so please do not expect any immediate responses to comments for a while.

After withstanding a snowstorm in the north, I did indeed find some warmth further south.

Almond trees are in bloom, and the grass is as green as it will ever get.

I explored the sweet Apulian local train system.

We had some cold and rainy days in the south also.

Turning back northwards towards Napoli under splendid blue skies, I passed this house beside a cafe I visited changing trains in Taranto.

I walked the wonderful Sentiero degli Dei that I remember so well from my visit in 2009.

This time around, I started at the bottom, in Praiano, walked up to the Convento San Domenico, spent the night there, and walked on through Nocelle back down to Positano next morning.

We had a terrible struggle to get there and back out again due to a bus strike. We finally reached Napoli, though, and first of all had a pizza.

The clouds returned and covered the Vesuvio.

Spring is eagerly awaited here also, even inspiring the pasticceria.

Now for the last instalment of the previous Revit API releases' news, bringing us up to date with the current day.

Major Changes and Renovations

to the Revit 2013 API

.NET 4.0 for compilation

All Revit components including RevitAPI.dll and RevitAPIUI.dll are now built with the .NET 4.0 compiler. Thus, add-in projects which reference Revit DLLs must be set as .NET 4.0 Framework projects as well.

New macro environment

VSTA has been replaced by SharpDevelop. This provides identical capabilities for macro creation, editing, and debugging as well as for deployment (application-level and document-level macros) and a simple upgrade procedure for existing macros.

SharpDevelop also provides expanded IDE capabilities, .NET 4.0, extended refactoring tools, code analysis tools, a regular expression toolkit, and macro IDE add-in support.

Revit.ini registration disabled

Add-ins will no longer be read from Revit.ini. Revit will look only to .addin files in the machine-wide and user-specific locations when deciding what add-ins to load.

Document.Element properties replaced

The indexed properties:

• Document.Element[ElementId]
• Document.Element[String]

have been replaced by methods:

• Document.GetElement(ElementId)
• Document.GetElement(String)

The old indexed properties have been marked obsolete.

The behavior for the new methods is identical to what they replaced.

Replacements for use of old-style collections

ElementArray and ElementSet are now obsolete

With a few exceptions, API methods using ElementArray and ElementSet have been replaced with equivalents using .NET generic collections of ElementIds (ICollection<ElementId>).

Some APIs have been obsoleted with no replacement; these methods are batch element creation methods which dated to the time when regeneration was automatic after every database change. Now that regeneration is manual, having separate batch creation methods provides no extra benefit as multiple element creation calls can be chained together with no delay caused by regeneration. Thus these methods are obsolete:

• ItemFactoryBase.NewTextNotes()
• Creation.Document.NewRooms(List<RoomCreationData>)
• Creation.Document.NewWalls() (all overloads)

When replacing calls to these methods, you should use the corresponding creation method which creates a single element in a loop, while delaying calls to Regenerate() until the loop has concluded. Because Regenerate() is delayed, you should not make inquiries to the newly created elements' geometry as a part of the loop.

Definitions and DefinitionGroups

These classes used to inherit from base classes consisting of old-style Revit API collections. The new versions of the classes offer the same functionality, but implement System.Collections.Generic.IEnumerable<T>.

Code which referred to the older base class or its associated iterator will need to be changed to access members through iteration or the now-available LINQ methods.

In addition, code which called ForwardIterator() or ReverseIterator() on these classes will need to be changed as the new version of the class does not offer these two legacy methods.

GeometryElement.Objects

The property

• GeometryElement.Objects

has been obsoleted. GeometryElement now inherits directly from IEnumerable<GeometryObject>, and it possible to directly iterate the contents of the GeometryElement using .NET and LINQ, if needed.

Replacements for wall creation methods

New wall creation APIs have been provided as a part of the Wall class:

• static Wall Create(Document document, Curve curve, ElementId levelId, bool structural) – Creates a new rectangular profile wall within the project using the default wall style.
• static Wall Create(Document document, Curve curve, ElementId wallTypeId, ElementId levelId, double height, double offset, bool flip, bool structural) – Creates a new rectangular profile wall within the project using the specified wall type, height, and offset.
• static Wall Create(Document document, IList<Curve> profile, bool structural) – Creates a non rectangular profile wall within the project using the default wall type:
• static Wall Create(Document document, IList<Curve > profile, ElementId wallTypeId, ElementId levelId, bool structural) – Creates a non rectangular profile wall within the project using the specified wall type.
• static Wall Create(Document document, IList<Curve> profile, ElementId wallTypeId, ElementId levelId, bool structural, XYZ normal) – Creates a non rectangular profile wall within the project using the specified wall type and normal vector.

These methods replace the obsolete methods on Autodesk.Revit.Creation.Document (NewWall() (all overloads)). The NewWalls() overloads are obsoleted without dedicated replacements, as described in the section ElementArray and ElementSet are now obsolete.

Idling event and External Events

Idling event frequency

The Idling event has been changed to offer two different modes of behavior. The default behavior has changed; pre-existing code that needs the original behavior will need to opt-in to the non-default behavior.

In the default mode, a single raise of the event will be made each time Revit begins an idle session. Note that when the user is active in the Revit user interface, idle sessions begin whenever the mouse stops moving for a moment or when a command completes. However, if the user is not active in the user interface at all, Revit may not invoke additional idling sessions for quite some time; this means that your application may not be able to take advantage of time when the user leaves the machine completely idle for a period of time.

In the non-default mode, your application forces Revit to keep the idling session open and to make repeated calls to your event subscriber. In this mode even if the user is totally inactive the Revit session will continue to make Idling calls to your application. However, this can result in performance degradation for the system on which Revit is running because the CPU remains fully engaged in serving Idling events during the Revit application's downtime.

You can indicate the preference for the non-default Idling frequency by calling

• IdlingEventArgs.SetRaiseWithoutDelay()

each time the Idling event callback is made. Revit will revert to the default Idling frequency if this method is not called every time in your callback.

Idling event with no active document

The Idling event now is invoked when there is no document active in Revit.

External Events framework

The External Events framework is a new API framework tailored for asynchronous processing such as that which is needed to support modeless dialogs. It operates similarly to the Idling event with default frequency.

With this framework, instead of implementing an event handler and implementing the handler to do nothing when there is no activity in your dialog, instead you do the following:

1. Implement an external event by deriving from the interface:
   • IExternalEvent
2. Create an ExternalEvent with
   • ExternalEvent.Create()
3. When an event happens in your modeless UI where a Revit action needs to be taken, call
   • ExternalEvent.Raise()
4. Revit will wait for an available Idling timecycle and call the implementation of your event:
   • IExternalEvent.Execute()

This framework is more useful for modeless dialog developers because you can skip the default no-op implementation when nothing has happened, and tell Revit when there is some work you need to do in Revit. It also saves on the time required for Revit to make repeated calls to the Idling event when there is no actual work to be done.

Calling OpenAndActivateDocument during events

The UIApplication.OpenAndActivateDocument can now be invoked during events under the following conditions:

1. When invoked from an External Event, not restrictions apply except for the original active document to be free of transactions and transaction groups.
2. When invoked from regular event handlers, the following restrictions apply:
   • There must be no active document open yet in Revit
   • The event must not be nested in other events or in execution external command

Document & worksharing changes

Worksharing properties

The information required to identify a workshared file on the central or local locations have changed due to changes to RevitServer. As a result, the members

• Application.GetRevitServerNetworkHosts()
• Application.CurrentRevitServerAccelerator
• Document.WorksharingCentralFilename

replace the properties

• Application.CentralServerName
• Application.LocalServerName
• Document.GetWorksharingCentralModelPath()

The new members:

• Application.GetWorksharingCentralGUID(ServerPath serverModelPath)
• Document.WorksharingCentralGUID

provides read access to the worksharing central GUID of the given server-based model. This is applicable only to workshared models saved in Revit 2013 or later.

New overloads for Application.OpenDocumentFile() and UIApplication.OpenAndActivateDocument()

The new overloads support parameters OpenOptions and OpenOptionsForUI, respectively, to specify how a Revit document should be opened. Both options classes currently offer the ability to detach the opened document from central if applicable.

The property:

• OpenOptions.DetachFromCentralOption

can be set to DoNotDetach (the default) or DetachAndPreserve.

The property:

• OpenOptionsForUI.DetachFromCentralOption

can be set to DoNotDetach (the default), DetachAndPreserveWorksets or DetachAndPrompt.

BasicFileInfo

The new class

• BasicFileInfo

offers basic information about a Revit file, including worksharing status, Revit version, username and central path. The information can be extracted without fully opening the file.

Point cloud engine API changes

Because these are new methods in a pre-existing interface, existing code will have to be modified to implement the methods.

Free()

Unlike other Point Cloud interfaces in the Revit 2012 release, this interface did not offer a method to be called when Revit is finished with it.

When Revit calls this function it indicates that the IPointCloudAccess interface is no longer going to be used and the provider of the interface can dispose of all allocated resources.

GetOffset()

Implement this method to return the offset stored in the point cloud. All points are assumed to be offset by the same offset vector. The offset should be expressed in the same units as used by the point coordinates (the scale conversion factor is not applied). The offset will be used by Revit if the user choose to place an instance relative to another point cloud (the "Auto – Origin To Last Placed" placement option).

CreatePointSetIterator()

A second overload with an additional argument – density – the desired number of points per unit area. Area is computed in native units of the point cloud.

IFC export APIs

The IFC export implementation in Revit has switched to a more generic toolkit. As a result, many of the APIs introduced in Revit 2012 to support customized IFC export have been removed and replaced, and new interfaces introduced that allow more flexibility in the data that is written to the IFC file. Autodesk recommends that any customization of IFC export begin with the implementation of the default Revit IFC exporter client, and that customizations written for 2012 be ported incrementally to support Revit 2013.

Construction Modeling changes

The following members are now obsolete:

• Part.GetDividedParents() – replaced with Part.GetSourceElementIds
• PartMaker.GetDividedElementIds() – replaced with PartMaker.GetSourceElementIds
• PartMaker.IsElementDivided() – replaced with PartMaker.IsSourceElement
• PartMaker.SetDividedElementIds() – replaced with PartMaker.SetSourceElementIds
• PartUtils.ArePartsValidForDivide -> replaced with PartUtils.AreElementsValidForDivide()

The following members are now obsolete – they are not being replaced with new members because the information they returned can be obtained by applying GetSourceElementIds recursively to source elements that are Parts.

• Part.OriginalDividedElementId
• Part.ParentDividedElementId
• PartUtils.GetDividedParent()

The following members are obsolete. Their replacements live on the PartMakerMethodToDivideVolumes class, which you can obtain for a given PartMaker using PartUtils.GetPartMakerMethodToDivideVolume():

• PartUtils.AreElementsValidIntersectingReferences()
• PartUtils.IsValidSketchPlane()
• PartUtils.SetOffsetForIntersectingReference()
• PartUtils.GetOffsetForIntersectingReference()
• PartUtils.PartMakerUsesReference()

The methods:

• AssemblyViewUtils.CreatePartList()
• AssemblyViewUtils.CreateMaterialTakeoff()

now return ViewSchedule instead of View.

Structure changes

Rebar.GetCenterlineCurves()

The overload taking one argument is now obsolete.

The new three-argument Rebar.GetCenterlineCurves(Boolean, Boolean, Boolean) has arguments to control whether or not to:

• Adjust for self-intersection
• Include hooks
• Include bend radius curves (fillets)

Rebar member changes

These members are now obsolete:

• Rebar.DistributionPath is replaced by Rebar.GetDistributionPath()
• Rebar.Host is replaced by Rebar.GetHostId() and SetHostId()
• Rebar.RebarShape is replaced by Rebar.RebarShapeId property
• Rebar.BarType is obsoleted. Use the inherited GetTypeId() and ChangeTypeId()

AreaReinforcement and PathReinforcement

BarDescription class

The new RebarInSystem element replaces the BarDescription class. This class and related methods:

• AreaReinforcement.NumBarDescriptions()
• AreaReinforcement.GetBarDescription()
• PathReinforcement.NumBarDescriptions()
• PathReinforcement.GetBarDescription()

are obsolete in 2013.

When ReinforcementSettings.HostStructuralRebar is true, Area and Path Reinforcement elements create individual rebar elements that participate in views and schedules. The individual RebarInSystem elements have the same graphical representation and parameters as Rebar elements, and have the same API methods for inquiry. But the RebarInSystem elements are almost entirely controlled by their system element (Area or Path). Therefore they are missing most of the modification methods of the Rebar class.

New methods:

• AreaReinforcement.GetRebarInSystemIds()
• AreaReinforcement.RemoveAreaReinforcementSystem()
• PathReinforcement.GetRebarInSystemIds()
• PathReinforcement.RemovePathReinforcementSystem()

MEP changes

ConnectorProfileType, PartType

ConnectorProfileType enums are renamed to:

• Invalid, Round, Rectangular, Oval

PartType::UndefinedPartType is renamed to PartType::Undefined.

ConnectorElement

Subclasses of ConnectorElement: PipeConnector, DuctConnector, and ElectricalConnector, are obsolete.

• IsPrimary – moved to ConnectorElement
• AssignAsPrimary – moved to ConnectorElement
• LinkedConnector – moved to ConnectorElement as GetLinkedConnectorElement and SetLinkedConnectorElement
• Please query the parameters RBS_PIPE_CONNECTOR_SYSTEM_CLASSIFICATION_PARAM, RBS_DUCT_CONNECTOR_SYSTEM_CLASSIFICATION_PARAM, or RBS_ELEC_CIRCUIT_TYPE on ConnectorElement to obtain the PipeSystemType, DuctSystemType, and ElectricalSystemType values on the now obsolete PipeConnector, DuctConnector, and ElectricalConnector elements.

Connector element types can now be created using new methods:

• ConnectorElement.CreatePipeConnector()
• ConnectorElement.CreateDuctConnector()
• ConnectorElement.CreateElectricalConnector()
• ConnectorElement.CreateConduitConnector()
• ConnectorElement.CreateCableTrayConnector()

These methods replace the methods on Autodesk.Revit.Creation.FamilyItemFactory (NewDuctConnector, NewPipeConnector, NewElectricalConnector). Those methods are now obsolete.

Obsolete API Cleanup

Many API classes and methods previously marked Obsolete in Revit 2012 and earlier have been removed from the API.

Classes removed

• MaterialConcrete, MaterialGeneric, MaterialOther, MaterialSteel, MaterialWood – all data is now accessed via the Material class
• Autodesk.Revit.DB.ConstructionType – replaced by Autodesk.DB.Analysis.ConstructionType
• SuspendUpdating – no longer needed because Automatic regeneration mode has been removed.Autodesk.Revit.UI.Macros.ApplicationEntryPoint
• Autodesk.Revit.VSTA.ApplicationEntryPoint – replaced by Autodesk.Revit.UI.Macros.ApplicationEntryPoint
• Autodesk.Revit.VSTA.DocumentEntryPoint – replaced by Autodesk.Revit.UI.Macros.DocumentEntryPoint
• Autodesk.Revit.VSTA.IEntryPoint – replaced by Autodesk.Revit.UI.Macros.IEntryPoint
• Autodesk.Revit.VSTA.AddInIdAttribute – replaced by Autodesk.Revit.UI.Macros.AddInIdAttribute
• Autodesk.Revit.VSTA.VendorIdAttribute – replaced by Autodesk.Revit.UI.Macros.VendorIdAttribute

Methods and properties removed

• AnalysisDisplayLegend.Width – replaced by legend settings of AnalysisDisplayStyle.
• AnalysisDisplayLegendSettings.SetTextTypeId(ElementId, Document)
• AnalysisDisplayMarkersAndTextSettings.SetTextTypeId(ElementId, Document)
• AnalyticalModel methods
  • IsValidAnalyticalProjectionType(AnalyticalDirection, AnalyticalProjectionType) replaced by IsValidProjectionType
  • GetAnalyticalProjectionDatumPlane(AnalyticalDirection ) replaced by GetAnalyticalProjectionDatumPlane(AnalyticalElementSelector, AnalyticalDirection)
  • IsValidDatumPlaneForProjection(AnalyticalDirection, ElementId ) replaced by IsValidProjectionDatumPlane
  • SetAnalyticalProjectionDatumPlane(AnalyticalDirection, ElementId ) replaced by setAnalyticalProjectionDatumPlane(AnalyticalElementSelector, AnalyticalDirection, ElementId)
  • SetAnalyticalOffset(XYZ) replaced by SetOffset
  • GetAnalyticalOffset() replaced by GetOffset
  • GetAnalyticalProjectionType(AnalyticalDirection) replaced by GetAnalyticalProjectionType(AnalyticalElementSelector, AnalyticalDirection)
  • SetAnalyticalProjectionType(AnalyticalDirection, AnalyticalProjectionType ) replaced by SetAnalyticalProjectionType(AnalyticalElementSelector, AnalyticalDirection, AnalyticalProjectionType)
• IFCExportOptions.CurrentViewOnly
• PointCloudFilter.GetFilterOutline() – replaced by PointCloudFilterUtils.GetFilteredOutline()
• RebarHostData.HasCoverTypeForReference(Reference ) – replaced by IsFaceExposed()
• SpatialFieldManager members
  • CurrentUnits replaced by AnalysisResultSchema.CurrentUnits and SpatialFieldManager.SetResultSchema()
  • UpdateSpatialFieldPrimitive(int, Autodesk.Revit.DB.Analysis.FieldDomainPoints, Autodesk.Revit.DB.Analysis.FieldValues)
  • SetUnits(System.Collections.Generic.IList<System.String>, System.Collections.Generic.IList<double>) replaced by AnalysisResultSchema.SetUnits() and SpatialFieldManager.SetResultSchema()
  • GetDescription() replaced by SpatialFieldManager.SetResultSchema() and AnalysisResultSchema.Description
  • SetDescription(System.String) replaced by AnalysisResultSchema.Description and SpatialFieldManager.SetResultSchema()
• AnnotationSymbol.AsFamilyInstance
• Area.Boundary – replaced by GetBoundarySegments(SpatialElementBoundaryOptions)
• Element members
  • ObjectType replaced by GetTypeId() and ChangeTypeId()
  • SimilarObjectTypes replaced by GetValidTypes()
• Materials members
  • AddOther(System.String) replaced by Material.Create
  • AddWood(System.String) replaced by Material.Create
  • AddConcrete(System.String) replaced by Material.Create
  • AddSteel(System.String) replaced by Material.Create
  • AddGeneric(System.String) replaced by Material.Create
• PropertySetElement.Create(Document, MaterialAspect) replaced by PropertySetElement.Create(Document, StructuralAsset) and PropertySetElement.Create(Document, ThermalAsset)
• Mullion.AsFamilyInstance
• Panel.AsFamilyInstance
• Rebar.IsShownInFrontOfGeometryInView[View] – replaced by IsUnobscuredInView() and SetUnobscuredInView()
• PointOnEdge members
  • PointOnEdge(Autodesk.Revit.DB.Reference, double) replaced by PointLocationOnCurve
  • CurveParameter replaced by LocationOnCurve
• Room.Boundary – replaced by GetBoundarySegments(SpatialElementBoundaryOptions)
• Face.MaterialElement – replaced by MaterialElementId
• Reference members
  • Element replaced by Document.GetElement(Reference)
  • GeometryObject replaced by Element.GetGeometryObjectFromReference(Reference)
  • Transform replaced by ReferenceByContext.GetInstanceTransform() after obtaining ReferenceWithContext from Document.FindReferencesWithContextByDirection()
  • ProximityParameter replaced by ReferenceByContext.ProximityParameter after obtaining ReferenceWithContext from Document.FindReferencesWithContextByDirection()
• PipingSystem members
  • FluidType, FluidType is now a property of the system type. Get the system type, and set the parameter RBS_PIPE_FLUID_TYPE_PARAM directly
  • FluidTemperature, FluidTemperature is now a property of the system type. Get the system type, and set the parameter RBS_PIPE_FLUID_TEMPERATURE_PARAM directly
  • FluidDensity, FluidDensity is now a property of the system type. Get the system type, and set the parameter RBS_PIPE_FLUID_DENSITY_PARAM directly
  • FluidViscosity, FluidViscosity is now a property of the system type. Get the system type, and set the parameter RBS_PIPE_FLUID_VISCOSITY_PARAM directly
• Space.Boundary – replaced by GetBoundarySegments(SpatialElementBoundaryOptions)
• Application.LibraryPaths – replaced by GetLibraryPaths() and SetLibraryPaths()
• ControlledApplication.LibraryPaths – replaced by GetLibraryPaths() and SetLibraryPaths()
• Application.NewPointOnEdge(Autodesk.Revit.DB.Reference, double edgeParam) – replaced by other constructor that uses PointLocationOnCurve
• Document members
  • Move() – all overloads – replaced by methods of ElementTransformUtils
  • Rotate() – all overloads – replaced by methods of ElementTransformUtils
  • Mirror() – all overloads – replaced by methods of ElementTransformUtils
  • Array() – all overloads – replaced by methods of LinearArray and RadialArray
  • ArrayWithoutAssociate() – all overloads – replaced by methods of LinearArray and RadialArray
  • SaveAs(System.String, bool) – replaced by SaveAs(String, SaveAsOptions)
  • FindReferencesByDirection() – replaced by FindReferencesWithContextByDirection() and ReferenceIntersector methods
  • ExternalFileReference & ImportFileData – all methods and enums related to material paths
  • AbbreviationItem – empty class removed completely
  • WorksharingCentralFilename – replaced by GetWorksharingCentralModelPath()
• ModelPathUtils.GetRevitServerPrefix() – RSN:// is the prefix string for Revit Server path.

Major Enhancements to the Revit API

Stairs and railings API

Stairs and stairs components

The new classes in the Autodesk.Revit.DB.Architecture namespace:

• Stairs
• StairsType

provide access to new stairs elements in the Revit database. Note that these API classes only provide access to the Stairs created "by component" introduced in this release. Stairs elements created by sketch cannot be accessed as a Stairs object in the API. It is possible to identify both type of stairs using the BuiltInCategory OST_Stairs and the static method Stairs.IsByComponent() can identify an element id represents a by component stairs.

The classes:

• StairsLanding
• StairsLandingType
• StairsRun
• StairsRunType

provide access to the subcomponents and subcomponent types of the new Stairs elements.

Railings and railing components

The new classes in the Autodesk.Revit.DB.Architecture namespace:

• Railing
• RailingType

provide access to the top level railing elements in the Revit database. Railings can be associated to a host, such as a stairs or a floor, or placed in space. Railings can be continuous or non-continuous. If non-continuous, only a limited level of access is provided.

Stairs annotations

The new class

• CutMarkType

provides access to the properties and capabilities of a CutMark annotation which can be associated to stairs.

The new classes

• StairsPath
• StairsPathType

provide access to the stairs path annotation.

View API

View Creation

Plan Views can now be created with the new ViewPlan.Create(document, viewFamilyTypeId, levelId) method.

For example, a ceiling plan can be created as follows:

  Element level = doc.GetElement(
    uidoc.Selection.PickObject(
      ObjectType.Element ) ) as Level;
 
  IEnumerable<ViewFamilyType> viewFamilyTypes
    = from elem in new FilteredElementCollector( doc )
      .OfClass( typeof( ViewFamilyType ) )
        let type = elem as ViewFamilyType
        where type.ViewFamily == ViewFamily.CeilingPlan
        select type;
 
  ViewPlan ceilingPlan = ViewPlan.Create(
    doc, viewFamilyTypes.First().Id, level.Id );
 
  ceilingPlan.Name = "New Ceiling Plan for "
    + level.Name;
 
  ceilingPlan.DetailLevel = ViewDetailLevel.Fine;
 
  // 3D views can be created with 
  // View3D.CreateIsometric and 
  // View3D.CreatePerspective. 
  // The new ViewOrientation3D object is used to 
  // get or set the orientation of 3D views.
 
  View3D view = View3D.CreateIsometric(
    doc, viewFamily3d );
 
  XYZ eyePosition = new XYZ( 10, 10, 10 );
  XYZ upDirection = new XYZ( -1, 0, 1 );
  XYZ forwardDirection = new XYZ( 1, 0, 1 );
  view.SetOrientation( new ViewOrientation3D(
    eyePosition, upDirection, forwardDirection ) );

• The ViewSection class now has methods that support the creation of Callout, Reference Callout, and Reference Section views.
• Rendering views containing images imported from disk can be created using the new ImageView class and the ImageView.Create method.

DisplayStyle

The enum DisplayStyle (with values including Wireframe, HLR, and Shading) has been added so the API can be used to get/set the new DisplayStyle property.

ViewDetailLevel

The enum ViewDetailLevel (with values Coarse, Medium, and Fine) has been added with get/set access to the new DetailLevel property.

ViewRange

The view range for plan views can now be retrieved via ViewPlan.GetViewRange().

3D View Locking

• 3D Views can now be locked and unlocked via the API with the methods SaveOrientationAndLock, RestoreOrientationAndLock, and Unlock.
• The property IsLocked indicates if a view is currently locked.
• NewTag can now be used in locked 3D Views.

View.Duplicate

Views can now be duplicated via the API with the View.Duplicate(ViewDuplicateOption) method.

UIView class and UIDocument.GetOpenUIViews()

The UIView class has been added to represent a view window in the Revit user interface. GetOpenUIViews provides a list of all open views. UIView.GetWindowRectangle() returns a rectangle that describes the size and placement of the UIView window.

Pan and Zoom

The method

• UIView.ZoomAndCenterRectangle()

offers the ability to zoom and pan the active view to center on the input region of the model.

The method

• UIView.GetZoomCorners()

returns the two points that define the corners of the view's rectangle in model coordinates.

PlanViewDirection

The enum PlanViewDirection has been added so API can be used to get/set the view direction to either Up or Down for StructuralPlan views.

ViewFamilyType class and ViewFamily enum

The ViewFamilyType class has been created to correspond to the Types seen in the UI's Properties dialog for each view. The ViewFamily enum (FloorPlan, Section, Legend, etc) specifies the family of the ViewFamilyType.

Temporary view modes

View.EnableRevealHiddenMode, View.EnableTemporaryAnalyticalDisplayMode, View.DisableTemporaryViewMode, and the TemporaryViewMode Enumeration have been added to allow control of temporary view modes.

Schedules

Schedule API

Several new classses have been added to allow schedule views to be created, modified, and added to drawing sheets. Major new classes include:

• The ViewSchedule class that represents the schedule view. Its create methods are used to create new schedules.
• The ScheduleField class for the inidivual fields in a schedule
• The ScheduleSheetInstance class represents schedules placed on sheets. The create method creates an instance of a schedule on a sheet.
• The ScheduleDefinition class defines the contents of a schedule view, including:
  1. Basic properties that determine the kind of schedule, such as the schedule's category.
  2. A set of fields that become the columns of the schedule.
  3. Filters that restrict the set of elements visible in the schedule.
  4. Sorting and grouping criteria.

Running API commands in Schedule Views

API commands may now be active when a Schedule is active in the current document.

Schedule export

The ViewSchedule class has been added to the API and the method ViewSchedule.Export method exports an existing schedule to a text file.

Discipline controls

The properties:

• Application.IsArchitectureEnabled
• Application.IsStructureEnabled
• Application.IsStructuralAnalysisEnabled
• Application.IsMassingEnabled
• Application.IsEnergyAnalysisEnabled
• Application.IsSystemsEnabled
• Application.IsMechanicalEnabled
• Application.IsMechanicalAnalysisEnabled
• Application.IsElectricalEnabled
• Application.IsElectricalAnalysisEnabled
• Application.IsPipingEnabled
• Application.IsPipingAnalysisEnabled

provide read and modify access to the available disciplines. Your application can read the properties to determine when to enable or disable aspects of the UI.

Enabling and disabling disciplines is available only in Autodesk Revit (and not in any other Revit product). When a discipline's status is toggled, Revit's UI will be adjusted, and certain operations and features will be enabled or disabled as appropriate.

Rendering Options

The settings shown in the Rendering Options Dialog are exposed, allowing an API user can get and set Rendering Options for a 3d view.

The new methods:

• View3D.GetRenderingSettings
• View3D.SetRenderingSettings

gets or changes the rendering settings for the 3d view.

The class

• RenderingSettings

offers properties and methods which correspond to the options in the UI dialog:

• RenderingSettings.UsesRegionRendering – Boolean value that indicates whether to use region rendering.
• RenderingSettings.BackgroundStyle – The enum value that controls the background style for rendering.
• RenderingSettings.ResolutionTarget – The resolution target.
• RenderingSettings.PrinterResolution – The resolution level when using printer.
• RenderingSettings.LightingSource – The lighting scheme type.
• RenderingSettings.ResolutionValue – The rendering resolution in dots per inch (DPI).
• RenderingSettings.GetBackgroundSettings() – Returns an object that represents the rendering background settings.
• RenderingSettings.SetBackgroundSettings() – Changes the rendering background settings details for the current background style.
• RenderingSettings.GetRenderingImageExposureSettings() – Returns an object that represents the rendering image exposure settings.
• RenderingSettings.SetRenderingImageExposureSettings() – Changes the rendering image exposure settings.
• RenderingSettings.GetRenderingQualitySettings() – Returns an object that represents the rendering quality settings.
• RenderingSettings.SetRenderingQualitySettings() – Changes rendering quality settings.
• RenderingSettings.GetRenderingRegionOutline() – Returns the outline of the rendering region.

The rendering properties are exposed with the following supplementary classes and enums:

• enum BackgroundImageFit – Represents the type of background image fit.
• enum ResolutionTarget – Represents the resolution target (Screen or Printer) used for rendering.
• enum PrinterResolution – Controls the resolution level for a printer target.
• enum LightingSource – Represents the lighting scheme type.
• enum RenderingQuality – Represents the rendering quality.
• enum BackgroundStyle- Represents the background style.
• class SkyBackgroundSettings – Represents the rendering sky background settings.
• class ColorBackgroundSettings – Represents the rendering color background settings.
• class ImageBackgroundSettings – Represents the rendering image background settings.
• class RenderingImageExposureSettings – Represents the exposure settings of rendering.

Example: checking rendering options for a 3D view:

  RenderingSettings renderingSettings
    = view3D.GetRenderingSettings();
 
  Transaction newTran = new Transaction(
    doc, "Change Rendering Settings" );
 
  newTran.Start();
 
  renderingSettings.BackgroundStyle
    = BackgroundStyle.Image;
 
  view3D.SetRenderingSettings( renderingSettings );
 
  newTran.Commit();

Construction Modeling

Linked element parents for parts

Parts can be created from linked elements. There are new overloads:

• PartUtils.CreateParts()
• PartUtils.IsValidForCreateParts()
• PartUtils.HasAssociatedParts()
• PartUtils.GetAssociatedParts()
• PartUtils.GetAssociatedPartMaker()

which accept LinkElementIds (representing the id of the element in the link). The existing Part utilities accepting ElementId have not been changed.

Merged parts

The methods:

• PartUtils.ArePartsValidForMerge()
• PartUtils.CreateMergedPart()
• PartUtils.FindMergeableClusters()
• PartUtils.GetChainLengthToOriginal()
• PartUtils.GetMergedParts()
• PartUtils.IsMergedPart()

provide support for merging of parts.

Excluded parts

The new property

• Part.Excluded

allows identification and assignment of parts to be excluded.

Part category

The new members:

• Part.OriginalCategoryId
• Part.GetSourceElementOriginalCategoryIds()

provide the ability to get and set the original category id for a given part.

Part division

Part divisions can now be assigned custom geometry divisions. The members:

• PartMakerMethodToDivideVolumes.ProfileMatch
• PartMakerMethodToDivideVolumes.DivisionGap
• PartMakerMethodToDivideVolumes.ProfileOffset
• PartMakerMethodToDivideVolumes.SplitterProfileType
• PartMakerMethodToDivideVolumes.ProfileFlipAcross
• PartMakerMethodToDivideVolumes.ProfileFlipAlong
• PartMakerMethodToDivideVolumes.GetSketchCurves()
• PartMakerMethodToDivideVolumes.GetPlaneOfSketch()
• PartMakerMethodToDivideVolumes.GetSplitRefsOffsets()
• PartMakerMethodToDivideVolumes.CanBeDivisionProfile()

offer the ability to examine and control properties of the divisions.

Assembly views

The method

• AssemblyViewUtils.AcquireAssemblyViews()

transfers the assembly views owned by a source assembly instance to a target sibling assembly instance of the same assembly type.

Assembly instance transform and location

The methods

• AssemblyInstance.GetTransform()
• AssemblyInstance.SetTransform()

provide read and write access to the transformation origin of the assembly. Changing this value causes the origin point to change relative to the assembly members (and does not move the assembly members). All assemblies of the same type should have changed their transforms by the same amount. For example, if you changed the transform of the assembly by a rotation of 90 degrees, then other assemblies should also have rotated their transform by 90 degrees.

The inherited property

• AssemblyInstance.Location

also has been modified to return a the location for an AssemblyInstance.

Structure improvements

New Rebar members

• RebarShapeMatchesCurvesAndHooks() checks if rebarShape matches curves and hooks.
• CreateFromCurvesAndShape() creates a new instance of a Rebar element with default shape parameters from the RebarShape
• GetBarPositionTransform()
• GetBarExistsAtPosition()
• GetHookTypeId() and SetHookTypeId()
• ScheduleMark property
• TotalLength property
• Volume property

ReinforcementSettings

The new class ReinforcementSettings controls project settings that are accessible from the Reinforcement Settings dialog in the Revit UI. For 2013 the only supported setting is the HostStructuralRebar property, which is new for 2013 and affects the AreaReinforcement and PathReinforcement elements.

AreaReinforcement/PathReinforcement

AreaReinforcement and PathReinforcement now have types.

The types – AreaReinforcementType and PathReinforcementType – contain only identity data.

There is no change to the interface for creating Area and Path Reinforcement elements. A default, or most-recently-used type, is automatically assigned on element creation.

New Area- and PathReinforcementTypes can be created using the following methods:

• (static) AreaReinforcementType AreaReinforcementType.Create(Document ADoc, AString Name)
• (static) PathReinforcementType PathReinforcementType.Create(Document ADoc, AString Name)

Analytical model

The new element type

• AnalyticalLink

can be created between two other Analytical Elements, e.g. an analytical beam and analytical column. There are two kinds of Links: user defined and automatically generated. Links have properties like "fixity state" that can be accessed via the API.

MEP improvements

Routing Preferences

Revit MEP now supports a system for selecting preferred pipe and duct sizes, materials, and fitting types for use in an MEP project. The routing preferences API can be used to set routing preference policies for end users as well as to query which fittings and segments will be used given size criteria.

• property MEPCurveType.RoutingPreferenceManager – accesses the main routing preferences object for a give MEPCurve Type. Currently, PipeType and DuctType are the only MEPCurve types that support Routing Preferences.
• class RoutingPreferenceManager – manages all routing preference rules for segments and fittings and allows the user to query which fitting or segment will be chosen by Revit, given a size condition.
• classes RoutingCriterionBase and PrimarySizeCriterion – These classes manage criteria for selecting fittings and segments based on minimum and maximum size constraints.
• class RoutingPreferenceRule – Manages one segment or fitting preference
• classes RoutingCondition and RoutingConditions – Inputs to RoutingPreferenceManager.GetMEPPartId() to select fittings and segments based on their selection criteria.
• class Segment – A class representing a length of MEPCurve that contains a material and set available sizes.
• class PipeSegment – a subclass of Segment representing a length of pipe
  • PipeSegment.Create(ElementId materialId, ElementId scheduleId) – Creates a new PipeSegment of given material, schedule, and size list.
• enum RoutingPreferenceRuleGroupType – Each routing preference rule is grouped according to what type of routing item it manages
  • Elbows
  • Junctions
  • Crosses
  • Transitions
  • Unions
  • MechanicalJoints
  • Segments
  • TransitionsRectangularToRound
  • TransitionsRectangularToOval
  • TransitionsOvalToRound

MEP Sections

The new class

• MEPSection

is the base class for duct and pipe section. It is a series of connected elements (segments – ducts or pipes, fittings, terminals and accessories). All section members should have same flow analysis properties: Flow, Size, Velocity, Friction and Roughness. One section member element which contains more than one connector can belongs to multiple section.

For example: One Tee fitting that has 3 connectors usually belongs to 3 sections. One segment that connects to a tap will be divided into 2 sections

FluidType and FluidTemperature

The new class

• FluidTemperature

represents the viscosity and density properties as defined at a certain temperature.

The class

• FluidType

has been extended to provide read and write access to a collection of FluidTemperature objects which represent the fluid's properties at various temperatures.

Panel schedule – spare values

The new functions

• PanelScheduleView.GetSpareLoadValue()
• PanelScheduleView.SetSpareLoadValue()
• PanelScheduleView.GetSpareCurrentValue()
• PanelScheduleViwe.SetSpareCurrentValue()

provide access to the parameter values of spare circuits.

LabelUtils

New overloads of

• LabelUtils.GetLabelFor()

have been added to supply the user-visible string matching members of the enums DuctLossMethodType, PipeLossMethodType, and PipeFlowState.

Physical Properties

Thermal properties

Thermal properties of various elements have been enhanced in Revit 2013.

• Class ThermalProperties
  • Absorptance
  • HeatTransferCoefficient
  • Roughness
  • ThermalMass
  • ThermalResistance

This class is a property on the following types:

• ThermalProperties WallType.ThermalProperties
• ThermalProperties FloorType.ThermalProperties
• ThermalProperties CeilingType.ThermalProperties
• ThermalProperties RoofType.ThermalProperties
• ThermalProperties BuildingPadType.ThermalProperties
• Class FamilyThermalProperties
  • AnalyticConstructionTypeId – This value corresponds to the 'id' property of a constructionType node in Constructions.xml, a supplied data library of thermal properties of common construction types.
  • HeatTransferCoefficient
  • SolarHeatGainCoefficient
  • ThermalResistance
  • VisualLightTransmittance
  • Find() – returns a FamilyThermalProperties object from an "id" string in Constructions.xml
• FamilySymbol.GetThermalProperties() – Gets the thermal properties of a family symbol of a door, window, or curtain panel.
• FamilySymbol.SetThermalProperties()-- Sets the thermal properties of a family symbol of a door, window, or curtain panel.

This class is a property on Door, Window, and Curtain Panel family symbols

• FamilyThermalProperties FamilySymbol.ThermalProperties

Structural properties

Beam, Column, and Foundation family instances now support an ElementId of an additional structural Material element

• ElementId FamilyInstance.StructuralMaterialId (Foundation, Beam, and Column instances)

All compound structurals can now elect one layer in the structural to be used as the "structural" layer.

• int CompoundStructure.StructuralMaterialIndex
• PropertySetElement now supports a StructuralAsset property via the GetStructuralAsset and SetStructuralAsset methods.

StructuralAsset contains named properties for various structural values, such as PoissonModulus and YoungModulus, that offer enhanced ease of use over the previous parameter-API based access to these same values.

Material assets

• StructuralAsset – contains structural properties that can be set on materials via PropertySetElement and SetMaterialAspectByPropertySet()
• ThermalAsset – contains thermal properties that can be set on materials via PropertySetElement and SetMaterialAspectByPropertySet()
• PropertySetElement.Create() – now takes a StructuralAsset or ThermalAsset as a parameter instead of a MaterialAspect.

GBXML Export

Thermal properties of building construction element types can now be set to use calculated values or pre-defined values from Constructions.xml with:

• MEPBuildingConstruction.GetBuildingConstructionOverride
• MEPBuildingConstruction.SetBuildingConstructionOverride

EnergyDataSettings.IncludeThermalProperties indicates if thermal information from model assemblies and components is included in GreenBuildingXML export of the detailed model.

User interface API improvements

Contextual help support

Items placed on the Ribbon can now be assigned an action for contextual help using

• RibbonItem.SetContextualHelp()

The options supported include linking to an external URL, launching a locally installed help file, or linking to a topic on the Autodesk help wiki.

You can also invoke the same set of contextual help options at any arbitrary time within your add-in by creating a ContextualHelp object with the appropriate target location, and invoking

• ContextualHelp.Launch()

Support for Keyboard Shortcuts and Quick Access Toolbar

API commands may now be assigned keyboard shortcuts, and those assignments will be preserved even if add-ins are added, removed or changed in subsequent sessions.

API commands may also be moved to the Quick Access Toolbar, and that assignment will also be preserved even if add-ins are added, removed or changed in subsequent sessions.

Replace implementation of commands

It provides ability to replace the existing Revit command (located in any tab, application menu and right-click menus) implementation with add-in routine.

• RevitCommandId

The new class RevitCommandId provides ability to look up and retrieve an object representing Revit Command id given an id string. The id string of the command is the string which appears in the journal when the command is clicked, e.g. "ID_APP_EXIT".

• AddInCommandBinding

The new class AddInCommandBinding provides ability to override the Revit command implementation with Executed and CanExecute events.

• UIApplication.CreateAddInCommandBinding()
• UIControlledApplication.CreateAddInCommandBinding()

These two new methods provide the ability to create a command binding with a given Revit command id.

Preview control

The new class

• PreviewControl

provides the ability to embed an interactive Revit view as a WPF control inside a dialog.

Options dialog customization

Subscribe to the new event

• UIApplication.DisplayingOptionsDialog

to be notified when Revit is preparing the Options dialog for display. During the event callback, your application can call

• DisplayingOptionsDialogEventArgs.AddTab()

to add a new tab to the dialog. The contents of the panel shown when this new tab is selected are determined by the members assigned to the input class:

• TabbedDialogExtension

Drag & Drop support

The new methods

• UIApplication.DoDragDrop(ICollection<String>)
• UIApplication.DoDragDrop(Object, IDropHandler)

initiate a drag and drop operation on the Revit user interface.

The first method accepts a list of file names, which can be Revit files, import CAD and images, or some combination of the two. The second method accepts arbitrary data, and provides an IDropHandler callback to handle the drop of the data when the user completes it.

Translation API enhancements

Several updates have been made to the APIs related to data exchange and translation of models.

DGN import

The new method

• Document.Import(string, DGNImportOptions, View)

supports import of DGN files into Revit views.

DXF import

The method

• Document.Import(string, DWGImportOptions)

now also supports DXF files for import.

DWG and DXF export settings changes

The options supported for DWG and DXF export have been expanded. A new base class

• BaseExportOptions

supports all properties shared by DWG/DXF & DGN export tasks. New properties include:

• BaseExportOptions.HideScopeBox
• BaseExportOptions.HideReferencePlane
• BaseExportOptions.HideUnreferenceViewTag

DGN export

The options supported for DGN export have changed to match the new implementation of DGN export based on DWG supporting DGN V8. The previously existing class

• DGNExportOptions

thus offers many new properties inherited from the same base classes as DWGExportOptions.

The property

• DGNExportOptions.TemplateFile

has been replaced with:

• DGNExportOptions.SeedName

FBX Export

Three new options have been added:

• FBXExportOptions.UseLevelsOfDetail – true to use levels of detail, false otherwise
• FBXExportOptions.LevelsOfDetailValue – the value of the levels of detail
• FBXExportOptions.WithoutBoundaryEdges – true to export without boundary edges, false otherwise

DividedPath

A DividedPath is an element supported in the massing environment that consists of a set of points distributed along a connected set of curves and edges. The points can be the result of a uniform distribution along the curves. The type of the distribution is determined by a selected 'layout'. The distance between the layout points depends on the curves, the layout, and layout specific settings. In addition, points can also be the result of intersecting the curves with other elements.

The class

• DividedPath

exposes the interface for this element type. It permits creation of a new DividedPath from input curves and edges, as well as optionally, intersecting elements. It allows control over the layout type and parameters, as well as other miscellaneous settings.

Analysis Visualization Framework

The following additions have been made to support deformed shapes in analysis visualization display:

• AnalysisDisplayStyleDeformedShapeTextLabelType class
• AnalysisDisplayDeformedShapeSettings class

A new override to CreateAnalysisDisplayStyle accepts an input argument of AnalysisDisplayDeformedShapeSettings

Revit Link creation

The API now contains two creation methods for Revit links.

• RevitLinkType.Create(Document, ModelPath, RevitLinkOptions) will create a new Revit link type and load the associated linked file into the document. This returns a RevitLinkLoadResult, which stores the ElementId of the newly-created RevitLinkType and contains any errors which occurred when trying to load the linked file (The RevitLinkLoadResultType enumeration contains the full list.)
• RevitLinkInstance.Create(Document, ElementId) will create a new instance of an already-loaded RevitLinkType.

FilledRegion

The class

• FilledRegion

has been extended to offer the ability to create Filled regions, to get the boundaries of the region, and to apply a linestyle to all boundary segments.

The class

• FilledRegionType

has been added providing access to the visible properties of a filled region type.

Light API

The classes

• LightType
• LightFamily

have been added to offer the ability to get and set photometric data and all other lighting parameters from both family instances in project documents and all family types in family documents. The LightType and LightFamily classes expose the same data except for light shape and distribution types which are only available from the LightFamily class.

Some examples of lighting parameters exposed are;

• Initial color
• Initial intensity
• Loss factor
• Color filter
• Dimming color

Light Group API

The classes

• LightGroupManager
• LightGroup

have been added to offer the ability to manage light groups to allow control over which lights are used when rendering the scene.

The LightGroupManager class gives the user the ability to

• Create a new light group
• Delete an existing light group
• Turn on or off all the lights in a light group
• Turn on or off individual lights
• Set the dimmer value for individual lights

The LightGroup class gives the user the ability to

• Get the name of a light group
• Rename light group
• Add a light to a light group
• Remove a light from a light group

Light groups are used in rendering options to turn lights on or off when rendering.

ReferenceIntersector

The new class ReferenceIntersector allows ray-cast selection of elements, given a point and direction, similar to FindReferencesWithContextByDirection(), but with support for filtering the output based on element or reference type.

The enum FindReferenceTarget is used with ReferenceIntersector to filter selection of elements, meshes, edges, curves, and faces.

Key members of ReferenceIntersector

• ReferenceIntersector(ElementId targetElementId, FindReferenceTarget targetType, View3d view3d) – constructor specifying a single element to search for in the intersection test.
• ReferenceIntersector(ElementIdSet targetElementIds, FindReferenceTarget targetType, View3d view3d) – constructor specifying a set of ElementIds to search for in the intersection test.
• ReferenceIntersector(ElementFilter filter, FindReferenceTarget targetType, View3d view3d) – constructor specifying an ElementFilter for the intersection test.
• Find(XYZ origin, XYZ direction) – Finds all references intersecting the origin-direction ray given the selection criteria set up in the ReferenceIntersector constructor
• FindNearest (XYZ origin, XYZ direction) – Finds the reference closest to the origin in the origin-direction ray given the selection criteria set up in the ReferenceIntersector constructor

Small Enhancements & API Interface Changes

Elements & filtering

Element.PhaseCreated and Element.PhaseDemolished

These readonly properties have been obsoleted and replaced with read/write properties:

• Element.CreatedPhaseId
• Element.DemolishedPhaseId

The new method Element.AllowsPhases() indicates whether these phase id properties can be modified for any given element.

Phase filter

The new class

• PhaseFilter

and related types support read/write and create access to phase filters.

SelectionFilterElement

The new class

• SelectionFilterElement

provides access to a filter type which contains a selected set of element ids, rather than criteria based on parameters.

Ceiling, Floor and CeilingAndFloor

The newly exposed Ceiling class represents a ceiling in Revit. It inherits from CeilingAndFloor. The Floor class has been modified to also inherit from CeilingAndFloor.

Geometry & sketching

Split volumes

The new method:

• SolidUtils.SplitVolumes()

takes a solid which includes multiple disjoint enclosed volumes, and returns newly allocated Solids representing each volume. If no splitting was necessary, a copy of the input Solid is returned.

Solid tessellation

The new method:

• SolidUtils.TessellateSolidOrShell()

generates a single triangulated structure for the given input Solid (which could one or more fully closed volumes, or a shell of faces which do not form a closed volume). The function returns:

• TriangulatedSolidOrShell

which allows access to the stored triangulated components and triangles.

Use the method:

• FacetingUtils.ConvertTrianglesToQuads()

with a TriangulationInterface object constructed from the TessellateSolidOrShell results to convert pairs of adjacent, coplanar triangles into quadrilaterals.

Face.Triangulate()

A new overload to Face.Triangulate() accepts a level of detail as an argument. Levels of detail close to 0 (the minimum) will result in coarser triangulations than levels of detail close to 1 (the maximum).

Ellipse – axes

The new properties:

• Ellipse.XDirection
• Ellipse.YDirection

provide the unit vectors of the ellipse for the X and Y directions.

GeometryElement.GetBoundingBox()

This new method provides read access to the bounding box of a given geometry element.

ItemFactoryBase.NewAlignment()

This method can now align a line and a reference plane as well as all other geometry types from previous versions.

CylindricalHelix curve type

A new subclass of Curve has been introduced: CylindricalHelix. The class offers methods useful for reading and creating such curves.

In this release, CylindricalHelix curves are used only in specific applications in stairs and railings, and should not be used or encountered when accessing curves of other Revit elements and geometry.

CurveLoop as IEnumerable<Curve>

The members of a CurveLoop can now be traversed, as CurveLoop implements IEnumerable<Curve>.

CurveElement – center point reference

The new property:

• CurveElement.CenterPointReference

returns a reference to the center of a curve if that curve is one that has a center (e.g. arcs, circles, elliptical arcs or ellipses). This reference can be used for dimensioning to the center point.

ModelCurve.ChangeToReferenceLine

ModelCurve.ChangeToReferenceLine is now supported in all family types, not just conceptual modeling.

NewSketchPlane(Document, Reference)

This new overload for NewSketchPlane in the ItemFactoryBase class supports creation of a sketch plane directly from a Reference representing a planar face.

Detailing & Annotations

MultiSegmentGrid class

This class has been added to the API to support multi-segment grids.

Grid geometry

Element.Geometry now supports Grids and MultiSegmentGrids, including the ability to see gaps and extents applied to the grid lines to form different segments.

Diameter dimensions

Revit now supports Diameter dimensions. The DimensionShape enumeration contains a new Diameter member. And there is a new creation method for diameter dimensions:

• FamilyItemFactory.NewDiameterDimension()

DimensionSegment overrides

There are several new properties on DimensionSegment to override text properties.

• DimensionSegment.Prefix
• DimensionSegment.Suffix
• DimensionSegment.Above
• DimensionSegment.Below
• DimensionSegment.ValueOverride

These properties are also available on Dimension, for use with dimensions with just one segment.

Detail element draw order

The class

• DetailElementOrderUtils

has been added providing the ability to affect the draw order of detail elements (including FilledRegions)

Families & content

SpatialElementCalculationPoint

This class provides access to the "Room or Space Calculation Point" seen in families. The Spatial Element Calculation Point is graphically showed as a location point marker with a "snake" line from the origin of the family. If the Spatial Element Calculation Point is turned on, this point will be used as a search point for room and space relations for all instances of this family. The API offer creation, read and modification options for this object type.

RPC content assets

The AssetType enum now contains a value "Content", which can be used to enumerate the loaded RPC content assets in the Revit session.

NewFamilyInstance validation

Some validation has been added to overloads of NewFamilyInstance(). This validation is intended to prevent use of the incorrect overload for a given family symbol input. For specific details on the exceptional conditions which will be validated, consult the documentation.

Family.PlacementType

This new property provides information about the placement type for instances of the given family. PlacementType roughly maps to the overloads of NewFamilyInstance.

DataStorage element

The new DataStorage class represents an element that API applications can create logically organize different sets of ExtensibleStorage entities into separate elements. This allows an application to update one set of data in a local workshared project without locking other elements.

ApplicationInitialized event

The ControlledApplication object now supports an ApplicationInitialized event, which is called once the Revit application is fully initialized, after all external applications have been started and when the application is ready to work with documents.

ProgressChanged application event and ProgressChangedEventArgs

The application object now supports a ProgressChanged event and ProgressChangedEventsArgs object that returns progress bar data from time-consuming transactions.

• ProgressChangedEventArgs
  • Caption – The name of the current transaction or subtransaction in progress
  • Stage – The type of progress event (Started, RangeChanged, PositionChanged, CaptionChanged, UserCancelled, Finished)
  • Position – The numerical index between zero and UpperRange showing the number of completed steps of the current transaction or subtransaction
  • UpperRange – The total number of steps in the current transaction or subtransaction
  • Cancel – Cancels the current transaction in progress, if possible.
  • Cancellable – indicates if the current transaction can be cancelled.

SiteLocation – PlaceName

The new property:

• SiteLocation.PlaceName

provides the place name of the site location.

Application.DefaultProjectTemplate

Provides the full path to the default template file for new project documents

UnitType, DisplayUnit and FamilyParameter updates

Many new units have been added to UnitType, DisplayUnitType and ParameterType.

One UnitType was renamed: UT_TemperalExp was renamed to UT_ThermalExpansion.

The corresponding ParameterType value (TemperalExp) was also renamed to ThermalExpansion.

BasePoint and BASEPOINT_ANGLETON_PARAM "True North" Parameter

The parameter to return the "True North" angle parameter "BASEPOINT_ANGLETON_PARAM" on the BasePoint object is now a double instead of a string.

Journaling of Add-in user interface

Revit now activates a tool to collect and journal certain actions which take place in the user interface provided by an add-in. The tool supports actions in both WPF and Windows Forms dialogs.

Some actions and some components may not be fully recorded.

This capability is useful to Autodesk in the event that a journal can be supplied from a Revit user indicating the presence of a software problem. Replay of add-in UI via journals is not supported.

---

End of document

---

That completes the list of news in the Revit 2013 API from last year, A.D. 2012, bringing us up to date with the current release.

As said, I look up information in these sections regularly, and still discover topics that I was previously not aware of, frequently leading me to research new Revit API classes and methods.

Since this documentation was not previously available to online Internet searches, it required the extra effort of opening the individual help files and searching it release by release on the off chance of finding something hitherto unknown and useful for the task at hand.

I hope making this information available online proves as helpful to you as it will to me!

What's New in the Revit 2012 API

This is the third instalment of a series publishing the information provided in the 'What's New' sections of the past few Revit API releases help file RevitAPI.chm.

The first instalment covering What's New in the Revit 2010 API explains my motivation for this and provides an overview of the other releases.

We now move on to the Revit 2012 API, looking at:

• Major renovations
• Major enhancements
• Small enhancements and changes

First, however, another update on my vacation.

Unexpected Places, and Warmer

I am still on holiday in Italy, so please do not expect any immediate responses to comments for a while.

I love adventures, and finding myself in unexpected places, and I am getting my fill of that here and now.

I found better weather further south, and a beautiful empty beach north of Bari.

Acting on a recommendation by a cyclist whom I asked about his unintelligible dialect in a bar, I also ended up enjoying the unique trulli of Alberobello.

From there we continued to Lecce and started exploring the sweet and efficient little local train system connecting many of the communities on the peninsula of Salento.

We visited Galatina, continued to Nardo, and walked a long way on foot towards Santa Caterina to reach the protected natural park and beach of Porto Selvaggio.

In spite of some rain and cold, with some warm sunshine in between, we spent a day or two in pure uninterrupted nature.

On the way out towards Nardo again, a passing car picked us up and took us to Galipoli, another surprise visit, with a direct train connection back to Lecce.

Now, to continue the promised series of 'What's New' documentation from the past few Revit API releases.

Major renovations to the Revit 2012 API

.NET 4.0 now used by the Revit API

The Revit API has been enhanced to run with the .NET 4.0 runtime. As a result, Visual Studio 2010 with a framework target of .NET 3.5 or 4.0 must be used to debug your addins. Addins compiled with Visual Studio 2008 will run normally outside the debugging environment.

All samples in the Revit API SDK have been upgraded to Visual Studio 2010.

Microsoft has not yet announced when Visual Studio Tools for Applications (VSTA) for .NET 4.0 will be available. VSTA is the technology used for Revit macros. The Microsoft VSTA debugger is not compatible with the default Revit 2012 .NET 4.0 environment. VSTA macros can run successfully in the .NET 4.0 environment, but a special Revit configuration is required for debugging. In order to use VSTA debugging, you must:

1. Ensure you have user permissions sufficient to modify files in the Revit installation folder.
2. Exit Revit.
3. Run '[Revit.exe directory]\RevitVSTAConfig.exe'
4. Click the 'Prepare Revit for VSTA' button.
5. Restart Revit.

Note: Revit's native components continue to be compiled with the VS 2008 C++ compiler. Therefore Revit 2012 does not include the VS2010 redistributable. Third-party applications which include natively compiled C++ components should use the VS 2008 C++ compiler or must include the VS 2010 C++ redistributables with the installation.

RegenerationMode

Automatic regeneration mode has been removed. You no longer have to include the RegenerationMode attribute on your add-ins. All APIs expect that add-in code is written using manual regeneration when necessary.

Add-In registration – new required property VendorId

Two new registration properties have been added:

• VendorId – a mandatory string conforming to the Autodesk vendor ID standard. Register your vendor id string with Autodesk at http://www.autodesk.com/symbreg. An error will be shown if the add-in manifest file does not contain this required node for add-in entry.
• VendorDescription – optional string containing vendor's legal name and/or other pertaining information.

Here is an example of the new entries:

<?xml version="1.0" encoding="utf-16" standalone="no"?
<RevitAddIns>
  <AddIn Type="Command">
    <Assembly>Command.dll</Assembly>
    <ClientId>d7e30025-97d4-4012-a581-5f8ed8d18808</ClientId>
    <FullClassName>Revit.Command</FullClassName>
    <Text>Command</Text>
    <VendorId>ADSK</VendorId>
    <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
  </AddIn>
</RevitAddIns>

CompoundStructure and WallSweeps

The CompoundStructure class has been replaced. The old CompoundStructure class in the API was read-only and supported only the nominal layers list without 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 include vertical regions, sweeps and reveals.

The CompoundStructure.Layers property has been replaced by CompoundStructure.GetLayers() and CompoundStructure.SetLayers().

The CompoundStructureLayer class has also been replaced for the same reasons as CompoundStructure.

The following table maps properties from the old CompoundStructureLayer to the new version of the class:

• DeckProfile – DeckProfileId: Is now an ElementId.
• DeckUsage – DeckEmbeddingType: Uses a different enum.
• Function – Function: Uses a different enum.
• Material – MaterialId: Is now an ElementId.
• Thickness – Width.
• Variable – N/A: Not a part of the layer class, use CompoundStructure.VariableLayerIndex instead.

The property HostObjAttributes.CompoundStructure has been replaced by two methods:

• HostObjAttributes.GetCompoundStructure()
• HostObjAttributes.SetCompoundStructure()

Remember that you must set the CompoundStructure back to the HostObjAttributes instance in order for any change to be stored in the element.

In addition to the information on wall sweeps found in the CompoundStructure class, there is a new API representing a wall sweep or reveal. The WallSweep class is an element that represents either a standalone wall sweep/reveal, or one added by the settings in a given wall's compound structure. Standalone wall sweeps and reveals may be constructed using the static method Create().

LinePattern

The LinePattern class has been replaced. The old LinePattern class in the API represented both the line pattern itself and the element that contains it, and offered no details on the contents of the pattern beyond its name. The new classes available are:

• LinePatternElement – an element that contains a line pattern
• LinePattern – the line pattern. This 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.

The method

• LinePatternElement.Create()

offers the ability to add new LinePattern elements to the Revit database.

The property of the Settings class:

• Settings.LinePatterns

has been removed. LinePatterns may be found by the following approaches:

1. Use of a FilteredElementCollector filtering on class LinePatternElement
2. Use of the static methods of LinePatternElement:
   • LinePatternElement.GetLinePattern(Document, ElementId)
   • LinePatternElement.GetLinePatternByName(Document, string)

FillPattern

The FillPattern class has been replaced. The old FillPattern class in the API represented both the fill pattern itself and the element that contains it, and offered no details on the contents of the pattern beyond its name. The new classes available are:

• FillPatternElement – an element that contains a fill pattern
• FillPattern – the fill pattern. This class provides access to the pattern name and the set of grids that make up the pattern.
• FillGrid – a single fill pattern grid, described in the two dimensions of a face.

The method

• FillPatternElement.Create()

offers the ability to add new FillPattern elements to the Revit database.

The property of the Settings class:

• Settings.FillPatterns

has been removed. FillPatterns may be found by the following approaches:

1. Use of a FilteredElementCollector filtering on class FillPatternElement
2. Use of the static methods of FillPatternElement:
   • FillPatternElement.GetFillPattern(Document, ElementId)
   • FillPatternElement.GetFillPatternByName (Document, string)

IndependentTag

A good portion of the IndependentTag class and related classes have been renovated.

• Leader has been renamed HasLeader.
• LeaderMode has been renamed LeaderEndCondition, and the members of the LeaderEndCondition enum have been renamed.
• A new method CanLeaderEndConditionBeAssigned() determines if the LeaderEndCondition can be set.
• TagMode has been replaced by multiple properties: IsMaterialTag, IsMulticategoryTag.
• Members of the TagOrientation enum have been renamed.

Some new members were added to determine the elements referenced by the tag:

• New property TaggedElementId – provides the id of the element referenced by the tag.
• New property TaggedLocalElementId – provides the id of a linked element reference by the tag.
• New method GetTaggedLocalElement() – returns the handle of the element reference by the tag.
• New property IsOrphaned – Orphans are those tags that are associated with an instance of a linked Revit file but have no host element. Tags become orphaned when the element they were tagging was deleted from the link.

Import and Export APIs changes

The import and export APIs no longer have special argument combinations which permit use of the "active view". If you wish to export from or import to the active view, you must obtain it directly and pass it as input to the method.

• For the following APIs, a non-empty ViewSet must be provided:
  • bool Export (string folder, string name, ViewSet views, DGNExportOptions options);
  • bool Export (string folder, string name, ViewSet views, DWGExportOptions options);
  • bool Export (string folder, string name, ViewSet views, DXFExportOptions options);
  • bool Export (string folder, string name, ViewSet views, SATExportOptions options);
  • bool Export (string folder, string name, ViewSet views, DWFExportOptions options);
  • bool Export (string folder, string name, ViewSet views, DWFXExportOptions options);
  • bool Export (string folder, string name, ViewSet views, FBXExportOptions options);

• For the following API, a 3D view must be provided:
  • bool Export(string folder, string name, View3D view, ViewPlan grossAreaPlan, BuildingSiteExportOptions options);

• For import APIs, the 'View' property has been removed from the DWGImportOptions and ImageImportOptions. Instead, a new required argument has been added for the following APIs:
  • bool Import (string file, DWGImportOptions options, View view, out Element element);
  • bool Import (string file, ImageImportOptions options, View view, out Element element);
  • bool Link (string file, DWGImportOptions options, View view, out Element element);

The methods

• ACADExportOptions.GetPredefinedSetupNames()
• DWGExportOptions.GetPredefinedOptions()
• DXFExportOptions.GetPredefinedOptions()

provide access to predefined setups and settings from a given document for DWG and DFX export.

The method

• Document.Import(String, InventorImportOptions)

has been replaced by

• Application.OpenBuildingComponentDocument(String)

Save and Close API changes

• Document.Close()
• Document.Close(bool saveModified)

The behaviour of these methods has been changed. Previously, they would prompt the interactive 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 they will throw an exception if the document's path name is not yet set, or if the saving target file is read-only.

• Document.Save()

The behaviour of this method has been changed. Previously, it would prompt the interactive 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 set yet. In this case, it needs to be first saved using the SaveAs method instead, or when the target file is read-only.

• Document.Save(SaveOptions)

This new method behaves identically to Document.Save(), but allows you to specify a temporary id to use to generate the file preview.

• Document.SaveAs(string fileName)
• Document.SaveAs(string fileName, bool changeDocumentFilename)

The behaviour of these methods has been changed. Previously, they would prompt the user before overwriting another file. Now an exception will be thrown in that situation.

• Document.SaveAs(string fileName, SaveAsOptions options)

This new method 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.

• UIDocument.SaveAndClose()

This new method 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.

• UIDocument.SaveAs()

This new method saves the document to a file name and path obtained from the Revit user (via the "Save As" dialog).

Reference properties

The Reference class is being 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 it was obtained from. The following table lists the replacement API calls for the obsolete Reference properties:

• Element – ElementId or Document.GetElement(Reference)
• GeometryObject – Element.GetGeometryObjectFromReference(Reference)
• Transform – ReferenceWithContext.GetInstanceTransform() (see below)
• ProximityParameter – ReferenceWithContext.ProximityParameter (see below)
• ElementReferenceType – Unchanged
• GlobalPoint – Unchanged
• UVPoint – Unchanged

The method

• Document.FindReferencesByDirection()

is affected most by this change. The method was the only method to populate the Transform and ProximityParameter properties of Reference. You should switch to the replacement method:

• Document.FindReferencesWithContextByDirection()

This replacement method returns a list of ReferenceWithContext objects, containing the Reference plus additional members:

• ReferenceWithContext.ProximityParameter
• ReferenceWithContext.GetInstanceTransform()

Note that methods which existed in Revit 2011 and earlier will continue in this release to return a fully populated Reference object (it is not necessary to change code dealing with these methods). However, methods added in Revit 2012 may not return a fully populated Reference handle and will need to be parsed using the replacement methods above. Also, affected members have been marked obsolete and planned to be removed in a future release.

Event argument changes

A few changes have been made to event argument classes as we align frameworks to generate code for events.

Note: some of these classes and methods may change again in future.

The following table of changes lists the affected property, the classes providing it, and the new member with optional notes:

• Cancel – Many event argument classes – Methods Cancel(), IsCancelled() – Now available only in argument classes for pre-events that derive from RevitAPIPreEventArgs.
• ImportedInstance – FileImportedEventArgs – Property ImportedInstanceId – Now an ElementId.
• PrintedViews – DocumentPrintedEventArgs – Method GetPrintedViewElementIds().
• FailedViews – DocumentPrintedEventArgs – Method GetFailedViewElementIds().
• Views – DocumentPrintingEventArgs – Method GetViewElementIds().

Event sender changed for UI events

For some UI events on UIApplication and UIControlledApplication, the type of the "sender" object has been changed.

• For the ApplicationClosing event, the sender object is now a UIControlledApplication object (it was previously a ControlledApplication);
• For all other UI events, the sender object is now a UIApplication (it was previously an Application).

Move/Mirror/Rotate/Array changes

Move method replacements

The new static methods

• ElementTransformUtils.MoveElements(Document, ICollection<ElementId>, XYZ)
• ElementTransformUtils.MoveElement(Document, ElementId, XYZ)

replace the Document.Move() overloads.

Mirror method replacements

The new static methods

• ElementTransformUtils.MirrorElements(Document, ICollection<ElementId>, Plane)
• ElementTransformUtils.MirrorElement(Document, ElementId, Plane)

replace the Document.Mirror() methods. These new methods allow you to mirror one or more elements directly about a geometric plane which you may construct directly. Previously the Document.Mirror() methods required you to obtain a reference to an actual plane, or implicitly used the active view to calculate the mirror plane.

Rotate method replacements

The new static methods

• ElementTransformUtils.RotateElements(Document, ICollection<ElementId>, Line, double)
• ElementTransformUtils.RotateElement(Document, ElementId, Line, double)

replace the Document.Rotate() methods.

New Copy methods

The new static methods

• ElementTransformUtils.CopyElements(Document, ICollection<ElementId>, XYZ)
• ElementTransformUtils.CopyElement(Document, ElementId, XYZ)

allow you to copy and translate one or more physical elements and place the newly copied elements by applying the given translation vector.

LinearArray creation replacement methods

The new methods

• LinearArray.Create(Document, View, ICollection<ElementId>, int, XYZ, ArrayAnchorMember)
• LinearArray.Create(Document, View, ElementId, int, XYZ, ArrayAnchorMember)

replace the Document.Array() overloads that return LinearArray.

The new methods

• LinearArray.ArrayElementsWithoutAssociation(Document, View, ICollection<ElementId>, int, XYZ, ArrayAnchorMember)
• LinearArray.ArrayElementWithoutAssociation(Document, View, ElementId, int, XYZ, ArrayAnchorMember)

replace the Document.ArrayWithoutAssociate() methods that create sets of elements based on linear translation.

RadialArray creation replacement methods

The new methods

• RadialArray.Create(Document, View, ICollection<ElementId>, int Line, double, ArrayAnchorMember)
• RadialArray.Create(Document, View, ElementId, int Line, double, ArrayAnchorMember)

replace the Document.Array() overloads that return RadialArray. The new methods require a view input (where previously the old overloads would use the active view implicitly, which could lead to unexpected failure in some conditions).

The new methods

• RadialArray.ArrayElementsWithoutAssociation(Document, View, ICollection<ElementId>, int, Line, double, ArrayAnchorMember)
• RadialArray.ArrayElementWithoutAssociation(Document, View, ElementId, int, Line, double, ArrayAnchorMember)

replace the Document.ArrayWithoutAssociate() methods that create sets of elements based on rotation.

Structural AnalyticalModel changes

AnalyticalModel now an Element

The AnalyticalModel class is now a subclass of Element.

One consequence of this change: the AnalyticalModel of a newly created structural element can no longer be obtained without regeneration (as the AnalyticalModel element must be generated).

AnalyticalModelSelector

The following two constructors were removed from AnalyticalModelSelector:

• AnalyticalModelSelector(IList<Curve>, int index)
• AnalyticalModelSelector(IList<Curve>, int index, AnalyticalCurveSelector)

The following method was also removed:

• bool IsValidIndex(IList<Curve>, int index)

Instead of passing the array of curves and the index to create the selector, you should use the constructor that accepts the Curve directly (obtain the curve from the collection prior to input).

SlabFoundationType

The enumerated value SlabFoundationType.Slab is now SlabFoundationType.SlabOneWay. A new option, SlabTwoWay, is also available. Existing floors assigned the value Slab will report SlabOneWay.

Major enhancements to the Revit API

Extensible Storage

The Revit API now allows you to create your own class-like Schema data structures and attach instances of them to any Element in a Revit model. This functionality can be used to replace the technique of storing data in hidden shared parameters. Schema-based data is saved with the Revit model and allows for higher-level, metadata-enhanced, object-oriented data structures. Schema data can be configured to be readable and/or writable to all users, just a specific application vendor, or just a specific application from a vendor.

The extensible storage classes are all found in Autodesk.Revit.DB.ExtensibleStorage

• Autodesk.Revit.DB.ExtensibleStorage.SchemaBuilder -- Used to create Schemas definitions
• Autodesk.Revit.DB.ExtensibleStorage.Schema --Contains a unique schema identifier, read/write permissions, and a collection of data Field objects.
• Autodesk.Revit.DB.ExtensibleStorage.Field -- Contains data name, type, and unit information and is used as the key to access corresponding data in an Element
• Autodesk.Revit.DB.ExtensibleStorage.FieldBuilder -- A helper class used with SchemaBuilder used when creating a new field.
• Autodesk.Revit.DB.ExtensibleStorage.Entity -- An object containing data corresponding to a Schema that can then be inserted into an Element.

The following data types are currently supported:

• int
• short
• double
• float
• bool
• string
• Guid
• ElementId
• Autodesk.Revit.DB.XYZ
• Autodesk.Revit.DB.UV
• Autodesk.Revit.DB.ExtensibleStorage.Entity (An instance of another Schema, also known as a SubSchema)
• Array (as a System.Collections.Generic.IList<T>)
• Map (as a System.Collections.Generic.IDictionary<TKey, TValue>)
• All types supported for simple types, including Entity, are supported for the <TValue> parameter.
• All types supported for simple types *except* double, float, XYZ, UV, and Entity are supported for the <TKey> parameter.

Simple usage of ExtensibleStorage

// Create a data structure, attach it to a wall, 
// populate it with data, and retrieve the data 
// back from the wall
public void StoreDataInWall(
  Wall wall,
  XYZ dataToStore )
{
  Transaction createSchemaAndStoreData
    = new Transaction(wall.Document, "tCreateAndStore");
  createSchemaAndStoreData.Start();
  SchemaBuilder schemaBuilder = new SchemaBuilder(
    new Guid("720080CB-DA99-40DC-9415-E53F280AA1F0"));
  // allow anyone to read the object
  schemaBuilder.SetReadAccessLevel(AccessLevel.Public);
  // restrict writing to this vendor only
  schemaBuilder.SetWriteAccessLevel(AccessLevel.Vendor);
  // required because of restricted write-access
  schemaBuilder.SetVendorId("ADSK");
  // create a field to store an XYZ
  FieldBuilder fieldBuilder = schemaBuilder
    .AddSimpleField("WireSpliceLocation", typeof(XYZ));
  fieldBuilder.SetUnitType(UnitType.UT_Length);
  fieldBuilder.SetDocumentation(
    "A stored location value representing a wiring splice in a wall.");
  schemaBuilder.SetSchemaName("WireSpliceLocation");
  // register the Schema object
  Schema schema = schemaBuilder.Finish();
  // create an entity (object) for this schema (class)
  Entity entity = new Entity(schema);
  // get the field from the schema
  Field fieldSpliceLocation
    = schema.GetField("WireSpliceLocation");
  // set the value for this entity
  entity.Set<XYZ>(fieldSpliceLocation,
    dataToStore, DisplayUnitType.DUT_METERS);
  // store the entity in the element
  wall.SetEntity(entity);
  // get the data back from the wall
  Entity retrievedEntity = wall.GetEntity(schema);
  XYZ retrievedData = retrievedEntity.Get<XYZ>(
    schema.GetField("WireSpliceLocation"),
    DisplayUnitType.DUT_METERS);
  createSchemaAndStoreData.Commit();
}

Worksharing API

Several new classes were added to provide access to worksharing information in the document:

• Workset – Represents a workset in the document. Worksets are a way to divide a set of elements in the Revit document into subsets for worksharing.
• WorksetId – Identifies a workset within a single document.
• WorksetKind – An enumerated type that indicates one of the standard kinds of workset (as available in the UI).
• WorksetTable – A table containing references to all the worksets contained in a document.
• WorksetVisibility – An enumerated type that indicates the visibility settings of a workset in a particular view.
• WorksetDefaultVisibilitySettings – An object that manages default visibility of worksets in a document.
• FilteredWorksetCollector – This class is used to search, filter and iterate through a set of worksets. Developers can assign a condition to filter the worksets that are returned. If no condition is applied, it attempts to access all the worksets in the document.
• FilteredWorksetIdIterator – An iterator to a set of workset ids filtered by the settings of a FilteredWorksetCollector.
• FilteredWorksetIterator – An iterator to a set of worksets filtered by the settings of a FilteredWorksetCollector.
• WorksetFilter – A base class for a type of filter that accepts or rejects worksets based upon criteria.
• WorksetKindFilter – A filter used to match worksets of the given WorksetKind.
• ElementWorksetFilter – A filter used to match elements which reside in a given workset (use this filter with FilteredElementCollector).
• WorksharingUtils – access to information about a work-shared document.
• WorksharingTooltipInfo – basic read-only information about a work-shared document, such as owner, creator, etc.

Some related additions were made to existing classes:

• Document.GetWorksetTable() – Gets the WorksetTable of this document. There is one WorksetTable for each document.
• Document.GetWorksetId(ElementId id) – Gets the id of the Workset which owns the element.
• Element.WorksetId – Gets the id of the workset which owns the element.
• View.GetWorksetVisibility(WorksetId worksetId) – Returns the visibility settings of a workset for this particular view.
• View.SetWorksetVisibility(WorksetId worksetId, WorksetVisibility visible) – Sets visibility for a workset in this view. This setting overrules implicit visibility of the workset for this particular view.
• View.IsWorksetVisible(WorksetId worksetId) – Indicates whether the workset is visible in this view.

In addition, there is API support for the new 2012 worksharing visualization functionality:

• View.SetWorksharingDisplayMode and View.GetWorksharingDisplayMode allow the API to control which worksharing display mode is enabled in the view.
• WorksharingDisplaySettings allows getting and setting the specific graphic overrides that will be applied in the various worksharing display modes.

Setting the Active View

The new property

• UIDocument.ActiveView

has both a getter and setter, so it allows you to query the currently active view of the currently active document, and also allows you to set it similarly to what an end user can do by changing a view in the Project Browser in Revit.

The setter has a number of limitations:

• It can only be used in an active document, which must not be in read-only state and must not be inside a transaction.
• The setter also cannot be used during ViewActivating and ViewActivated events, or during any pre-action event, such as DocumentSaving, DocumentExporting, or other similar events.

Opening and activating a document

A new method:

• UIApplication.OpenAndActivateDocument(String)

was added to the UI API. It opens a Revit document and makes it the active one. The document is opened with its default view displayed.

There are limitations preventing this method to be called at certain situations:

• when there is a transaction open in the currently active document (if there is an active document)
• during execution of any event handler

Adding a custom Ribbon tab

The new methods

• UIApplication.CreateRibbonTab()
• UIApplication.CreateRibbonPanel(string, string)
• UIApplication.GetRibbonPanels(string)

(and the corresponding methods in UIControlledApplication) provide the ability to add a new ribbon tab to Revit, at the end of the list of static tabs (to the right of the Add-Ins tab, if shown). If multiple tabs are added, they will be shown in the order added.

There is a limit to the number of custom tabs supported in a given session of Revit (20). This limit is provided to ensure that the standard tabs remain visible and usable. Because of this, your application should only add a custom tab if it's really needed.

Construction modeling API

New functionality in Revit 2012 allows elements to be divided into sub-parts, collected into assemblies, and displayed in special assembly views. The API for dividing parts is still under development and likely to change.

Read, write and create access to assemblies in the Revit environment is provided through the classes:

• Autodesk.Revit.DB.Assembly.AssemblyInstance
• Autodesk.Revit.DB.Assembly.AssemblyType

A new assembly containing the selected elements can be created as follows:

  ElementId categoryId = doc.get_Element(
    uidoc.Selection.GetElementIds().
  FirstOrDefault() ).Category.Id;
 
  ElementId titleblockId
    = doc.TitleBlocks.Cast<FamilySymbol>()
      .First<FamilySymbol>().Id;
 
  AssemblyInstance instance = null;
 
  Transaction t = new Transaction( doc );
 
  if( AssemblyInstance.IsValidNamingCategory( doc,
    categoryId, uidoc.Selection.GetElementIds() ) )
  {
    t.SetName( "Create Assembly Instance" );
    t.Start();
    instance = AssemblyInstance.Create( doc,
      uidoc.Selection.GetElementIds(), categoryId );
    t.Commit();
 
    t.SetName( "Set Assembly Name" );
    t.Start();
    string assemblyName = "Assembly #1";
    if( AssemblyInstance.IsValidAssemblyName( doc,
      assemblyName, categoryId ) )
    {
      instance.AssemblyTypeName = assemblyName;
    }
    t.Commit();
  }

Other important methods include AssemblyInstance.GetMemberIds(), AssemblyInstance.SetMemberIds(), and AssemblyInstance.Disassemble().

Assembly views, that display only the elements in the assembly, are created with the AssemblyViewUtils class such as:

  if( instance.AllowsAssemblyViewCreation() )
  {
    ViewSheet viewSheet = AssemblyViewUtils
      .CreateSheet( doc, instance.Id, titleblockId );
 
    View3D view3d = AssemblyViewUtils
      .Create3DOrthographic( doc, instance.Id );
 
    ViewSection detailSectionA = AssemblyViewUtils
      .CreateDetailSection( doc, instance.Id,
      AssemblyDetailViewOrientation.DetailSectionA );
 
    View materialTakeoff = AssemblyViewUtils
      .CreateMaterialTakeoff( doc, instance.Id );
 
    View partList = AssemblyViewUtils
      .CreatePartList( doc, instance.Id );
  }

The PartUtils class provides methods to identify Part elements that are created by sub-dividing model elements. These methods describe the relationship between Parts and the elements (such as walls, floors, etc) that are divided to create the Parts.

DB-level applications

The add-in framework has been extended to support database-level add-ins. These add-ins should be used when the purpose of your application is to assign events and/or updaters to the Revit session, but not to add anything to the Revit user interface or use APIs from RevitAPIUI.dll.

To implement a DB-level application, implement the methods in the Autodesk.Revit.DB.IExternalDBApplication interface:

• public Result OnStartup(Autodesk.Revit.ApplicationServices.ControlledApplication app)
• public Result OnShutdown(Autodesk.Revit.ApplicationServices.ControlledApplication app)

Within the OnStartup() method you should register events and updaters which your application will respond to during the session.

To register the DB-level application with Revit, add the appropriate registry entry to a manifest file in the Addins folder. A DB-level application has a similar structure as for a UI external application:

<?xml version="1.0" standalone="no"?>
<RevitAddIns>
  <AddIn Type="DBApplication">
    <Assembly>MyDBLevelApplication.dll</Assembly>
    <AddInId>DA3D570A-1AB3-4a4b-B09F-8C15DFEC6BF0</AddInId>
    <FullClassName>MyCompany.MyDBLevelAddIn</FullClassName>
    <Name>My DB-Level AddIn</Name>
  </AddIn>
</RevitAddIns>

Geometry API enhancements

Get original geometry of a FamilyInstance

The new method

• FamilyInstance.GetOriginalGeometry()

returns the original geometry of the instance, before the instance is modified by joins, cuts, coping, extensions, or other post-processing.

Extrusion analysis of a solid

The utility class

• ExtrusionAnalyzer

allows you to attempt to “fit” a given piece of geometry into the shape of an extrusion. An instance of this class is a single-time use class which should be supplied a solid geometry, a plane, and a direction. The utility will calculate a base boundary parallel to the input plane which is the outer boundary of the shadow cast by the solid onto the input plane and along the extrusion direction.

After the extrusion has been calculated, the class permits a second step analysis to identify all faces from the original geometry which do not align with the faces of the calculated extrusion.

This utility works best for geometry which are at least somewhat “extrusion-like”, for example, the geometry of a wall which may or may not be affected by end joins, floor joins, roof joins, openings cut by windows and doors, or other modifications.

GeometryCreationUtilities

The new utility class GeometryCreationUtilities offers the ability to create solid geometry from input curves:

• GeometryCreationUtilities.CreateBlendGeometry()
• GeometryCreationUtilities.CreateExtrusionGeometry()
• GeometryCreationUtilities.CreateRevolvedGeometry()
• GeometryCreationUtilities.CreateSweptGeometry()
• GeometryCreationUtilities.CreateSweptBlendGeometry()

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 (SpatialFieldManager.AddSpatialFieldPrimitive())
• As the input solid to finding 3D elements by intersection
• As one or more of the inputs to a Boolean operation
• As a part of a geometric calculation (using, for example, Face.Project(), Face.Intersect(), or other Face, Solid, and Edge geometry methods)

Find 3D elements by intersection

The new element filters:

• ElementIntersectsElementFilter
• ElementIntersectsSolidFilter

pass elements whose actual 3D geometry intersects the 3D geometry of the target object. With ElementIntersectsElementFilter, the target object is another element. The intersection is determined with the same routine used to determine if an interference exists during generation of an InterferenceReport. With ElementIntersectsSolidFilter, the target object is any solid, including one created from scratch using GeometryCreationUtilities.

This example uses a created cylinder centered on the end of a wall to find other walls in close proximity (whether or not they are actually joined):

public ICollection<ElementId>
  FindWallJoinsAtEndUsingProximity(
    Wall wall, int end )
{
  // Get properties of wall at the end point 
  LocationCurve wallCurve = wall.Location
    as LocationCurve;
  XYZ endPoint = wallCurve.Curve.get_EndPoint( end );
  double height = wall.get_Parameter(
    BuiltInParameter.WALL_USER_HEIGHT_PARAM ).AsDouble();
  double elevation = wall.Level.Elevation;
  // Build cylinder centered at wall end point, 
  // extending 3' in diameter 
  CurveLoop cylinderLoop = new CurveLoop();
  XYZ arcCenter = new XYZ(
    endPoint.X, endPoint.Y, elevation );
  Application application = wall.Document.Application;
  Arc firstArc = application.Create.NewArc( arcCenter,
    1.5, 0, Math.PI, XYZ.BasisX, XYZ.BasisY );
  Arc secondArc = application.Create.NewArc( arcCenter,
    1.5, Math.PI, 2 * Math.PI, XYZ.BasisX, XYZ.BasisY );
  cylinderLoop.Append( firstArc );
  cylinderLoop.Append( secondArc );
  List<CurveLoop> singleLoop = new List<CurveLoop>();
  singleLoop.Add( cylinderLoop );
  Solid proximityCylinder = GeometryCreationUtilities
    .CreateExtrusionGeometry( singleLoop,
      XYZ.BasisZ, height );
  // Filter walls 
  FilteredElementCollector proximityCollector
    = new FilteredElementCollector( wall.Document );
  proximityCollector.OfClass( typeof( Wall ) );
  // Exclude the wall itself 
  List<ElementId> toExclude = new List<ElementId>();
  toExclude.Add( wall.Id );
  proximityCollector.Excluding( toExclude );
  // Filter only elements intersecting our target cylinder 
  proximityCollector.WherePasses(
    new ElementIntersectsSolidFilter(
      proximityCylinder ) );
  // Return matches 
  return proximityCollector.ToElementIds();
}

Boolean operations

The new methods

• BooleanOperationsUtils.ExecuteBooleanOperation()
• BooleanOperationsUtils.ExecuteBooleanOperationModifyingOriginalSolid()

execute a boolean operation combining a pair of solid geometry objects. Options to the method include the operations type: Union, Difference, or Intersect.

The first method takes a copy of the input solids and produces a new solid as a result. Its first argument can be any solid, either obtained directly from a

Revit element or created via another operation like GeometryCreationUtils.

The second method performs the boolean operation directly on the first input solid. The first input must be a solid which is not obtained directly from a Revit

element. The property

• GeometryObject.IsElementGeometry

can identify whether the solid is appropriate as input for this method.

In this example, the geometry of intersecting columns and walls is obtained by a Boolean intersection operation. The intersection volume and number of boundary faces is shown in the resulting dialog.

/// <summary> 
/// A data structure containing the details 
/// of each intersecting wall/column pair. 
/// </summary> 
struct Intersection
{
  public Element Wall;
  public Element Column;
  public Solid Solid;
}
 
/// <summary> 
/// A collection of all intersections. 
/// </summary> 
private List<Intersection> m_allIntersections;
 
/// <summary> 
/// Finds and posts information on wall/column intersections. 
/// </summary> 
/// <param name="doc">The document.</param> 
public void FindIntersectionVolumes( Document doc )
{
  // Find all Wall elements. 
  FilteredElementCollector collector
    = new FilteredElementCollector( doc );
  collector.OfClass( typeof( Wall ) );
  m_allIntersections = new List<Intersection>();
  foreach( Wall wall in collector.OfType<Wall>() )
  {
    // Find all intersecting columns 
    FilteredElementCollector columnIntersectionCollector
      = new FilteredElementCollector( doc );
    // Columns may be one of two different categories 
    List<BuiltInCategory> categories
      = new List<BuiltInCategory>();
    categories.Add( BuiltInCategory.OST_Columns );
    categories.Add( BuiltInCategory.OST_StructuralColumns );
    ElementMulticategoryFilter categoryFilter
      = new ElementMulticategoryFilter( categories );
    // Apply intersection filter to find matches 
    ElementIntersectsElementFilter intersectsFilter
      = new ElementIntersectsElementFilter( wall );
    columnIntersectionCollector
      .WhereElementIsNotElementType()
      .WherePasses( categoryFilter )
      .WherePasses( intersectsFilter );
    foreach( Element element in
      columnIntersectionCollector )
    {
      // Store information on intersection 
      Intersection intersection;
      intersection.Wall = wall;
      intersection.Column = element;
      Solid wallSolid = GetGeometry( wall );
      Solid columnSolid = GetGeometry( element );
      // Intersect the solid geometry of the two elements 
      intersection.Solid = BooleanOperationsUtils
        .ExecuteBooleanOperation( wallSolid,
        columnSolid, BooleanOperationsType.Intersect );
      m_allIntersections.Add( intersection );
    }
  }
  TaskDialog td = new TaskDialog( "Intersection info" );
  td.MainInstruction = "Intersections found: "
    + m_allIntersections.Count;
  StringBuilder builder = new StringBuilder();
  foreach( Intersection intersection in
    m_allIntersections )
  {
    builder.AppendLine( String.Format(
      "{0} x {1}: volume {2} faces {3}",
      intersection.Wall.Name,
      intersection.Column.Name,
      intersection.Solid.Volume,
      intersection.Solid.Faces.Size ) );
  }
  td.MainContent = builder.ToString();
  td.Show();
}
 
/// <summary> 
///  Gets the solid geometry of an element. 
/// </summary> 
/// <remarks>Makes an assumption that each element 
/// consists of only one postive-volume solid, and 
/// returns the first one it finds.</remarks> 
/// <param name="e"></param> 
/// <returns></returns> 
private Solid GetGeometry( Element e )
{
  GeometryElement geomElem = e.get_Geometry(
    new Options() );
  foreach( GeometryObject geomObj in
    geomElem.Objects )
  {
    // Walls and some columns will have a 
    // solid directly in its geometry 
    if( geomObj is Solid )
    {
      Solid solid = (Solid)geomObj;
      if( solid.Volume > 0 )
        return solid;
    }
    // Some columns will have a instance 
    // pointing to symbol geometry 
    if( geomObj is GeometryInstance )
    {
      GeometryInstance geomInst
        = (GeometryInstance) geomObj;
      // Instance geometry is obtained so that the 
      // intersection works as expected without 
      // requiring transformation 
      GeometryElement instElem
        = geomInst.GetInstanceGeometry();
      foreach( GeometryObject instObj in
        instElem.Objects )
      {
        if( instObj is Solid )
        {
          Solid solid = (Solid)instObj;
          if( solid.Volume > 0 )
            return solid;
        }
      }
    }
  }
  return null;
}

HostObject – top, bottom, side faces

The new methods

• HostObjectUtils.GetTopFaces()
• HostObjectUtils.GetBottomFaces()
• HostObjectUtils.GetSideFaces()

provide a shortcut to 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 host face of a FamilyInstance

The property

• FamilyInstance.HostFace

gets the reference to the host face of family instance, or if the instance is placed on a work plane, the reference to the geometry face underlying the work plane.

Element.Geometry

This property has been modified to throw an exception when attempting to read the geometry of a newly added or modified element, if the element has not yet been regenerated. Call Document.Regenerate() to regenerate the affected element and to be able to obtain the geometry.

This property now returns results for ElementType subclasses which own geometry.

GeometryObject.GraphicsStyleId

This new property allows access to the GraphicsStyle and Category of individual family primitives to be determined while working in the project environment.

Curve representation of an Edge

The methods

• Edge.AsCurve()
• Edge.AsCurveFollowingFace(Face faceForDir)

provide a curve that corresponds to the edge (either oriented along the edge's parametric direction, or oriented in the edge's topological direction on the specified face).

Centroid of a Solid

The method

• Solid.ComputeCentroid

calculates the centroid of the solid using an approximation, with an accuracy suitable for architectural purposes. This will correspond only with the center of gravity if the solid represents a homogeneous structure of a single material.

Transforming geometry

The new method

• GeometryElement.GetTransformed()

returns a copy of the geometry in the original element, transformed by the input coordinate transformation.

Instance.GetTransform() and Instance.GetTotalTransform()

These new methods provide the transform for a given Instance (which is the parent class for elements like family instances, link instances, and imported CAD content). GetTransform() obtains the basic transform for the instance based on how the instance is placed. GetTotalTransform() provides the transform modified with the true north transform, for instances like import instances.

Serialization/deserialization of References

The new methods

• Reference.ConvertToStableRepresentation()
• Reference.ParseFromStableRepresentation()

allow you to save a reference to a geometry object, for example a face, edge, or curve, as a string, and to obtain an identical Reference later using the String as input.

Face.HasRegions & Face.GetRegions()

This property and method provide information about the faces created by the Split Face command. HasRegions returns a boolean indicating if the face has any Split Face regions. GetRegions returns a list of faces. As the material of these faces can be independently modified through the UI with the Paint tool, the material of each face can be found from its MaterialElementId property.

Face.MaterialElementId replaces Face.MaterialElement

Face.MaterialElement has been obsoleted. Face.MaterialElementId should be used instead.

In some cases the return face will not have access to its Document, so the MaterialElement cannot be returned, but the id can.

NewHermiteSpline tangency control

A new overload takes optional XYZ inputs for the tangency at the start and end of the spline.

New NewNurbSpline overload

The new overload

• Autodesk.Revit.Creation.Application.NewNurbSpline(IList<XYZ> controlPoints, IList<double> weights)

creates a NurbSpline in an identical manner to how the spline sketching tool creates such a curve in the Revit UI. Remaining fields in the curve definition (Knots, Degree) are automatically assigned from the calculation.

PolyLine returned from Element.Geometry

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). Previous Element.Geometry[] would skip extraction of these geometry object completely.

Analysis of Room and Space 3D geometry

The new method:

• SpatialElementGeometryCalculator.CalculateSpatialElementGeometry()

computes the 3D geometry of the input spatial element (room or space) and returns it, along with information about the elements which form the boundary of the element.

The new classes:

• SpatialElementGeometryResults
• SpatialElementBoundarySubface

encapsulate the results of the geometric calculation.

The class:

• SpatialElementBoundaryOptions

provides the available options for the calculation (currently limited to an option to calculate the boundaries at the finish face or at the boundary object's centerlines and whether to include the free boundary faces in the calculation result).

Detailed Energy Analysis Model API

A new API is provided to obtain and analyze the contents of a project's detailed energy analysis model, as seen in the Export to gbXML and the Heating and Cooling Loads features:

This analysis produces 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.

The new classes in Autodesk.Revit.DB.Analysis namespace:

• EnergyAnalysisDetailModel
• EnergyAnalysisDetailModelOptions
• EnergyAnalysisOpening
• EnergyAnalysisSpace
• EnergyAnalysisSurface
• Polyloop

can be used to generate and analyze the contents of the detailed energy analysis model. Use

• EnergyAnalysisDetailModel.Create()

to create and populate the model (while setting up appropriate options); use

• EnergyAnalysisDetailModel.GetAnalyticalSpace()
• EnergyAnalysisDetailModel.GetAnalyticalSurfaces()
• EnergyAnalysisDetailModel.GetAnalyticalOpenings()
• EnergyAnalysisDetailModel.GetAnalyticalShadingSurfaces()

to extract the entities from the analysis; and use

• EnergyAnalysisDetailModel.Destroy()

to clean up the Revit database after finishing with the analysis results.

Conceptual energy analysis API

The new classes in the Autodesk.Revit.DB.Analysis namespace:

• ConceptualConstructionType
• ConceptualSurfaceType
• MassEnergyAnalyticalModel
• MassLevelData
• MassSurfaceData
• MassZone

provide access to the elements and objects created by Revit to perform energy analyses on conceptual design models.

The method

• Document.Export(string,string,MassGBXMLExportOptions)

supports export of a gBXML file containing conceptual energy analysis elements (mass elements) only.

Analysis visualization framework

The analysis visualization framework was improved to support multiple analysis results shown in the same view at the same time.

The new class

• AnalysisResultSchema

was added to store meta-data for each analysis result. The Results Visibilty view frame control in the user interface and the API's SpatialFieldManager.ResultsEnabledInView and AnalysisResultSchema.IsVisible properties control which results (if any) are displayed.

The class SpatialFieldManager now has new methods:

• RegisterResult()
• GetResultSchema()
• SetResultSchema()
• GetRegisteredResults()

to register and access results meta-data. Corresponding methods and properties of SpatialFieldManager:

• SetUnits()
• CurrentUnits
• GetDescription()
• SetDescription()

are deprecated. They can be used if SpatialFieldManager contains only one analysis result, but they throw an exception if multiple results are registered.

The method

• UpdateSpatialFieldPrimitive()

is changed to take a result index as an additional argument; the old version is deprecated and can be used if SpatialFieldManager contains only one analysis result.

New classes allow for different types of analysis data and different appearance of results:

• AnalysisDisplayDiagramSettings
• AnalysisDisplayVectorSettings

  // Create a SpatialFieldManager for the active view 
  SpatialFieldManager sfm = SpatialFieldManager
    .CreateSpatialFieldManager(doc.ActiveView, 1);
  int primitiveIndex = sfm.AddSpatialFieldPrimitive();
 
  // This example creates two result schema. 
  // Each schema contains a single value at the origin. 
  IList<XYZ> pts = new List<XYZ>();
  pts.Add(XYZ.Zero);
 
  FieldDomainPointsByXYZ pnts = new FieldDomainPointsByXYZ(pts);
 
  // Create the schema 
 
  AnalysisResultSchema resultSchemaA = new AnalysisResultSchema(
    "Schema A", "Time");
 
  AnalysisResultSchema resultSchemaB = new AnalysisResultSchema(
    "Schema B", "Distance");
 
  // Data in Schema A measures time and can be 
  // displayed using Hours or Minutes for units 
 
  List<string> unitsList = new List<string>();
  unitsList.Add("Hours");
  unitsList.Add("Minutes");
  List<double> unitsMultipliers = new List<double>();
  unitsMultipliers.Add(1);
  unitsMultipliers.Add(60);
  resultSchemaA.SetUnits(unitsList, unitsMultipliers);
 
  List<double> doubleList = new List<double>();
 
  // The data value in Schema A is 3.5 hours 
 
  doubleList.Add(3.5);
  IList<ValueAtPoint> valueList
    = new List<ValueAtPoint>();
  valueList.Add(new ValueAtPoint(doubleList));
  FieldValues fieldValuesA
    = new FieldValues(valueList);
 
  // Data in Schema B measures distance and can be 
  // displayed using Feet or Inches for units 
  unitsList.Clear();
  unitsMultipliers.Clear();
  unitsList.Add("Feet");
  unitsList.Add("Inches");
  unitsMultipliers.Add(1);
  unitsMultipliers.Add(12);
  resultSchemaB.SetUnits(unitsList, unitsMultipliers);
 
  doubleList.Clear();
  valueList.Clear();
  // The data value in Schema B is 5 feet 
  doubleList.Add(5);
  valueList.Add(new ValueAtPoint(doubleList));
  FieldValues fieldValuesB = new FieldValues(valueList);
 
  // Update the view's spatial field primitive with the schema 
  sfm.UpdateSpatialFieldPrimitive(primitiveIndex,
    pnts, fieldValuesA, sfm.RegisterResult(resultSchemaA));
  sfm.UpdateSpatialFieldPrimitive(primitiveIndex,
    pnts, fieldValuesB, sfm.RegisterResult(resultSchemaB));

Point Cloud API

Revit offers two sets of APIs related to Point Clouds.

The client API is capable of working with point cloud instances within Revit (creating them, manipulating their properties, and reading the points found matching a given volumetric filter).

The major classes of the client API are:

• PointCloudType – a type of a point cloud, representing the points obtained from a single file or engine's identifier.
• PointCloudInstance – an instance of a point cloud in a location in the Revit project.
• PointCloudFilter – a filter determining the volume of interest when extracting points.
• PointCollection – a collection of points obtained from an instance and a filter.
• PointIterator – an iterator for the points in a PointCollection.
• CloudPoint – an individual point cloud point, representing an X, Y, Z location in the coordinates of the cloud, and a color.

There are two methods to access the points as a client:

1. In the traditional IEnumerable interface, you can iterate the resulting points directly from the PointCollection.
2. In an unsafe interface usable only from C# and C++/CLI, you can get a pointer to the point storage of the collection and access the points directly in memory. Although you must deal with pointers directly, there may be performance improvements when traversing large buffers of points.

The following snippets show how to iterate part of a point cloud using both methods. The same point cloud filter is applied for both routines:

Reading point cloud points by iteration

private int ReadPointCloud_Iteration(
  PointCloudInstance pcInstance )
{
  PointCloudFilter filter = CreatePointCloudFilter(
    pcInstance.Document.Application, pcInstance );
 
  // Get points.  Number of points is 
  // determined by the needs of the client
 
  PointCollection points = pcInstance.GetPoints(
    filter, 10000 );
 
  int numberOfPoints = 0;
  foreach( CloudPoint point in points )
  {
    // Process each point
    System.Drawing.Color color
      = System.Drawing.ColorTranslator.FromWin32(
        point.Color );
 
    String pointDescription = String.Format(
      "({0}, {1}, {2}, {3}",
      point.X, point.Y, point.Z, color.ToString() );
 
    numberOfPoints++;
  }
  return numberOfPoints;
}

Reading point cloud points by pointer

public unsafe int ReadPointCloud_Pointer(
  PointCloudInstance pcInstance )
{
  PointCloudFilter filter = CreatePointCloudFilter(
    pcInstance.Document.Application, pcInstance );
 
  // Get points.  Number of points is 
  // determined by the needs of the client
 
  PointCollection points = pcInstance.GetPoints(
    filter, 10000 );
 
  int totalCount = points.Count;
  CloudPoint* pointBuffer = (CloudPoint*) points
    .GetPointBufferPointer().ToPointer();
 
  for( int numberOfPoints = 0;
    numberOfPoints < totalCount; numberOfPoints++ )
  {
    CloudPoint point = *( pointBuffer + numberOfPoints );
 
    // Process each point
 
    System.Drawing.Color color
      = System.Drawing.ColorTranslator.FromWin32(
        point.Color );
 
    String pointDescription = String.Format(
      "({0}, {1}, {2}, {3}",
      point.X, point.Y, point.Z, color.ToString() );
  }
  return totalCount;
}

Point cloud filter creation

private PointCloudFilter CreatePointCloudFilter(
  Application app, PointCloudInstance pcInstance )
{
  // Filter will match 1/8 of the overall point cloud
  // Use the bounding box (filter coordinates 
  // are in the coordinates of the model)
 
  BoundingBoxXYZ boundingBox
    = pcInstance.get_BoundingBox( null );
 
  List<Plane> planes = new List<Plane>();
 
  XYZ midpoint
    = ( boundingBox.Min + boundingBox.Max ) / 2.0;
 
  // X boundaries
  planes.Add( app.Create.NewPlane(
    XYZ.BasisX, boundingBox.Min ) );
  planes.Add( app.Create.NewPlane(
    -XYZ.BasisX, midpoint ) );
 
  // Y boundaries
  planes.Add( app.Create.NewPlane(
    XYZ.BasisY, boundingBox.Min ) );
  planes.Add( app.Create.NewPlane(
    -XYZ.BasisY, midpoint ) );
 
  // Z boundaries
  planes.Add( app.Create.NewPlane(
    XYZ.BasisZ, boundingBox.Min ) );
  planes.Add( app.Create.NewPlane(
    -XYZ.BasisZ, midpoint ) );
 
  // Create filter
 
  PointCloudFilter filter = PointCloudFilterFactory
    .CreateMultiPlaneFilter( planes );
 
  return filter;
}

There are two special API-only tools intended to help your client application interact with the user:

1. The SetSelectionFilter() method and FilterAction property of PointCloudInstance allow you to specify a volumetric filter to be applied to the cloud. The parts of the cloud that pass this filter will be rendered differently in the user interface than the rest of the cloud. If the FilterAction is Highlight, the selected part of the cloud will show in highlight color (blue). If the action is Isolate, only the selected part of the cloud will be visible.
2. The overloaded method Selection.PickBox() invokes a general purpose two-click editor that lets the user to specify a rectagular area on the screen. While this editor makes no changes in Revit as a result of the selections, you can use the returned box to generate a filter and apply a highlight or isolate action to the point cloud.

This example prompts the user to select a portion of the cloud, and creates a highlight filter for it.

Prompt for cloud selection and highlight

public void PromptForPointCloudSelection(
  UIDocument uiDoc, PointCloudInstance pcInstance )
{
  Application app = uiDoc.Application.Application;
  Selection currentSel = uiDoc.Selection;
 
  PickedBox pickedBox = currentSel.PickBox(
    PickBoxStyle.Enclosing,
    "Select region of cloud for highlighting" );
 
  XYZ min = pickedBox.Min;
  XYZ max = pickedBox.Max;
 
  //Transform points into filter
  View view = uiDoc.ActiveView;
  XYZ right = view.RightDirection;
  XYZ up = view.UpDirection;
 
  List<Plane> planes = new List<Plane>();
 
  // X boundaries
  bool directionCorrect = IsPointAbovePlane(
    right, min, max );
  planes.Add( app.Create.NewPlane( right,
    directionCorrect ? min : max ) );
  planes.Add( app.Create.NewPlane( -right,
    directionCorrect ? max : min ) );
 
  // Y boundaries
  directionCorrect = IsPointAbovePlane(
    up, min, max );
  planes.Add( app.Create.NewPlane( up,
    directionCorrect ? min : max ) );
  planes.Add( app.Create.NewPlane( -up,
    directionCorrect ? max : min ) );
 
  // Create filter
  PointCloudFilter filter = PointCloudFilterFactory
    .CreateMultiPlaneFilter( planes );
 
  Transaction t = new Transaction(
    uiDoc.Document, "Highlight" );
  t.Start();
 
  pcInstance.SetSelectionFilter( filter );
  pcInstance.FilterAction
    = SelectionFilterAction.Highlight;
 
  t.Commit();
}
 
private static bool IsPointAbovePlane(
  XYZ normal, XYZ planePoint, XYZ point )
{
  XYZ difference = point - planePoint;
  difference = difference.Normalize();
  double dotProduct = difference.DotProduct( normal );
  return dotProduct > 0;
}

The engine API is capable of supplying points in a point cloud to Revit. A custom engine implementation consists of the following:

• An implementation of IPointCloudEngine registered to Revit via the PointCloudEngineRegistry.
• An implementation of IPointCloudAccess coded to respond to inquiries from Revit regarding the properties of a single point cloud.
• An implementation of IPointSetIterator code to return sets of points to Revit when requested.

Engine implementations may be file-based or non-file-based:

• File-based implementations require 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.
• Non-file-based engine implementations 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. The engine provider should supply a custom command using PointCloudType.Create() and PointCloudInstance.Create() 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 to the point cloud, the user cannot manage, reload or remap point clouds of this type.

Regardless of the type of engine used, the implementation must supply enough information to Revit to display the contents of the point cloud. There are two ReadPoints methods which must be implemented:

• IPointCloudAccess.ReadPoints() – this provides a single set of points in a one-time call from Revit. Revit uses this during some display activities including selection prehighlighting. It is also possible for API clients to call this method directly (via PointCloudInstance.GetPoints()).
• IPointSetIterator.ReadPoints() – this provides a subset of points as a part of a larger iteration of points in the cloud. Revit uses this method during normal display of the point cloud; quantities of points will be requested repeatedly until it obtains enough points or until something in the display changes. The engine implementation must keep track of which points have been returned to Revit during any given point set iteration.

Material API changes and PropertySets

The Revit Materials API is largely renovated to allow for a representation of materials that is both more compact and more extensible.

The following classes are now obsolete:

• MaterialWood
• MaterialConcrete
• MaterialSteel
• MaterialGeneric
• MaterialOther

The properties on these classes are now accessible from PropertySets or the Material class itself.

All named properties on Material specific to appearance or structure (e.g. Shininess) are also obsolete.

In their place, a material will have one or more aspects pertaining to rendering appearance, structure, or other major material category. Each aspect is represented by a PropertySet or PropertySetElement. Each material can own its properties of an aspect via a PropertySet or share them with other materials as a reference to a PropertySetElement.

New enumerated types:

• MaterialAspect – An enumeration of material aspects. Currently, we support rendering and structural aspects.

New classes:

• PropertySetElement – an Element containing a PropertySet – used for sharing PropertySets among materials.

New methods:

• Material.Create()
• PropertySetElement.Create()
• Material.SetMaterialAspectByPropertySet()
• Material.SetMaterialAspectIndependent()
• Material.GetMaterialAspectPropertySet()

Performance Adviser

The new Revit feature Performance adviser is designed to analyze the document and flag for the user any elements and/or settings that may cause performance degradation. The Performance Adviser command executes set of rules and displays their result in a standard review warnings dialog.

The API for performance adviser consists of 2 classes (PerformanceAdviser and IPerformanceAdviserRule). PerformanceAdviser is an application-wide singleton that has a dual role: it is a registry of performance checking rules and an engine to execute them. The methods of PerformanceAdviser:

• AddRule()
• DeleteRule()
• GetNumberOfRules()
• GetRuleIDs()
• GetRuleName()
• GetRuleDescription()
• ExecuteRules()
• ExecuteAllRules()

allow you to manipulate what rules are checked. Applications that create new rules are expected to use AddRule() to register the new rule during application startup and DeleteRule() to deregister it during application shutdown.

Methods of PerformanceAdviser

• SetRuleEnabled
• IsRuleEnabled
• ExecuteRules

allow UI or API application to mark rules for execution and run them on a given document, getting report as a list of FailureMessage objects.

The new interface IPerformanceAdviserRule allows you to define new rules for the Performance Adviser. Your application should create a class implementing this interface, instantiate an object of the derived class and register it using PerformanceAdviser.AddRule(). Methods of IPerformanceAdviserRule available for override include:

• GetName()
• GetDescription()

which provide rule identification information;

• InitCheck()
• FinalizeCheck()

which are executed once per check and can be used to perform checks of the document "as a whole";

• WillCheckElements()
• GetElementFilter()
• ExecuteElementCheck()

which allow the rule to identify a subset of elements in the document to be checked and run the check on the individual elements.

Potentially problematic results found during rule execution are reported by returning FailureMessage(s).

External File References (Linked Files)

The API can now tell what elements in Revit are references to external files, and can make some modifications to where Revit loads external files from.

An Element which contains an ExternalFileReference is an element which refers to some external file (ie. a file other than the main .rvt file of the project.) Two new Element methods, IsExternalFileReference() and GetExternalFileReference(), let you get the ExternalFileReference for a given Element.

ExternalFileReference contains methods for getting the path of the external file, the type of the external file, and whether the file was loaded, unloaded, not found, etc. the last time the main .rvt file was opened.

The classes RevitLinkType and CADLinkType can have IsExternalFileReference() return true. RevitLinkTypes refer to Revit files linked into another Revit project. CADLinkTypes refer to DWG files. Note that CADLinkTypes can also refer to DWG imports, which are not external file references, as imports are brought completely into Revit. A property IsImport exists to let users distinguish between these two types.

Additionally, the element which contains the location of the keynote file is an external file reference, although it has not been exposed as a separate class.

There is also a class ExternalFileUtils, which provides a method for getting all Elements in a document which are references to external files.

Additionally, the classes ModelPath and ModelPathUtils have been exposed. ModelPaths can store paths to a location on disk, a network drive, or a Revit Server location. ModelPathUtils provides methods for converting between modelPath and String.

Finally, the class TransmissionData allows users to examine the external file data in a closed Revit document, and to modify path and load-state information for that data. Two methods, ReadTransmissionData, and WriteTransmissionData, are provided. With WriteTransmissionData, users can change the path from which to load a given link, and can change links from loaded to unloaded and vice versa. (WriteTransmissionData cannot be used to add links to or remove links from a document, however.)

Newly exposed classes:

• ExternalFileReference – A non-Element class which contains path and type information for a single external file which a Revit project references. ExternalFileReference also contains information about whether the external file was loaded or unloaded the last time the associated Revit project was opened.
• ExternalFileUtils – A utility class which allows the user to find all external file references, get the external file reference from an element, or tell whether an element is an external file reference.
• RevitLinkType – An element representing a Revit file linked into a Revit project.
• CADLinkType – An element representing a DWG drawing. CADLinkTypes may be links, which maintain a relationship with the file they originally came from, or imports, which do not maintain a relationship. The property IsImport will distinguish between the two kinds.
• LinkType – The base class of RevitLinkType and CADLinkType.
• ModelPath – A non-Element class which contains path information for a file (not necessarily a .rvt file.) Paths can be to a location on a local or network drive, or to a Revit Server location.
• ModelPathUtils – A utility class which provides methods for converting between strings and ModelPaths.
• TransmissionData – A class which stores information about all of the external file references in a document. The TransmissionData for a Revit project can be read without opening the document.

Customizing IFC export

The classes

• ExporterIFCRegistry
• IExporterIFC

allow your custom application to override the default implementation for the IFC export process.

The interface is passed an ExporterIFC object. The ExporterIFC object is the starting point for all IFC export activities and offers access to the options selected for the given export operation. It also contains access to information cached by Revit during the export process; this information is cached to provide easy access to it later, and sometimes to write it to the file at the end of the export process.

There are several auxiliary objects provided to support implementation of an IFC export client. These are the most important:

• IFCFile – a representation of the IFC file being written. This class contains methods which directly generate handles to IFC entries and write them to the file.
• IFCAnyHandle – a wrapper around any sort of IFC element, product, or other data.
• IFCLabel – a string in an IFC file.
• IFCMeasureValue – a parameterized value in an IFC file.
• ExporterIFCUtils – a collection of utilities to support the Revit IFC export client.

The IFC export client for Revit 2012 represents a transitional state between the version implemented internally in Revit 2011 and the final state which should be written 100% using the Revit API. Temporary APIs are exposed to bridge the gaps between the API client code and portions of the previous implementation. As Autodesk continues to evolve this export client, temporary APIs will be changed, deprecated and/or removed in future versions of Revit.

MEP API major enhancements

Pipe settings and sizes

The following new classes provide read/write access to MEP pipe settings:

• PipeSettings – The pipe settings. There is one object of this type in a document accessible through the static method GetPipeSettings().
• PipeSizeSettings – The main class to access pipe sizes. There is one object of this type in a document accessible through the static method GetPipeSizeSettings(). Stores PipeConnections per each pipe material, using the id of the pipe material element as key to access.
• PipeSizeSettingIterator – An iterator to a set of items from PipeSizeSettings. Each item is a KeyValuePair.
• PipeConnections – Represents a set of pipe connection types. Stores PipeSchedules per each pipe connection type, using the id of the pipe connection type as key to access.
• PipeConnectionIterator – An iterator to a set of items from PipeConnections. Each item is a KeyValuePair.
• PipeSchedules – Represents a set of pipe schedules. Stores PipeSizes per each pipe schedule type, using the id of the pipe schedule type as key to access.
• PipeScheduleIterator – An iterator to a set of items from PipeSchedules. Each item is a KeyValuePair.
• PipeSizes – Stores a set of pipe sizes, with the ability to add and remove from the set as needed.
• PipeSizeIterator – An iterator to a set of MEP pipe sizes from PipeSizes.
• MEPSize – Stores the basic size information for an MEP duct, pipe, cable tray, or conduit.

Placeholder ducts and pipes

The following new properties identify placeholder ducts and pipes:

• Duct.IsPlaceholder
• Pipe.IsPlaceholder

These new static methods allows creation of placeholder ducts and pipes:

• Duct.CreatePlaceholder
• Pipe.CreatePlaceholder

New utility methods are exposed to convert a set of placeholder ducts and pipes to real 3D entities:

• MechanicalUtils.ConvertDuctPlaceholders()
• PlumbingUtils.ConvertPipePlaceholders()

Duct & pipe insulation & lining

The new classes

• DuctInsulation
• PipeInsulation
• DuctLining

and related types support read/write and create access to duct & pipe insulation and lining. In Revit 2012, these objects are now accessible as standalone elements related to their parent duct, pipe, or fitting.

Small enhancements & API interface changes

SiteLocation and City TimeZone

The properties

• SiteLocation.Latitude
• SiteLocation.Longitude

now use Revit's TimeZone calculation engine to assign an appropriate time zone for the coordinates. (Previously the time zone was not modified when these values were changed).

SiteLocation retains the ability to set the TimeZone manually as the calculation is may not be accurate for locations near the boundaries.

The City class has been adjusted to return the more accurate TimeZone values.

The new static method

• SunAndShadowSettings.CalculateTimeZone()

provides direct access to the results of a time zone calculation.

FamilyParameter.GUID property

Returns the GUID of a particular family parameter. Allows you to determine if family parameters are shared or not.

InternalDefintion.Visible property

Identifies if a parameter definition represents a visible or hidden parameter (hidden applies to shared parameters only).

Selection.GetElementIds() method

Returns a collection containing the ids of the selected elements. This collection can be used directly with FilteredElementCollector.

API to prompt for rubber band box

• PickBoxStyle- A new enum that controls the style of the pick box.
• PickedBox-A new class that contains two XYZ points representing the pick box on the screen.
• The following two new methods are added to Selection class that invoke a general purpose two-click editor that lets the user to specify a rectangular area on the screen:

PickedBox Selection.PickBox(PickBoxStyle style);
PickedBox Selection.PickBox(PickBoxStyle style, String statusPrompt)

Save and SaveAs APIs permitted in most event handlers

The limitation against calling Save/SaveAs has been removed for most events.

The restriction against calling Save/SaveAs remains only in the following special events:

• DocumentSaving
• DocumentSaved
• DocumentSavingAs
• DocumentSavedAs
• DocumentSynchronizingWithCentral
• DocumentSynchronizedWithCentral
• FileExporting
• FileImporting
• DocumentPrinting
• ViewPrinting
• DocumentClosing

Please note that other restrictions may still prevent a successful save (e.g. save cannot be performed if a transaction group or transaction is still opened by the API client or via Revit's UI when the event handler is invoked)

Opening IFC Documents

A new method allows opening an IFC Document. This method is similar in behaviour to OpenDocumentFile rather than to standard Import methods. It opens the specified file as a newly created document rather than importing it into an existing one. The new document is retuned by the method if opening was successful.

• Application.OpenIFCDocument(String fileName)

RevitUIFamilyLoadOptions

The class RevitUIFamilyLoadOptions is no longer available for direct construction in the API. If you want to trigger the Revit UI to respond to situations when a loaded family is already found in the target project, obtain a special IFamilyLoadOptions instance from the new static method UIDocument.GetRevitUIFamilyLoadOptions() (in RevitAPIUI.dll) instead.

Reference documentation for BuiltInParameter members

The members of the BuiltInParameter enum (which are parameter "ids" for Revit use) now have automatically generated documentation. The documentation for each id includes the parameter name, as found in the Element Properties dialog in the English version of Autodesk Revit. Note that multiple distinct parameter ids may map to the same English name; in those case you must examine the parameters associated with a specific element to determine which parameter id to use.

SolidSolidCutUtils.CanTwoElemsHaveSolidSolidCut() method

This method has been removed and replaced by

• SolidSolidCutUtils.CanElementCutElement()

The new method provides a reason why the cutting element cannot cut the other element.

Adaptive component API

The methods in the new classes

• AdaptiveComponentFamilyUtils
• AdaptiveComponentInstanceUtils

provide access to data related to adaptive component families and instances.

ViewSheet.ConvertToRealSheet()

This new method converts a placeholder sheet to a real view sheet, optionally applying a titleblock at the same time.

Initial View Settings

A new class

• IntitialViewSettings

allows access to the initial view settings for a document that controls which view should initially be shown when the model is opened.

It has the following public methods/properties:

• GetInitialViewSettings – Returns the initial view settings for the specified document.
• ViewId – Returns (if set) or sets the Id of an initial view
• IsAcceptableInitialView – Checks whether the given view is acceptable as an initial view.

Document preview

The new method

• Document.GetDocumentPreviewSettings()

gets the settings related to the stored document preview image for a given document. It returns a DocumentPreviewSettings object, whose members include:

• DocumentPreviewSettings.PreviewViewId – the id of the view to use for the preview. This value is stored in the document and used in subsequent save operations.
• DocumentPreviewSettings.ForceViewUpdate() – sets the document to update the view before saving (useful when the document is never displayed)

Note that it is also possible to temporarily assign a preview view id for one save operation through the SaveOptions and SaveAsOptions classes. The id set to these classes is not stored in the saved documented.

Document identification

An override for

• Document.Equals()

was added to determine if two Documents represent the same document currently opened in the Revit session.

An override for

• Document.GetHashCode()

was added to return the same hashcode for document instances that represent the same document currently opened in the Revit session.

Dynamic Update Framework API changes

There are new settings to flag an updater as optional. Optional updaters will not cause prompting the end user when they are opening a document which was modified by that updater but the updater is not currently registered. red). Optional updaters should be used only when necessary. By default, updaters are non-optional. New methods introduced to support this change are:

• UpdaterRegistry.SetIsUpdaterOptional(UpdaterId id, bool isOptional)
• UpdaterRegistry.RegisterUpdater(UpdaterId id, bool isOptional)
• UpdaterRegistry.RegisterUpdater(UpdaterId id, Document doc, bool isOptional)

New methods were added to access information about currently registered updaters:

• UpdaterRegistry.GetRegisteredUpdaterInfos(Document doc)
• UpdaterRegistry.GetRegisteredUpdaterInfos()

Revit now disallows any calls to UpdaterRegistry from within the Execute() method of an updater. That means any calls to RegistryUpdater(), AddTrigger(), etc. will now throw an exception. The only method of UpdaterRegistry allowed to be called during execution of an updater is UnregisterUpdater(,) but the updater to be unregistered must be not the one currently being executed.

Enclosure class renamed

The Enclosure class, introduced in Revit 2011 as the parent class for Rooms, Spaces and Areas, was renamed to SpatialElement.

Room, Area and Space boundary segments

The individual BoundarySegment properties for the Room, Space and Area classes have been marked obsolete.

The SpatialElement class contains a new method:

• SpatialElement.GetBoundarySegments()

which works for all subclass types.

Line origin and direction

Two new properties added to Line class to get the origin and direction of a line:

• Line.Origin
• Line.Direction

TextElement properties

Five new read-only properties have been added to the TextElement class:

• TextElement.UpDirection – The direction towards the top of the text.
• TextElement.BaseDirection – The base direction for the text.
• TextElement.LineWidth – The TextElement line width.
• TextElement.Height – The TextElement height.
• TextElement.Align – The TextAlignFlags of the TextElement.

FaceSplitter class

The FaceSplitter class, representing the element produced by a Split Face operation, has been exposed to the API.

Use this class to identify the element whose face was split by the element (SplitElementId property).

  Autodesk.Revit.DB.Options opt
    = app.Create.NewGeometryOptions();
  opt.ComputeReferences = true;
  opt.IncludeNonVisibleObjects = true;
 
  FilteredElementCollector collector
    = new FilteredElementCollector( doc );
 
  ICollection<FaceSplitter> splitElements
    = collector.OfClass( typeof( FaceSplitter ) )
      .Cast<FaceSplitter>().ToList();
 
  foreach( FaceSplitter faceSplitter in
    splitElements )
  {
    Element splitElement = doc.get_Element(
      faceSplitter.SplitElementId );
 
    Autodesk.Revit.DB.GeometryElement geomElem
      = faceSplitter.get_Geometry( opt );
 
    foreach( GeometryObject geomObj in
      geomElem.Objects )
    {
      Line line = geomObj as Line;
      if( line != null )
      {
        XYZ end1 = line.get_EndPoint( 0 );
        XYZ end2 = line.get_EndPoint( 1 );
        double length = line.ApproximateLength;
      }
    }
  }

To find the faces created by the split, use the new Face.GetFaceRegions() method on the face of the host element for the split.

ColumnAttachment

The newly exposed ColumnAttachment class represents an attachment of the top or bottom of a column to a roof, floor, ceiling, or beam. Static methods:

• ColumnAttachment.GetColumnAttachment()
• ColumnAttachment.AddColumnAttachment()
• ColumnAttachment.RemoveColumnAttachment()

provide access to the settings in this class for a given element.

Color class

The API color class may represent an invalid or uninitialized color when an instance of it is obtained from Revit. Invalid colors cannot be read; a new exception will throw from the Red, Green, and Blue properties if you attempt to read them. Setting the color properties is permitted and makes the color no longer invalid.

The property

• Color.IsValid

identifies if the color is valid.

FamilyInstance: flip work plane

The new property

• FamilyInstance.IsWorkPlaneFlipped

is a settable property capable of changing if the work plane for a particular family instance is flipped.

The new property

• FamilyInstance.CanFlipWorkPlane

identifies if the family instance allows flipping of the work plane.

New NewFamilyInstance() overloads

Two new overloads are provided for creating family instances from References:

• Autodesk.Revit.Creation.ItemFactoryBase.NewFamilyInstance(Reference, Line, FamilySymbol)
• Autodesk.Revit.Creation.ItemFactoryBase.NewFamilyInstance(Reference, XYZ, XYZ, FamilySymbol)

These are identical to their counterparts that accept Faces as input. Because the Reference member will not always be populated in all Face handles, these overloads allow an alternate means of creating the target family instance attached to the right face.

The new overload

• Autodesk.Revit.Creation.ItemFactoryBase.NewFamilyInstance(Line, FamilySymbol, View)

provides the ability to create a line-based detail component.

Allow and disallow wall end joins

The new methods

• WallUtils.DisallowWallJoinAtEnd()
• WallUtils.AllowWallJoinAtEnd()
• WallUtils.IsWallJoinAllowedAtEnd()

provide access to the setting for whether or not joining is allowed at a particular end of the wall. 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 toggled to allow the joins, the wall will automatically join to its neighbors if there are any.

Element.Pinned property

The Element.Pinned property is no longer read-only. It now allows you to set an element to be pinned or unpinned.

ElementFilter.PassesElement

Two new overloads allow you to evaluate the result of an ElementFilter:

• bool ElementFilter.PassesElement(Element)
• bool ElementFilter.PassesElement(Document, ElementId)

ElementMulticategoryFilter

This new ElementFilter subtype allows you to easily find elements whose category matches any of a given set of categories.

ElementMulticlassFilter

This new ElementFilter subtype allows you to easily find elements whose class type matches any of a given set of classes.

ElementPhaseStatus

The new method

• Element.GetPhaseStatus()

returns the status of a given element in the input phase. Options include none (elements unaffected by phasing), new, demolished, past, future, existing and temporary.

The new element filter allows you to filter for elements which have a status matching one of the set of input statuses.

Temporary view mode information

The new method:

• View.IsInTemporaryViewMode()

identifies if a particular temporary view mode is active for a view.

The new method:

• View.IsElementVisibleInTemporaryViewMode()

identifies if an element should be visible in the indicated view mode. This applies only to the TemporaryHideIsolate and AnalyticalModel view modes.

Generalized Array, Set, Map classes removed

The Revit API classes in Autodesk.Revit.Collections:

• Array
• Set
• Map

have been removed. More flexible alternatives exist in the .NET framework System.Collections and System.Collections.Generic namespaces.

Replacement for ExternalCommandData.Data

The property

• ExternalCommandData.Data

has been replaced by

• ExternalCommandData.JournalData

The data type is now an IDictionary<String, String>.

The previous Data property has been marked Obsolete.

Replacement for Application.LibraryPaths

The property

• Application.LibraryPaths

has been replaced by two methods

• Application.GetLibraryPaths()
• Application.SetLibraryPaths()

The data type is now an IDictionary<String, String>.

The previous LibraryPaths property has been marked Obsolete.

LinkElementId property changes

The members of the LinkElementId class have changed in order to clarify what element is represented by an instance of this object. The new properties are:

• LinkElementId.LinkInstanceId – The id of the link, or invalidElementId if no link.
• LinkElementId.LinkedElementId – The id of the element in the link, or invalidElementId if no link.
• LinkElementId.HostElementId – The id of the element in the host, or invalidElementId if there is a link.

Application properties

The new properties:

• Application.Username
• Application.CentralServerName
• Application.LocalServerName

provide read access to information in the current Revit session.

RevitAddInUtility.dll

This DLL is now compiled as a compatible binary capable of execution on 32-bit or 64-bit systems.

VSTA changes

VSTA enabled for multiple Revit sessions

Macros can now be used in multiple Revit sessions launched from a single installation. Revit will no longer warn you about VSTA being disabled when the second and subsequent sessions are launched.

There are a few restrictions regarding what you can do from the second and subsequent sessions:

1. Application level macros in the second session may be run, but not edited, until the first session is closed.
2. Document level macros in the second session can be run and edited freely. However, edits to macro projects from a document opened in both sessions can't be saved until the document is closed by the first session.

Structure API

Track Changes UI

The track changes UI previously offered by Revit Structure has been removed. In previous releases, this offered the ability to highlight elements changed by API commands, and a limited ability to revert some or all of the changes.

Unfortunately, the functionality was limited in certain ways:

• It only watched and highlighted some types of changes that the API could make.
• It expected that only one transaction would be committed during a given API command.
• It did not respect changes made by applications during updaters and events.
• Some application developers did not want the changes they made to be undone partially.

If you wish to offer some ability for your users to see what changes were made by a given transaction, you can implement something similar or more sophisticated using the DocumentChanged event. End users are best served using the Undo mechanism to revert all changes made during a given transaction, if that is their desire. The Undo mechanism is consistent and compatible with multiple API transactions, events and updaters as well as individual commands.

LineLoad.UniformLoad

This property has been corrected to be Boolean instead of integer.

NewBeamSystem() changes

The family of NewBeamSystem() methods has changed. Previously curves could be input without a sketch plane or level as input, and the orientation of the active view would determine the orientation of the resultant beam system. Now, there are overloads accepting either the sketch plane or the level and those inputs are required.

The overloads of NewBeamSystem() now check that the input profile curves lie properly in the sketch plane or level. They also check to ensure that the profile forms a closed loop.

NewTruss() change

The SketchPlane input for this method is now required. Previously null could be input, and the orientation of the active view would determine the orientation of the resultant truss.

Rebar changes

RebarShape creation and modification

RebarShape elements are no longer modifiable (except for Allowed Bar Types). Instead of changing a RebarShape, create a new one based on the old one. This change results in a simplified API that works in the same way as the UI.

Also, the syntax for RebarShape creation has been changed. In 2011, the steps were:

1. Create a RebarShape inside the Document.
2. Create a RebarShapeDefinition inside the RebarShape.
3. Add data to the RebarShapeDefinition.
4. Commit the RebarShape.

In 2012, the steps are:

1. Create a RebarShapeDefinition. (It refers to the Document, but is not inside the document.)
2. Add data to the RebarShapeDefinition.
3. Create a RebarShape inside the Document based on the RebarShapeDefinition. (Only now is the document modified.)

Specifically, the following methods are removed:

• Autodesk.Revit.Creation.Document.NewRebarShape()
• RebarShape.NewDefinitionBySegments()
• RebarShape.NewDefinitionByArc()

and replaced by:

• RebarShape.Create(Document, RebarShapeDefinition, ... )
• The RebarShapeDefinitionBySegments constructor.
• The RebarShapeDefinitionByArc constructors.

The ability to modify hook angle, hook orientation, and style has been removed. These can only be set at creation.

• There is no SetHookAngle(int) method.
• There is no SetHookOrientation(int) method.
• The SetRebarStyle(RebarStyle) method has been removed.

Rebar Shape Parameters

The interface for Rebar Shape Parameters has changed. Throughout the Rebar API, all methods now use ElementId to stand for a shared parameter, instead of ExternalDefinition. Methods are provided in the new RebarShapeParameters class to convert between ElementId and ExternalDefinition:

• RebarShapeParameters.GetAllRebarShapeParameters(Document), which returns an array of ElementIds.
• RebarShapeParameters.GetElementIdForExternalDefinition(Document, ExternalDefinition), which retrieves or adds the parameter to the document.
• RebarShapeParameters.GetExternalDefinitionForElementId(Document, ElementId, DefinitionFile), which retrieves a shared parameter corresponding to an id.
• The class RebarShapeMultiplanarDefinition and the RebarShape method getMultiplanarDefinition() have been added to support 3D rebar shape definitions.
• Families of category "Structural Connection" support the Structural Material Type parameter. Structural Connection families of type Concrete or Precast Concrete are considered corbels. Corbels support the following features:
  • Hosting rebar.
  • Autojoining to columns and walls.
  • Manual joining to other concrete elements.
• Families of category "Generic Model" support the "Can Host Rebar" parameter. Turning on this yes/no parameter allows instances to host rebar. Instances also now support the "Volume" parameter. (Join behaviour does not change.)

The following RebarShape properties were replaced with get methods:

• Property int HookAngle[int] -> GetHookAngle(int)
• Property RebarHookOrientation HookOrientation[int] -> GetHookOrientation(int)
• Property bool SameShapeIgnoringHooks[RebarShape] -> IsSameShapeIgnoringHooks(RebarShape)

The ability to modify hook angle, hook orientation, and style has been removed.

• There is no SetHookAngle(int) method.
• There is no SetHookOrientation(int) method.
• The SetRebarStyle(RebarStyle) method has been removed.

The return type of RebarShape.GetCurvesForBrowser() was changed from CurveArray to IList<Curve>.

RebarHookType

The method

• Autodesk.Revit.Creation.Document.NewRebarHookType(double angle, double multiplier)

was replaced by

• RebarHookType.Create(int angleDegrees, double multiplier)

New members were added to the RebarHookType class are new (its properties were only available through the Parameters interface before).

RebarHostData class

The RebarHostData class has the following changes:

• Method getRebarHostData(Element) renamed to GetRebarHostData(Element).
• Property CoverType[Reference] replaced with GetCoverType(Reference) and SetCoverType(Reference, CoverType).
• Property Valid deprecated; use IsValidHost() instead.
• Method HasCoverTypeForReference(Reference) deprecated; use IsFaceExposed(Reference) instead.
• New methods pertaining to cover: GetExposedFaces(), GetCommonCoverType(), SetCommonCoverType(CoverType).
• Other new methods: GetRebarsInHost(), GetAreaReinforcementsInHost(), GetPathReinforcementsInHost().

Rebar class

The two methods Creation.Document.NewRebar() were replaced by:

• Rebar.CreateFromCurves()
• Rebar.CreateFromRebarShape()

The new methods are similar to the old ones, except that they no longer return null for invalid arguments, and they no longer regenerate the document.

The new class RebarBendData is to support functionality that is not part of Alpha 3.

MEP API small enhancements and changes

Spare and space circuits

The new property

• ElectricalSystem.CircuitType

identifies the type of an electrical circuit (circuit, spare or space).

The method ElectricalSystem.AddToCircuit now throws an exception when the system is a spare or space circuit.

Cable tray and conduit domain

The enum class

• Autodesk.Revit.DB.Domain

adds a new enum value to represent cable tray & conduit.

Connector

New read-only properties have been added:

• Connector.JointType
• Connector.GenderType
• Connector.EngagementLength

MEPSystem

The new property

• MEPSystem.IsEmpty

identifies if the system currently contains no components.

Graphical warnings for disconnects

The new properties:

• Application.ShowGraphicalWarningCableTrayConduitDisconnects
• Application.ShowGraphicalWarningDuctDisconnects
• Application.ShowGraphicalWarningElectricalDisconnects
• Application.ShowGraphicalWarningPipeDisconnects

and the matching setters control whether Revit MEP will highlight disconnects in systems graphically.

Space properties

The new property

• Space.BaseHeatLoadOn

indicates if the value of Space.LatentHeatGainperPerson and Space.SensibleHeatGainperPerson properties is the default value or if it is user-defined.

To accomodate this property, the namespace of enum BaseLoadOn has changed from Autodesk.Revit.DB.Electrical to Autodesk.Revit.DB.

Fitting methods

The following methods no longer remove unused or dangling curve connectors:

• Document.NewTeeFitting
• Document.NewCrossFitting
• Document.NewElbowFitting
• Document.NewUnionFitting
• Document.NewTransitionFitting
• Document.NewTakeoffFitting

Please use ConnectorManager.UnusedConnectors.Erase to remove unused connectors after creating a new fitting.

---

End of document

---

That was the news in the Revit 2012 API back in the year 2011.

Please be aware that some of the changes mentioned above have been updated yet again since.

Stay tuned for the next installment, coming soon, leading up towards the current day.

What's New in the Revit 2011 API

This is the second instalment of a series publishing the information provided in the 'What's New' sections of the past few Revit API releases help file RevitAPI.chm.

The first instalment covering What's New in the Revit 2010 API explains my motivation for this and provides an overview of the other releases.

We now move on to Revit 2011, looking at:

• Major renovations
• Major enhancements
• Small enhancements and changes

First, however, an update on my vacation so far.

Snowstorm in Italy

I am still on holiday in Italy, so please do not expect any immediate responses to any comments for a while.

    My first cappuccino in Domodossola was slightly disappointing.

    It improved later, though.

Searching for sun and warmth, we found cold and snow, and started heading southward to flee it.

Instead of getting better, it got worse, causing huge trees to crash down or lose their branches under loads of snow never previously experienced.

We did what we could to improve the situation.

The result is anti-art.

Still hoping for better weather further south...

Now, to continue the promised series of 'What's New' documentation from the past few Revit API releases.

Major renovations to the Revit 2011 API

Autodesk is using the 2011 Release to position the Revit API for significant future growth. In order to ensure that as the API grows, the interfaces created during this expansion can remain stable for a significant period of time, there are some quite significant up-front changes being made to the existing API.

Changes to the Revit API namespaces

The Revit API namespaces have been changed to be more consistent and more suitable to expansion. In previous releases, API classes were split along the lines of functionality and Revit vertical product, which led to confusion about where classes which were Elements or Symbols belonged if they were specific to one vertical. In the new namespace structure, there is a primary division into three sets of namespaces:

• Autodesk.Revit.ApplicationServices – contains classes accessing settings and options for the main Revit application
• Autodesk.Revit.DB – contains classes accessing data from the Revit file
• Autodesk.Revit.UI – contains classes accessing or customizing the Revit user interface

Within these main namespaces there are subdivisions based on discipline, e.g.:

• Autodesk.Revit.DB.Architecture
• Autodesk.Revit.DB.Structure
• Autodesk.Revit.DB.Mechanical
• Autodesk.Revit.DB.Electrical
• Autodesk.Revit.DB.Plumbing

Classes which are useful in more than one discipline are placed in the Autodesk.Revit.DB main namespace.

Less commonly used classes, like event arguments, are also placed in subordinate namespaces, e.g.:

• Autodesk.Revit.DB.Events
• Autodesk.Revit.UI.Events

As a result of the rearrangement of the namespaces, a few classes have been modified more drastically than simply being moved to new namespaces:

• Autodesk.Revit.Geometry.Element has been renamed to Autodesk.Revit.DB.GeometryElement to avoid a naming conflict.
• Autodesk.Revit.Geometry.Instance has been renamed to Autodesk.Revit.DB.GeometryInstance to avoid a naming conflict.
• Autodesk.Revit.Structural.Enums.Material has been renamed to Autodesk.Revit.DB.MaterialType to avoid a naming conflict.
• Autodesk.Revit.Options.Application has been removed. The properties accessible from this class have been moved into Autodesk.Revit.ApplicationServices.Application.

To obtain a full list mapping the changes from the Revit 2010 API, see the document Revit 2011 API Namespace Remapping.xlsx in the Software Development Kit install.

Split of Revit API DLL

The Revit API has been split into two DLLs. The new DLLs are:

• RevitAPI.dll – which now contains only methods used to access Revit's application, documents, elements, and parameters at the database level.
• RevitAPIUI.dll – which contains all API interfaces related to manipulation and customization of the Revit user interface, including:
  • IExternalCommand and External Command related interfaces
  • IExternalApplication and related interfaces
  • Selection
  • RibbonPanel, RibbonItem and subclasses
  • TaskDialogs

In order to facilitate access to application and document level interfaces from both DLLs, the Application and Document classes have also split into two:

• Autodesk.Revit.UI.UIApplication – provides access to UI-level interfaces for the application, including the ability to add RibbonPanels to the user interface, and the ability to obtain the active document in the user interface.
• Autodesk.Revit.ApplicationServices.Application – provides access to all other application level properties.
• Autodesk.Revit.UI.UIDocument – provides access to UI-level interfaces for the document, such as the contents of the selection and the ability to prompt the user to make selections and pick points
• Autodesk.Revit.DB.Document – provides access to all other document level properties

The ExternalCommandData interface now provides access to the UIApplication object as well as the active view. From the active UIApplication object you can obtain the active UI document. You can also construct the UIApplication from the Application object, and the UIDocument from the DB level document at any time.

New classes for XYZ, UV, and ElementId

New classes have been introduced for the basic XYZ, UV and ElementId classes used in the API. These classes are:

• Autodesk.Revit.DB.XYZ
• Autodesk.Revit.DB.UV
• Autodesk.Revit.DB.ElementId

These new classes provide a more consistent and complete interface, operate more quickly by having their implementation be entirely in managed code, and are immutable thus making them more suitable for use as properties. The following table summarizes the old and new methods for the XYZ and UV classes listing the old XYZ/UV member, the new member, and optional notes:

• AlmostEqual() – IsAlmostEqualTo()
• Angle() – AngleTo()
• AngleAround() – AngleOnPlaneTo()
• Cross() – CrossProduct()
• Distance() – DistanceTo()
• Dot() – DotProduct()
• Basis – N/A: Use BasisX, BasisY, BasisZ as required
• IsNormalized – IsUnitLength()
• IsZero – IsZeroLength()
• Item – Item: Property is now read-only
• Length – GetLength()
• Normalized – Normalize()
• X – X: Property is now read-only
• Y – Y: Property is now read-only
• Z – Z: Property is now read-only

All Revit API methods accepting or returning these types have been converted to the new classes.

In addition, the collections for these types have been removed.

Methods which used to take dedicated Revit collections now take equivalent .NET collection interfaces containing these types:

• Autodesk.Revit.ElementIdSet – ICollection<Autodesk.Revit.DB.ElementId>
• Autodesk.Revit.Geometry.XYZArray – IList<Autodesk.Revit.DB.XYZ>
• Autodesk.Revit.Geometry.UVArray – IList<Autodesk.Revit.DB.UV>

The major impact to existing code is the replacement of the collections, and the changes to the classes designed to make them immutable. Code which previously change the coordinates of an XYZ via setting XYZ.X, XYZ.Y, and/or XYZ.Z, now should construct a new XYZ with the desired coordinates.

One further impact is the fact that ElementId is now a class, instead of a struct, and should not be passed with "ref" in C# or "ByRef" in VB.NET.

Replacement for Symbol and properties that access types

The Symbol class has been renamed to ElementType.

The Element ObjectType and SimilarObjectTypes properties that access types from elements have been replaced:

• ObjectType – Element.GetTypeId(), Element.ChangeTypeId(): ChangeTypeId() returns the id of a new element; in rare cases, changing the element type will result in deletion of the current element. Static versions which operate on sets of elements are also supplied.
• Element.SimilarObjectTypes – Element.GetValidTypes()

New transaction interfaces

New interfaces have been added to the API related to Transactions. These interfaces will provide a more comprehensive set of options for managing changes being made to the Revit document.

At this time, the new transaction interfaces are not compatible with the automatically-opened transactions created around ExternalCommand callbacks and VSTA macros. So, Autodesk recommends that you not use these interfaces until compatible changes have been made to those frameworks. In order to experiment with the new interfaces, a document needs to be opened or created while in an external command. In the new document, either the old transaction interfaces or the new ones can be used, as long as they are not used together in the same document.

There are three main classes among the new interfaces plus a few supporting classes. The main classes represent three different (but related) transaction contexts.

Transaction – a context required in order to make any changes to a Revit model. Only one transaction can be open at a time; nesting is not allowed. Each transaction must have a name, which will be listed on the Undo menu in Revit once a transaction is successfully submitted.

SubTransaction – can be used to enclose a set of model modifying commands. Sub-transactions are optional. They are not required in order to modify the model. They are a convenience tool to allow logical splitting of larger tasks into smaller ones. Sub-transaction can only be created within an already opened transaction and must be closed (either committed or rolled back) before the transaction is closed (committed or rolled back). Unlike transactions, sub-transaction may be nested, but any nested sub-transaction must be closed before the enclosing sub-transaction is closed. Sub-transactions do not have name, for they do not appear on the Undo menu in Revit.

Transaction group – allows grouping together several independent transactions, which gives the owner of a group an opportunity to treat many transactions at once. When a transaction group is to be closed, it can be rolled back, which means that all already submitted transactions will be rolled back at once. If not rolled back, a group can be either submitted or assimilated. In the former case, all submitted transactions (within the group) will be left as they were. In the later case, transactions within the group will be merged together into one single transaction that will bear the group's name. A transaction group can only be started when there is no transaction open yet, and must be closed only after all enclosed transactions are closed (rolled back or committed). Transaction groups can be nested, but any nested group must be closed before the enclosing group is closed. Transaction groups are optional. They are not required in order to make modifications to a model.

All three transaction objects share some common methods:

• Start – Will start the context.
• Commit – Ends the context and commits all changes to the document.
• RollBack – Ends the context and discards all changes to the document.
• GetStatus – Returns the current status of a transaction object

Besides having the GetStatus returning the current status, both Commit and RollBack methods also return a status indicating whether or not the method was successful. Available status values include:

• Uninitialized – The initial value after object is instantiated; the context has not started yet
• Started – Set after a transaction object successfully started (Start method was called)
• Committed – Set after a transaction object successfully committed (Commit method was called)
• RolledBack – Set after a transaction object successfully rolled back (RollBack method was called)
• Pending – Set after transaction object was attempted to be either submitted or rolled back, but due to failures that process could not be finished yet and is waiting for the end-user's response (in a modeless dialog). Once the failure processing is finished, the status will be automatically updated (to either Committed or RolledBack status).

The new Transaction interfaces replace the old APIs:

• Document.BeginTransaction()
• Document.EndTransaction()
• Document.AbortTransaction()

which have been removed from the API.

Refactored Document properties related to transactions

Two existing properties have been re-implemented to better complement the changes in the transaction framework:

• Document.IsReadOny

Indicates that a document is – either temporarily or permanently – in read-only state. If it is read-only, it would mean that new transactions may not be started in that document, thus no modification could be made to the model.

• Document.IsModifiabe

Indicates whether a document is or is not currently modifiable. A document is not modifiable if either there is no transaction currently open or when some temporary state lock modification for a certain operation. Taken from another perspective, a transaction may be started only when document is not yet modifiable, but is also not read-only.

Transactions in events

All events have been changed to no longer automatically open transactions like they originally did in earlier releases. As a result of this new policy, the document will not be modified during an event unless one of the event’s handlers modifies it by making changes inside a transaction. A transaction may be opened by either the event handler if there is no transaction already opened (sometimes when the event is invoked, there is already a trasnaction open). If an event handler opens a transaction it is required that it will also close it (commit it or roll it back), otherwise all eventual changes will be discarded.

Please be aware that modifying the active document is not permitted during some events (e.g. the DocumentClosing event). If an event handler attempts to make modifications during such an event, an exception will be thrown. The event documentation indicates whether or not the event is read-only.

New ExternalCommand and ExternalApplication registration mechanism

The Revit API now offers the ability to register API applications via a .addin manifest file.

Manifest files will be read automatically by Revit when they are places in one of two locations on a user's system:

• In a non-user specific location in "application data"
  • For Windows XP – C:\Documents and Settings\All Users\Application Data\Autodesk\Revit\Addins\2011\
  • For Vista/Windows 7 – C:\ProgramData\Autodesk\Revit\Addins\2011\
• In a user specific location in "application data"
  • For Windows XP – C:\Documents and Settings\[user]\Application Data\Autodesk\Revit\Addins\2011\
  • For Vista/Windows 7 – C:\Users\[user]\AppData\Roaming\Autodesk\Revit\Addins\2011\

All files named .addin in these locations will be read and processed by Revit during startup.

A basic file adding one ExternalCommand looks like this:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
  <AddIn Type="Command">
    <Assembly>c:\MyProgram\MyProgram.dll</Assembly>
    <AddInId>76eb700a-2c85-4888-a78d-31429ecae9ed</AddInId>
    <FullClassName>Revit.Samples.SampleCommand</FullClassName>
    <Text>Sample command</Text>
    <VisibilityMode>NotVisibleInFamily</VisibilityMode>
    <VisibilityMode>NotVisibleInMEP</VisibilityMode>
    <AvailabilityClassName>Revit.Samples.SampleAccessibilityCheck</AvailabilityClassName>
    <LongDescription>
      <p>This is the long description for my command.</p>
      </p/>
      <p>This is another descriptive paragraph, with notes about how to use the command properly.</p>
    </LongDescription>
    <TooltipImage>c:\MyProgram\Autodesk.jpg</TooltipImage>
    <LargeImage>c:\MyProgram\MyProgramIcon.png</LargeImage>
  </AddIn>
</RevitAddIns>

A basic file adding one ExternalApplication looks like this:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
  <AddIn Type="Application">
    <Name>SampleApplication</Name>
    <Assembly>c:\MyProgram\MyProgram.dll</Assembly>
    <AddInId>604B1052-F742-4951-8576-C261D1993107</AddInId>
    <FullClassName>Revit.Samples.SampleApplication</FullClassName>
  </AddIn>
</RevitAddIns>

Multiple AddIn elements may be provided in a single manifest file.

The new mechanism currently offers the following XML tags:

• Assembly – The full path to the add-in assembly file. Required for all ExternalCommands and ExternalApplications.
• FullClassName – The full name of the class in the assembly file which implements IExternalCommand or IExternalApplication. Required for all ExternalCommands and ExternalApplications.
• ClientId – A GUID which represents the id of this particular application. ClientIds must be unique for a given session of Revit. Autodesk recommends you generate a unique GUID for each registered application or command. Required for all ExternalCommands and ExternalApplications. The property UIApplication.ActiveAddInId provides programmatic access to this value, if required.
• Name – The name of application. Required; for ExternalApplications only.
• Text – The name of the button. Optional; use this tag for ExternalCommands only. The default is "External Tool".
• Description – Short description of the command, will be used as the button tooltip. Optional; use this tag for ExternalCommands only. The default is a tooltip with just the command text.
• VisibilityMode – Provides the ability to specify if the command is visible in project documents, family documents, or no document at all. Also provides the ability to specify the discipline(s) where the command should be visible. Multiple values may be set for this option. Optional; use this tag for ExternalCommands only. The default is to display the command in all modes and disciplines, including when there is no active document. Previously written external commands which need to run against the active document should either be modified to ensure that the code deals with invocation of the command when there is no active document, or apply the NotVisibleWhenNoActiveDocument mode.
• AvailabilityClassName – The full name of the class in the assembly file which implemented IExternalCommandAvailability. This class allows the command button to be selectively grayed out depending on context. Optional; use this tag for ExternalCommands only. The default is a command that is available whenever it is visible.
• LargeImage – The path to the icon to use for the button in the External Tools pulldown menu. The icon should be 32 x 32 pixels for best results. Optional; use this tag for ExternalCommands only. The default is to show a button without an icon.
• LongDescription – Long description of the command, will be used as part of the button's extended tooltip. This tooltip is shown when the mouse hovers over the command for a long amount of time. You can split the text of this option into multiple paragraphs by placing <p> tags around each paragraph. Optional; use this tag for ExternalCommands only. If neither of this property and TooltipImage are supplied, the button will not have an extended tooltip.
• TooltipImage – The path to an image file to show as a part of the button extended tooltip, shown when the mouse hovers over the command for a longer amount of time. Optional; use this tag for ExternalCommands only. If neither of this property and TooltipImage are supplied, the button will not have an extended tooltip.
• LanguageType – Localization setting for Text, Description, LargeImage, LongDescription, and TooltipImage of external tools buttons. Revit will load the resource values from the specified language resource dll. The value can be one of the eleven languages supported by Revit. If no LanguageType is specified, the language resource which the current session of Revit is using will be automatically loaded. For more details see the section on Localization.

The Revit.ini registration mechanism remains in place for the 2011 release but will be removed in the future. The Revit.ini mechanism does not offer any of the new capabilities listed above. In addition, because Dynamic Model Update registration requires a valid AddInId, updaters may not be registered from applications declared in Revit.ini.

Localization

You can let Revit localize the user-visible resources of an external command button (including Text, large icon image, long and short descriptions and tooltip image). You will need to create a .NET Satellite DLL which contains the strings, images, and icons for the button. Then change the values of the tags in the .addin file to correspond to the names of resources in the Satellite dll, but prepended with the 'at' character '@'. So the tag:

 <Text>Extension Manager</Text>

Becomes

  <Text>@ExtensionText</Text>

where ExtensionText is the name of the resource found in the Satellite DLL.

The Satellite DLLs are expected to be in a directory with the name of the language of the language-culture, such as en or en-US. The directory should be located in the directory that contains the add-in assembly. Please refer to how to create managed Satellite DLLs.

You can force Revit to use a particular language resource DLL, regardless of the language of the Revit session, by specifying the language and culture explicitly with a LanguageType tag. For example:

  <LanguageType>English_USA</LanguageType>

would force Revit to always load the values from the en-US Satellite DLL and to ignore the current Revit language and culture settings when considering the localizable members of the external command manifest file.

Revit supports the 11 languages defined in the Autodesk.Revit.ApplicationServices.LanguageType enumerated type: English_USA, German, Spanish, French, Italian, Dutch, Chinese_Simplified, Chinese_Traditional, Japanese, Korean, and Russian.

External Command Accessibility

The interface

• IExternalCommandAvailability

allows you control over whether or not an external command button may be pressed. The IsCommandAvailable interface method passes the application and a set of categories matching the categories of selected items in Revit to your implementation. The typical use would be to check the selected categories to see if they meet the criteria for your command to be run.

In this example accessibility check allows a button to be clicked when there is no active selection, or when at least one wall is selected:

public class SampleAccessibilityCheck : IExternalCommandAvailability
{
  public bool IsCommandAvailable(
    Autodesk.Revit.ApplicationServices.Application data,
    CategorySet selectedCategories )
  {
    // Allow button click if there is no active selection
    if( selectedCategories.IsEmpty )
      return true;
 
    // Allow button click if there is at least one wall selected
    foreach( Category c in selectedCategories )
    {
      if( c.Id.IntegerValue == (int)BuiltInCategory.OST_Walls )
        return true;
    }
    return false;
  }
}

External Command and External Application registration utility

The .NET utility DLL RevitAddInUtility.dll offers a dedicated API capable of reading, writing and modifying Revit Add-In manifest files. It is intended for use from product installers and scripts. Consult the API documentation in the RevitAddInUtility.chm help file in the SDK installation folder.

Here are some code snippets showing use of the RevitAddInUtility API.

First, creating a new .addin manifest file which contains one external command and one external application:

  //create a new addin manifest
  RevitAddInManifest Manifest = new RevitAddInManifest();
  //create an external command
  RevitAddInCommand command1 = new RevitAddInCommand(
    "full path\\assemblyName.dll", Guid.NewGuid(),
    "namespace.className" );
  command1.Description = "description";
  command1.Text = "display text";
  //this command only visible in Revit MEP, Structure, 
  // and only visible in Project document or when no 
  // document at all
  command1.VisibilityMode = VisibilityMode.NotVisibleInArchitecture
    | VisibilityMode.NotVisibleInFamily;
  //create an external application
  RevitAddInApplication application1
    = new RevitAddInApplication( "appName",
      "full path\\assemblyName.dll",
      Guid.NewGuid(), "namespace.className" );
  //add both command(s) and application(s) into manifest
  Manifest.AddInCommands.Add( command1 );
  Manifest.AddInApplications.Add( application1 );
  //save manifest to a file
  RevitProduct revitProduct1 = RevitProductUtility
    .GetAllInstalledRevitProducts()[0];
  Manifest.SaveAs( revitProduct1.AllUsersAddInFolder
    + "\\RevitAddInUtilitySample.addin" );

Second, reading from an existing addin file:

  RevitProduct revitProduct1 = RevitProductUtility
    .GetAllInstalledRevitProducts()[0];
 
  RevitAddInManifest revitAddInManifest
    = Autodesk.RevitAddIns.AddInManifestUtility
      .GetRevitAddInManifest(
        revitProduct1.AllUsersAddInFolder
          + "\\RevitAddInUtilitySample.addin" );

Attributes for configuring ExternalCommand and ExternalApplication behavior

Transaction mode

The custom attribute Autodesk.Revit.Attributes.TransactionMode should be applied to your implementation class of the IExternalCommand interface to control transaction behavior for external command. There is no default for this option. You must apply it to legacy application classes to allow your application to function in Revit 2011.

This mode controls how the API framework expects transactions to be used when the command is invoked. There are three supported values:

1. TransactionMode.Automatic – The API framework will create a transaction on the active document before the external command is executed and the transaction will be committed or rolled back after the command is completed (based upon the return value of the ExternalCommand callback). This means that command code cannot create and start its own Transactions, but it can create SubTransactions as required during the implementation of the command. The command must report its success or failure status via the Result return value.
2. TransactionMode.Manual – The API framework will not create a transaction (but it will create an outer group to roll back all changes if the external command returns a failure status). Instead, you may use combinations of Transactions, SubTransactions, and TransactionGroups as you please. You will have to follow all rules regarding use of transactions and related classes. You will have to give your transaction(s) names, which will then appear in the Undo menu. Revit will check that all transactions (also groups and sub-transactions) are properly closed upon return from an external command. If not, it will discard all changes made to the model.
3. TransactionMode.ReadOnly – No transaction (nor group) will be created, and no transaction may be created for the lifetime of the command. The External command may use methods that only read from the model, but not methods that write anything to it. Exceptions will be thrown if the command either tries to start a transaction (or group) or attempts to write to the model.

In all three modes, the TransactionMode applies only to the active document. You may open other documents during the course of the command, and you may have complete control over the creation and use of Transactions, SubTransactions, and TransactionGroups on those other documents (even in ReadOnly mode).

For example, to set an external command to use automatic transaction mode:

  [Regeneration( RegenerationOption.Manual )]
  [Transaction( TransactionMode.Automatic )]
  public class Command : IExternalCommand
  {
    public Autodesk.Revit.IExternalCommand.Result
      Execute(
        Autodesk.Revit.ExternalCommandData commandData,
        ref string message,
        Autodesk.Revit.ElementSet elements )
    {
      // Command implementation, which modifies the 
      // active document directly and no need to
      // start/commit any transactions.
    }
  }

Regeneration option

The custom attribute Autodesk.Revit.Attributes.RegenerationAttribute should be applied to your implementation class of the IExternalCommand interface and IExternalApplication interface to control the regeneration behavior for the external command and external application. There is no default for this option. You must apply it to legacy application classes to allow your application to function in Revit 2011.

This mode controls whether or not the API framework automatically regenerates after every model modification. There are two supported values:

1. RegenerationOption.Automatic – The API framework will regenerate after every model level change (equivalent behavior with Revit 2010 and earlier). Regeneration and update can be suspended using SuspendUpdating for some operations, but in general the performance of multiple modifications within the same file will be slower than RegenerationOption.Manual. This mode is provided for behavioral equivalence with Revit 2010 and earlier; it is obsolete and will be removed in a future release.
2. RegenerationOption.Manual – The API framework will not regenerate after every model level change. Instead, you may use the regeneration APIs to force update of the document after a group of changes. SuspendUpdating blocks are unnecessary and should not be used. Performance of multiple modifications of the Revit document should be faster than RegenerationOption.Automatic. Because this mode suspends all updates to the document, your application should not read data from the document after it has been modified until the document has been regenerated, or it runs the risk of accessing stale data. This mode will be only option in a future release.

For example, to set an external command to use manual regeneration mode:

  [Regeneration( RegenerationOption.Manual )]
  [Transaction( TransactionMode.Automatic )]
  public class Command : IExternalCommand
  {
    public Autodesk.Revit.IExternalCommand.Result
      Execute(
        Autodesk.Revit.ExternalCommandData commandData,
        ref string message,
        Autodesk.Revit.ElementSet elements )
    {
      // Command implementation, which modifies the 
      // document and calls regeneration APIs when
      // needed.
    }
  }

To set an external application to use automatic mode

  [Regeneration( RegenerationOption.Automatic )]
  public class Application : IExternalApplication
  {
    public Autodesk.Revit.UI.Result OnStartup(
      ControlledApplication a )
    {
      // OnStartup implementation
    }
    public Autodesk.Revit.UI.Result OnShutdown(
      ControlledApplication a )
    {
      // OnShutdown implementation
    }
  }

The regeneration mode used for code executed during events and updater callbacks will be the same mode applied to the ExternalApplication or ExternalCommand during which the event or updater was registered.

Manual regeneration and update

• Document.Regenerate
• Document.AutoJoinElements

These new methods have been added to allow an application running in manual regeneration mode to update the elements in the Revit document at any time.

Journaling mode

The custom attribute Autodesk.Revit.Attributes.JournalingAttribute can optionally be applied to your implementation class of the IExternalCommand interface to control the journaling behavior during the external command execution session.

• JournalMode.UsingCommandData

Uses the “StringStringMap” supplied in the command data. Hides all Revit journal entries in between the external command invocation and the StringStringMap entry. Commands which invoke the Revit UI for selection or for responses to task dialogs may not replay correctly.

• JournalMode.NoCommandData

Does not write contents of the ExternalCommandData.Data map to the Revit journal. But does allow Revit API calls to write to the journal as needed. This option should allow commands which invoke the Revit UI for selection or for responses to task dialogs to replay correctly.

New element iteration interfaces

New interfaces have been added to the API to permit iteration of elements and element ids. These new interfaces have been designed to provide a more flexible and usable interface for a variety of applications, while being completely implemented in native Revit code to provide the best possible performance.

Existing element iteration routines have been replaced, including:

• Document.Elements (all versions of this property)
• ElementIterator
• Filter and all subclasses of it
• Application.Create.Filter
• Classes and properties related to the ParameterFilter:
  • CriteriaFilterType
  • Document.FilterTypeSupported
  • FilterCriterion
  • ParameterStorage

The new element iteration interfaces offer several enhanced capabilities from their predecessors:

• The ability to iterate and filter elements from a document, or only elements from an arbitrary list of element ids, or elements visible in a view (replacing View.Elements)
• The ability to clearly identify filters which are designed for best performance ("Quick Filters"), which do not expand the element in memory when evaluating whether the element passes the filter
• The ability to use chained shortcuts which automatically apply commonly used filters, e.g.

  FilteredElementCollector collector
    = new FilteredElementCollector( document );
 
  // Finds all walls in a certain design option
 
  ICollection<ElementId> walls = collector
    .OfClass( typeof( Wall ) )
    .ContainedInDesignOption( myDesignOptionId )
    .ToElementIds();

• The ability to logically group more than two filters.
• The ability to match derived types automatically when using the type filter and type filter shortcut.
• The ability to iterate elements from all design options or from any specific design option.
• The ability to use foreach on the collector element, and to use the class with LINQ queries. This is due to the connection between the collector class and System.Collections.Generic.IEnumerable. Note that because the ElementFilters and the shortcut methods offered by this class process elements in native code before their managed wrappers are generated, better performance will be obtained by using as many native filters as possible on the collector before attempting to process the results using LINQ queries.

  FilteredElementCollector collector
    = new FilteredElementCollector( doc );
 
  // First apply a built-in filter to minimize
  // the number of elements processed by LINQ
 
  collector.WherePasses( new ElementCategoryFilter(
    BuiltInCategory.OST_Levels ) );
 
  // LINQ query to find level with name == "Level 1"
 
  var levelElements = from element in collector
                      where element.Name == "Level 1"
                      select element; 
 
  Level level1 = levelElements.Cast<Level>()
    .ElementAt<Level>( 0 );

Detailed information on the new element iteration interfaces can be found in the document "Element iteration APIs" in the SDK.

Note that there are a few behavioral changes in the new iteration mechanism when compared to the old:

• View templates were previously returned as Element. They are now returned as the correct View subclass (ViewPlan, View3d, etc). You can identify these using the new View.IsTemplate property.
• Previous element iteration methods only returned elements of the main model, the active design option, and primary design options of each option set. Elements of design options which were not active and not primary were excluded. In the new iteration API, by default, design option membership is no longer considered when iterating elements. In order to find the same elements which were iterated in the 2010 API, you should use the following filters combined using 'OR':
  • An ElementDesignOptionFilter with id = InvalidElementId, to match all elements not associated to a design option.
  • An ElementDesignOptionFilter with id = DesignOption.GetActiveDesignOptionId(), to match elements in the active design option.
  • A PrimaryDesignOptionMemberFilter, to match all elements in primary design options.

Replacement for View.Elements

The property View.Elements has been removed and replaced with a constructor for FilteredElementCollector taking a document and view id. This allows you to use filtering and LINQ queries against the elements visible in a given view.

Replacement for 3 structural enums

The enumerated types

• Autodesk.Revit.Structural.Enums.InstanceUsage
• Autodesk.Revit.Structural.Enums.Material
• Autodesk.Revit.Structural.Enums.WallUsage

have been replaced with new enums:

• Autodesk.Revit.DB.Structure.StructuralInstanceUsage
• Autodesk.Revit.DB.Structure.StructuralMaterialType
• Autodesk.Revit.DB.Structure.StructuralWallUsage

Some of the names of the members have changed.

Replacement for AnalyticalModel

The class hierarchy for accessing the structural analytical model has been replaced. The new class hierarchy offers a more streamlined interface and more capabilities to read data and modify analytical model settings.

The following AnalyticalModel subclasses have been removed:

• AnalyticalModel3D
• AnalyticalModelFloor
• AnalyticalModelFrame
• AnalyticalModelLocation
• AnalyticalModelWall

Access the data you used to find on those subclasses on the base AnalyticalModel class, as indicated by the following list of classes, old properties, and new methods:

• AnalyticalModelFrame – Curve – GetCurves(): If analytical model was approximated, .Curve would have previously returned non-approximated analytical model. Now GetCurves() will return approximated analytical model when analytical model is approximated. GetCurve() is a shortcut method returning the single curve.
• AnalyticalModel3D, AnalyticalModelFloor, AnalyticalModelFrame, AnalyticalModelLocation, AnalyticalModelWall – Curves – GetCurves(): AnalyticalCurveType.ActiveCurves will return the analytical model displayed by Revit. Most of the time, this is what is desired.
• AnalyticalModelLocation – Point – GetPoint(): GetCurves() can also be called, the return will be a single curve of almost 0-length containing the point.
• AnalyticalModelFrame – Profile – GetSweptProfile()
• AnalyticalModelFrame – RigidLink – GetCurves(AnalyticalCurveType.RigidLinkHead) or GetCurves(AnalyticalCurveType.RigidLinkTail): AnalyticalCurveType.RigidLinkHead retrieves the Rigid Link at the end, and AnalyticalCurveType.RigidLinkTail retrieves the Rigid Link at the start.
• AnalyticalModel3D, AnalyticalModelFloor,: AnalyticalModelFrame, AnalyticalModelLocation, AnalyticalModelWall – SupportData – GetAnalyticalModelSupports()

Note that the curves returned from these new methods will not have their Reference properties set, and cannot be used for the properties like Curve.EndPointReference. Instead, you can obtain References to the curves and their endpoints through construction of an AnalyticalModelSelector object containing the necessary information.

The AnalyticalModel class offers new methods to access other Analytical Model properties, such as:

• Adjustment information, both manual and automatic
• Parameter information, including projection, hard points, approximation, and rigid links
• Analytical offset

The AnalyticalModelProfile class has been replaced by the AnalyticalModelSweptProfile class, which offers similar contents to the original class.

The AnalyticalSupportData and AnalyticalSupportInfo classes have been replaced by collections of AnalyticalModelSupport objects. This new class offers the same information offered by AnalyticalSupportInfo, plus:

• The support priority
• The curve, point, and face providing support

The new AnalyticalSupportChecking interface offers the ability to run the check for unsupported structural elements. The new AnalyticalConsistencyChecking interface offers the ability to run a consistency check for the Analytical Model.

The results of both checks are added to the document as warnings.

Access the AnalyticalModel through the method GetAnalyticalModel() on Element. This replaces the AnalyticalModel property of Wall, Floor, ContFooting and FamilyInstance.

The integer values of the enumerated type AnalyticalSupportType have changed. They no longer match the values returned for the built-in parameter BOUNDARY_CONDITIONS_TYPE, use the members of the enum BoundaryConditionsType instead.

Replacement for gbXMLParamElem

The new class EnergyDataSettings replaces the gbXMLParamElem class. The members of the old class, the gbXMLParamElem properties, can be accessed via the new EnergyDataSettings properties as follows:

• BuildingConstruction – ConstructionSetElementId
• BuildingService – ServiceType
• BuildingType – BuildingType
• ExportComplexity – ExportComplexity
• GroundPlane – GroundPlane
• PostalCode – This is not supported in the new interface as the property has been removed from the element stored within Revit. It was removed because the data often conflicted with other settings provided during gbXML export.
• ProjectLocation – This data is not supplied; it was always the same as Document.ActiveProjectLocation.
• ProjectPhase – ProjectPhase

Revit exceptions

All Revit API methods have been changed to throw subclasses of Autodesk.Revit.Exceptions.ApplicationException. Some Revit exceptions, such as

• ArgumentException
• InvalidOperationException
• FileNotFoundException

closely mirror the corresponding .NET System exception types. However, some of them have subclasses which are unique to Revit, e.g.

• AutoJoinFailedException
• RegenerationFailedException
• ModificationOutsideTransactionException

In addition, there is a special exception type called InternalException, which represents a failure path which was not anticipated. Exceptions of this type carry extra diagnostic information which can be passed back to Autodesk for diagnosis.

Removed deprecated events

The pre-Revit 2010 events:

• Application.OnDocumentSaved
• Application.OnDocumentSavedAs
• Application.OnDocumentOpened
• Application.OnDocumentClosed
• Application.OnDocumentNewed
• Application.OnDialogBox
• Document.OnSaveAs
• Document.OnSave
• Document.OnClose

have been removed from the API. To replace these, use the replacement events in both Revit External Applications and VSTA macros.

Changes to VSTA

There are many changes to the VSTA framework:

1. Revit VSTA no longer depends on the proxy DLL. Macros are now written referencing RevitAPI.dll and RevitAPIUI.dll directly. This allows macros access to the full features of the Revit API, including generic methods, all events and other methods missing from the proxy previously. Module templates have been updated accordingly, and the references will be added automatically when upgrading macros from previous releases.
2. The entry point classes ThisApplication and ThisDocument have been adjusted to the direct reference of the API classes. They also now represent UIApplication and UIDocument (instead of Application and Document).
3. The Transaction and Regeneration attributes must be applied to the ThisApplication and ThisDocument class. Their meanings for VSTA are same as for external commands. Module templates have been updated with default assignments, but upgraded modules must have these added manually.
   • A special AddInId attribute can be added to modules. This allows VSTA macros to work with updaters. When new modules are created this attribute is automatically generated with a random Guid.
   • The Module_Startup methods are now executed at the time when the module is first loaded (as the Revit application starts for Application-level macros, and as the document is loaded for document-level macros).
4. No transactions may be opended in the Module_Startup and Module_Shutdown methods.

New modules created in Revit 2011 should be "ready to code" – all framework changes have been incorporated into the templates.

Upgraded macros and modules will need to be adjusted to the framework changes mentioned above, as well as all of the API changes (namespace changes, modified APIs).

Major enhancements to the Revit API

Dynamic Model Update

Dynamic model update offers the ability for a Revit API application to modify the Revit model as a reaction to changes happening in the model. This facility is offered through implementation of updaters. The updater interface offers the ability to implement a method that is informed of the scope of changes that triggered the update.

In order to "subscribe" an updater to the right set of changes, the updater should be assigned one or more update triggers. Update triggers are combinations of "Change Scope" and "Change Type". Change Scope may be either an explicit list of element ids in a document, or an implicit list of elements communicated via an ElementFilter. Change Type represents one of an available list of possible changes, including element addition, deletion, and modification of geometry, parameters, or any property of the element.

For a more detailed introduction to the Dynamic Model Update capabilities, consult the "Introduction to Dynamic Model Update" document in the SDK.

Elements changed event

The new event

• Application.DocumentChanged

is raised after every transaction gets committed, undone, or redone. This is a read-only event, designed to allow you to keep external data in synch with the state of the Revit database. To update the Revit database in response to changes in elements, use the Dynamic Model Update framework.

Failure API

There are two capabilities offered by the new failure API:

1. The ability to define and post failures from within API code when a user-visible problem has occurred.
2. The ability to respond to failures posted by Revit and by API code through code in your application.

This section offers a high level overview of both capabilities; more detail about the failures API is provided in the "Failure API" document in the Revit API help file.

As a part of exposing these new capabilities, all overloads accepting "PostedErrors" have been removed from the API.

Failure posting

If you are using the failure posting mechanism to report your problem, all you need to do is:

1. If you are creating a new failure not already existing in Revit, define the new failure and register it in the FailureDefinitionRegistry during the OnStartup() call of your ExternalApplication (new failures must be registered at Revit startup).
2. Find the failure definition id, either from the BuiltInFailures classes or from your pre-registered custom failure using the class related to FailureDefinition.
3. Post a failure to a document that has a problem – using the classes related to FailureMessage to set options and details related to the failure.

Failure handling

Normally posted failures are processed by Revit's standard failure resolution UI at the end of transaction. The user is presented information and options in the UI to deal with the failures.

However, if your operation (or set of operations) on the document requires some special treatment for certain errors (or even all possible errors), you can customize failure resolution. Custom failure resolution can be supplied:

• For a given transaction using the interface IFailuresPreprocessor.
• For all possible errors using the FailuresProcessing event.

Finally, the API offers the ability to completely replace the standard failure processing user interface using the interface IFailuresProcessor.

Select element(s), point(s) on element(s), face(s) or edge(s)

• Selection.PickObject
• Selection.PickObjects

New methods have been added to prompt the user to select items from the Revit model. When using the new selection methods from your application you can:

• Allow users to make one or multiple selections
• Allow users to make multiple selections via box select
• Provide a custom status prompt to direct the user what to select
• Provide a custom selection filter (Autodesk.Revit.UI.ISelectionFilter) to accept only those items which your application supports
• Provide a list of preselected items which will be selected and highlighted when the selection activity starts
• Reference(Element) – This new constructor allows you to obtain a Reference for an Element; it can be useful when adding preselected elements to the PickObjects() call.

Pick point on the view active workplane

• Selection.PickPoint()

New methods have been added to prompt the user to pick a point on the view active workplane. When using these methods you have the option of overriding the user's default snap settings and providing a custom status prompt to direct the user what to pick. The method returns an XYZ location corresponding to the user's pick.

For 2D and 3D views, you can set the active workplane via the new setter property for View.SketchPlane. This allows you to control the plane used for calls to the PickPoint() method.

For 2D views where the active workplane cannot be changed, such as drafting and sheet views, the method picks a point in the default coordinate system of the view.

Additional options for Ribbon customization

There are new Ribbon components supported via the Ribbon API:

• SplitButton – a pulldown button with a default pushbutton attached
• RadioGroup – a set of ToggleButtons, where only one of the set can be active at a time
• ComboBox – a pulldown containing a set of selectable items, which can be grouped optionally
• TextBox – an input field for users to enter text
• SlideOut panel – an extra panel can optionally slide down from a Ribbon panel; this panel can contain any of the standard Ribbon components

For ComboBox and TextBox, events are included; these events call your API code when the component is changed by the user.

The new property:

• RibbonItem.Visible

provides control over whether a particular item is visible.

The new properties:

• RibbonItem.LongDescription
• RibbonItem.ToolTipImage

allow you to set up an extended tooltip for the Ribbon item. This tooltip can display a longer set of text, and/or a single image.

The new property:

• PushButton.AvailabilityClassName

allows assignment of an availability class to controlled whether or not the button is available, similar to the option provided for ExternalCommands registered by manifest.

There is also a new option supported for PulldownButton – a separator can now be added between buttons this component.

There is also a new option to add custom panels to the Analyze tab in Revit as well as the Add-Ins tab, via a new overload of Application.CreateRibbonPanel().

As a result of these enhancements, some pre-existing APIs have changed:

• RibbonPanel.AddButton() has been replaced with RibbonPanel.AddItem()
• RibbonPanel.AddStackedButtons() overloads have been replaced with RibbonPanel.AddStackedItems() overloads
• Property RibbonPanel.Items has been replaced with method RibbonPanel.GetItems()
• Property PulldownButton.Items has been replaced with method PulldownButton.GetItems()
• Methods RibbonPanel.AddPushButton() and RibbonPanel.AddPulldownButton() have been removed. Use RibbonPanel.AddItem() for this operation.
• RibbonPanel.AddToPulldown() has been removed. Use PulldownButton.AddItem() for this operation.
• PulldownButton.AddPushButton() has been removed. Use PulldownButton.AddItem() for this operation.

Create and display Revit-style Task Dialogs

The API now offers the ability to create and display Revit-style Task Dialogs. It is intended to provide capabilities similar to System.Windows.Forms.MessageBox with a Revit look-and-feel such as:

Construct an instance of the class:

• Autodesk.Revit.UI.TaskDialog

and use the members of that class to set the instructions, detailed text, icons, buttons and command links to be displayed in the task dialog. Then display the dialog using the Show() method. After the user responds to the dialog by clicking one of the buttons or links, the Show() method returns an identifier indicating the user's preferred choice.

There are also shortcut static Show() methods on this class providing a quick way to show simple task dialogs.

Idling event

The new event

• UIApplication.Idling

is raised when it is safe for the API application to access the active document between user interactions. The event is raised only when the Revit UI is in a state where the user could successfully click on an API command button. The event allows changes to a document if a new transaction is opened.

Because this event is invoked between user actions in the Revit UI, if the handler for this event requires a significant amount of processing time, users will perceive a slowdown in the responsiveness of Revit. If the execution for updates can be safely split across multiple calls to this event, the user perception of Revit responsiveness will be improved.

Sun and shadows settings element

The SunAndShadowSettings class represents the settings applied to a project or view regarding the position, dates, time intervals and other options for the sun control and solar studies. Obtain the SunAndShadowSettings for a particular view from the View.SunAndShadowSettings property. Obtain the SunAndShadowSettings for the project from SunAndShadowSettings.GetActiveSunAndShadowSettingsId().

MEP Electrical API

Demand factor and load classifications

The property

• ElectricalSystem.LoadClassification

has been replaced with a new property

• ElectricalSystem.LoadClassifications

The new property returns a semicolon-delimited string listing the load classifications assigned to the system. Load classifications are now an element and can be found through regular element iteration.

The class

• DemandFactor

was replaced by

• ElectricalDemandFactorDefinition.

The method

• ElectricalSetting.GetDemandFactor()

has been replaced by

• ElectricalLoadClassification.DemandFactorId

which returns the id of the ElectricalDemandFactorDefinition element assigned to the load classification.

Panel schedules

A new comprehensive API has been introduced to support access to Panel Schedules and their contents. The major classes exposed by this API are:

• TableView – represents a view that shows a table.
• TableData – holds most of the data that describe the style of the rows, columns, and cells in a table.
• TableSectionData – holds row, column and cell data for a TableData instance.
• PanelScheduleView – represents a view that shows a panel schedule.
• PanelScheduleData – holds most of the data that describe the layout, appearance, and style of the rows, columns, and cells of a panel schedule.
• PanelScheduleTemplate – represents a branch panel, a switchboard or a data panel template.
• PanelScheduleSheetInstance – represents an instance of a panel schedule placed on sheet.

Cable tray and conduit

New classes and elements have been added to the API related to Cable Tray and Conduit elements. The major classes introduced by this API are:

• CableTrayConduitBase – the base class for cable trays and conduits.
• CableTrayConduitRunBase – the base class for cable tray and conduit runs.
• CableTray – a cable tray instance.
• CableTrayType – a cable tray type.
• CableTrayRun – a cable tray run.
• Conduit – a conduit instance.
• ConduitType – a conduit type.
• ConduitRun – a conduit run.

The previously existing API classes

• ConduitType
• ConduitTypeSet

have been renamed to

• WireConduitType
• WireConduitTypeSet

as a result of the introduction of the new conduit elements.

Analysis Visualization Framework

This new functionality creates a mechanism for external analysis applications to easily display the results of their computation as 3D data in the Revit model. Note that the results data is transient; it is stored only in the model for the duration of the current Revit session.

The SpatialFieldManager class is used to create, delete, and modify the "containers" in which the analysis results are stored.

The FieldDomainPoints sub-classes indicate the points where analysis results are computed.

The FieldValues class contains the values for each domain point. Each domain point can have multiple values, each for a separate "measurement" at this point. For example, if a solar calculation is being done for every day of the year, each point would have 365 corresponding values.

The code below assigns results for two data points on a surface:

  SpatialFieldManager sfm = SpatialFieldManager
    .CreateSpatialFieldManager( view, 1 );
 
  Reference reference = doc.Selection.PickObject(
    ObjectType.Face, "Select a face" );
 
  int idx = sfm.AddSpatialFieldPrimitive( reference );
 
  Face face = reference.GeometryObject as Face;
 
  IList<UV> uvPts = new List<UV>();
  uvPts.Add( new UV( 0, 0 ) );
  uvPts.Add( new UV( 0.1, 0.1 ) );
  FieldDomainPointsByUV pnts = new FieldDomainPointsByUV(
    uvPts );
 
  List<double> doubleList = new List<double>();
  IList<ValueAtPoint> valList = new List<ValueAtPoint>();
  doubleList.Add( 0 );
  valList.Add( new ValueAtPoint( doubleList ) );
  doubleList.Clear();
  doubleList.Add( 10 );
  valList.Add( new ValueAtPoint( doubleList ) );
  FieldValues vals = new FieldValues( valList );
 
  sfm.UpdateSpatialFieldPrimitive( idx, pnts, vals );

Small enhancements & API interface changes

Family & massing API enhancements

Rehost a form

The overloaded methods

• Form.Rehost()

rehost a form to a new edge, face, curve, or sketch plane.

Obtain the location of point placement references from a family

The methods

• FamilySymbol.GetFamilyPointPlacementReferences()
• FamilyInstance.GetFamilyPointPlacementReferences()

provide information about the location and geometry of point placement references in the loaded family symbol or placed family instance. These points are found in Panel families and flexible components.

Associate array dimension to label in families

The property

• BaseArray.Label

associates the number of members of the array with a family parameter.

A BaseArray only can be labelled in a family document and only can be labelled to an integer FamilyParameter. The property can also unbind a labelled family parameter.

Dissociate label from dimension in families

The property

• Dimension.Label

can be set to null to dissociate a dimension from a label parameter.

Rename and replace a family parameter

The method

• FamilyManager.RenameParameter()

allows you to rename a Family parameter.

The overloaded methods

• FamilyManager.ReplaceParameter()

allow you to replace a Family parameter with a new shared parameter, or a shared parameter with a new Family parameter.

Reporting parameters

The property

• FamilyParameter.IsReporting

identifies if the parameter is a reporting parameter. If true, the parameter is associated to a dimension value and cannot be modified. If false, the parameter is a driving parameter and if associated to a dimension, can modify the dimension it labels.

The methods

• FamilyManager.MakeReporting()
• FamilyManager.MakeNonReporting()

change a family parameter to be reporting or non-reporting.

Place 2D family types on views

A new overload

• ItemFactoryBase.NewFamilyInstance(XYZ, FamilySymbol, View)

has been added to support placement of 2D families in target views. This can be used for placement of detail components, annotation symbols, and titleblocks into their target views.

Prompt user to interactively place a family type

The method

• UIDocument.PromptForFamilyInstancePlacement()

prompts the user to place one or more instances of a particular FamilySymbol.

Use IFamilyLoadOptions to override behavior when loading family or family symbol from disk

New overloads for

• Document.LoadFamily()
• Document.LoadFamilySymbol()

have been added. These overloads accept IFamilyLoadOptions as an argument, allowing your application to automatically respond to the prompts Revit typically shows the user when reloading a family which already exists in a document. These new overloads apply when loading a family or a family symbol from a file on disk.

Extract PartAtom from loaded family

The method

• Family.ExtractPartAtom()

writes a PartAtom file describing the loaded family to a specified file on disk.

FamilyHostingBehavior

The enum FamilyHostingBehavior represents the type of host a family expects. The value for a particular family can be obtained from the family's BuiltInParameter.FAMILY_HOSTING_BEHAVIOR parameter.

FamilyInstance.Host property improved

The property

• FamilyInstance.Host

will now return the host element of face-hosted family instances. Previously it returned null.

Convert family to be face host based

The method

• FamilyUtils.ConvertFamilyToFaceHostBased()

converts a family to be face host based.

Extract id of a family parameter

The new property

• FamilyParameter.Id

extracts the id of a FamilyParameter as an ElementId. When you have a shared or family parameter, this Id is needed in order to use the parameter from an ElementParameterFilter during element iteration and as a ParameterChange for an updater. When you have a built-in parameter, the integer value of the id is the same as the integer value of the BuiltInParameter enumeration.

API for solid/solid cut

The static methods in the class

• SolidSolidCutUtils

expose the ability to add and remove new solid/solid cuts, and to inquire if an element is used in solid/solid cut in a family.

Additional DividedSurface API

Some additional methods have been added to the DividedSurface class and provide access to intersection references:

• DividedSurface.GetAllIntersectionElements()
• DividedSurface.AddIntersectionElement()
• DividedSurface.RemoveIntersectionElement()
• DividedSurface.RemoveAllIntersectionElements()
• DividedSurface.CanBeIntersectionElement()

View API changes

NewViewPlan input change

The method

• Autodesk.Revit.Creation.Document.NewViewPlan()

now accepts a ViewPlanType enum, which contains only those view types which can be created by the method.

Refresh active view

The method

• Document.RefreshActiveView()

refreshes the display of the active view during the execution of your command so users can see incremental updates to their model. As in the past, Revit will automatically redraw the view after the command completes.

View.IsTemplate

This property identifies if an instance of the View class represents an instance view (which users see in the project browser and graphics window) or a template view.

Save image to new view

The new method

• Document.SaveToProjectAsImage()

saves the graphics shown in the current view to a rendering view in the document.

API for placeholder sheets

The method

• ViewSheet.CreatePlaceholder()

creates a placeholder sheet in the document. Placeholder sheets represent sheets stored outside of the Revit model, but which should be organized along with the Revit sheets.

The property

• ViewSheet.IsPlaceholder

identifies if a sheet is a placeholder sheet or not.

Import, export and print changes

Import DWG as link

The method

• Document.Link()

imports a DWG into the document as a link.

Identify if import instance is linked

The property

• ImportInstance.IsLinked

identifies if an import instance element is a link to an external file.

Print API changes

The property

• PrintSetup.CurrentPrintSetting

has been changed to an IPrintSetting. This interface may represent a PrintSetting element, or an InSessionPrintSetting object representing the In-session print settings for Revit printing.

The property

• PrintSetup.InSessionPrintSetting

has been added to return the In-session print settings object. The in-session print settings will no longer returned in the collection of elements from the property

• Document.PrintSettings

The event arguments for the event

• Document.DocumentPrinting

has been changed to return an IPrintSetting object as well.

The property

• ViewSheetSetting.CurrentViewSheetSet

has been changed to an IViewSheetSet. This interface may represent a ViewSheetSet element, or an InSessionViewSheetSet object representing the In-session view sheet set for Revit printing.

The property

• ViewSheetSetting.InSessionViewSheetSet

has been added to return the In-session view sheet set object. The in-session view sheet set will no longer returned in the collection of elements from the property

• Document.ViewSheetSets

Export option for colour mode

The new property

• ACADExportOptions.Colors

allows the option of exporting colours matching the AutoCAD Color Index colours, or as 24-bit true colour RGB values.

Export model to IFC

The new method

• Document.Export(string, string, IFCExportOptions)

exports the document to the Industry Standard Classes (IFC) format.

Export model to DXF

The new method

• Document.Export(string, string, ViewSet, DXFExportOptions)

exports the document or set of selected views to the DXF format.

Export model to SAT

The new method

• Document.Export(string, string, ViewSet, DXFExportOptions)

exports the document or set of selected views to the SAT format.

Export image

The new method

• Document.ExportImage()

exports the graphics shown in one or more views to image file(s).

Extract image of an ElementType

The new method

• ElementType.GetPreviewImage()

extracts the preview image of an Element Type. This image is similar to what is seen in the Revit UI when selecting the type of an element. You can specify the size of the image in pixels.

Updated DWF and DWFX export methods

The four 2010 Document.Export methods for exporting of DWF-2D, DWF-3D, DWFX-2D and DWFX-3D files were consolidated into just two methods, one for exporting to DWF format, another to DWFX format. The corresponding export options classes are:

• DWFExportOptions
• DWFXExportOptions

Both methods can export both 2D views as well as 3D views in one call.

Export id

The static method

• ExportUtils.GetExportId()

retrieves the GUID representing an element in DWF and IFC export. This id is used in the contents of DWF export and IFC export and it should be used only when cross-referencing to the contents of these export formats. When storing Ids that will need to be mapped back to elements in future sessions, UniqueId must be used instead.

Parameter API changes

ParameterFilterElement

Provides access to filter elements associated to views. You can access and modify the categories associated to a filter and the rules associated to a filter. You can also create new filters using an input list of categories and rules.

Rules are organized in a hierarchy based on parameter value type:

• FilterIntegerRule – applies to integer and enumerated type parameters.
• FilterDoubleRule – applies to double type parameters.
• FilterElementIdRule – applies to ElementId type parameters.
• FilterStringRule – applies to String type parameters.

Rules are associated to evaluators and value providers.

Evaluators are classes which determine how to evaluate the rule based on the value of the parameter and the value set in the rule. There are two hierarchies of evaluators:

• FilterStringRuleEvaluator – applies to FilterStringRule rules, offers options for equality, begins with, ends with, contains, greater than, and less than evaluations.
• FilterNumericRuleEvaluator – applies to other rule types, offers options for equality, greater than, and less than.

At this time, the hierarchy of evaluators is not extendable in the API.

Value providers determine how the value is obtained for the evaluation. In this release, there is only one value provider available: ParameterValueProvider.

Extract GUID from a Parameter

The new properties

• Parameter.IsShared
• Parameter.GUID

identify if a given parameter is a shared parameter, and if it is, extract its GUID.

Extract id of a parameter

The new property

• Parameter.Id

extracts the id of a parameter as an ElementId. When you have a shared or family parameter, this Id is needed in order to use the parameter from an ElementParameterFilter during element iteration and as a ParameterChange for an updater. When you have a built-in parameter, the integer value of the id is the same as the integer value of the BuiltInParameter enumeration.

SuspendUpdating applies to Parameter.Set

SuspendUpdating performance improvements now apply to Parameter.Set by default. By using the new constructor for SuspendUpdating which takes a boolean suspendForParameterSet, you can turn off this option.

The performance benefits of this can be extremely significant (95-99% improvement in speed) if you are setting instance parameters on family instances (where the instance parameters are defined in the family itself, and not added to the instances via shared parameters). For most other applications of Parameter.Set this will likely have no visible performance benefit.

Note that SuspendUpdating applies only to RegenerationMode.Manual.

Alignment and ItemFactoryBase.NewAlignment() method

The Alignment element subclass has been removed. NewAlignment() and element iteration will now return alignments as Dimension elements.

DimensionType – access to the dimension style

The property

• DimensionType.StyleType

identifies the style to which the dimension type can be applied, e.g. linear, angular, radial, etc.

Create sloped wall on mass face

The method

• FaceWall.Create()

creates a new instance of a face wall on the sloped face of a mass.

Face.GetBoundingBox() method

This new method returns a BoundingBoxUV with the extents of the parameterization of the face.

NewFootPrintRoof() input

The method

• Autodesk.Revit.Creation.Document.NewFootPrintRoof()

has been changed. It now outputs an array of Model Curves corresponding to the set of Curves input in the footPrint. By knowing which Model Curve was created by each footPrint curve, you can set properties like SlopeAngle for each curve.

Floor slope and elevation

The slope and elevation at a point on floor's surface can be found using the methods:

• Floor.GetVerticalProjectionPoint()
• Floor.GetNormalAtVerticalProjectionPoint()

Converting between Model Curves and Detail/Symbolic Curves

The Revit API offers new utilities to convert model curves to and from detail curves or symbolic curves.

• Document.ConvertModelToDetailCurves()
• Document.ConvertDetailToModelCurves()
• Document.ConvertModelToSymbolicCurves()
• Document.ConvertSymbolicToModelCurves()

In all these methods, the original curves are deleted. If the curves do not lie in the appropriate plane for their target curve type, they will be projected to the target plane.

CurveElement type

The new property

• CurveElement.CurveElementType

identifies if a particular curve is a model curve, detail curve, symbolic curve, reference line, room, area or space separation line, insulation detail curve, repeating detail profile line, or revision cloud line.

Shared base classes for Room, Space, Area and their tags

The new classes Enclosure and EnclosureTag act as shared base classes for rooms, spaces, and areas, and room tags, space tags, and area tags, respectively. Some shared functionality from the derived classes has been moved into the base classes. There are some minor impacts to the previous API interfaces:

1. The RoomTag, SpaceTag, AreaTag property Leader has been renamed to HasLeader.
2. The Room and Space properties Area and Perimeter have been moved to the base class, thus granting access to these properties for the Area class as well.

View-specific elements

The new properties

• Element.ViewSpecific
• Element.OwnerViewId

identify if the element is owned by a particular view (for example, a Detail Curve is owned by the drafting view in which it is drawn), and which view is the owner. These properties align with the ElementOwnerViewFilter which can be used in Element iteration.

Monitoring elements

The new functions

• Element.IsMonitoringLinkElement()
• Element.IsMonitoringLocalElement()
• Element.GetMonitoredLinkElementIds()
• Element.GetMonitoredLocalElementIds()

indicate whether an element is monitoring any elements in the local document or in linked files.

Design Options

The new static function

• DesignOption.GetActiveDesignOptionId()

returns the id of the active design option within the document.

The new property

• DesignOption.IsPrimary

identifies if the design option is the primary option within its owning design option set.

Family template path

The property

• Application.FamilyTemplatePath

provides the default path for family template files.

Write comments to the Revit Journal File

The method

• Application.WriteJournalComment()

allows the API application to write comments to the Revit Journal file for diagnostic, testing, and other purposes.

Window extents

The properties

• UIApplication.MainWindowExtents
• UIApplication.DrawingAreaExtents

provide access to the outer coordinates of the Revit window and drawing area, in pixels. An application can use these value to correctly locate its own UI relative to the Revit UI.

City.WeatherStation

The new property

• City.WeatherStation

provides an identifier for the nearest weather station.

Labels matching commonly used enumerated type values

The new class LabelUtils provides methods to obtain the user-visible label corresponding to certain enum values. These routines obtain the label corresponding to the name in the current Revit language. Support is offered for:

• BuiltInParameter
• BuiltInParameterGroup
• ParameterType
• UnitType
• DisplayUnitType
• gbXMLBuildingType

Keyboard shortcut support for API buttons

API buttons found on the Ribbon can be assigned a keyboard shortcut. Buttons created by applications registered using manifest files now use an id based on their application id and button name to provide a unique identifier for the button. The keyboard shortcut will be maintained even if the order of registration of API applications changes.

MEP API

Validation in ElectricalSystem properties

The properties

• ElectricalSystem.Length
• ElectricalSystem.VoltageDrop

now throw an InvalidOperationException when the value cannot be computed (instead of returning 0).

WireMaterialType, InsulationType, TemperatureRatingType

These methods now inherit from ElementType.

DuctConnector, PipeConnector, ElectricalConnector

The methods now inherit from a new common base class, ConnectorElement.

Structural API

NewTruss() in Revit Architecture

The Autodesk.Revit.Creation.Document.NewTruss method, which was previously only enabled in Revit Structure, is now also enabled in Revit Architecture.

Truss – attach and detach chord

The methods

• Truss.AttachTopChord
• Truss.DetachTopChord

have been replaced by methods

• Truss.AttachChord
• Truss.DetachChord

supporting both top and bottom chords as inputs.

Drop truss and beam systems

The new methods

• Truss.DropTruss()
• BeamSystem.DropBeamSystem()

delete the parent collection elements after disassociating their constituent members.

Rebar API changes

The new methods

• Autodesk.Revit.Creation.Document.NewRebarBarType()
• Autodesk.Revit.Creation.Document.NewRebarHookType()
• Autodesk.Revit.Creation.Document.NewRebarCoverType()

allow creation of new instances of these elements.

The RebarBarType class has a new interface. (Formerly some properties were available through parameters only.)

• BarDiameter
• StandardBendDiameter
• StandardHookBendDiameter (new property for 2011)
• StirrupTieBendDiameter
• MaximumBendRadius
• GetHookPermission() / SetHookPermission()
• GetAutoCalcHookLengths() / SetAutoCalcHookLengths()
• GetHookLength() / SetHookLength()
• GetHookOffsetLength() / SetHookOffsetLength()

The Rebar class has two new properties, includeFirstBar and includeLastBar, which allow suppression of the end bars in a rebar array.

Rebar also has a new interface to its Array functionality. (Formerly these properties were available through parameters only.)

• LayoutRule: (read-only) Array layout rule.
• SetLayoutAsSingle() / SetLayoutAsFixedNumber() / SetLayoutAsMaximumSpacing() / SetLayoutAsNumberWithSpacing() / SetLayoutAsMinimumClearSpacing(): Change the array layout rule. Note that the layout rule interacts with several other properties; to avoid confusion, the SetLayout methods require you to specify values for these other properties.
• ArrayLength: Array length.
• NumberOfBarPositions: Number of bar positions in the array. The actual number may be 1 or 2 fewer and is given by getQuantity().
• MaxSpacing: maxium spacing.
• Quantity: (read-only) Number of bars in the array, equal to getNumberOfBarPositions() minus the number of end bars suppressed with includeFirstBar / includeLastBar.
• BarsOnNormalSide: flip the array with respect to the start plane.

The method SetLayoutRuleWithoutExaminingHost() has been removed in favour of the new setLayoutRuleAs...() methods.

The methods:

• Rebar.IsUnobscuredInView()
• Rebar.SetUnobscuredInView()
• Rebar.IsSolidInView()
• Rebar.SetSolidInView()

control the visibility of the Rebar in the indicated view.

New Rebar properties and methods have been introduced to work with spiral rebar:

• Rebar.Height
• Rebar.Pitch
• Rebar.BaseFinishingTurns
• Rebar.TopFinishingTurns
• Rebar.ScaleToBoxForSpiral()
• RebarShapeDefinitionByArc.SetArcTypeSpiral()

Finally, HostedSweep elements are now valid for the Rebar.Host property.

Structural Settings

The class StructuralSettings provides access to many of the values shown in the Revit Structural Settings dialog box:

• Symbolic Cutback distances
• Brace symbols
• Analytical model settings
• Boundary conditions settings

To obtain the StructuralSettings for a given document, use the static method:

• StructuralSettings.GetStructuralSettings(Document)

Some items in the Revit Structural Settings dialog box are not accessed through StructuralSettings in the API:

• Connection Types are individual elements of type StructuralConnectionType that are part of the document.
• Load cases are individual elements of type LoadCase that are part of the document.

Rigid link built-in parameter change

The built-in parameter id STRUCTURAL_ANALYTICAL_RIGID_LINK has been replaced with STRUCTURAL_ANALYTICAL_COLUMN_RIGID_LINK and STRUCTURAL_ANALYTICAL_BEAM_RIGID_LINK.

You can also access the value of this parameter for a given element via the AnalyticalModel.RigidLinksOption property.

BoundaryConditions type

A new enum BoundaryConditionsType has been introduced. The values of this enum match the values of the built-in parameter id BOUNDARY_CONDITIONS_TYPE.

---

End of document

---

So that was the news in the Revit 2011 API way back in the year 2010.

Please be aware that some of the changes listed above obviously have changed yet again since.

Stay tuned for the next installment, coming soon, leading up towards the current day.

What's New in the Revit 2010 API

I am in vacation in Italy, and trying not to work.

There is one project that I had in mind for quite a while, though, and will start addressing now anyway during this break: I plan to publish the contents of the Revit API documentation 'What's New' sections from the previous few releases of the Revit API help file RevitAPI.chm here, so that they become included in future Internet searches.

The reason for this is that I have found them to be a very valuable source of information. I regularly look for answers in these document sections myself first of all when I encounter a question in an API area that I am not familiar with.

So let's start chronologically, with the Revit 2010 API news.

Well, on second thoughts, the Revit 2008 and 2009 API releases also included some 'What's New' information in the form of an 'API Changes' folder containing XML files listing the additions and removals, which I will simply provide for download right here:

• Revit 2008 API Changes
• Revit 2009 API Changes

For Revit the 2010 API, I actually extracted the following from the document 'Revit Platform API Changes and Additions.doc' provided in the Revit 2010 SDK, which lists the same information as the help file.

I plan to follow up with the corresponding information for the Revit 2011, 2012 and 2013 APIs by and by.

Major Enhancements and Modifications Affecting the Revit 2010 API

New Revit user interface

Autodesk Revit 2010 offers a new user-interface system based on Ribbons. The API has been modified to support customization of the Ribbon user-interface in a similar manner to what was supported in previous releases for toolbars and menus.

External commands registered directly to Revit via the Revit.ini file are now located on the “Add-ins” tab under the “External commands” pulldown. No code changes are required to move the buttons to this location. The Add-ins tab will be automatically displayed if any external command is registered with Revit.

External applications can register and lay out panels on the Add-ins tab of the Ribbon. Custom panels may be given an application-specified name, and may contain:

• Pushbuttons – a single button with label and icon that invokes a command when pressed.
• Pulldown buttons – a button with label and icon that opens a menu with different choices when pressed.
• Separators – a vertical line separating panel components.

Pushbuttons and Pulldown buttons may be created as large size, or stacked in sets of 2 or 3.

The API for creating Ribbon Panels is completely different from the Toolbar and Menubar API. External applications which added content to the toolbars and menus will need to be modified to create Ribbon panel(s) instead.

Family Creation API

The Family Creation API provides programmatic access for creation and modification of the contents of Revit Family documents. Geometric data, Family Types, and other information that can be specified through the Revit Family Editor can now be specified via the API. As a result of this project, API external commands are now displayed while editing a family document in the Family Editor. API access to in-place family editing is still restricted. The project introduces the class Autodesk.Revit.FamilyManager, which allows access to family types and parameters. Using this class you can add and remove types, add and remove family and shared parameters, set the value for parameters in different family types, and define formulas to drive parameter values.

The Category and Categories classes have been enhanced and a new GraphicsStyle class has been created to provide control of the appearance of Revit families.

The new class FamilyItemFactory provides the ability to create elements in families. Access this class through the Document.FamilyCreate property. It includes the following methods:

• NewBlend
• NewDimension
• NewDuctConnector (in Revit MEP only)
• NewElectricalConnector (in Revit MEP only)
• NewExtrusion
• NewFamilyInstance
• NewModelText
• NewPipeConnector (in Revit MEP only)
• NewRevolution
• NewSketchPlane
• NewSweep
• NewSweptBlend
• NewSymbolicCurve
• NewTextNote

The new class ItemFactoryBase provides the ability to create elements both in project and family documents and includes the NewAlignment method.

New document methods – Document.LoadFamily and Document.EditFamily – are introduced to bring families from the Family Editor to the Project environment and vice versa. These methods can be used to examine the contents of the family in terms of its elements, parameters and types; as a result, the properties of Family which access the contents have been removed (Family.SolidForms, Family.VoidForms, Family.Components, Family.LoadedSymbols, Family.Others).

New Events

The Revit API offers totally revamped events that allow an application to subscribe to events taking place in the Revit user interface or in API workflows. In all of the new events, events now occur before and after various triggering actions (known as "pre" and "post" events). Many of the new pre-events are cancellable, offering the API application the ability to prevent the event from taking place based on criteria it cares about. (It is the responsibility of the event subscriber to inform the user of the reason for the cancellation).

Events that existed before release 2010 have been marked Obsolete. You should use the new events added in this release to cover situations like:

1. Document creation
2. Document opening
3. Document saving
4. Document saving as (new filename)
5. Document closing
6. Dialog box showing

The dialog box showing event has been restructured to support notification by Revit when task dialogs are shown.

The new events added in Revit 2010 are:

1. File export
2. File import
3. View printing
4. Document printing
5. View activating
6. Document synchronize with central

API for new Massing functionality

Revit 2010 introduces new conceptual design functionality for creation of complex geometry. Intuitive and flexible form-making is supported by the addition of new objects: points and spline curves that pass through these points. The resulting surfaces can be divided, patterned, and panelized to create buildable forms with persistent parametric relationships.

The following classes provide the API user with access to this functionality:

• CurveByPoints
• CurveByPointsArray
• DividedSurface
• DividedSurfaceData
• Form
• ReferencePoint
• ReferencePointArray
• TilePatterns
• TilePattern

Other methods and properties added to support this functionality are:

• ModelCurve.ChangeToReferenceLine()
• FamilyCreate.NewLevel(double)
• Family.IsCurtainPanelFamily
• Family.CurtainPanelHorizontalSpacing
• Family.CurtainPanelVerticalSpacing
• Family.CurtainPanelTilePattern
• SketchPlane.PlaneReference
• Level.PlaneReference

The following classes cannot be used in 2010 Mass families. Instead, equivalent geometry can be created with the Form class.

• Blend
• Extrusion
• Revolution
• Sweep
• SweptBlend

MEP API for ducts and pipes

This project provides read/write access to HVAC and Piping data in a Revit model including:

1. Traversing ducts, pipes, fittings, and connectors in a system
2. Adding, removing, and changing ducts, pipes, and other equipment
3. Getting and setting system properties
4. Determining if the system is well-connected

The following classes have new methods and properties related to duct and pipes:

• Autodesk.Revit.MEP.Connector
• Autodesk.Revit.Elements.MechanicalSystem
• Autodesk.Revit.Elements.PipingSystem

Elements related to duct and pipe systems can be created using new methods on Autodesk.Revit.Creation.Document:

• NewCrossFitting
• NewDuct
• NewElbowFitting
• NewFlexDuct
• NewFlexPipe
• NewMechanicalSystem
• NewPipe
• NewPipingSystem
• NewTakeoffFitting
• NewTeeFitting
• NewTransitionFitting
• NewUnionFitting

All MEP-related classes have been moved into the MEP namespace from namespaces such as Elements and Symbols.

Upgrade to .NET Framework version 3.5

Revit now uses Microsoft .NET Framework version 3.5. Applications compiled using .NET 2.0 should continue to work unless they are affected by other changes in the Revit 2010 API.

Small enhancements & API interface changes

Parameters

The new property Autodesk.Revit.Parameters.InternalDefinition.BuiltInParameter provides access to the enumerated type for the parameter, if it is a built-in parameter. The property makes it easier to locate a built-in parameter value based on the name of the parameter shown in the Revit UI.

Rooms and Spaces

The new method Autodesk.Revit.Elements.Room.IsPointInRoom determines if a 3D point is in the volume of a room.

The new method Autodesk.Revit.Elements.Space.IsPointInSpace determines if a 3D point is in the volume of a space.

The new methods Autodesk.Revit.Document. GetRoomAtPoint() and GetSpaceAtPoint() find the Room or Space that encloses a given 3D point within the project.

The new property Autodesk.Revit.Elements.FamilyInstance.Space allows an API application to determine what in which Space an air terminal or other family instance exists in Revit MEP.

Grids

The new method Autodesk.Revit.Elements.Grid.ExtendToAllLevels() method allows grids to intersect all levels of a project.

The method Autodesk.Revit.Creation.Document.NewGrid will throw an exception if given an unbounded line.

Batch creation methods (NewWalls, NewGrids, etc.)

If one of the elements which is supposed to be created can't be created the entire the operation will be properly rolled back.

Rebar

NewRebar:StartHookOrientation and EndHookOrientation arguments were changed to an enum. Rebar.SetLayoutRuleWithoutExaminingHost value type was changed to an enum.

Structural framing

Beams created with an offset from their level now have their analytical model aligned with the physical geometry of the beam.

Curved beams can be created in the vertical plane.

Categories

Internal categories that are not directly exposed through the Revit UI can be accessed via the API. This makes it possible to add shared parameters to Materials using Revit API.

The new Category.AllowsBoundParameters property indicates if a category can have shared or project parameter. When category.AllowsBoundParameters is false, it may not be bound to shared parameters using the BindingMap.

Category. AllowsVisibilityControl(view) indicates if the visibility of a category can be controlled in a given view.

Sketch

Autodesk.Revit.Elements.Sketch.CurveLoop now returns CurveArrayArray instead of CurveArray. If the sketch contains multiple loops, the output will be segregated into separate CurveArrays within the output.

Revit session properties

The new Autodesk.Revit.Application.Language property identifies the language used in the current session of Revit.

The new Autodesk.Revit.Application.Product property identifies the Revit vertical application (Building, Structure, MEP) via an enumerated type.

External Commands and Applications

Revit now offers improved diagnostics when Revit is unable to run an external application or command listed in the Revit.ini file. A popup message will explain the problem. If the problem is related to an exception caught from the application, the popup will include the exception stack trace.

Revit no longer silently renumbers the Revit.ini file entries when they fail to load or start. An option in the popup message will allow a user to permanently disable a failed API application.

HostedSweep

In the Autodesk.Revit.Elements.HostedSweep class the new abstract method AddSegment() allows applications to write generic code that operates upon all hosted sweep types (gutter, fascia, or slab edge).

VolumeCalculationOptions

The Autodesk.Revit.VolumeCalculationOptions.VolumeComputationEnbale field was removed. Use the property VolumeComputationEnable instead.

Curtain Systems

Autodesk.Revit.Elements.CurtainGridLine new property ExistingSegmentCurves allows access to the existing segments in the grid line (excluding those which have been removed).

Autodesk.Revit.Elements.Mullion now provides access to its location via the LocationCurve property.

Output Arguments from API methods

Output arguments are now marked with the [Out] attribute. Methods changed include:

• Application.GetAllTopMenus
• ControlledApplication.GetAllTopMenus
• Document.Import - both overloads
• Face.Intersect
• Curve.Intersect
• Curve.IsInside
• Face.IsInside
• Document.LoadFamily
• Document.LoadFamilySymbol

Where previously these output arguments were declared as “reference”. In C#, where these arguments were passed using the “ref” keyword, this should now be “out”.

Visual Studio Tools for Applications (VSTA) 2.0

Revit's macro functionality is now based on VSTA 2.0. More information about VSTA and version 2.0 are available on Microsoft's MSDN Developer Center.

Find references in the direction of a ray

This new method returns a reference array of all references found when moving through the Revit model from a specified point at a specified direction.

Syntax:

public ReferenceArray FindReferencesByDirection(XYZ origin, XYZ direction, View3D view)

Reference parsing

The Autodesk.Revit.Geometry.Reference class now offers properties to extract the element, geometry object, transform, point, and parameters of the referenced item.

Element Hiding

To allow hiding and un-hiding of elements via the API, the methods View.Hide(ElementSet) and View.Unhide(ElementSet) have been added. The properties Element.IsHidden(View) and Element.CanBeHidden(View) return a boolean value that indicates if an element is current hidden and if it can be hidden.

Parameter.Set return value when value is unchanged

Previously, Revit returned False if the input value for Parameter.Set was the same as the current value. Revit now returns True in this case.

NoConditionType removed for Spaces

The NoConditionType enum has been removed as an option for Spaces. All spaces must have a ConditionType value and the default is HeatedAndCooled. A user wishing to specify an unconditioned space may use the value ConditionType::Unconditioned.

Detail Curves use sketch plane of their view

NewDetailCurve and NewDetailCurveArray no longer require specification of a sketch plane. The sketch plane of the view is used.

SketchPlane property added to View class

The property View.SketchPlane has been created to return a view's sketch plane.

Export family data to XML for Autodesk Seek integration

The method ExtractPartAtomFromFamilyFile will open a family file and create an XML file with data used by Autodesk Seek for content search.

Exceptions when parameters are disabled

Set and Get for the following parameters may now result in exceptions when the parameter is disabled for the specified object: View.Scale, RoofBase.FasciaDepth, FootPrintRoof.SlopeAngle

New options for export to DWF

The new option DWF2DExportOptions.ExportFormat allows specification of the paper format for the DWF.

The new option DWF2DExportOptions.PortraitLayout allows specification of the layout for the DWF.

The new option DWF2DExportOptions.ImageFormat allows specification of the format for the exported image in the DWF.

The new option DWF2DExportOptions.ImageQuality allows specification of the format for the exported image in the DWF.

The new option DWF2DExportOptions.StopOnError and DWF3DExportOptions.StopOnError controls whether or not the export process stops when an error is generated during export of one view, or whether Revit attempts to continue the export for other pending views.

New option for export to FBX

The new option FBXExportOptions.StopOnError controls whether or not the export process stops when an error is generated during export of one view, or whether Revit attempts to continue the export for other pending views.

New method for export to DGN

The new method Document.Export(String, String, ViewSet, DGNExportOptions) exports a Revit project exports a model into DGN format.

New method for export to Civil3D

The new method Document.Export(String, String, View3D, ViewPlan, BuildingSiteExportOptions) exports a Revit project exports a model in the format of Civil Engineering design applications.

New method for import from gbXML

The new method Document.Import(String, GBXMLImportOptions) imports a Green-Building XML file into Revit.

New method for import from Inventor

The new method Document.Import(String, InventorImportOptions) imports an Inventor file into Revit. The Inventor file must be a .adsk file exported from Inventor for the purposes of transfer to Revit.

Document.Application property

The new property Document.Application returns the Application object which contains this document.

New element collector properties

Two new methods for collecting elements have been added.

• int Elements[Filter, ElementArray] – Collects all elements which satisfy specified filter within the document.
• int Elements[Type, ElementArray] – Collects all elements which satisfy specified type within the document.

These methods are similar to previously existing methods accepting a System.Collection.Generics.ICollection.

ImportInstance elements

A new element sub-type ImportInstance represents external geometry content such as DWG that has been imported to Revit. This element type is also output from the Import() methods, however, those methods have not been updated to specific output this new type. You can downcast the output to this sub-type.

The ImportInstance element types offer the ability to access and modify the Visibility and Pinned parameters.

LocationCurve.ElementsAtJoin

This property has changed type since Revit release 2009. The property now returns an ElementArray, instead of List.

Element material quantities

The API provides access to the material quantities for a material in a given element. These values are the same values calculated by Revit to show in material takeoff schedules. In some cases the value may be approximate. Access these values through:

• Category.HasMaterialQuantities
• Element.Materials
• Element.GetMaterialArea()
• Element.GetMaterialVolume()

Instance.Transformed and Geometry of Instances

This property has been removed. Obtain the transformed geometry of the instance using Instance.GetInstanceGeometry(), Instance.GetSymbolGeometry(Transform) and Instance.GetInstanceGeometry(Transform)

PlaceGroup()

The method Autodesk.Revit.Creation.Document.PlaceGroup() has been modified to correctly interpret the coordinates of the input point in the coordinates of the document. Previously it interpreted the points in the coordinates of the group, which were not accessible.

gbXMLParamElem.ShadingSurfaces

This property has been removed and replaced with gbXMLParamElem.ExportComplexity with a wider variety of options.

Creating topography surfaces

The new methods

• Autodesk.Revit.Creation.Document.NewTopographySurface()
• Autodesk.Revit.Elements.TopographySurface.AddPoints()

allow you to create and populate topography surface elements in projects.

Changes to Printing

The workflows used to change print settings via the PrintManager class have changed. Previously, changes to settings happened immediately and would be visible in the Revit Print dialogs and applicable to all API printing activities. In the 2010 API, you must commit the changes you have made to the PrintManager, PrintSettings and PrintParameters classes by one of these methods:

1. Calling PrintManager.SubmitPrint to execute a print job.
2. Calling PrintManager.Apply to save settings without executing a print job.

The properties PrintSetup.PaperSizes and PrintSetup.PaperSources have moved to the PrintManager class.

A new option has been added to PrintParameters: ReplaceHalftoneWithThinLines.

Geometry extraction

A new option Autodesk.Revit.Geometry.Options.IncludeNonVisibleObjects has been added. Use this option to instruct Revit to include GeometryObjects whose Visibility type is something other than ‘Visible’ when extracting geometry from Revit. Objects which appear in this category include MEP Duct lining and insulation and joined geometry currently selected and highlighted in the Revit User Interface. When this option is not set (the default) only visible geometry is extracted, the same as in Revit 2009.

The geometry extraction API uses new algorithms to extract the faces and edges from a solid. The handles to these faces and edges are no longer maintained centrally (which means they are not suitable to be used as an index for collections like a Dictionary or Map). The new algorithm also changes the order in which the faces are returned, thus they may not be returned in the same order as in Revit 2009.

Additional enums

Several enums have been added to the Revit API to assist developers with interpretation of the values of certain BuiltInParameter types:

• Autodesk.Revit.Enums.AnalyzesAsType – For the parameter STRUCTURAL_ANALYZES_AS
• Autodesk.Revit.Enums.SlantedOrVerticalColumnType – For the parameter SLANTED_COLUMN_TYPE_PARAM
• Autodesk.Revit.Enums.StickSymbolJustification – For the parameter STRUCTURAL_STICK_SYMBOL_LOCATION
• Autodesk.Revit.Enums.StructuralReleaseType – For the parameter STRUCTURAL_END_RELEASE_TYPE
• Autodesk.Revit.Enums.WallFunction – For the parameter WALL_ATTR_EXTERIOR

---

End of document

---

So that was the news in the Revit 2010 API back in 2009.

Stay tuned for the next installments leading up to the current day.

Implement a Progress Bar and Abort a Lengthy Process

The time has come to talk of many things: of shoes and ships, and sealing-wax, of cabbages and kings [^]... or no, let's continue sticking to the Revit API for now, more or less; today's topics are:

• A walk in the snow and a crystal covered baby tree
• Implementation of a Revit add-in progress bar
• Aborting a lengthy process from the progress bar
• Harry's image generation video competition

A Walk in the Snow

I went for a walk in snow and fog on a local hill and appreciated this wind-driven ice crystal covered baby tree that:

I thought I would like to share that with you. Sorry that it is so dark, but that's the way it was.

Implementing a Revit Add-in Progress Bar

I chatted with Harry Mattison on various topics during the winter break. One of them was the implementation of a Revit add-in progress bar:

Question: I am trying to make a simple progress dialog based on your post on modeless dialogues. It seems to work well basically but has a few problems:

1. The first time I run the command, the progress dialog flashes briefly on the screen and then disappears.
2. The text label does not display properly.
3. Sometimes the entire progress dialogue content turns white and the title bar says 'Not Responding'.

Could you help me figure out if my approach is flawed or if it just needs some small adjustments?

Answer: Thank you, but no thank you... :-)

Instead, I propose that you look at my existing modeless progress bar implementation in the ADN Revit MEP sample add-in, which has worked flawlessly for years now.

Response: Your progress bar is great! I wish I had found it earlier.

Aborting a Lengthy Process

Here's hopefully one last question about the progress bar:

How can the user cancel the operation from the progress bar?

Answer: You could implement some standard .NET stuff on the progress bar; maybe simply add a cancel button to it, and an event handler for that.

Response: After spending some time thinking about events and the like, I realized the progress bar cancel solution is almost trivial.

An idle event wouldn't work in my case, because Revit was never going idle. It was too busy doing hard work of exporting images for my Image-O-Matic application. Instead, all I needed to do is add the Abort button to the progress dialog, and put this little bit of code in the progress bar class:

  private void btnAbort_Click(
    object sender,
    EventArgs e )
  {
    btnAbort.Text = "Aborting...";
    abortFlag = true;
  }
 
  public bool getAbortFlag()
  {
    return abortFlag;
  }

Then, inside my foreach loops, I just need to check the status of the flag:

  foreach( string phaseName in phaseList )
  {
    if( progressForm.getAbortFlag() )
      break;
 
    // . . .
  }

Many thanks to Harry for the fruitful discussion and helpful hint!

Image Generation Video Competition

Yet another item from Harry, this time a rather shameless plug, but I guess he earned it :-)

Harry announced a competition in which you can win a free, custom-built Revit API add-in according to your own specifications for downloading his Image-O-Matic application, generating a video with it, and uploading that to YouTube.

Have fun, and good luck to you!

What I Do, Wall Layers and Open Transactions

One of my tasks today and tonight will be a minimal little contribution to an internal ADN meeting, where I was asked to explain briefly to my colleagues in just a couple of minutes what my job involves and what I have been up to for the last couple of months. Tonight, since we have a session each for the western and eastern hemisphere, and the eastern one will require me to set my alarm for 2:30 tomorrow morning.

I thought I might as well share the result here with you also, to provide a rough idea for all of what my everyday work looks like.

Further down I'll also mention two recent cases, dealing with:

• Determining wall layer materials, areas and volumes
• Determining whether a transaction is open
• The Application IsQuiescent property

What I Do

My spontaneous picture of my work life is that I never do anything at all except dealing with ADN cases and writing The Building Coder blog.

My main motivation is probably solving problems, but maybe even stronger than that an urge to help people in whatever manner possible.

Unfortunately for me, I seem to often find it more helpful just to shuffle information around that I receive from others, rather than performing my own research. I would love to spend more time programming and exploring new issues myself, rather than managing information provided by others.

I have a large number of other interests besides that, such as reading, languages, nature, sports, especially climbing, dancing, 5rhythms and dj-ing.

I also have four grown up kids who have left home by now and are out in the world doing their own things, such as composing their own music.

Job-wise, I recently switched from a Windows computer to a Mac and still enthusiastic about that, busy retraining my fingers and compiling open source software. I am a keyboard user and avoid touching the mouse or using the GUI whenever possible. It will take much longer to train my fingers to all the new shortcuts, but they are starting to adapt. I am overjoyed at having a Unix command console now again, after a couple of decades of cmd.exe.

When I offered to talk, I said that I would only be able to cover 30 seconds, since all I do is handle cases and blog, and that is quickly said.

Of course I also do some work creating presentations and conducting trainings at conferences and events such as AU (2, 3) or DevCamp (2, lab).

Jim suggested I could mention my visit to Australia.

Yes, indeed, I went there and gave a Revit API training, followed by a three-day DevLab. It really was a great learning experience and good fun. Some of the participants were extremely well versed in the Revit product usage, and the importance of knowing the product in depth before embarking on any add-in development plans was strongly reinforced.

In spite of that, I spent a while with one of the participants discussing how to implement a family and a command to toggle the family instance state between two conditions, until we discovered that we could save hundreds of lines of code, family complexity, workflow development and user training by just using the existing functionality already provided by Revit: define two different types for the two states, and let the user switch via the instance properties using standard built-in tools – a very impressive experience, cool.

What I Actually Did

That said, I do indeed spend almost all my time with cases and the blog. In 2012 ADN provided a couple of hands-on classroom trainings. The trend in some highly developed areas of the world seems to be going away from hands-on face-to-face trainings and meetings and moving towards virtual interactions and blogging instead.

So, to answer the question more precisely, I put together some statistics on the time I spent on various tasks in the year 2012 in per cent:

• 44% – ADN cases, special support cases, learning new Revit API features cases, newsletter articles
• 17% – Conferences: Autodesk University, DevCamp, DevDays, webcasts
• 14% – Admin including meetings and participating in trainings
• 13% – Blogging
• 6% – Providing hands-on Revit API training
• 6% – Other stuff, including cloud & mobile, plug-in development, Mac learning and setup

I was a bit surprised by some of these results and find them interesting. Maybe you do too.

The results are rather skewed, actually, since a lot of the work I do for the blog stems from case answering, trainings, and conference preparations, so maybe it would be more realistic to classify something between a fifth and a third of the case, conference and training work as blogging instead.

Basically, the intention of the blog is to eliminate the need for questions via ADN cases and discussion forum threads, and simultaneously the latter feed the former.

You could even go to the extreme of saying teat the blog is a filter for everything I do: if it is useful for the blog and can be shared in public, it is worthwhile doing; if not, not.

Therefore, let's return to the Revit API and present some notes on the two cases I mentioned above.

Determining Wall Layer Materials, Areas and Volumes

I recently started looking at foreign language cases as well as English ones, just for fun. I am very impressed by the advances in automatic translation. Here is a question on wall layers:

Question: 如何获取墙的材质厚度、名称等属性

我想请问下墙分层材料能够获取哪些信息？

我通过PickObject()获得墙（基本墙 外部 带砖与金属立筋龙骨复合墙）的Element， 再通过Element.Materials访问到MaterialSet，遍历得到各个Material信息，可得到墙的各个材质， 再根据Element.GetMaterialArea(Material)、Element.GetMaterialVolume(Material)获得该Material的体积和表面积。 单独墙体利用“体积/表面积”得到该Material的厚度是否正确？ 相交墙、曲面墙的情况呢？ 是否有API可以直接访问到该Material的厚度值？

Simply passing that though Google translate yields the following:

How to get the wall thickness of the material, the name and other attributes?

I would like to ask the next wall of layered materials able to get what information?

I PickObject wall (the wall externally with bricks and metal studs keel composite wall) Element. By Element.Materials access to MaterialSet, traverse various Material available wall material. According Element.GetMaterialArea (Material), Element.GetMaterialVolume (Material) to obtain the volume and surface area of the Material. Separate wall volume / surface area of the Material thickness is correct? Intersecting walls, curved wall? API can directly access to the thickness of the Material value?

Answer: Just as you say, the GetMaterialArea and GetMaterialVolume methods will return the volume and surface area of specific materials used within a wall.

This should work just fine for curved and intersecting walls as well.

You can also traverse the wall compound structure yourself to obtain more detailed information. Here is my very first discussion exploring wall compound layers.

Another exploration of this topic looks at extracting material volumes.

The access to the wall layers has been significantly enhanced since then, by the introduction of the new read-write compound layer structure access in Revit 2012, but the basic principles still apply just the same.

If you need more exact values than those returned by the built-in API methods, you can also split the wall into separate parts for a detailed analysis.

Here is a discussion describing such an approach used to determine the exact corner points of the various layers in the internal structure.

This apparently helped, at least to get started in further exploration of this topic.

Determining Whether a Transaction is Open

The other case was in English right from the start:

Question: My Revit add-in presents a modeless form to my users. How can I check from that context whether any other commands or transactions are open in Revit?

For example, the 'insert doors' command may be active.

If Revit is already waiting for user input, e.g. to insert a door, trying to start a transaction causes an error. It would be useful to be able to check whether a transaction is already in progress.

Answer: As you hopefully know, the implementation to handle the Idling event needs to be really clean and clear and is a little bit tricky.

Therefore, I strongly suggest basing anything you do on the ModelessForm_IdlingEvent and ModelessForm_ExternalEvent SDK samples introduced in Revit 2013.

If you implemented your Idling event handler in any other way in the past, it might be a good idea revisiting it now and comparing notes with those samples.

Also note that using an external event is often a little bit simpler and more appropriate than using an Idling event handler.

Please look at the implementation of my own tooltip for a more detailed explanation.

Basically, you never, ever, need to check for yourself whether a transaction is open at all.

Why? Because, to check whether a transaction is open, you need to use the Revit API. You cannot use the Revit API, though, unless you are in a valid Revit API context.

Mostly, when you are in a valid Revit API context, it is clear whether or not you can start a new transaction, since it depends to a large extent on the event handler that is currently being called.

Therefore, if your requirement is what I imagine it to be, I would simply suggest that you implement whatever you want to achieve based on the Revit SDK samples mentioned, and you will not need any further checks whether or not you can start a transaction, since it will be obvious: when your Idling event handler or external event Execute method is called, you can do what you like, and at all other times you can do nothing at all

Of course, in addition to being allowed to start a transaction at all, you may also have some restrictions due to read-only project documents etc., that also need to be gracefully dealt with.

Two methods are provided which may help with this: Document.IsModifiable andDocument.IsReadOnly. Look at the Revit API help file RevitAPI.chm for further oinformation on their application and usage.

The Application IsQuiescent Property

In addition to this, the Revit API does provide the Application.IsQuiescent property to check whether the application is quiescent. Unfortiunately, this method is not really useful for anything at all in the API right now.

Firstly, it is not at all related to transactions, thus one cannot make any assumption about starting a new transaction based on this. If any document in the current application is in editing mode or an in-place family is being edited, it returns false. Otherwise, true will be returned. That might correspond pretty well to what you are looking for. In reality, this property is by far not as useful as the two other ones mentioned above.

So, secondly, what it does tell you is whether you are currently in a command or edit mode or not. However, as pointed out above, as an API programmer, you already know that. For example, in your own external command, the method would return False, all the time. Ditto in many events and updaters. On the other hand, it should return True when called from Idling event, which again is obvious.

Just as a background information, this method was implemented in a very early attempt to mimic the AutoCAD API. However, due to significant differences, the quiescent state is not equally important in Revit, and thus the method ends up not actually being used in any Revit code.

Response: Thank you, that helped.

I'm making a 'Content Library' function as a modeless form in Revit. The form is intended to be open beside Revit when users work.

It provides content (RFA families) either by browsing by category or searching on family name, family type name, parameter name or parameter value on each of the family types.

The families are located by default on a website using REST. The database behind the website contains information about the family types, its parameters, and also thumbnails and a DWFX file of the RFA. For users with slow internet connections I made it possible to change provider to connect to content in a local database instead of the online website.

The above worked fine until I implemented SendKey Esc x 2 to cancel insert family in Revit.

When you mentioned the Idling event I looked through my code again and found the 'load family into Revit' function called from outside the Idling event. After moving this call into the Idling event handler all worked fine. :-)

Solid Centroid and Volume Calculation

I have not posted anything since last Friday, being too caught up in the West European Developer days and travelling. Today and tomorrow we spend in Gothenburg on the last lap of our journey, after Paris, Milano, Farnborough and Munich. I had a nap in the taxis to and from the airport yesterday, both in Germany and Sweden, so I was able to burn some midnight oil to share the following exploration with you.

One of the many interesting conversations I had at Autodesk University that caught my special attention dealt with a simple geometrical Revit API question; geometrical questions are among my favourites, and this one is really basic: how to calculate the centre of mass or centroid of a solid.

Once again, that led to the exploration of a number of interesting little sub-topics:

• Revit API centroid and volume calculation methods
• Gap free triangulation for polyhedral approximation
• Polyhedron centroid calculation algorithm
• Revit implementation and CentroidVolume class
• Polyhedron centroid calculation implementation
• Support for multiple solids
• Mainline with picking twists
• Results
• Download

Before getting into that, here is a quick heads-up to point out a new free technology preview to simulate airflow around buildings or other objects in a virtual wind tunnel:

Project Falcon Computational Fluid Dynamics CFD Add-in

Autodesk released Falcon for Revit to Autodesk Labs. Project Falcon is an outdoor airflow simulation add-in for Revit:

Emile Kfouri describes the use and advantages of Falcon in some depth on his Building Performance Analysis blog that I was previously unaware of. He includes detailed explanations of the kind of problems this software addresses, getting started, and comparisons with other technologies such as the wind tunnel feature in Project Vasari and Simulation CFD 360. Fascinating stuff.

By the way, this is extremely interesting to look at for any Revit add-in developer, even if you do not care about this specific kind of analysis, because it shows an impressive example of using Revit as a front-end input tool to a powerful analysis component, reporting the results back graphically using the analysis visualisation framework AVF. If you hook up these components intelligently, a lot of functionality can be achieved with little effort.

Centroid and Volume of a Solid

Returning to the centroid and volume calculation, the Revit API provides both of these through the Solid ComputeCentroid method and Volume property. As said, a conversation prompted me to explore how to implement these calculations on my own as well.

Calculating exact results for an arbitrary solid is not trivial, of course, and could currently only be achieved making use of an external library.

If high precision is not paramount, however, we can simplify the solid to a planar faceted representation by triangulating all its faces to create a polyhedral approximation of it.

Determining the centroid of a polyhedron is something that can be achieved in a very few lines of code, as I will show below.

Gap Free Triangulation for Polyhedral Approximation

Happily, the Revit 2013 API provides a method for triangulating the entire surface of a solid in one single call, ensuring a closed volume, unlike doing it face by face, which does not.

The Face.Triangulate method returns a triangular mesh approximation to the face. Revit defines the approximation tolerance internally. Calling it separately for neighbouring faces, however, will return independent triangulations that do not line up where the faces meet, leaving gaps in the shell of the original solid.

This deficiency was eliminated by the SolidUtils class introduced in Revit 2013, which provides the TessellateSolidOrShell method to facet an entire solid or open shell in one single call. This enables each boundary component of the solid or shell to be represented by a single properly closed triangulated structure.

Polyhedron Centroid Calculation Algorithm

With these necessary and powerful basics in place, I searched the Internet for a bit of help on implementing an algorithm to calculate the centroid, and found a discussion on determining the centre of mass of a 3D model from the Game Maker Community. Here is my edited version summarising the results of that thread:

Question: I'm working on a model editor and I have a set centre function to reset the centre of a model. I can do this a few ways which I have implemented.

Method 1: Add vertices, average them and move the model; pseudocode:

  for each point
    dx += point.x
    dy += point.y
    dz += point.z
    count ++

  dx/=count
  dy/=count
  dz/=count

  for each point
    point.x-=dx
    point.y-=dy
    point.z-=dz

The problem: If the model has many points in one area, the deviation favours that area. Which is not always good because some models have many, many points like at the tip of a gun or the cone of a ship.

Method 2: Find min max of vertices, average the min max into a deviation and move the model:

  for each point
    mindx = min( point.x, mindx )
    maxdx = max( point.x, maxdx )
    same for y and z

  dx = (mindx + maxdx) / 2
  same for dy, dz;

  for each point
    point.x -= dx
    same for y and z

That works OK.

For my third method, I would really like to centre the model on its estimated centre mass.

I have a series of 3 points defining the planes/faces. I figure I could plug either the plane area or perimeter into the deviation calculation. That way many points defining a tiny area would not affect the calculation that much. But I can't figure out the right math for this.

Can you determine the surface areas of each face?

Answer: Well, one would assume that we'd want to count the inside of the model into the mass calculation as well, in which case you want to find the volume of the model. This actually isn't too difficult to compute assuming that the model is closed (no holes; otherwise it wouldn't really have a well-defined volume) and that it's simple (in the mathematical sense; that means it doesn't intersect with itself). Each triangular face contributes a tetrahedron's worth of volume to the whole model. To find this volume given the three vertices of the face v1, v2, and v3, you need only compute v1 · (v2 × v3 ) / 6.

The following is very important. The vertices of every face must be oriented the same way. This means that if you look at a face from the outside of a model, its vertices should be oriented in a clockwise fashion (counter-clockwise is valid too, as long as you're consistent).

So, now we essentially have a way to compute a weighting factor for every face in the model. The coordinates we have to weight this by are the centroids of each tetrahedron, given by (v1 + v2 + v3)/4. This is because one of the vertices of every tetrahedron is the origin so it's 0, so there's no reason to include it here. So, the centroid of the model is given by the following:

∑ (v1 + v2 + v3)/4 [v1 · (v2 × v3 )] / ∑ [v1 · (v2 × v3)]

The sum is performed over each face.

Also, the factor of 6 in the volume is left out because it cancels out because of the division. So, loop over each face, compute the volume contribution and add that onto a total volume counter and also multiply it by that average position (you can move the division by 4 outside of the sum to make the loop faster; that way only one division needs to be performed instead of one for each face) of the tetrahedron (i.e. multiply it by the sum of the vertices). Then, outside of the loop, divide by the total volume times 4 (assuming you moved that division by 4 outside of the loop). You now have the centroid assuming constant density.

The variables are all vectors. The product of the three vectors is a triple scalar product. It's the dot product with the cross product (and also the determinant of the matrix of these vectors). It's equal to this, which can be used as a formula for the volume:

  x1*(y2*z3 - y3*z2)
  + y1*(z2*x3 - z3*x2)
  + z1*(x2*y3 - x3*y2)

This is because one of the vertices of every tetrahedron is the origin.

Note that this does not require the model to be convex. All the tetrahedrons are not necessarily entirely contained inside the model.

I only assume that the model is closed and simple. Any tetrahedrons outside the model will have their area computed to be negative. They'll subtract off their contributions. The origin of the system can be anywhere as well. It doesn't have to be inside the model.

Here is the entire pseudo-code:

  var cx, cy, cz, volume, v, i, x1, y1, z1, x2, y2, z2, x3, y3, z3;
  volume = 0;
  cx = 0; cy = 0; cz = 0;
  // Assuming vertices are in vertX[i], vertY[i], and vertZ[i]
  // and faces are faces[i, j] where the first index indicates the
  // face and the second index indicates the vertex of that face
  // The value in the faces array is an index into the vertex array
  i = 0;
  repeat (numFaces) {
    x1 = vertX[faces[i, 0]]; y1 = vertY[faces[i, 0]]; z1 = vertZ[faces[i, 0]];
    x2 = vertX[faces[i, 1]]; y2 = vertY[faces[i, 1]]; z2 = vertZ[faces[i, 1]];
    x3 = vertX[faces[i, 2]]; y3 = vertY[faces[i, 2]]; z3 = vertZ[faces[i, 2]];
    v = x1*(y2*z3 - y3*z2) + y1*(z2*x3 - z3*x2) + z1*(x2*y3 - x3*y2);
    volume += v;
    cx += (x1 + x2 + x3)*v;
    cy += (y1 + y2 + y3)*v;
    cz += (z1 + z2 + z3)*v;
    i += 1;
  }
  // Set centroid coordinates to their final value
  cx /= 4 * volume;
  cy /= 4 * volume;
  cz /= 4 * volume;
  // And, just in case you want to know the total volume of the model:
  volume /= 6;

Remember that the vertices of each face must be oriented in the same way (one way to see if they are is to turn on back face culling; if the model appears normally then they're all oriented properly--the model could also appear inside-out which would also be a valid orientation).

Part of this is actually calculating the area of each triangle without having to figure out the angles, simply using the 3 side lengths.

One way to achieve this is using Heron's Formula:

  A = sqrt( s * (s - a) * (s - b) * (s - c) )

Here a, b, c are the lengths of each side and s is the semi-perimeter, s = (a + b + c) / 2.

You can also just take the magnitude of the cross product of two edge vectors of the face and divide it by 2. This means that you can find the area of a face as a side effect of determining its normal vector, just as I do in my GetSignedPolygonArea method.

Revit Implementation and CentroidVolume Class

I used the algorithm described above to implement a volume and centre of mass calculation for a Revit solid.

As said, curved solids are approximated by triangulating them. The result is pretty precise for solids that are planar faceted to start with.

The code includes an assertion to ensure that the volume calculated as a side effect is not too far removed from the value provided by the Solid.Volume property.

Since the algorithm above calculates both the centroid and volume, I implemented the following little helper class to package the two together:

  class CentroidVolume
  {
    public CentroidVolume()
    {
    }
 
    public XYZ Centroid { get; set; }
    public double Volume { get; set; }
 
    override public string ToString()
    {
      return RealString( Volume ) + "@"
        + PointString( Centroid );
    }
  }

Polyhedron Centroid Calculation Implementation

My translation of the algorithm described above to Revit API looks like this, including the validation assertions at the end and an exception handler around the call to TessellateSolidOrShell for reasons explained below:

CentroidVolume GetCentroid( Solid solid )
{
  CentroidVolume cv = new CentroidVolume();
  double v;
  XYZ v0, v1, v2;
 
  SolidOrShellTessellationControls controls
    = new SolidOrShellTessellationControls();
 
  controls.LevelOfDetail = 0;
 
  TriangulatedSolidOrShell triangulation = null;
 
  try
  {
    triangulation
      = SolidUtils.TessellateSolidOrShell(
        solid, controls );
  }
  catch( Autodesk.Revit.Exceptions
    .InvalidOperationException )
  {
    return null;
  }
 
  int n = triangulation.ShellComponentCount;
 
  for( int i = 0; i < n; ++i )
  {
    TriangulatedShellComponent component
      = triangulation.GetShellComponent( i );
 
    int m = component.TriangleCount;
 
    for( int j = 0; j < m; ++j )
    {
      TriangleInShellComponent t
        = component.GetTriangle( j );
 
      v0 = component.GetVertex( t.VertexIndex0 );
      v1 = component.GetVertex( t.VertexIndex1 );
      v2 = component.GetVertex( t.VertexIndex2 );
 
      v = v0.X*(v1.Y*v2.Z - v2.Y*v1.Z)
        + v0.Y*(v1.Z*v2.X - v2.Z*v1.X)
        + v0.Z*(v1.X*v2.Y - v2.X*v1.Y);
 
      cv.Centroid += v * (v0 + v1 + v2);
      cv.Volume += v;
    }
  }
 
  // Set centroid coordinates to their final value
 
  cv.Centroid /= 4 * cv.Volume;
 
  XYZ diffCentroid = cv.Centroid
    - solid.ComputeCentroid();
 
  Debug.Assert( 0.6 > diffCentroid.GetLength(),
    "expected centroid approximation to be "
    + "similar to solid ComputeCentroid result" );
 
  // And, just in case you want to know 
  // the total volume of the model:
 
  cv.Volume /= 6;
 
  double diffVolume = cv.Volume - solid.Volume;
 
  Debug.Assert( 0.3 > Math.Abs(
    diffVolume / cv.Volume ),
    "expected volume approximation to be "
    + "similar to solid Volume property value" );
 
  return cv;
}

As you may have noticed, the assertion limits are pretty arbitrarily chosen.

Support for Multiple Solids

Since the centroid of any given element will be determined by all of its solids, which may be multiple, I implemented the following GetCentroid method to determine all solids belonging to a given element and calculate its total centroid and volume across all its component solids:

/// <summary>
/// Calculate centroid for all non-empty solids 
/// found for the given element. Family instances 
/// may have their own non-empty solids, in which 
/// case those are used, otherwise the symbol geometry.
/// The symbol geometry could keep track of the 
/// instance transform to map it to the actual 
/// project location. Instead, we ask for 
/// transformed geometry to be returned, so the 
/// resulting solids are already in place.
/// </summary>
CentroidVolume GetCentroid(
  Element e,
  Options opt )
{
  CentroidVolume cv = null;
 
  GeometryElement geo = e.get_Geometry( opt );
 
  Solid s;
 
  if( null != geo )
  {
    // List of pairs of centroid, volume for each solid
 
    List<CentroidVolume> a
      = new List<CentroidVolume>();
 
    Document doc = e.Document;
 
    if( e is FamilyInstance )
    {
      geo = geo.GetTransformed(
        Transform.Identity );
    }
 
    GeometryInstance inst = null;
 
    CentroidVolume cv1;
 
    foreach( GeometryObject obj in geo )
    {
      s = obj as Solid;
 
      if( null != s
        && 0 < s.Faces.Size
        && SolidUtils.IsValidForTessellation( s )
        && (null != ( cv1 = GetCentroid( s ) ) ) )
      {
        a.Add( cv1 );
      }
      inst = obj as GeometryInstance;
    }
 
    if( 0 == a.Count && null != inst )
    {
      geo = inst.GetSymbolGeometry();
 
      foreach( GeometryObject obj in geo )
      {
        s = obj as Solid;
 
        if( null != s
          && 0 < s.Faces.Size
          && SolidUtils.IsValidForTessellation( s )
          && (null != ( cv1 = GetCentroid( s ) ) ) )
        {
          a.Add( cv1 );
        }
      }
    }
 
    // Get the total centroid from the partial
    // contributions. Each contribution is weighted
    // with its associated volume, which needs to 
    // be factored out again at the end.
 
    if( 0 < a.Count )
    {
      cv = new CentroidVolume();
      foreach( CentroidVolume cv2 in a )
      {
        cv.Centroid += cv2.Volume * cv2.Centroid;
        cv.Volume += cv2.Volume;
      }
      cv.Centroid /= a.Count * cv.Volume;
    }
  }
  return cv;
}

The calculation of the total volume and centroid is similar to the base algorithm described above, with each centroid contribution weighted by the corresponding volume.

Mainline with Picking Twists

Finally, here is the external command Execute method implementation driving this and including some additional useful picking interaction handling twists, such as:

• Support for pre-selection or interactive picking.
• Checking for a valid active view type before prompting the user to pick an element.
• Exception handling to gracefully terminate picking and the entire command on cancels.

The resulting code looks like this:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
  List<ElementId> ids = new List<ElementId>();
  Selection sel = uidoc.Selection;
  SelElementSet set = sel.Elements;
 
  if( 0 < set.Size )
  {
    foreach( Element e in set )
    {
      ids.Add( e.Id );
    }
  }
  else
  {
    if( ViewType.Internal == doc.ActiveView.ViewType )
    {
      TaskDialog.Show( _caption,
        "Cannot pick elements in this view: "
        + doc.ActiveView.Name );
 
      return Result.Failed;
    }
 
    try
    {
      IList<Reference> refs = sel.PickObjects(
        ObjectType.Element,
        "Please select some elements" );
 
      foreach( Reference r in refs )
      {
        ids.Add( r.ElementId );
      }
    }
    catch( Autodesk.Revit.Exceptions.OperationCanceledException )
    {
      return Result.Cancelled;
    }
  }
 
  Options opt = app.Create.NewGeometryOptions();
 
  foreach( ElementId id in ids )
  {
    Element e = doc.GetElement( id );
 
    CentroidVolume cv = GetCentroid( e, opt );
 
    Debug.Print( "{0} {1}",
      (null == cv ? "<nil>" : cv.ToString()),
      ElementDescription( e ) );
  }
  return Result.Succeeded;
}

Results

I ran this on the basic sample model delivered with Revit, rac_basic_sample_project.rvt, simply selecting all elements on level 1. Not surprisingly, this causes a couple of hiccups, notably a few assertions stating that my volume approximation does not match Revit's and an exception thrown by the TessellateSolidOrShell method, in spite of calling IsValidForTessellation beforehand to ensure tht I only feed in acceptable solids to it. This exception is caused by the teapot in the model, which is in fact a rather abnormal building element, but still...

These hiccups can be ironed out. Here is the report logged to the debug output window with the hiccups and exception messages manually edited away, informing us that a large number of elements in the model are correctly processed and that for all of them my calculated approximate values correspond more or less to the ones reported by the built-in Revit API methods; copy and paste to an editor to see the truncated lines in full:

115.87@(-52.42,8.9,11.04) Wall Walls <117653 Foundation - 305 Concrete>
455.96@(-20.92,6.23,11.54) Wall Walls <117654 Generic - 200>
461.1@(-24.09,27.23,11.75) Wall Walls <117698 CORR>
<nil> Wall Walls <117714 Storefront>
52.65@(-19.42,13.54,4.88) Wall Walls <117945 Interior - Partition>
36.09@(-12.55,15.23,5.22) Wall Walls <117963 Interior - Partition>
<nil> Element Stairs <118049 open treads>
<nil> Railing Railings <118116 Handrail - Pipe>
64.4@(-7.56,11.37,4.92) Wall Walls <118356 Interior - Partition>
168.87@(11.08,17.15,13.97) Wall Walls <123926 CORR>
<nil> Wall Walls <123967 Storefront>
0.32@(5.54,12.96,0.69) FamilyInstance Doors Window_Insert <123981 Window_Insert>
0.24@(11.08,25.92,0.13) Mullion Curtain Wall Mullions Rectangular Mullion <123986 64 x 128 rectangular>
0.29@(11.08,22.37,1.31) Mullion Curtain Wall Mullions Rectangular Mullion <123987 64 x 128 rectangular>
0.34@(5.54,12.96,1.97) FamilyInstance Doors Window_Insert <123990 Window_Insert>
0.29@(10.95,27.23,1.31) Mullion Curtain Wall Mullions Rectangular Mullion <123995 64 x 128 rectangular>
0.29@(11.08,22.37,3.94) Mullion Curtain Wall Mullions Rectangular Mullion <124013 64 x 128 rectangular>
0.29@(11.08,27.1,1.31) Mullion Curtain Wall Mullions Rectangular Mullion <124015 64 x 128 rectangular>
0.29@(11.08,27.1,3.94) Mullion Curtain Wall Mullions Rectangular Mullion <124016 64 x 128 rectangular>
0.24@(11.08,25.92,2.62) Mullion Curtain Wall Mullions Rectangular Mullion <124017 64 x 128 rectangular>
0.29@(10.95,27.23,3.94) Mullion Curtain Wall Mullions Rectangular Mullion <124019 64 x 128 rectangular>
0.6@(-10.02,6.82,1.5) FamilyInstance Windows Fixed <125448 406 x 610>
3.16@(2.85,4.18,0.91) FamilyInstance Doors Double-Glass 1 <126295 1800 x 2100>
252.05@(-24.2,34.28,6.92) Wall Walls <127132 Foundation - 305 Concrete>
236.66@(-1.03,9.27,2.21) FamilyInstance Walls FIREPLACE <127491 FIREPLACE>
51.52@(-31.92,13.3,4.86) Wall Walls <127659 Interior - Partition>
79.29@(-31.83,20.23,5.11) Wall Walls <127660 Interior - Partition>
3.84@(-11.31,6.72,1.2) FamilyInstance Doors Single-Flush <127661 800 x 2100>
3.84@(-9.97,6.72,1.2) FamilyInstance Doors Single-Flush <127662 800 x 2100>
17.84@(-35.67,24.22,5.51) Wall Walls <127663 Interior - Partition>
0.26@(-5.33,3.72,0.31) FamilyInstance Plumbing Fixtures Sink Vanity-Square <127666 508 x 445>
3.84@(-11.92,7.41,1.2) FamilyInstance Doors Single-Flush <127667 800 x 2100>
1.47@(-8.6,1.54,1.38) FamilyInstance Windows Fixed <127718 1219 X 915>
1.47@(-5.51,1.54,1.38) FamilyInstance Windows Fixed <127719 1219 X 915>
28.59@(-27.64,23.9,6.44) Wall Walls <127941 Interior - Partition>
11.78@(-19.42,25.25,4.95) Wall Walls <128006 Interior - Partition>
<nil> CurtainGridLine Curtain Wall Grids <128399 Grid Line>
0.29@(0.69,13.62,0.69) FamilyInstance Doors Window_Insert <128400 Window_Insert>
0.3@(0.69,13.62,1.97) FamilyInstance Doors Window_Insert <128401 Window_Insert>
<nil> CurtainGridLine Curtain Wall Grids <128408 Grid Line>
0.57@(2.29,13.62,0.69) FamilyInstance Doors Window_Insert <128409 Window_Insert>
0.59@(2.29,13.62,1.97) FamilyInstance Doors Window_Insert <128410 Window_Insert>
0.46@(4.58,27.23,0.13) Mullion Curtain Wall Mullions Rectangular Mullion <128432 64 x 128 rectangular>
0.2@(1.37,27.23,2.62) Mullion Curtain Wall Mullions Rectangular Mullion <128433 64 x 128 rectangular>
0.46@(4.58,27.23,2.62) Mullion Curtain Wall Mullions Rectangular Mullion <128434 64 x 128 rectangular>
0.29@(2.41,27.23,1.31) Mullion Curtain Wall Mullions Rectangular Mullion <128450 64 x 128 rectangular>
0.29@(2.41,27.23,3.94) Mullion Curtain Wall Mullions Rectangular Mullion <128452 64 x 128 rectangular>
4.73@(19.5,10.48,9.25) FamilyInstance Columns Rectangular Column <128571 140 X 140>
2.38@(19.5,6.82,3.67) FamilyInstance Columns Rectangular Column <128683 140 X 140>
<nil> CurtainGridLine Curtain Wall Grids <130207 Grid Line>
0.55@(4.42,13.62,0.69) FamilyInstance Doors Window_Insert <130208 Window_Insert>
0.58@(4.42,13.62,1.97) FamilyInstance Doors Window_Insert <130209 Window_Insert>
0.44@(8.85,27.23,0.13) Mullion Curtain Wall Mullions Rectangular Mullion <130248 64 x 128 rectangular>
0.44@(8.85,27.23,2.62) Mullion Curtain Wall Mullions Rectangular Mullion <130249 64 x 128 rectangular>
0.29@(6.75,27.23,1.31) Mullion Curtain Wall Mullions Rectangular Mullion <130256 64 x 128 rectangular>
0.29@(6.75,27.23,3.94) Mullion Curtain Wall Mullions Rectangular Mullion <130257 64 x 128 rectangular>
2.38@(-8.38,34.98,3.67) FamilyInstance Columns Rectangular Column <130550 140 X 140>
4.23@(-5.81,5.05,1.21) FamilyInstance Doors Single-Flush <135477 915 x 2134>
13.47@(-15.67,13.3,4.92) Wall Walls <135527 Interior - Partition>
8.72@(-1.14,2.81,0.13) FamilyInstance Furniture Chair-Corbu <137191 Chair-Corbu>
8.72@(0.4,2.99,0.13) FamilyInstance Furniture Chair-Corbu <137272 Chair-Corbu>
4.73@(-26.85,34.98,9.25) FamilyInstance Columns Rectangular Column <137480 140 X 140>
0.29@(0.37,27.23,1.31) Mullion Curtain Wall Mullions Rectangular Mullion <139162 64 x 128 rectangular>
0.29@(0.37,27.23,3.94) Mullion Curtain Wall Mullions Rectangular Mullion <139163 64 x 128 rectangular>
0.2@(1.37,27.23,0.13) Mullion Curtain Wall Mullions Rectangular Mullion <139229 64 x 128 rectangular>
9.04@(-35.67,18.87,4.92) Wall Walls <140108 Interior - Partition>
15.8@(-39.9,17.9,6.41) Wall Walls <140130 Interior - Partition>
4.39@(-5.72,2.54,0.51) FamilyInstance Doors Bifold-4 Panel <140140 1800 x 2100>
9.04@(-28.17,18.87,4.92) Wall Walls <140190 Interior - Partition>
15.93@(-23.79,17.9,6.27) Wall Walls <140191 Interior - Partition>
4.39@(-3.4,2.54,0.51) FamilyInstance Doors Bifold-4 Panel <140192 1800 x 2100>
33.57@(1.08,8.95,4.79) Wall Walls <140204 Generic - 200>
13.99@(-8.49,6.36,0.37) FamilyInstance Specialty Equipment Dryer <144101 686 x 635 x 889>
13.63@(-10.27,8.48,0.49) FamilyInstance Specialty Equipment Washer <144494 686 x 635 x 889>
4.39@(-4.57,3.4,0.51) FamilyInstance Doors Bifold-4 Panel <144534 1800 x 2100>
4.39@(-3.27,3.4,0.51) FamilyInstance Doors Bifold-4 Panel <144657 1800 x 2100>
10.42@(-27.54,25.45,5.03) Wall Walls <144706 Interior - Partition>
64.17@(5.93,7.23,4.92) Wall Walls <144998 CORR>
22.4@(10.08,9.17,4.92) Wall Walls <145015 CORR>
12.23@(10.58,11.11,4.92) Wall Walls <145032 CORR>
36@(6.75,10.69,2) FamilyInstance Casework Bar <145182 Bar>
6.5@(-7.92,13.3,2.38) Wall Walls <145199 Interior - Partition>
0.29@(0.34,27.23,3.94) Mullion Curtain Wall Mullions Rectangular Mullion <150839 64 x 128 rectangular>
0.29@(0.34,27.23,1.31) Mullion Curtain Wall Mullions Rectangular Mullion <150840 64 x 128 rectangular>
308.55@(-22,6.39,-0.49) Wall Walls <150987 Generic - 305>
134.41@(-44.42,17.07,1.02) Wall Walls <151006 Generic - 200>
256.5@(-25.18,27.08,-0.49) Wall Walls <151081 Generic - 305>
1284.19@(-38.12,13.27,4) Room Rooms <152552 BEDROOM 1 5>
<nil> RoomTag Room Tags <152553 Room Tag>
1298.34@(-25.66,13.27,4) Room Rooms <152555 BEDROOM 2 6>
<nil> RoomTag Room Tags <152556 Room Tag>
420.33@(-27.44,22.07,4) Room Rooms <152557 HALL 7>
<nil> RoomTag Room Tags <152558 Room Tag>
423.9@(-39.98,23.65,4) Room Rooms <152559 BATH 8>
<nil> RoomTag Room Tags <152560 Room Tag>
839.97@(-10.26,9.39,4) Room Rooms <152561 STORAGE 9>
<nil> RoomTag Room Tags <152562 Room Tag>
<nil> ModelLine <Room Separation> <152596 Model Lines>
352.08@(-27.54,25.49,4) Room Rooms <152642 MECH 11>
<nil> RoomTag Room Tags <152643 Room Tag>
19.63@(-6.85,1.82,0.17) FamilyInstance Furniture Bed-Box <153466 Double 1346 x 1880>
19.63@(-3.76,1.79,0.17) FamilyInstance Furniture Bed-Box <153556 Double 1346 x 1880>
<nil> ReferencePlane Reference Planes <165634 Reference Plane>
<nil> Opening Rectangular Straight Wall Opening <166134 Rectangular Straight Wall Opening>
0.47@(-2.86,22.65,0.01) FamilyInstance Furniture Rug_zk <167847 1220 x 2134>
2.44@(-0.57,4.53,0.23) FamilyInstance Furniture Table-Coffee <168561 915 x 1830 x 457>
0.02@(-1.7,11.35,0.98) FamilyInstance Generic Models teapot <169568 teapot>
0.1@(-2.09,6.25,0.48) FamilyInstance Lighting Fixtures Floor Lamp 1 <171113 150 watt Halogen>
3@(-14.28,8.03,0.18) FamilyInstance Plumbing Fixtures Tub-Rectangular-3D <178179 Tub-Rectangular-3D>
<nil> CurtainGridLine Curtain Wall Grids <178753 Grid Line>
0.39@(11.19,23.55,1.38) Panel Curtain Panels System Panel <178754 Glazed>
0.41@(11.19,23.55,3.94) Panel Curtain Panels System Panel <178755 Glazed>
0.24@(11.08,23.55,0.13) Mullion Curtain Wall Mullions Rectangular Mullion <178774 64 x 128 rectangular>
0.24@(11.08,23.55,2.62) Mullion Curtain Wall Mullions Rectangular Mullion <178775 64 x 128 rectangular>
0.29@(11.08,24.73,1.31) Mullion Curtain Wall Mullions Rectangular Mullion <178782 64 x 128 rectangular>
0.29@(11.08,24.73,3.94) Mullion Curtain Wall Mullions Rectangular Mullion <178783 64 x 128 rectangular>
<nil> Room Rooms <180268 LIVING ROOM 12>
<nil> RoomTag Room Tags <180269 Room Tag>
11.72@(-0.33,2.33,0.13) FamilyInstance Furniture Chair-Corbu <181500 Couch Corbu>

This is more than enough for me and my rather quick and dirty exploration of this. Improved filtering and error handling is left as an exercise to the inclined reader.

Download

Here is GetCentroid.zip containing the complete source code, Visual Studio solution and add-in manifest for this command.

Boost Your BIM and Dance with an Elephant

Advent, advent! Yet another Revit API focused blog is born!

Harry Mattison, ex Revit API development team, has initiated Boost Your BIM and kicked it off with a series on using the built-in SharpDevelop development environment Revit macros to resolve duplicate tags:

1. Finding elements
2. Finding only family instances
3. Get & set parameter values
4. Transactions and wrapping up

Thank you, Harry, and the best of luck to you and your new blog!

Dances with Elephants

Also, for a more high-level strategic vision of things, don't forget to take a look now and then at Jim Quanci's Dances with Elephants.

Jim analyses how small companies can leverage big ones to help build their business, useful tactics eminently applicable to many Revit add-in developers.

He recently posted a number of exciting new essays, so I encourage you to go take a gander.

The Champions Roundtable at AU

Tuesday we held a DevLab at AU successfully exploring and resolving a bunch of interesting issues. I hope to get around to documenting and sharing some of them soon, before being overwhelmed by other new exciting stuff. The most pressing priority first, though: sharing the notes from the Revit API roundtable session.

My first session at AU was a very pleasant, comfortable and fun one, being a roundtable providing a free-for-all exchange of questions, views and feedback between the audience and a bunch of Autodesk employees. The Autodesk side included developers creating the Revit API, ADN developer supporters supporting people in making use of it, and consultants who actually use it themselves. The audience was you guys.

We tried to keep the questions and answers short and to the point, and I tried to take notes of everything said. They are provided below, only very slightly edited for readability, and possibly cryptic for those of you who did not attend the session. I wish you some enjoyable head-scratching trying to decipher what we actually meant.

Before we dive into the notes, here are its AU catalogue entry and a very few slides listing the goal of this meeting and the panellists answering the questions:

CP4109 – Revit API Round Table: Meet the Champions

Class Summary

• Interact with a panel of Autodesk Revit API experts
• Ask questions and discuss topics of your choice
• Get to know the people who shape the APIs you work with better
• Explain your views, ideas and problems directly face to face

Learning Objectives

At the end of this class, you will have

• Interacted with a panel of Autodesk Revit API experts
• Asked questions and discussed topics of your choice
• Got to know the people who shape the APIs you work with better
• Explained your views, ideas and problems directly face to face

Panellists

• Arnošt Löbel, Revit Developer
• Augusto Gonçalves, ADN
• Jeremy Tammik, ADN
• Miroslav Schonauer, Consulting
• Saikat Bhattacharya, ADN
• Steven Mycynek, Revit API Engineer

Learning More

• Revit Developer Center: DevTV and My First Plugin Introduction, SDK, Samples, API Help
• Developer Guide and Online Help
• API trainings, webcasts and archives > Revit API
• Discussion groups > Revit Architecture > Revit API
• API training classes
• ADN AEC DevBlog
• The Building Coder Revit API Blog
• ADN and ADN Open, The Autodesk Developer Network
• DevHelp Online for ADN members

Almost Unedited Notes from the Session

Here are my session notes in a rough and almost verbatim Q&A format:

What is coming up in future versions? We cannot talk about that here. Please join ADN for more info, sign an NDA agreement.

Why are you guys using Macs? No Autodesk or Revit-specific reason.

What are some common themes or requests for API app development? Hard to say, depends on company; high level: getting data from Revit, enterprise wide integration, setting up a BIM enterprise structure, company specific needs...

How can I effectively run a batch operation to open successive work shared Revit files and run an external command on them? Keep track of the processes; expect to handle failure and recovery. What do you want to achieve? You can use journaling, but not recommended. Open file, close file. No problem in theory. We are not leaking any memory. Managed stuff gets garbage collected eventually. To launch command automatically, install an external application and register for the OnDocumentOpenend event. Lots of communication pipelines available, various messaging mechanisms. What do you want to achieve? Export data to SQL, for example. One app doing this in a batch process, download file from Revit server. Ensure that the app provides feedback on what it is doing, log the events, be able to study log file. Maybe 1000 files process well and one of them fails. Saikat created a plug-in of the month which batch processes RVT files to upgrade them to a newer version doing SaveAs; it also logs all events and writes to text file. You can also look at the progress notification introduced in Revit 2013, that provides more feedback

General organisation of elements inside Revit: family dictates behaviour, categories, etc. this limits some things, pretty strict structure. Will this change? No, not significantly. We can take this as feedback.

External RealDWG application creates 3D drawing using Revit API? Develop Revit external application which queries external data source, query it regularly to write feedback... Revit threading model does not allow for directly attaching, need to use some kind of messaging model. An external program cannot directly access the Revit API.

AutoCAD provides the command console allowing data access without GUI... is anything similar coming for Revit? That would be a nice enhancement. Originally there was no API for Revit, it was highly user focused, and the thought was it would never need an API.

It is currently not possible to access the Revit database without opening Revit. What is the reason for that? You are always opening an application to access its complex internal data structures. It may be happening in the background, invisibly. We should be able to provide some kind of RealDWG-like access sometime in the future to RVT as well.

We would like to parametrically change the model to run different energy simulations on it; changing one parameter affects many other ones, creating a new model to export, but I do not want to see the changes, just change the model without visual feedback. How can this be achieved? The Revit model is parametric, you cannot even query it without regeneration, and it is in an invalid state until regeneration, e.g. transaction committed, half-baked until then. You can open documents in the background, then they are not visualised. Call OpenDocumentFile, it opens in the database but not in the UI. Later we added OpenAndActivate, which does both. Regeneration is smart. Revit updates only the minimal set requiring it. If you regenerate twice in a row, the second call does nothing.

Do I need to commit the transaction to ensure the model is correctly updated? Technically yes, but sometimes no. Sometimes the transaction needs to be committed to propagate the changes fully, sometimes simply regenerating is sufficient.

The API is great at customising the ribbon, but a more important aspect of Revit is its parameters, and there is little help there for users. Is there any way to improve this? We looked at putting a real API around parameters. Talk with the product managers, they need to balance requirements. Parameters could definitely be easier to use.

Managing large numbers of large Revit project files, it is difficult to keep everything up to date. Some people create a new local file every day, even update the central file. How stable is the program? Do I need to do anything to protect my model? We only create small test models. Some people create huge files. Stability is getting better all the time; regression tests improve all the time. Best practices improve. Most Revit problems have to do with not following best practice. The Revit API and every add-in always needs to respect best practice, not fight it. Completely different from other CAD systems. Big investment, understand the product and best practice.

Managing Revit server effectively? What are the best practices? It may be ok to update users every year, but painful to do so for servers, it is painful to update servers every year like Revit users. Is Revit server on the same release cycle as the Revit product? What would the alternative be? The file format should not change every release.

Can we edit a group in the API? No, you have to ungroup and regroup. There are some blog posts on this. If multiple instances of the group exist, you have to replace all the instances.

The dynamic updater framework can display a missing updater warning. Can I suppress that? There is an option to suppress that screen. When you register the updater you can set it as optional, so the end user is not bothered by the message if it is missing. Before that option appeared, you could just open the file without the updater, choose to ignore the missing updater, and save the file before sending it to someone else. Now you can control it as the updater implementer.

Some families have options for how they look in different views. Can I make other categories do the thing? Some families will only allow plan view. Can you achieve this from the UI? No. In that case you cannot do it programmatically either. Now I have to go and tag every damper in the section. The aim is to provide API access to everything available in the UI.

Issues with shared families. A family with no instances placed creates an instance of its geometry even if it is not placed. If an instance is placed which conflicts with the geometry, it can cause a 'cannot make type' error. How can this be worked around? This is a regeneration issue. Query noted.

How can I check what Revit is doing? Use the progress notification, which tells you all the sub-steps happening during transactions. You might have to do some primitive benchmarking.

Are processes that occur during regen behind the scenes documented in the journal file? Some stuff is, it is up to the individual programmer. They can check a journal coming back from a customer. The content may be cryptic and does not explain. Sometimes debugging significantly impacts performance, of course.

When I open a transaction on a work shared model, should I verify that all elements can be modified before committing the transaction? I don't think you can check whether an individual element is modifiable. There was a plan, maybe, for that. This kind of feature has been requested. Currently the transaction will be rolled back. Actually you can check this somehow, maybe.

DesignScript is now integrated in AutoCAD. Are there any plans for providing this in Revit as well? We would like to create parametric masses. DesignScript looks as if it is open enough to be integrated into Revit. No new language integration is simple, but it looks as if it might fit and be useful.

What are the most prominent issues you run across, the most common things that pops up? Install RevitLookup, explore the model. Driving from external process, use Idling event. Daily requests: multithreading, 100% API coverage of worksharing functionality, integration and speed. When we get several similar requests, we blog about them, either on The Building Coder or the ADN AEC DevBlog. Why do you ask this, actually? Just for sharing and discussing here together. Also we keep receiving recurring issues. It helps to know the real good solution. Another common issue: how to get data from Revit and export to Excel or Access, and reimport. It is easy, but customers face many challenges, lots of countrification needs. People coming from other CAD systems and used to the sketch plane modelling and create feature are a bit surprised by Revit family editor and constraints and dimensions etc. It is possible to create a dimensioned family and make it parametric through the API. That is not intuitive, that is a challenge. Take a few steps back, look at how Revit does things, and then reproduce that relationship programmatically. Revit is not mechanical engineering. Understand the UI first, and then move on to API.

Do you follow the Autodesk discussion forums? Yes.

Can I use formulas to establish parametric relations between different families, e.g. if I want the width of family A to be driven by the height of family B? Good question, not currently supported.

Can I access the document warnings? There is the failure API, but no access to the warnings. There are ways to get rid of failures. Install the failure processor at application level. You get called when transaction ends and if there are failures your processor is called and you can decide how to handle them. I get a model and it has 300 warnings in it. Can I get that list? The failure processor does not give you that list? No, probably not. If you go to look at warnings in Revit, you can export that list to a text file. It would be nice to be able to fix warnings such as the 'line off axis', provide tools and options to fix this, or an option to leave it as it is.

Every column I touch is part of a phase and design option. Currently the phase mapping is not part of the Revit API. I run into problems trying to match phases when they differ between linked and host model. We have a link API in 2013 and a list of additions, I think something more will be coming in that area. The goal for the API is to provide 100% access to all end user features. Right now all new features are automatically exposed to the API as well.

C# versus VB? It all goes to the same place. It all compiles to IL and can be decompiled as well.

Dispose is inherited through the class hierarchy from APIObject. Do we need to dispose of all the objects we use? It is probably good practice. It happens eventually through the GC. We have scoped objects, everything with a start and an end, e.g. transaction. If you dispose that, it is automatically ended. The easiest way is to use a 'using' block. You must call Commit, Rollback or Dispose. APIObject is only a very thin wrapper. Dispose does not actually do anything. If you need to clean up memory and access a lot of data from Revit, you may want to call Dispose yourself in between loop iterations, e.g. If you do not call Dispose, Revit will hold on to the object even if GC is called. If you call Dispose, then we let go. When the command ends, everything is disposed. Revit elements can have an unpredictable lifetime. It is always safer to hold on to an element id rather than an element. Native pointers are invalidated. You can test whether an element is invalid. You can modify an element, then delete it, undo the deletion, and the element pointer will go from valid to null and back to valid again. You do not have to refetch the element, actually, Revit handles its validity. The API creates a managed wrapper around the native pointer.

Error reporting. When a user has an error and we do not have all the info. Is there a central file location where more error reporting is available? Beside the journal there is something worksharing related log file, extension 'slog', monitoring activity between local and central, meant for programmers, not customers, that might provide some hints. Same folder as central file.

Insight into eTransmit? Visit Arnošt's AU session on Wednesday.

Unique id? Working with linked files, the unique id can actually be the same for different files. Looking for a view n a linked file, the view in link and host has the same unique id. Element id yes, of course, they only work within the session, and might change due to worksharing session, but unique id should be stable and unique. If you see a duplicate unique id, please report it to us.

What are the coolest projects you have seen? The ruby scripting plugin and its installer. ZoomToAwesome, which basically consists of one single line of code.

A plugin can bring down Revit. This should not happen. Revit builds in protection in the external command framework that should shield Revit and the end user from all misbehaviour. Dynamic updaters as well. App can cause exception within exception, very hard to protect against. We make it as robust as possible, and still try to open up wide and give you all the options. Example: call a command, do something bad, invalid geometry, try to commit transaction, failure handling, try to resolve, you have a failure resolver, this causes another exception, things can get really bad. A point about add-ins, which is a limitation of .NET and Windows: if your add-in uses COM interop and dereferences an invalid pointer, we cannot protect against that. Unsafe code and p/invoke cannot be protected completely.

Reload the keynotes text file from the API. Not supported, sorry.

Building is data. Can we tap into that without dB link? Direct query?

Thank you for a very interesting discussion with numerous insights on both sides! Have fun using the Revit API!

The Temporary Transaction Trick for Gross Slab Data

Last week I provided an updated version of the CmdSlabBoundary external command to determine a floor slab boundary.

Here is a follow-up to that issue:

Question: The solution provided to retrieve the slab boundary works fine for me if no openings are cut out.

I have a situation where my slabs are cut by openings, however, and I need to retrieve the original uncut gross slab boundary.

Here is an example with two slabs A and B and an opening cutting out part of both of them:

The solution provided retrieves the cut out net slab boundary:

How can I obtain the following original gross uncut slab boundary?

Answer: One way to obtain the unmodified geometry of the slab is to use the temporary transaction trick to temporarily eliminate all openings and other elements affecting its shape.

This technique was used to determine gross material quantities of floors, walls and roofs in the material quantities sample from Scott Conover's Autodesk University 2009 class on analysing building geometry, which was later add to the Revit SDK as the MaterialQuantities sample.

It shows how the transaction handling for the temporary operation can be simply and cleanly encapsulated.

It analyses the material quantities of walls, floors, and roofs, and outputs the result to Excel by implementing the following steps:

1. Collect all roof elements
2. Iterate through each material found in each roof element
3. Find the net volume and area of the material
4. Store the material quantities
5. Write the results to the output file
6. Find the gross material quantities
   1. Start a new transaction
   2. Delete the elements that cut the host (doors, windows, openings)
   3. Find the volume and area for each material
   4. Store the material quantities
   5. Write the results to the output file
   6. Rollback the transaction
7. Repeat the above steps for walls and floors
8. Open the output file in Microsoft Excel

To determine the boundary lines of the floor slab with all opening removed, you could proceed in the same fashion as described in step 6 for obtaining the gross material quantities.

Temporarily delete then openings in a separate transaction, retrieve the original slab geometry, and abort the transaction to restore the original state.

This technique is easy to implement. We reused this method for many different purposes a number of times, e.g.

• Determine host reference
• Material quantity extraction
• Unmodified element geometry
• Object relationships (VB)
• Retrieve all model elements via a temporary 3D view
• Access to sketch and sketch plane
• Retrieve unjoined wall geometry
• Retrieving detailed wall layer geometry
• Unit conversion and display string formatting
• Determine Revit demo mode

Addendum: Arnošt Löbel pointed out that this will not always work. Some modifications require the transaction to be committed before they take full effect. The workaround for that is to enclose it within a transaction group and roll back the group at the end.

Apphack @ AU

Do you have an interesting AutoCAD app you would like to publish?

Will you attend Autodesk University 2012 and would you like to win an attractive prize?

If so, take a look at the APPHACK @ AU Hackathon:

The official rules list some great prizes. Unfortunately, they also restrict the participation to AutoCAD apps, so Revit add-ins are not permissible.

Kean Walmsley provides a a few more details.

Revit 2013 Update Release 2

Revit 2013 Update Release 2 is now available.

I found a path to the Revit Architecture update via Autodesk Revit Products > Services & Support > Service Packs & Downloads > Autodesk Revit Architecture > Updates > Revit Architecture 2013 Update Release 2.

Phew. That was rather hard.

A much easier way to reach the exact download I am after is to enter the appropriate string in Google. That takes me directly to the download page with no need to manually traverse any convoluted search paths.

Here is a list of the Google search strings I entered and the resulting URLs:

• autodesk revit 2013 ultimate design suite update 2.
• autodesk revit 2013 architecture update 2
• autodesk revit 2013 mep update 2
• autodesk revit 2013 structure update 2

Here are the enhancements listed for this update. API enhancements are not included this time, unfortunately, but there are some of those in there as well:

Revit Architecture

• Improves stability when upgrading 2012 project which contains analytical walls.
• Improves stability when adjusting multiple sketch lines of a floor at the same moment.
• Improves stability when editing the gutters on a roof object with the Add/Remove Segment tool.
• Improves stability when renaming a Stair run type or landing to ‘none’.
• Improves stability when using the ribbon Cancel Edit Mode button to exit Stair Edit Mode.
• Improves stability when using an open profile for a wall sweep.
• Improves stability when splitting a wall.

Revit Structure

• Enables the Area, Area Boundary and Tag Area ribbon commands.
• Improves stability when using Beam Systems.
• Improves the respect of the Top In-Plane parameter for Analytical Models Walls after wall is modified.
• Improves the joining of Rebar to the host surfaces.
• Improves retention of Rebar Shapes upgraded within Revit 2012 projects.
• Improves stability when editing Rebar Shapes in the Family Editor.
• Improves display of underlay items in non-wireframe Structural Views.

Revit MEP

• Improves stability when sizing Duct.
• Corrects the use of tees when specified in duct routing preferences within projects upgraded from Revit 2012.
• Improves stability when upgrading a pipe fitting connected to multiple systems.
• Improves stability when editing duct fitting size in the active view and then editing the duct fitting type in the Property Palette.

Revit Platform

• Improves stability when Save to Central or Sync with Central.
• Improves stability when utilizing Create Assembly Views from the project browser.
• Improves stability when editing a label within the family editor.
• Improves stability when saving file to a location with low disc space.
• Improves stability when launching Export gbXML Settings dialog.
• Improves stability and memory usage within graphics display.
• Improves stability during IFC data import which contains openings with no usable geometry.
• Improves stability when importing IFC data which imported into Revit 2012 with warnings.
• Improves import of clipped solids during IFC import.
• Improves IFC Export to support buildingSMART International IFC certification.
• Improves stability when linking or attached DWG files.
• Improves stability of printing after Export to DWG or DXF format.
• Improves stability when creating, duplicating or deleting a material in the Material Editor.
• Improves the retention of part parameters within a part upgraded from Revit 2012.
• Corrects ribbon tab population after installing .NET 4.5
• Improves stability while editing calculated values within a schedule after deleting a parameter used in a formula.
• Improves stability with schedules which contains a filter based upon a user defined parameter and elements in linked files do not contain the user defined parameter.
• Improves stability when opening Sun Settings dialog.
• Improves stability when editing Text Notes.
• Improves stability when upgrading Revit 2012 project to Revit 2013.
• Improves stability when moving a Crop Region which utilizes the disjoin option.

The build identifier is 20121003_2115 Update Release 2.

UIView, Windows Coordinates, ReferenceIntersector and My Own Tooltip

Here is my well-meant contribution to making this the most exciting Wednesday of your entire week.

For the first time in history, the Revit 2013 UIView class provides a possibility to convert back and forth between Revit model coordinates and Windows device screen points.

I imagined making use of that right away when I read about the UIView class, and mentioned it when discussing UIView and Windows device coordinates.

I am still a bit surprised that I have not yet received any questions about these exciting possibilities. Well, anyway, that gives me a chance to finally dive into this exploration free of preconceptions.

Another Revit 2013 topic that I wanted to talk about for a long time is the new ReferenceIntersector class. My previous attempts at publishing anything on it were thwarted by running into some unintended features which have meanwhile been attended to.

Now I can combine both of these topics into a single nice example, presenting my very own tooltips displaying any information I like based on the cursor location in the Revit BIM.

Does that sound cool, or what?

To give you an idea of what I am talking about, here is a two-minute video depicting a sample run demonstrating the final result, with the normal Revit tooltips and my own specialised ones displayed side by side.

To run the demo, I open up the basic architectural sample project, switch away from the perspective view, since add-ins are disabled there, select Level 2, turn on my own tooltips, hover around different elements to compare the Revit tooltip with my own one, and turn off my tooltips again:

Table of Contents

To display a useful tooltip, the user needs to be free to play around in the model.

Simultaneously, my add-in needs to be able to access the Windows cursor location, determine the corresponding Revit model coordinates from it, and query the Revit BIM to determine the information I would like to display.

This calls for an Idling event handler, adding a third topic to the two already mentioned above.

We thus end up with the following list, including hints on the respective approaches, solutions, and helper methods:

• Top-level form and Idling event management: ModelessForm_IdlingEvent.
• Helper methods: GetActiveUiView, GetView3d, ElementDescription.
• Idling event handler:
  • Access Windows cursor location: System.Windows.Forms.Cursor.Position.
  • Determine Revit model coordinates: UIView.
  • Query Revit BIM for information: ReferenceIntersector.
  • Display tooltip: JtTooltipForm.
  • Entire implementation.
• Toggle tooltip on and off commands.
• Conclusion and download.

Before closing, I also mention Saikat's new posts on multi-image naming conventions and text file TaskDialog command links, DesignScript availability on Autodesk Labs, and a nice video of my friend Falk on the Schafberg.

Top-level Form and Idling Event Management

As you hopefully know by now, the implementation to handle the Idling event needs to be really clean and clear and is a little bit tricky.

I strongly suggest basing anything you do on the ModelessForm_IdlingEvent SDK sample.

If you implemented your Idling event handler in any other way in the past, it might be a good idea revisiting it now and comparing notes with that sample.

I based my WinTooltip external application on it, anyway.

It handles all the modeless form interaction in the external application implementation.

In my case, the modeless form is either a Visual Studio designer generated JtTooltipForm or a hand-built JtTooltipForm2.

The external application is instantiated as a singleton instance, and provides public access to that instance so that external commands can access it and use its functionality to show and hide the modeless form.

It implements an internal CloseForm method, public methods ShowForm and HideForm, called by the external commands, and the standard interface methods OnStartup and OnShutdown, like this:

  /// <summary>
  /// Singleton external application class instance.
  /// </summary>
  internal static App _app = null;
 
  /// <summary>
  /// Provide access to singleton class instance.
  /// </summary>
  public static App Instance
  {
    get { return _app; }
  }
 
  /// <summary>
  /// The tooltip form to display.
  /// </summary>
  internal static JtTooltipForm2 _form = null;
 
  /// <summary>
  /// Dispose and null out form.
  /// Return true if it was previously not disposed.
  /// </summary>
  static bool CloseForm()
  {
    bool rc = _form != null;
 
    if( rc )
    {
      if( !_form.IsDisposed )
      {
        _form.Dispose();
      }
      _form = null;
    }
    return rc;
  }
 
  /// <summary>
  /// Create and show the form, 
  /// unless it already exists.
  /// </summary>
  /// <remarks>
  /// The external command invokes 
  /// this on end-user request.
  /// </remarks>
  public void ShowForm( UIApplication uiapp )
  {
    // If we do not have a form yet, create and show it
 
    if( _form == null || _form.IsDisposed )
    {
      // Instantiate JtTooltipForm to use 
      // the designer generated form.
 
      _form = new JtTooltipForm2();
 
      _form.Show();
 
      // If we have a form, we need Idling too
 
      uiapp.Idling += IdlingHandler;
    }
  }
 
  /// <summary>
  /// Hide the form.
  /// </summary>
  /// <remarks>
  /// The external command invokes 
  /// this on end-user request.
  /// </remarks>
  public void HideForm( UIApplication uiapp )
  {
    if( CloseForm() )
    {
      // If the form was showing, we had subscribed
 
      uiapp.Idling -= IdlingHandler;
    }
  }
 
  public Result OnStartup( UIControlledApplication a )
  {
    _app = this;
    _form = null;
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown( UIControlledApplication a )
  {
    if( CloseForm() )
    {
      a.Idling -= IdlingHandler;
    }
    return Result.Succeeded;
  }

Helper Methods

Apart from the top-level management, the Idling event handler does all the rest of the work.

Before we get to the event handler itself, I'll present the three helper methods it uses:

• GetActiveUiView: retrieve the active UIView.
• GetView3d: retrieve the 3D view named "{3D}".
• ElementDescription: return a descriptive text for a given Revit element.

We can get the active document view directly, but need some additional coding to determine the associated UIView, for example like this:

/// <summary>
/// Return currently active UIView or null.
/// </summary>
static UIView GetActiveUiView( 
  UIDocument uidoc )
{
  Document doc = uidoc.Document;
  View view = doc.ActiveView;
  IList<UIView> uiviews = uidoc.GetOpenUIViews();
  UIView uiview = null;
 
  foreach( UIView uv in uiviews )
  {
    if( uv.ViewId.Equals( view.Id ) )
    {
      uiview = uv;
      break;
    }
  }
  return uiview;
}

The ReferenceIntersector constructor requires a 3D view argument in which the ray tracing takes place. In this sample, I assume that a suitable 3D view named "{3D}" is available and retrieve that using one single line of filtered element and LINQ driven code:

/// <summary>
/// Return the 3D view named "{3D}".
/// </summary>
View3D GetView3d( Document doc )
{
  return new FilteredElementCollector( doc )
    .OfClass( typeof( View3D ) )
    .Cast<View3D>()
    .FirstOrDefault<View3D>( 
      v => v.Name.Equals( "{3D}" ) );
}

You can obviously modify this in any way you like and set up a suitable 3D view to suit your specific view setting, sectioning and filtering needs.

The location dependent BIM information displayed in the tooltip can be determined completely freely. In my case, I simply detect what element the cursor is hovering over and use the ElementDescription method to put together a descriptive text for it:

/// <summary>
/// Return a string describing the given element:
/// .NET type name,
/// category name,
/// family and symbol name for a family instance,
/// element id and element name.
/// </summary>
static string ElementDescription(
  Element e )
{
  if( null == e )
  {
    return "<null>";
  }
 
  // For a wall, the element name equals the
  // wall type name, which is equivalent to the
  // family name ...
 
  FamilyInstance fi = e as FamilyInstance;
 
  string typeName = e.GetType().Name;
 
  string categoryName = ( null == e.Category )
    ? string.Empty
    : e.Category.Name + " ";
 
  string familyName = ( null == fi )
    ? string.Empty
    : fi.Symbol.Family.Name + " ";
 
  string symbolName = ( null == fi
    || e.Name.Equals( fi.Symbol.Name ) )
      ? string.Empty
      : fi.Symbol.Name + " ";
 
  return string.Format( "{0} {1}{2}{3}<{4} {5}>",
    typeName, categoryName, familyName,
    symbolName, e.Id.IntegerValue, e.Name );
}

This is somewhat similar to and yet does not exactly match the information displayed by the standard Revit tooltip and other parts of the user interface, as you might have noticed in the video recording.

Idling Event Handler

The Idling event handler implements the following steps, which we first discuss one by one before presenting the entire code in context:

• Access Windows cursor location: System.Windows.Forms.Cursor.Position.
• Determine Revit model coordinates: UIView.
• Query Revit BIM for information: ReferenceIntersector.
• Display tooltip: JtTooltipForm.
• Entire implementation.

Access Windows Cursor Location

Converting from the cursor position retrieved in Windows device coordinates to Revit model coordinates is possible by calculating the relative position in the UIView.

Here is an illustration assuming a screen resolution of 1600 x 1200 with a Revit view located at the rectangle 800,150 to 1500,650, displaying a plan view of part of the Revit model, with model coordinates ranging from 10,40,0 to 220,120,0. The current cursor location is represented by the green spot:

The Windows device coordinate origin 0,0 is at the upper left, and Y values increase downwards, whereas the Revit model coordinate Y values increase upwards.

You can easily query the cursor position in device coordinates on the Windows screen from .NET framework at any time using the System.Windows.Forms.Cursor.Position property:

  Point p = System.Windows.Forms.Cursor.Position;

Determine Revit Model Coordinates

The cursor location is obviously returned in Windows device coordinates, stored in the point (or vector) variable 'p'.

The aim is to determine the location indicated by this point in Revit model coordinates, for example by determining the vector v from the lower left corner of the Revit view to that location.

We can easily determine the relative position of p between the two corners of the UIView in Windows device coordinates by subtracting the lower left hand corner and dividing by the total width and height to obtain the relative width and height location values dx and dy like this:

  UIView uiview = GetActiveUiView( uidoc );
 
  Rectangle rect = uiview.GetWindowRectangle();
 
  Point p = System.Windows.Forms.Cursor.Position;
 
  double dx = (double) ( p.X - rect.Left )
    / ( rect.Right - rect.Left );
 
  double dy = (double) ( p.Y - rect.Bottom )
    / ( rect.Top - rect.Bottom );

From the UIView, we can also determine model coordinates of the view corners. They are stored in a and b, respectively.

Now it is easy to calculate the cursor point 'q' in model coordinates from the two relative values like this:

  IList<XYZ> corners = uiview.GetZoomCorners();
  XYZ a = corners[0];
  XYZ b = corners[1];
  XYZ v = b - a;
 
  XYZ q = a
    + dx * v.X * XYZ.BasisX
    + dy * v.Y * XYZ.BasisY;

Query Revit BIM for Information using ReferenceIntersector Ray Casting

Once we have the model space cursor location 'q', we can calculate a point beyond the model extents (hopefully) from which one can picture the user looking into the model.

The first element intersected by a ray cast from that point in the view direction should be the one we are interested in displaying information about.

Initially, the sample run was a bit boring, because the only element encountered when looking from straight above was always the roof.

I tweaked that to make the example more interesting, not by modifying the model itself – I use the standard architectural basic sample project rac_basic_sample_project.rvt – but by adding a filter to remove all roof category elements from the reference intersector results instead. The exact elements of interest and information to display are entirely up to you and your needs to determine, of course.

The ray casting requires a 3D view to operate in. In this case, I simply pick the one named "{3D}" returned by the GetView3d helper method. You can set up your own view with specific graphics properties, section cuts, and only certain elements visible, if that better suits your requirements.

Here is the code determining the view, view direction and ray origin, setting up the intersector, determining the target element, and defining the tooltip text to display in the variable 's':

  View3D view3d = GetView3d( doc );
 
  XYZ viewdir = view.ViewDirection;
 
  XYZ origin = q + 1000 * viewdir;
 
  // Find all elements:
 
  //ReferenceIntersector ri
  //  = new ReferenceIntersector( view3d );
 
  // Find all elements except roofs:
 
  ElementFilter f = new ElementCategoryFilter( 
    BuiltInCategory.OST_Roofs, true );
 
  ReferenceIntersector ri 
    = new ReferenceIntersector( f, 
      FindReferenceTarget.Element, view3d );
 
  ReferenceWithContext rc
    = ri.FindNearest( origin, -viewdir );
 
  string s = "Element not found";
 
  if( null != rc )
  {
    Reference r = rc.GetReference();
 
    Element e = doc.GetElement( r );
 
    s = ElementDescription( e );
  }

Display Tooltip and the JtTooltipForm class

I originally used the Visual Studio designer to create a simple tooltip form named JtTooltipForm for me, then tweaked that auto-generated code to create one named JtTooltipForm2 myself programmatically from scratch.

Besides the constructor setting up the form and the Label object to display the tooltip text, it also manages an offset from the cursor position at which to display itself, provides a method to set the tooltip text, and overrides the OnShown and OnVisibleChanged methods to react appropriately to position changes:

/// <summary>
/// A tooltip window designed to move 
/// around with the cursor position.
/// </summary>
class JtTooltipForm2 : Form
{
  /// <summary>
  /// The offset from the mouse pointer 
  /// at which to show the form.
  /// </summary>
  public Point Offset { get; set; }
 
  /// <summary>
  /// Tooltip text.
  /// </summary>
  Label _label;
 
  /// <summary>
  /// Set the tooltip text.
  /// </summary>
  public void SetText( string s )
  {
    _label.Text = s;
  }
 
  /// <summary>
  /// Move the window to an offset of mouse pointer.
  /// </summary>
  protected override void OnShown( EventArgs e )
  {
    base.OnShown( e );
 
    Location = new Point(
      MousePosition.X + Offset.X,
      MousePosition.Y + Offset.Y );
  }
 
  /// <summary>
  /// Move the window to an offset of mouse pointer.
  /// </summary>
  protected override void OnVisibleChanged(
    EventArgs e )
  {
    base.OnVisibleChanged( e );
 
    if( Visible )
    {
      Location = new Point(
        MousePosition.X + Offset.X,
        MousePosition.Y + Offset.Y );
    }
  }
 
  public JtTooltipForm2()
  {
    Size = new Size( 200, 20 );
 
    _label = new Label();
 
    SuspendLayout();
 
    _label.AutoSize = false; // the label will not change its height automatically, only width, so switch off AutoSize to wrap text
    _label.CausesValidation = false;
    _label.Dock = DockStyle.Fill;
    _label.Location = new Point( 0, 0 );
    _label.Size = new Size( 35, 13 );
    _label.Parent = this;
 
    AutoScaleDimensions = new SizeF( 6F, 13F );
    AutoScaleMode = AutoScaleMode.Font;
    BackColor = SystemColors.Info;
    ClientSize = new Size( 200, 12 );
    Controls.Add( _label );
    FormBorderStyle = FormBorderStyle.None;
    Name = "JtTooltipForm";
    Opacity = 0.8D;
    ShowInTaskbar = false;
    TopMost = true;
    TransparencyKey = Color.White;
 
    ResumeLayout( false );
    PerformLayout();
 
    Offset = new Point( 10, 0 );
  }
}

You may note that I switched off the AutoSize property. Setting it to true enables the label to automatically expand, and that just means getting wider to fit the text length. The label will not change its height automatically, only width.

A neat trick to wrap text before putting it into the label that I spotted and did not make use of employs a regular expression to do the job:

  WrappedMessage := RegExReplace( 
    LongMessage, "(.{50}\s)", "$1`n" );

Controlling the text and position from the Idling event handler is a trivial two-liner:

  // Move tooltip to current cursor 
  // location and set tooltip text.
 
  _form.Location = p + new Size( _form.Offset );
  _form.SetText( s );

Entire Idling Event Handler Implementation

For better readability, here is the entire Idling event handler implementation in all its glory.

It even includes one slight improvement that is not demonstrated by the ModelessForm_IdlingEvent SDK sample implementation:

If the Revit project is closed while the Idling event is still subscribed to, the UI document may be null. One needs to add a check for that situation as well in the Idling handler, in case the hander relies on an open document.

/// <summary>
/// Idling event handler.
/// </summary>
/// <remarks>
/// We keep the handler very simple. First check
/// if we still have the form. If not, unsubscribe 
/// from Idling, for we no longer need it and it 
/// makes Revit speedier. If the form is around, 
/// check if it has a request ready and process 
/// it accordingly.
/// </remarks>
public void IdlingHandler( 
  object sender, 
  IdlingEventArgs args )
{
  UIApplication uiapp = sender as UIApplication;
  UIDocument uidoc = uiapp.ActiveUIDocument;
 
  if( null == uidoc || _form.IsDisposed )
  {
    uiapp.Idling -= IdlingHandler;
  }
  else // form still exists
  {
    Document doc = uidoc.Document;
    View view = doc.ActiveView;
 
    UIView uiview = GetActiveUiView( uidoc );
 
    Rectangle rect = uiview.GetWindowRectangle();
 
    Point p = System.Windows.Forms.Cursor.Position;
 
    double dx = (double) ( p.X - rect.Left )
      / ( rect.Right - rect.Left );
 
    double dy = (double) ( p.Y - rect.Bottom )
      / ( rect.Top - rect.Bottom );
 
    IList<XYZ> corners = uiview.GetZoomCorners();
    XYZ a = corners[0];
    XYZ b = corners[1];
    XYZ v = b - a;
 
    XYZ q = a
      + dx * v.X * XYZ.BasisX
      + dy * v.Y * XYZ.BasisY;
 
    // If the current view happens to be a 3D view, 
    // we could simply use it right away. In 
    // general we have to find a different one to 
    // run the ReferenceIntersector in.
 
    View3D view3d = GetView3d( doc );
 
    XYZ viewdir = view.ViewDirection;
 
    XYZ origin = q + 1000 * viewdir;
 
    // Find all elements:
 
    //ReferenceIntersector ri
    //  = new ReferenceIntersector( view3d );
 
    // Find all elements except roofs:
 
    ElementFilter f = new ElementCategoryFilter( 
      BuiltInCategory.OST_Roofs, true );
 
    ReferenceIntersector ri 
      = new ReferenceIntersector( f, 
        FindReferenceTarget.Element, view3d );
 
    ReferenceWithContext rc
      = ri.FindNearest( origin, -viewdir );
 
    string s = "Element not found";
 
    if( null != rc )
    {
      Reference r = rc.GetReference();
 
      Element e = doc.GetElement( r );
 
      s = ElementDescription( e );
    }
 
    // Move tooltip to current cursor 
    // location and set tooltip text.
 
    _form.Location = p + new Size( _form.Offset );
    _form.SetText( s );
  }
}

Toggle Tooltip On and Off Commands

To simplify the usage and cooperation with other add-ins, I implemented two trivial read-only external commands calling the external application ShowForm and HideForm methods to toggle my personal tooltips on and off:

[Transaction( TransactionMode.ReadOnly )]
public class CmdTooltipOn : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.ShowForm( 
      commandData.Application );
 
    return Result.Succeeded;
  }
}
 
[Transaction( TransactionMode.ReadOnly )]
public class CmdTooltipOff : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.HideForm(
      commandData.Application );
 
    return Result.Succeeded;
  }
}

Conclusion and Download

I hope you find this as useful as I imagine it might become, and look forward to your feedback.

By the way, I will be talking about this sample and the possibilities it demonstrates along with many other topics in my Autodesk University presentation CP4107 on the new Revit 2013 UI API functionality, probably making this the most exciting one of my three AU sessions.

Here is a current snapshot of the entire source code, Visual Studio solution and add-in manifest of the WinTooltip sample application, together the rest of my CP4107 sample material. The latter is based on my DevCamp Revit 2013 UI API samples.

Here are a couple of other items of interest before I wrap up, related to the Revit API, technology and purely human interst.

DWG and Image Export Naming Convention

Saikat Bhattacharya points out that the naming convention for exporting multiple images follows the one used for DWG export: [FileName]-[ViewType]-[ViewName].[image format].

Displaying a Text File from a TaskDialog Command Link

I recently mentioned the order of TaskDialog command links.

Now Saikat Bhattacharya picked up a related issue, on how to define a TaskDialog command link to open up a text file in the local system.

URLs and local system HTML links work fine out of the box. A text file, however, needs special processing. One way to launch it is by using the Process.Start method in the .NET System.Diagnostics namespace. Saikat provides the source.

DesignScript

A very exciting new technology is now publicly available on Autodesk Labs: DesignScript:

• A powerful scripting language for exploratory programming.
• Managing and distinguishing between a generative description of a design (as a script) and the resulting generated model.
• A language to help designers build and analyze complex geometric models that would be difficult to model with interactive techniques.
• Integrated into a host geometry application (currently AutoCAD).

The designer no longer directly models the resulting design: instead she develops a script whose execution generates the model. This enables a completely different kind of design model to be created. The design process is also different. An apparently minor edit to the script can have a profound effect on the generated model, enabling the exploration of a vast array of alternatives, with much less effort than manual interactive modeling. Here is a five-minute video explanation of Design Computation by Robert Aish for Autodesk University last year:

Kean Walmsley provides a very nice explanation and description of the DesignScript sample he implemented for it together with Robert in 2008 for the Design Computation Symposium and AU mainstage presentation.

Now you can try it for yourself. Unfortunately, DesignScript is not yet available for Revit...

Falk on Schafberg

For something completely unrelated to any technology at all, here is a nice little video of my friend Falk recently when we hiked over the Wildhauser Schafberg (sheep mountain) together, clearly illustrating some basic and sympathetic human and ovine commonalities :-)

Element Intersection

A common question when analysing a BIM is determining whether any of its elements intersect.

This was actually surprisingly difficult to answer programmatically in Revit a few releases back, as some of the interesting uses of the FindReferencesByDirection method show, for example the FindColumns SDK sample. Later, that method was enhanced to lead to FindReferencesWithContextByDirection.

The FindColumns sample searches for intersections between walls and columns by shooting a ray along the wall centre line, raised above the bottom level by a foot or so, and detecting any columns hit by it. One obvious problem with this approach is its inaccuracy – any column just partially intersecting the wall may easily be missed by the ray.

A few years ago, that was the best an add-in developer could hope for, and things looked even worse before the advent of these methods.

So what is the situation today? In short:

Question: How can I programmatically detect whether two Revit elements intersect?

Answer: You can now perform a Boolean operation on Revit element solids and determine whether they intersect using the BooleanOperationsUtils class ExecuteBooleanOperation method.

Please note that the resulting intersection solid is transient, in-memory only. It can be used for calculation and short-term visualisation using the analysis visualisation framework AVF, but it cannot be added to the Revit database or made persistent.

This class was introduced in the Revit 2012 API, and the associated webcast showed it being used impressively in a much improved version of the FindColumns SDK sample. This version determines the exact intersection solids between all columns and walls instead of roughly approximating the intersection detection by casting a single ray, and displays them to the user through AVF.

The Boolean intersection demo is described in detail and the source can be downloaded from the discussion of a simpler derived sample using AVF to highlight rooms.

Another example of making use of this class is given by the GeometryCreation_BooleanOperation SDK sample.

Finally, here are two discussions on element intersection before the introduction of the BooleanOperationsUtils class, on intersection between elements in Revit 2011 and the InstanceVoidCutUtils class.

AEC Technology Update

If you are interested in a succinct summary of all the key developments in the AEC technology industry in the past couple of months, here is a potantial cancidate: the AEC Technology Updates, Fall 2012, including some snippets of Autodesk related news such as Revit LT and the Vela acquisition.

Updating Properties and Announcing Revit LT

Today, exceptionally, a second post, partly to highlight an interesting comment submitted by Jinshou on how to programmatically trigger a refresh of the Revit element properties window, and partly to announce a non-API issue, totally non-API, the imminent arrival of Autodesk Revit LT.

Refreshing Revit Element Properties

If I first invoke the UIApplication OpenAndActivateDocument method, then highlight elements as described in a previous post, the 'properties' window is updated.

The trick is that in order to call OpenAndActivateDocument on the document containing the elements to highlight, you have to first ensure that it is not the active document. To achieve this, I:

• Create an empty RVT file.
• Invoke OpenAndActivateDocument to activate that.
• Invoke OpenAndActivateDocument again on the document of interest.
• Highlight the elements.
• Don't forget to close the empty RVT file when finished.

Many thanks to Jinshou for this interesting hint.

Announcing Autodesk Revit LT

For the nonce, here is an announcement completely unrelated to the Revit API. In fact, the product announced is specifically designed to not be customisable.

Autodesk today announced Autodesk Revit LT software, a new addition to its award winning family of Revit software products. Designed for architects, designers and building industry professionals using 2D workflows who are looking to transition to the Building Information Modeling (BIM) process, Autodesk Revit LT software delivers a focused 3D application to help users create higher-quality and more accurate designs and documentation.

"Autodesk Revit LT reflects our commitment to provide architects, designers and building professionals, particularly those in small firms, the tools they need to ease the transition to get started with – and take advantage of – a BIM workflow," said Amar Hanspal, Autodesk senior vice president, information modeling products. "With Revit LT, customers can deliver higher-quality, more accurate designs and documentation – allowing them to bring projects to market faster and save time and money."

Autodesk Revit LT is built on the Revit platform for BIM and allows users to create designs efficiently with 3D, real-world building objects to produce reliable, coordinated documentation faster. Revit-based applications help deliver better coordination and quality, and can contribute to higher profitability for architects, design professionals and the rest of the building team. Some of the benefits of Revit LT include:

• Work more efficiently with a single, coordinated model that allows users to concurrently design and document building projects. Autodesk Revit LT automatically manages iterative changes to building models throughout the documentation process. As a result, a consistent representation of the building is maintained, helping to improve drawing coordination and reducing errors.
• Design and visualize in 3D. Revit LT allows users to see their designs virtually, improving their understanding of the building and its spaces, and helping them communicate design ideas to clients more clearly and effectively.
• Create photorealistic renderings in the cloud. Users who purchase Autodesk Subscription with Revit LT can render in the cloud directly from the Revit LT interface, enabling them to produce compelling, photorealistic visualizations without tying up their desktop
• Exchange designs in the DWG or RVT file formats. Produce designs in the DWG file format, and experience fluid file exchange with project team members using other Autodesk Revit software applications.

Availability

Autodesk Revit LT 2013 is scheduled to be available within the month in North America and in select countries worldwide. The product is available as a standalone version and as part of the new AutoCAD Revit LT Suite 2013, which includes both Autodesk Revit LT 2013 and AutoCAD LT 2013. Product availability varies by country. Details and purchasing options are available at www.autodesk.com/revitlt

AU Registration and ADN Open

Preparations for Autodesk University 2012 on November 27-29 at the Mandalay Bay hotel in Las Vegas are moving along as usual. Registration is now open, and, following Kean's suit, I just registered as well. I already mentioned the classes I will be presenting. More details on these have emerged, since the time plan has been settled and the AU class catalogue is now available:

• CP4107 Let's face it: New Autodesk Revit 2013 UI API Functionality
  Thursday, Nov 29, 1:00 PM - 2:30 PM
• CP4108 Revit MEP Programming: All Systems Go
  Wednesday, Nov 28, 1:00 PM - 2:30 PM
• CP4109 Revit API Round Table: Meet the Champions
  Tuesday, Nov 27, 5:30 PM - 7:00 PM

Before the beginning of the conference proper, I will obviously be attending the ADN conference at AU (6302) on Monday with its AEC breakout session in the afternoon, and happily the late afternoon round table timing on Tuesday will also allow me to spend almost all that day at the DevLab, which is always one of the very most interesting chances to interact directly with developers and their issues.

Autodesk Developer Network Open

Something else that just opened up wide, besides the AU registration, is the Autodesk Developer Network ADN.

In the past, this was reserved for members only, to a certain extent.

As you probably noticed, we recently opened up significantly by launching numerous ADN DevBlogs publishing programming and customisation solutions.

Certain members-only areas remain, such as free access to Autodesk software, preview releases, and direct support.

We are making a large effort to simplify access to the basic knowledgebase content, though, and to support discussion forums.

One goal is that a simple Google search should bring up all available information on Autodesk API questions, and to strongly encourage peer-to-peer support in discussion groups.

Stephen Preston published an announcement introducing ADN Open describing the whole scenario in full, and Kean Walmsley's description adds additional background.

Last and definititely not least, if you just want to jump straight in to the real thing with no further ado, here is the official link to Autodesk Developer Network Open:

www.autodesk.com/adnopen