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?

Adjustable Versus Perpendicular Spud

I recently presented an explanation of some Revit MEP family editor part type classes, which led to a follow-up:

Question: Thank you for the detailed answer about the duct fittings. I have a similar problem with one of the pipe fittings, namely spud. I know what a spud is, but not the difference between an adjustable and a perpendicular one.

Can you explain the actual difference, please?

Here is an image with some different spuds that I collected:

Answer: Spuds are analogous to taps in ductwork, which also have adjustable and perpendicular part types.

Their difference is probably best described by example. Here are two smaller branches, both routed from the larger main at 45 degrees:

The adjustable tap on the left adjusted to accommodate the 45-degree route.

The perpendicular tap on the right is constrained to tap perpendicularly off the main. Then, an elbow is automatically inserted after a short duct length to route the branch to the picked point.

Many thanks to Martin Schmid for this explanation.

Simple MEP System Traversal

Here is a simple MEP system traversal implementation that especially addresses the issue of determining what equipment is connected to the systems.

The following read-only external command traverses all MEP systems in the document, using the MEPSystem.Elements property to retrieve most of the desired elements with very little effort.

More than half the code is actually fussing about with formatting the result:

[Transaction( TransactionMode.ReadOnly )]
public class Command : IExternalCommand
{
  static string PluralSuffix( int n )
  {
    return 1 == n ? "" : "s";
  }
 
  void TraverseSystems( Document doc )
  {
    FilteredElementCollector systems
      = new FilteredElementCollector( doc )
        .OfClass( typeof( MEPSystem ) );
 
    int i, n;
    string s;
    string[] a;
 
    StringBuilder message = new StringBuilder();
 
    foreach( MEPSystem system in systems )
    {
      message.AppendLine( "System Name: "
        + system.Name );
 
      message.AppendLine( "Base Equipment: "
        + system.BaseEquipment );
 
      ConnectorSet cs = system.ConnectorManager
        .Connectors;
 
      i = 0;
      n = cs.Size;
      a = new string[n];
 
      s = string.Format(
        "{0} element{1} in ConnectorManager: ",
        n, PluralSuffix( n ) );
 
      foreach( Connector c in cs )
      {
        Element e = c.Owner;
 
        if( null != e )
        {
          a[i++] = e.GetType().Name
            + " " + e.Id.ToString();
        }
      }
 
      message.AppendLine( s
        + string.Join( ", ", a ) );
 
      i = 0;
      n = system.Elements.Size;
      a = new string[n];
 
      s = string.Format(
        "{0} element{1} in System: ",
        n, PluralSuffix( n ) );
 
      foreach( Element e in system.Elements )
      {
        a[i++] = e.GetType().Name
          + " " + e.Id.ToString();
      }
 
      message.AppendLine( s
        + string.Join( ", ", a ) );
    }
 
    n = systems.Count<Element>();
 
    string caption =
      string.Format( "Traverse {0} MEP System{1}",
      n, (1 == n ? "" : "s") );
 
    TaskDialog dlg = new TaskDialog( caption );
    dlg.MainContent = message.ToString();
    dlg.Show();
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    TraverseSystems( doc );
 
    return Result.Succeeded;
  }
}

I executed this on an absolutely trivial system:

That generates the following message box as a result:

Obviously, you will want to clean up the reporting significantly to suit your needs. Currently, the owner elements in the ConnectorSet are listed, and the same elements also appear in the system elements list. Here is another result of running this on two systems, an electrical and a duct system, with the elements highlighted in yellow:

Also, the API reports four elements in the system including one duct segment, whereas the UI reports three, which is what one would expect, so some identification of duplicate elements needs to be added to make this useful.

Furthermore, reporting on these ‘logical’ systems may have the limitation that in-line equipment such as duct dampers and valves are not reported as part of the system. The other system traversal samples based on physical connectivity provide this info, however.

For now, the main point is to demonstrate that this simple access exists at all.

For your convenience, here is MepSystemTraversal.zip containing the source code, Visual Studio solution and add-in manifest for this command.

For more advanced traversal algorithms and determining the correct order of the individual system elements in the direction of the flow, you can look at the TraverseSystem SDK sample (2010, 2011) for mechanical systems and the AdnRme sample for electrical ones.

Content Localisation

How to manage families and content creation is a crucial topic for a large number of Revit add-ins.

Brian Johnson, technical specialist on structural engineering solutions at Autodesk in Austin, Texas, discusses how to efficiently address some important aspects of this below.

First, however, let me wish everybody a Happy New Year of the Snake!

A year for reflection, planning and searching answers. A good time for shrewd dealings, political affairs and coups d'état. People will be more likely to scheme and ponder over matters before acting on them. An auspicious year for commerce and industry.

Let's hope so, indeed, and return to the issue of content localisation:

Content Localisation

Question: We have a large number of library items that we would like to work with in Revit, and they are used in many different countries and languages.

How can we manage this efficiently, please?

We would like to avoid duplicating any of the content, of course.

The differences include things like product name, description, part code, cost, and many other properties.

As far as I see, a Revit family cannot hold different values for a single property such as the item description.

What are your advice and the best practice for creating and maintaining a Revit family library for thousands of items and numerous languages?

Answer: Just as you say, Revit is not equipped to localise parameter names and types nor family names themselves.

Some level of automation will probably help significantly to solve or at least simplify this task.

A proof-of-concept for generating content from data and organizing content can be found in the Content Generator Extension available from the Autodesk Subscription centre. Note that all the Revit Extensions are bundled into a single download:

The content generator is intended for structural content from around the world using the section and material libraries (XML files) that also form the libraries for Robot Structural Analysis Professional and AutoCAD Structural Detailing:

I describe some of the inner workings of the Content Generator on pages 7-9 in the hand-out of my Autodesk University 2012 course SE3904 – Linking Revit Structure and Robot Structural Analysis: Beyond the Basics. For your convenience as a valued reader of The Building Coder, here is a direct download link.

I suggest installing the Extensions and trying it out. Your version of this might pull country specific data from your libraries/databases and generate a specific element for a specific language.

When considering creating your own custom families, my suggestion is to create the content with the best-suited family. If you use a specialised category like Structural Framing, you will get built-in parameters and behaviours that you may or may not want. The Generic Model set of family templates is the most basic and may be the most appropriate. I suggest populating the Identity Data and creating Shared Parameters for each family type and use those to filter, sort, and group the Schedule views in Revit.

As always, it is of utmost importance to discuss your plans with some of your Revit users and to get some training on how things are done in the typical workflows in Revit. This will help you understand what can be done with Revit out-of-the-box and what parts might use more automation.

Thank you, Brian, for the valuable advice!

MEP Family Editor Part Type Classes

While we are talking about content creation, here is another MEP specific question on the different classes of fitting types:

Question: I would like to know the definition for some of the part types of the fittings in the family editor.

Simple classes of fitting types like cap, cross, elbow, multiport, tap, transition, tee and union is clear, but I am uncertain about the more complex and less clear-cut parts.

Could you please clarify the following?

1. What is the difference between wye and pants?
2. Lateral tee and lateral cross are probably tees with an angle other than 90 degrees. They can also be rounded. Is this correct?
3. Offset is probably a kind of S-bend. Is this correct? Are eccentric transitions also included in this group?

Answer: Sure:

1. What is the difference between wye and pants?

It is no difference between creating wye and pants families. We just choose a part type that is close to the family name, which will makes sense if users check the part type.

Examples for wye:

Examples for pants:

2. Lateral tee and lateral cross are probably tees with an angle other than 90 degrees. They can also be rounded. Is this correct?

Again, lateral tee and lateral cross are used when the family name has similar words. The rule for using 'Lateral tee', 'Lateral cross' and 'Wye' is that the branch angle will be fixed when using the family in the project, so if the branch pipe has a different angle with the fitting, an elbow will be automatically added. If the part type is 'tee' or 'cross', the fitting will have a flexible angle branch itself.

Examples for lateral tee:

Example for lateral cross:

Lateral tee and lateral cross are also used as part types for pipe fittings, so they can be round as well.

3. Offset is probably a kind of S-bend. Is this correct? Are eccentric transitions also included in this group?

Examples for offset:

An eccentric transition should use the 'Transition' part type.

AU Classes on the View, MEP and Link APIs

Wednesday was my first normal and full AU day, after completing the developer conference and DevLab activities. I was able to attend two interesting classes held by Revit API developers Steven Mycynek and Arnošt Löbel, and present my own Revit MEP API one. Here they are in chronological order:

• CP3133 Using the Revit Schedule and View APIs by Steven Mycynek
• CP4108 Revit MEP Programming: All Systems Go by Jeremy Tammik
• CP3455 Managing Revit Links with the Revit API by Arnošt Löbel

I am including the class materials below, both for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

Schedule and View APIs

Revit 2013 includes a major expansion of the Schedule and View APIs. This class introduces the API for Schedule and Elevation views as well as many methods and properties that apply to all views. Learn how to create and modify these views to help document and display your Revit model.

• Handout
• Presentation
• Sample code
• Sample models

This class should really resolve all those recurring questions associated with the creation of different views once and for all! Take a special deep look at Steve's multitude of useful utility classes in the sample code.

Revit MEP Programming

This class shows how to work programmatically with Revit MEP models. It provides an overview of the entire Revit MEP API with specific focus on the major enhancements in Revit 2013. The most important 2013 feature is the routing preference functionality. An overview of the available samples is provided. All MEP domains including HVAC, electrical, and plumbing are addressed. It shows how to analyse existing systems and create new MEP models from scratch; covers mechanical and electrical system traversal; display of system hierarchies in a tree view; components such as circuits, ducts, pipes, fittings, connectors, cable trays, and conduits; and automatic calculation and sizing based on room and space requirements.

• Handout
• Presentation
• Sample code

Managing Revit Links

This class explains common pitfalls working with links and how to avoid them. It details the creation of Revit link types and instances, and recommends how to easily check or modify the parameters of links. Material describing ways to inquire for data about the various types of external files, including Revit links, is included. It concludes with an overview of a larger Revit link API application – the eTransmit add-in, which enables users to move an entire package of Revit files while maintaining relationships with all linked files.

• Presentation
• Sample code and models

Implementing a BIM Business Transformation

Unrelated to any direct programming topic, here is a white paper on implementing a BIM business transformation that is of interest to visionaries and decision makers and neatly complements the recently released BIM for Infrastructure one.

Sweep PickPath Tolerance Criteria

Here is a rather specialised and hitherto undocumented topic of great importance to anyone trying to model precise complex swept geometry.

The issues below arose exploring the tolerance requirements of the 'Pick Path' options in the Revit UI, which map to the ReferenceArray and Reference input to the two FamilyItemFactory API calls for generating this kind of geometry:

Sweep NewSweep(
  bool isSolid,
  ReferenceArray path,
  SweepProfile profile,
  int profileLocationCurveIndex,
  ProfilePlaneLocation profilePlaneLocation );

SweptBlend NewSweptBlend(
  bool isSolid,
  Reference path,
  SweepProfile bottomProfile,
  SweepProfile topProfile );

It required quite a bit of research to resolve, both by the Revit development team and most of all by Bill Adkison of MarinCAD Custom Software Engineering, who is using this to create detailed furniture families like this:

Bill ran into a number of issues creating these very precise and detailed sweeps.

Here is an example of some of the ensuing discussions and results:

Question: I have problems with sweeps created via PickPath.

I am creating many successful pickpath sweeps. However, in some cases, pickpath sweeps are failing with a MemoryAccessViolation.

One example has two model lines which can each be selected to create a PickPath sweep, but when both are selected together, the sweep fails. I have confirmed that their endpoints meet up. One curve is a Hermite spline, the other a line. When I convert the spline to a set of line segments connecting the fit points, it works. What is the problem with connecting these two curves into a common sweep pattern? They fail interactively as well as via API. This is still basically a programming problem, because I need to know the criteria for when attaching splines and arcs will work. In another case of failure, a model line and a model arc of short radius: 0.34 inches, and included arc of .61 radians, so the ultimate arc length is .224 inches, well above the 1/32" Revit precision threshold. You can sweep these curves independently, but they do not sweep when picked together. In the debugger, their endpoints line up.

Answer: There is a small gap between the line and arc in the model that causes the problems for that sweep path. Such gaps should be avoided.

Other conditions to watch out for are curves that are nearly tangent, but not quite tangent, or arcs with very large radii that are nearly indistinguishable from lines.

Here are some internal observations which may help give an idea of what is going on:

1. CollectPath3dCurveGRefs complains about the gap between the line and arc in the model. The gap has size about 9.8e-6, but that function uses DOUBLE_EPS (= 1.0e-9) as a point-to-point tolerance. It issues a DBG_WARN but returns ERR_SUCCESS when it finds a gap.

The unit tangents of the line and arc at the point where they (nearly) meet differ by about 0.002 in the z-coordinate (and somewhat less than that in the y-coordinate). Apparently, Revit can bridge huge angles in lines, while being rather intolerant of even small angles in other areas.

CreateSweptSolid calls fixGapsInSweepPath, which calls trimCurvesToNbrs, but the latter function uses sqrt(0.1)*DOUBLE_EPS as a point-to-point tolerance, so it considers the gap to need "repair". It attempts to intersect the line and the arc, but that ultimately calls circXLine2d, which uses DOUBLE_EPS as a tolerance, so that function does not find an intersection. TrimCurvesToNbrs therefore does not modify the path (i.e., it does not "fix" the gap). It does check that the result is continuous to within a certain tolerance, but it uses the vertex tolerance for that check, and this gap is smaller than the vertex tolerance (which is about 0.0005).

CreateSweptSolid ultimately fails because getCornerTurningTrf fails when finding the corner-turning transform from the line to the arc, because vecAlmostEqual(cornerPnt1, cornerPnt2) is false. This essentially uses DOUBLE_EPS as a point-to-point tolerance. I confirmed that avoiding that rejection in the debugger allows the swept solid to be constructed successfully. Nevertheless, such gap and lack of tangency should be avoided whenever possible.

2. In the model, the line and the Hermite spline are not accurately tangent. Their tangent vectors at the point where the curves meet differ by about 0.01 in one of the coordinates; they meet at an angle of about 0.017 radians (= 1.02 degrees). While computing the mitre surface between the line and the spline, getMiterCurve then calls pathSegsAreNearlyTangent, but that uses a tolerance of one degree, so this case doesn't even meet the criterion for being nearly tangent. getMiterCurve then fails at the check for parallel normVec = (0.49, -0.85, 0.13) and planeNorm = (-0.86, -0.5, 0.0) (approximately).

PlaneNorm is the normal vector of the plane of the sweep path, as computed by getMiterCurve, while normVec was passed down from createSweepAlongCurve, where it was computed by a call to getRadii, which gets it directly from the sweep frame passed to createSweptSolid.

3. Please make the line accurately tangent to the spline in the example. They meet at an angle slightly greater than one degree.

Of course, making the line accurately tangent to the spline is a difficult numerical problem, and will involve modifying both curves, which are in different planes, which will also have to be modified. Alternatively, one could recognize the situation and either break the sweep, or go back to all line segments.

4. Please make analytic computations (i.e., those involving lines, arcs, planes, and other simple curves or surfaces as accurate as possible for double-precision floating-point computations. In such cases, values that would ideally be equal should be considerably less than 1.0e-9. In general, Revit expects points that are ideally coincident to have a distance considerably less than about 1/160". In some cases, though, Revit code demands a tighter tolerance. Curves that are ideally tangent should have an angle at most 0.1 degrees.

The failure to create a sweep for the line/spline path in the sample with a circular profile of radius about 0.4329 might be fixed by making the line tangent to the spline.

5. There seem to be a number of hardcoded almost vertical and almost unit vectors in your code.

Revit definitely does not like slightly off-axis lines and planes.

It will certainly help stability if you can replace all vectors like the following one by the almost identical ones aligned with the cardinal axes:

  XYZ normalizedMajorAxis 
    = new XYZ( 1.0,
      -0.00000000000024924835886401896,
      0.0000000000000012680828609390458 );

Specifying very slightly off-axis data is just asking for trouble. Do you really need to model anything that absolutely has to be so slightly off-axis? Is rounding an option for the input data you provide? This is not hard, once you are aware of the issue.

Response: 1. Details such as the point-to-point tolerance is exactly the kind of information I am looking for.

The gap in my data is a somewhat bigger than I expected, so I will write code to re-close them after my Revit computations are finished.

Does the fact that the tangents differ by this amount matter, i.e. cause the failure? Sweep handles 90-degree corners for line segments. Do non-lines have to have matching tangents? If so, that is great to know, as well as utterly unobvious. I can take evasive action if the tangents must match.

What is 'the vertex tolerance' exactly, in contrast to 'point to point'? For use by sweeps or path validation after the basic point to point? Is it used for Angles? Should I just be concerned with the DOUBLE_EPS distance for this problem?

2. So you require tangency for connecting PickPath segments that aren't lines? That is good to know. As noted earlier, because PickPath works with corners between lines, I assumed there was no tangent requirement for connecting elements, nor did I see any in the documentation. So to clarify the rules: must connecting PickPath elements have shared tangents at their connection point, UNLESS they are bound line segments? Here is the current list of possibilities:

• Line – Line: no tangency requirements.
• Line – Spline: tangency required.
• Line – Arc: tangent required or no?
• Spline – Arc: ?
• Spline – Spline: ?
• Spline – Arc: ?

If tangency requirements are a problem, I will correct them if possible, or revert to line segments.

I updated my logic to detect gaps and tangential inequality at connection points of multi-curve PickPaths, leading to the key logic summarised in the following code:

  /// <summary>
  /// Revit angle tolerance: 1 degree
  /// has been shown to be stable.
  /// </summary>
  const double kRevitAngleTolerance = Math.PI / 180.0;
 
  XYZ curCurveStartPt = null; // from current curve
  XYZ prevCurveEndPt = null; // from previous curve or null
  XYZ shiftVector = null;
 
  // Use DOUBLE_EPS tolerance in IsAlmostEqualTo 
  // for legitimate endpoint proximity.
 
  bool shiftCurve = ( prevCurveEndPt != null ) 
    && !curCurveStartPt.IsAlmostEqualTo( 
      prevCurveEndPt );
 
  if( shiftCurve )
  {
    // This case very rarely triggers.
 
    shiftVector = curCurveStartPt.Subtract( 
      prevCurveEndPt );
  }
 
  XYZ nextCurveStartTan = null; // from next curve or null
  bool nextCurveIsLine = null; // from next curve, if any
 
  XYZ curCurveEndTan = null; // from current curve
  bool curCurveIsLine = null; // from current curve
 
  double epsTanAngle = nextCurveStartTan.AngleTo( 
    curCurveEndTan );
 
  // Use cited tolerance of 1 degree between 
  // connecting endpoint tangent vectors. 
  // I actually experimented with up to 5 degrees, 
  // and although I observed cases of tangent 
  // differences of at least 2.6 degrees to
  // successfully sweep, sometimes it works and 
  // sometimes it excepts.
  // 1 degree has held up well so far; 
  // I have no known failures with it.
  // But the result is annoying notches in Revit 
  // in places where AutoCAD sweeps can handle 
  // the same curves automatically.
 
  bool writeSweepNow = false;
 
  if( ( nextCurveStartTan != null )
    // connecting lines have unequal 
    // tangents but work in Revit.
    && ( !curCurveIsLine || !nextCurveIsLine ) 
    && ( epsTanAngle > kRevitAngleTolerance ) )
  {
    // Break off sweep and start a new one;
    // when tangent angles exceed this, 
    // the sweep can except.
 
    // Final code to tweak current curve tangents 
    // would go here; this is a big project in itself.
 
    writeSweepNow = true;
  }
 
  // if (shiftCurve)
 
  // Current curve is re-read, with shift in 
  // location set in shiftVector.
  // Append current curve to model and record its 
  // references in current curve reference array.
 
  // if (writeSweepNow)
 
  // Sweep is written with current curve, and new 
  // Sweep begins with the next curve.
  // Loop until all curves are accumulated, 
  // then write final sweep.

This eliminates all the failures due to connecting multiple curves in PickPath sweep creation.

MEP Calculations

A second question was raised on another rather specialised calculation topic:

Question: Can you point to any documents describing the Revit MEP calculation methodology?

Answer: The MEP calculations are described in the Revit WikiHelp Reference.

You can also look at Martin Schmid's Autodesk University 2010 classes ME330-3 Calculations in Revit MEP, primarily focused on duct and pipe, and ME231-2 Categorically, Demand It on Your Schedule: You Con-Du-It in Revit MEP, with a focus on electrical calculation. The former includes a video recording.

The Hub Class

Saikat Bhattacharya published an article taking a look at the Revit API Hub class, never before mentioned here. It lives in the Autodesk.Revit.DB.Structure namespace and is derived from the base Element class. It represents a connection between two or more Revit Elements, avoiding the need to connect them with each other directly. They each refer to the hub, which manages all the connectivity information for them. Its interface is pretty minimal; the only members not inherited from Element appear to be:

• GetHubConnectorManager to retrieve the hub ConnectorManager.
• HasOrigin to indicate whether the hub has a specific location in 3D space.
• GetOrigin to retrieve the hub 3D position, if it has one.

Saikat presents a sample code snippet showing how to access the elements connected to a given hub.

Leaving the Unshaved

I shaved again, after a couple of weeks of abstinence. Here is a last parting shot before leaving the unshaved masses, and afterwards:

Note the prow of a boat sticking out of the wall in the left-hand picture... special bonus points for anyone who can tell where this photo was taken :-)

Updated Revit MEP 2013 Material

I presented the Revit MEP API at the AEC DevCamp in June. In preparation for that, I provided a quick Revit 2013 MEP API overview and migrated and more fully described the AdnRme sample application. I will be presenting on this topic again at Autodesk University in November, so I revisited the material and fleshed out the description of the Revit 2013 changes a bit more. Here is the completed overview:

The Revit MEP 2013 API

The information provided in this section is based on the Revit API help file RevitAPI.chm 'What's New' section. The help file is available as part of the Revit SDK from the Revit developer page (cf. Further Reading at the end).

One of the main Revit MEP 2013 product features is the support for routing preferences. Previously, you could only define one single default elbow, tee, etc. The routing preferences support multiple settings for different materials and sizes.

Routing Preferences

The routing preferences enable you to select your preferred pipe and duct fitting types for various materials and sizes. It can be used to set routing preference policies for end users and query fittings and segments used for given size criteria.

The RoutingPreferenceManager class is used to manage routing preference rules for segments and fittings or query the fitting or segment chosen by Revit for a given size condition. The MEPCurveType class now provides a RoutingPreferenceManager property to access the main routing preferences object for that type. This is currently only support by the derived PipeType and DuctType classes.

Routing preferences choose the first symbol in a rule list matching the given criteria. To ensure that a certain symbol is chosen for a given scenario, you can either set appropriate size criteria, or temporarily re-order the rules using the RemoveRule and AddRule methods.

Programmatic use of routing preferences is demonstrated by RoutingPreferenceTools SDK sample.

Flow Analysis Sections

The MEPSection base class has been introduced to represent duct and pipe sections, i.e. a series of connected elements, mainly for pressure loss calculation. A section includes ducts or pipes, fittings, terminals and accessories, where all section members have same the flow analysis properties, e.g. Flow, Size, Velocity, Friction and Roughness. An element can belong to multiple sections. For example, a tee fitting with three connectors usually belongs to three sections, and a tap will divide a duct or pipe segment into two sections.

Fluid Viscosity and Density

Revit MEP 2013 provides support for more precise temperature dependant friction calculation via the new FluidTemperature class, which can represent viscosity and density properties at a given temperature. The FluidType class has been extended to provide read and write access to a collection of FluidTemperature objects representing the fluid properties at various different temperatures. This collection can be accessed and manipulated using the new AddTemperature, GetTemperature, RemoveTemperature and GetFluidTemperatureSetIteratormethods.

Thermal Properties

Thermal properties have been enhanced in several areas. New properties are provided on the ThermalProperties class, e.g. Absorptance, HeatTransferCoefficient, Roughness, ThermalMass, ThermalResistance. These are available on BIM elements such as wall, floor, ceiling, roof, door, window, etc.

The new ThermalAsset class is provided, representing the properties of a material pertinent to energy analysis. It is specified using the PropertySetElement and SetMaterialAspectByPropertySet classes.

The gbXML export provides more precise control of thermal properties of BIM types. They can be set to use calculated values or pre-defined values from Constructions.xml using the MEPBuildingConstruction methods GetBuildingConstructionOverride and SetBuildingConstructionOverride. The EnergyDataSettings.IncludeThermalProperties flag determines whether thermal information from model assemblies and components is included in the gbXML export.

More Revit MEP API News

Other enhancements include read and write access to spare circuit values, retrieval of more of the localised user-visible display strings for enumeration values.

ConnectorProfileType and PartType enumeration changes, ConnectorElement changes and new static creation methods, more LabelUtils access to localised user-visible display strings, access to panel schedule spare circuit values, a light and light group API,

The new ReferenceIntersector class provides a simpler access to geometric ray-tracing analysis.

Finally, a new external services framework has been put into place. It wraps external service functionality, which can be used to enable encapsulation and replacement of various calculation and analysis workflows, providing a basis for future MEP calculations and structural code checking. It is already in place and fully functional, but not yet used, so no examples are yet provided.

For completeness' sake, here is a draft preview of my AU presentation and handout document.

Elbow Fitting Selection and Dimensioning

Vacation time is approaching fast for me and lots of things need finishing off beforehand.

Meanwhile, one thing that had a number of developers champing at their bits for a while now finally came to fruition:

Autodesk Exchange

The Autodesk Exchange store is now open for application submissions. Stephen Preston already published several articles exaplaining the full details:

• Summary information
• Information for Revit developers
• Publishing an app

Here is another topic that recently kept me busy, with some helpful input from Martin Schmid and Steve Mycynek:

Selecting a Pipe Elbow Fitting

Question: I need to set the diameter of a pipe elbow fitting programmatically. The elbow diameter obviously needs to be adapted to the pipe diameter. The two pipes may also have different diameters.

I tried using the NewElbowFitting method to insert the elbow and simply pass in the two pipe connectors to it like this:

  doc.Create.NewElbowFitting( con1, con2 );

This does successfully create an elbow fitting instance. However, I don't see how to control which elbow symbol is inserted by this method. Is there any way to influence this?

Answer: Calling the NewElbowFitting method is similar to using the Trim tool in the user interface. When this method is called, Revit automatically chooses the appropriate elbow for you.

In Revit 2013, you can control the selection process through the routing preferences, whereas previous versions only enabled you to define one single default elbow, tee, etc. The routing preferences support multiple settings for different materials and sizes.

The routing preferences API is demonstrated by the RoutingPreferenceTools SDK sample. It implements three commands, one for analysis and reporting purposes, two for importing and exporting routing preferences to XML:

• Routing Preference Analysis: Analyze the routing preferences of a given pipe type to check for common problems, using the routing preferences API to look at all rules and criteria for a given PipeType.
• Routing Preference Builder with its two commands CommandReadPreferences and CommandWritePreferences: Set pipe type, fitting, and routing preferences in a project from data in an XML file and export these preferences to XML for archival, documentation, and collaboration purposes, allowing a user to work with routing preference data in a shareable XML format suitable for reuse in a wide variety of BIM management environments.

When you call NewElbowFitting, it inspects the pipe type and finds the first elbow in the appropriate routing preferences.

If the elbow inlet and outlet sizes differ, you need a reducing elbow.

How to Use the Routing Preferences API to Set the Elbow Symbol

The NewElbowFitting method will insert the elbow symbol specified in the routing preferences. Please note that while RP will choose the first symbol in the rule list that matches its criteria, you can always programmatically either set size criteria to ensure a later symbol is chosen for a given scenario, or re-order the rules using RoutingPreferenceManager RemoveRule and AddRule methods, at least temporarily, to force RP to choose a different elbow symbol than normal.

For example, if you have defined routing preference for 'Elbow Reducing - Threaded - MI - Class 150.rfa' and call this method, you will get an elbow that has different connection sizes as shown below on the left. If you don't have a transitioning elbow, but you do have a reducer defined, you will get a result as below right. Note that the reducer is quite odd in this particular model file :-)

In this case, both the Reducing Elbow and the Elbow + Reducer 'work'; which is used depends on their order in the definition of the RP.

The RP is the only way to influence this selection, both in the UI and in the API.

I Beg to Differ

In some cases, the outer diameter of the fitting and the pipes may differ. This is a content issue. Pipes and fittings are selected and connected based on the pipe 'Nominal Diameter' and the 'Nominal Diameter' of the fitting connector. In the Pipe Settings, a user can make the 'outer diameter' of a pipe bigger or smaller than its nominal diameter.

Here is an example with the following pipe type properties:

• Diameter 18 mm
• Outer Diameter 18 mm
• Inner Diameter 16 mm
• Size 18 mm

The generic pipe elbow fitting connected to the pipes by calling the NewElbowFitting method has the following properties:

• Nominal Diameter 18 mm
• Size 18 mm - 18 mm

For a fitting, the geometry of the elbow is completely arbitrary.

If you would like the elbow and pipe to have the same outer diameter, there are two ways to achieve this:

1. Make the outer diameter of the pipes bigger.
2. Modify the geometry of the elbow to be smaller.

Welded pipe fittings, for example, would have the same outer diameter, whereas threaded fittings, PVC, and others, typically have a larger outer diameter than the pipe itself, because the pipe engages into the fitting.

Change Elbow Dimension

Saikat handled an independent but related case that also happened to catch my attention:

Question: How can I change the diameter of an elbow pipe fitting, depending on the pipe diameter?

Answer by Saikat Bhattacharya: To test this, I created a pipe with an elbow fitting attached at one end. In the user interface, you can see that the nominal diameter parameter of the pipe is disabled, i.e. greyed out. The only thing I can do interactively in the user interface is modify the Nominal Radius of the pipe.

Based on this observation, I wrote the following few lines of code to modify the Nominal Radius of the selected elbow fitting using the API and it worked well:

  UIApplication uiApp = commandData.Application;
  UIDocument uiDoc = uiApp.ActiveUIDocument;
  Document doc = uiDoc.Document;
 
  Transaction trans = new Transaction( doc );
  trans.Start( "Change Diameter" );
  foreach( Element e in uiDoc.Selection.Elements )
  {
    FamilyInstance i = e as FamilyInstance;
 
    Parameter p = i.get_Parameter( 
      "Nominal Radius" );
 
    p.Set( 10 * 0.08333 );
  }
  trans.Commit();

For the complete solution and additional background information, please refer to Saikat's article on changing the diameter of an elbow fitting.

Invoke External Command on Start-up

Finally, to wrap this up, a little note on another issue that also cropped up and really is completely unrelated :-)

Question: I would like to call my Revit add-in in a batch operation in order to process multiple Revit files. The process would involve starting Revit, loading a model, invoking my add-in, and shutting down the application afterwards. I don't see any obvious command line option to achieve this. Is it possible at all?

Answer: Yes. This can be easily addressed by creating an external application, implementing appropriate OnStartup and DocumentOpened events, and driving the whole thing through a journal file or even directly from the command line.

DevCamp Day Two

This morning I presented my second session, on some of the Revit 2013 UI API enhancements, in the Revit API beginner track. After that, I returned back to the Revit API expert one to attend the presentations on modeless interaction and IFC before presenting my final session on the Revit MEP API. Here then are my sessions of today, in chronological order:

• 1-4 Revit 2013 UI API enhancements
• 2-3 Asynchronous interactions
• 2-2 IFC export open source
• 2-7 Revit MEP API

Revit 2013 UI API Enhancements

Enhanced add-in integration is an important topic in the Revit 2013 API. This session discusses four of the add-in integration topics in more depth, building on a preceding presentation by Saikat Bhattacharya presenting a snapshot of the entire Revit UI API functionality:

• Revit progress bar notifications
• Options dialogue WPF custom extensions
• Embed and control a Revit view
• Drag and drop

All four of these are covered by existing SDK samples, the first by ProgressNotifier (Events), the others by the comprehensive UIAPI sample.

For someone like me, feeling a strong affinity to Winnie the Pooh, the "bear of very little brain", the existing SDK samples are way beyond simple comprehension and reuse, so I ended up creating four own extremely simple and minimal ones exercising these features in just a few lines of code each instead, to reduce the code and required audience comprehension power to an absolute minimum.

Revit progress bar notifications

To receive information about the current Revit progress bar status, you can subscribe to the ProgressChanged event.

The event handler will receive a ProgressChangedEventArgs instance providing the following properties:

• Caption – progress bar caption describing operation in progress
• Stage – current stage of the progress bar, one of Started, CaptionChanged, RangeChanged, PositionChanged, UserCancelled, Finished
• LowerRange – lower limit of range, always zero
• UpperRange – upper limit of range, any non-zero number
• Position – Value between zero and UpperRange incremented with "PositionChanged" stage

The ProgressNotifier SDK sample displays a WPF-based dialogue box. It provides a button to open and load a Revit model. Loading the selected file will cause a number of progress bar actions to execute. These actions are monitored and presented in a stack structure, since occasionally more than one progress bar event may be active simultaneously:

My new ProgressWatcher sample in much simpler and tracks all progress bar events by just printing the event argument data to the Visual Studio debug output window. This can be achieved in a very few lines of code, basically only one each to subscribe to the event and to access and print the progress bar event data:

[Transaction( TransactionMode.ReadOnly )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    Application app = uiapp.Application;
 
    app.ProgressChanged 
      += new EventHandler<ProgressChangedEventArgs>( 
        OnProgressChanged );
 
    return Result.Succeeded;
  }
 
  void OnProgressChanged( 
    object sender, 
    ProgressChangedEventArgs e )
  {
    double percent = 100.0 * e.Position / e.UpperRange;
 
    Debug.Print( 
      "'{0}' stage {1} position {2} [{3}, {4}] ({5}%)",
      e.Caption, e.Stage, e.Position, e.LowerRange, 
      e.UpperRange, percent.ToString( "0.##" ) );
  }
}

Saving the output to a text file will allow you to analyse in detail the progress bar event sequence and nesting.

Options dialogue WPF custom extensions

In Revit 2013, an add-in can add its own custom tabs to the standard Revit Options dialogue.

This is achieved by defining a WPF control to display and subscribing to the UIApplication DisplayingOptionsDialog event.

The event handler receives an DisplayingOptionsDialogEventArgs instance. It has a PagesCount property providing the number of Options dialogue tabs including default Revit ones. It also sports the AddTab method that can be used to add a tab, providing a name and a handler for it. The handler information is encapsulated in the TabbedDialogExtension class.

The TabbedDialogExtension class provides a constructor taking two arguments, a WPF user control instance and an OK handler. These cannot be changed later. It provides methods to get and set contextual help, and properties to read the WPF control and OK handler. It also provides properties to both get and set the cancel and 'restore defaults' handlers:

• Control – the control
• OnOKAction – the ok handler
• OnCancelAction – the cancel handler
• OnRestoreDefaultsAction – the restore defaults handler

The UIAPI SDK sample adds several custom tabs demonstrating most available features.

I created a minimal sample named AddOptionsTab which defines the simplest possible WPF control with one single button to click:

If you click the button, the corresponding event handler on the form is called, which simply displays a task dialog:

If this tab has ever been activated after the Options dialogue was opened, its OK, cancel and 'restore defaults' handlers are called, depending on the user actions.

Here is the entire user control source code defining its handlers:

public partial class UserControl1 : UserControl
{
  string _name;
 
  public UserControl1( string name )
  {
    _name = name;
 
    InitializeComponent();
  }
 
  private void button1_Click( 
    object sender, 
    RoutedEventArgs e )
  {
    TaskDialog.Show( _name, "I was clicked..." );
  }
 
  public void OnOK()
  {
    TaskDialog.Show( _name, "OK" );
  }
 
  public void OnCancel()
  {
    TaskDialog.Show( _name, "OnCancel" );
  }
 
  public void OnRestoreDefaults()
  {
    TaskDialog.Show( _name, "OnRestoreDefaults" );
  }
}

The event handler code reacting to the Options dialogue displaying simply instantiates the user control, calls the TabbedDialogExtension constructor with it, and feeds that to the event handler arguments AddTab method:

void OnDisplayingOptionsDialog( 
  object sender, 
  DisplayingOptionsDialogEventArgs e )
{
  UserControl1 c = new UserControl1( 
    "DevCamp User Control" );
 
  e.AddTab( "DevCamp Custom Tab", 
    new TabbedDialogExtension( 
      c, c.OnOK ) );
}

The event handler is called each time the Options dialogue is invoked once the event has been subscribed to, which is achieved in a single line of code like this in the AddOptionsTab external command:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
 
  uiapp.DisplayingOptionsDialog 
    += new EventHandler<DisplayingOptionsDialogEventArgs>( 
      OnDisplayingOptionsDialog );
 
  return Result.Succeeded;
}

Embed and control a Revit view

Another of the add-in integration enhancements enables you to embed and control a Revit view in your own form, dialogue or window.

The new PreviewControl class presents a preview control to browse the Revit model. It takes two input arguments, a document and a view id. The hosting form or window must be modal. The View can be any graphical view, i.e. must be printable. Perspective views are also supported, and all 3D Views can be manipulated by view cube. The visibility and graphical settings of the view are effective and respected by the control.

The UIAPI SDK sample proves a demonstration of this as well, which allows you to interactively select any of the open documents to view, or even open a new one, and secondly presents a list of all the documents views for you to switch between. Each time you change any of these two selections, the current preview control is discarded and a new one is instantiated with the updated input arguments. These input arguments are the only way in which the add-in affects the view, all further interaction happens between the control and the user.

To use a Revit preview control, you simply create a standard .NET form and insert a WPF host in it. A suitable host is the System.Windows.Forms.Integration.ElementHost. You populate this with a new Revit preview control instance, e.g. like this

  elementHost.Child = new PreviewControl( 
    doc, view.Id );

The PreviewControl instance needs to be disposed of after use:

  PreviewControl vc = elementHost.Child
    as PreviewControl;

  if( vc != null ) { vc.Dispose(); }

Here is a code snippet showing how all the printable views can be retrieved using a filtered element collector:

  IEnumerable<View> views
    = new FilteredElementCollector( doc )
      .OfClass( typeof( View ) )
      .Cast<View>()
      .Where<View>( v => v.CanBePrinted );

I created a minimal sample application PreviewControlSimple for this DevCamp class with much less code (and functionality than the UIAPI one, since it just displays the current view of a document with no further ado.

It does add one interesting twist, though: to show exactly how the hosting form is set up, I implemented that twice over, first using the Visual Studio designer as usual, and then converting the form to be completely programmatically generated. Here is the DisplayRevitView method taking the document and view input arguments for the preview control. It also takes a third argument for the main Revit window, so that the generated control can be hooked up to that as a parent window. This defines an appropriate relationship between the two as far as the Windows OS is concerned, ensuring correct minimisation and restoration behaviour:

const string _caption_prefix
  = "Simple Revit Preview - ";
 
void DisplayRevitView( 
  Document doc,
  View view,
  IWin32Window owner )
{
 
  using( PreviewControl pc
    = new PreviewControl( doc, view.Id ) )
  {
 
#if CREATE_FORM_BY_CODE
 
    using( System.Windows.Forms.Form form
      = new System.Windows.Forms.Form() )
    {
      ElementHost elementHost = new ElementHost();
 
      elementHost.Location
        = new System.Drawing.Point( 0, 0 );
 
      elementHost.Dock = DockStyle.Fill;
      elementHost.TabIndex = 0;
      elementHost.Parent = form;
      elementHost.Child = pc;
 
      form.Text = _caption_prefix + view.Name;
      form.Controls.Add( elementHost );
      form.Size = new Size( 400, 400 );
      form.ShowDialog( owner );
    }
 
#else // if not CREATE_FORM_BY_CODE
 
    Form1 form = new Form1( pc );
    form.ShowDialog( owner );
 
#endif // CREATE_FORM_BY_CODE
 
  }
}

Please note that correct disposal of the preview control is ensured by the 'using' statement. This is similar to Arnošt's strong recommendation to always encapsulate Revit Transactions in a 'using' statement.

Calling this method from the external command mainline with the current document view is trivial. I add one line of code to access the Revit main window:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  IWin32Window revit_window
    = new JtWindowHandle(
      ComponentManager.ApplicationWindow );
 
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  View view = doc.ActiveView;
 
  DisplayRevitView( doc, view, revit_window );
 
  return Result.Succeeded;
}

Drag and Drop API

I recently discussed the new drag and drop functionality and the UIAPI sample command demonstrating it.

The UIApplication provides the new static DoDragDrop method, with two overloads:

• DoDragDrop( ICollection<string> ) – initiate a standard built-in Revit drag and drop operation taking a collection of file names.
• DoDragDrop( object, IDropHandler ) – initiate a drag and drop operation with a custom drop implementation.

This method is designed for use in a modeless form.

Please note that this is currently the one and only Revit API method not requiring a valid Revit API context.

This method can be called from your modeless form at any time, even without Revit giving you explicit permission to interact with the API via some form of callback or notification, as required for all other Revit API calls.

The behaviour of drag and drop given a list of filenames depends on the type of files, as I already recently pointed out:

• One AutoCAD format or image file dragged onto Revit – A new import placement editor is started to import the file.
• More than one AutoCAD format or image files dragged – A new import placement editor is started for the first file.
• One family file dragged onto Revit – The family is loaded, and an editor started to place an instance.
• More than one family file dragged onto Revit – All the families are loaded.
• More than one family file including other format files dragged – Revit tries to open all the files.
• Valid file or list of files is passed – Revit does its best to use them appropriately.
• Any files are not usable – Failure is signalled to user, no exception is thrown, add-in is not notified.

Here again, I implemented a new DevCamp sample add-in DragDropApi to be able to show the necessary steps in a simpler context than the corresponding UIAPI example.

Here are my four new Revit 2013 UI API samples AddOptionsTab, DragDropApi, PreviewControlSimple, ProgressWatcher and the slides I used.

Asynchronous Interactions

Arnošt Löbel already presented on this topic at Autodesk University 2011 in his class CP5381 'Asynchronous Interactions and Managing Modeless UI with the Autodesk Revit API', as mentioned in the overview of the AU 2011 Revit and AEC API sessions.

In this class, Arnošt also covered the new external events and demonstrated his ModelessForm_ExternalEvent, ModelessForm_IdlingEvent (ModelessDialog) and WorkThread (MultiThreading) SDK samples.

The conclusion of the presentation is the following pledge that we are all strongly recommended to take:

• I shall not call the API unless invoked by it
• I shall not call the API from anywhere but the main thread
• I shall call the API only, not directly the Revits UI
• I shall use the Idling event cautiously and considerably

Here is a snapshot of the entire slide deck. This is not the final version, which will be posted soon after the end of DevCamp.

IFC Export Open Source

Angel Velez is senior principal engineer in the Revit development team and presented on the IFC exporter open source project, covering the following main topics:

• Introduction
  • History of IFC in Revit
  • Why open source?
• How the code Works
  • Overall structure of code
  • Key points of interest, e.g. element traversal, property sets
  • Look at alternate UI

Here is the snapshot of his slides.

Revit MEP API

The Revit MEP API is a recurring topic of mine at Autodesk University, and I presented on this once again last year in my session CP4453 'Everything in Place with Autodesk Revit MEP Programming', as mentioned in the overview of the AU 2011 Revit and AEC API sessions. The AU materials and the sample code that I use there was already published and discussed.

In preparation for the sessions here in Waltham, I also discussed the Revit 2013 MEP API and completed the migration of the ADN MEP sample code to Revit 2013.

Here is the slide deck I used today, based on the AU one and updated for Revit MEP 2013.

Please note again that all the materials provided above are just snapshots. Soon after the conference completes, the complete and final materials will be published.

Winding Down and Winding Up Again

In the evening we went out for a DevTech dinner, Japanese and Chinese cuisine. It was great to hang out with the guys for a while and wind down a bit:

Next stop is the DevLab tomorrow with a record number of almost fifty registered participants, so we will be way busy! Time to wind up again. No rest for the wicked! These events are always great, and I'm looking forward to it a lot.

Family Instance Element Coordinate System

I spent last weekend in Sweden for my 35 year school anniversary, having graduated from the German school in Stockholm in May 1977.

The day after our reunion I visited a friend's summer house on the little lake Kvarnsjön in Huddinge:

Back to the Revit API, after having taken a second look at connector orientation, here is another MEP coordinate system topic that can bear updating and coincidentally also has a connection to Scandinavia, since Progman Oy and Olli are Finnish.

I recently presented the discussion with Olli Kattelus of MagiCAD at Progman Oy on defining an ECS or element coordinate system for MEP ducts and pipes.

This is required for exporting them to IFC. Their geometry is specified in ECS there so that the same element definition can be reused consistently for all of its occurrences.

That took care of ducts and pipes, but the issue of family instances was not completely resolved, especially how to handle their potentially 'flipped' geometry.

Now Olli reports an easy solution for that as well, which is actually easier and more obviously canonical than the duct and pipe one, since a family instance already has a transform that we can base our ECS on:

I managed to solve problems with those flipped objects.

I changed the style how I constructed the transform a little bit.

With fittings, I use the hand/facing orientation & location point of the family instance instead of the connector direction & location:

  Transform ^tf = Transform::Identity;

  // Create correct vectors, 
  // taking flipping into account

  XYZ ^ho = famInstance->HandFlipped 
    ? famInstance->HandOrientation->Negate() 
    : famInstance->HandOrientation;

  XYZ ^fo = famInstance->FacingFlipped 
    ? famInstance->FacingOrientation->Negate() 
    : famInstance->FacingOrientation;

  ho = ho->Normalize();
  fo = fo->Normalize();

  tf->BasisX = ho;
  tf->BasisY = fo;
  tf->BasisZ = ho->CrossProduct(fo);
  tf->Origin = famInstance->Location->Point;

  tf = tf->Inverse;

You may be wondering why we need this, since fittings are family instances whose geometry is already defined the way we need it for the IFC export.

However, a fitting may also have an insulation added to it. The InsulationLiningBase class representing the insulation is inherited from MEPCurve, so we have the same issues for defining an ECS as we did for the duct and curve.

Thus only fittings with insulation need this transform treatment, in order to export their insulation geometry, not the fitting's own one.

Many thanks to Olli for this simple and elegant solution!

Connector Orientation

Today is the Pentecost or Whit Monday holiday in Neuchâtel, and I am in full tilt preparing for the AEC DevCamp in Waltham next week.

I will be presenting sessions on the new Revit 2013 UI API features, the Revit MEP API, and extensible storage.

I am of course looking forward much more to the many exciting other presentations by my colleagues in the ADN DevTech AEC team and especially by members of the Revit development team, directly from the horse's mouth, so to speak. Have a look at the session list and descriptions to see them all in their full glory.

Meanwhile, here is yet another MEP related topic to pick up:

Two years ago, I presented a solution for determining the width and height orientation of a Revit MEP connector.

Now Martin Schmid describes a new useful aspect of this issue which also leads to a very important point on real numbers comparisons.

Question: How do I determine the orientation of a connector in my project? From Revit Lookup, I can find where the information is, but I'm not sure how to interpret this without a 'visual'.

Answer: It was easy enough to determine by exporting a simple Revit model to AutoCAD, and displaying the coordinate entries there.

I thought I would share what I found to save other users from having to go through the same research.

For a FamilyInstance, such as a pipe fitting, the information can be found via

• FamilyInstance > MEPModel > ConnectorManager > ConnectorSet > Connector > CoordinateSystem

As the image below shows, the Z coordinate of CoordinateSystem indicates the normal direction of the connector. The CoordinateSystem.Origin is the actual location in the model:

For a MEPCurve such as a pipe, the access is slightly different:

• MEPCurve > ConnectorManager > ConnectorSet > Connector > CoordinateSystem

So, if you're trying to determine if two connectors are parallel and facing opposite directions, you can test that the Z axis vectors of the two connectors' CoordinateSystem properties pointing in exactly opposite directions, i.e. one equals the negation of the other.

Many thanks to Martin for this explanation!

Real Number Equality Testing

Jeremy adds: since the connector CoordinateSystem Z axis vector is an XYZ instance, i.e. a triple of three real numbers, comparing their equality leads back to a floating point number comparison.

In this case, you should actually almost never ever use an exact equality comparison such as Equals, or '=='.

You need to use an appropriate real number equality test instead.

Our guru GNU says: "we recommend that you consider not comparing real numbers for exact equality with the == operator, but rather check that real numbers are within an acceptable tolerance".

For the Revit API XYZ point and vector instances, this can easily be achieved by using the IsAlmostEqualTo method instead.

The comparison between the two connectors' CoordinateSystem Z axis vectors can therefore be implemented like this, for example:

  conn1.CoordinateSystem.BasisZ.IsAlmostEqualTo( 
    -conn2.CoordinateSystem.BasisZ );

I already discussed taking this one step further several times, for instance to implement the XyzEqualityComparer for retrieving unique geometry vertices, nested instance geometry, toposurface point classification and accessing the top faces ofa sloped wall.

Pipe Insulation and Insulation Material

I recently looked at the Revit MEP 2013 API and migrated the AdnRme sample to it.

To follow up on that, here is an unexpectedly hard Revit MEP 2013 question by Victor Chekalin, who recently created the nice DataStorage sample. The new question leads to some tricky and interesting aspects on how to access data or database elements through the Revit API that are not immediately accessible via the expected route or "normal" channels. Where there's a will, there's a way, though :-)

Question: I always get Element materials using an Element.Materials property. But now I've found the issue that I cannot retrieve PipeInsulation and pipe material using Materials property, although these elements have a material.

Furthermore, even if I can retrieve the pipe material via Pipe.PipeType.Material, I still cannot find any way to get PipeInsulation.

So I have two questions

1. Why there is no possibility to get PipeInsulation and pipe materials via Element.Materials Property?
2. Is there a way to get the PipeInsulation material?

I understand that pipe material is defined by the pipe type, but, for example, wall materials are defined by wall type as well and I can retrieve them from a wall instance without resorting to the wall type using the Wall.Materials property. Furthermore, the pipe material has a PipeMaterialType type not a Material type. Why?

I looked at the API help, API Reference Guide and read the post on the Revit MEP 2012 API describing the new pipe and duct insulations, but I didn't find the answer how to retrieve PipeInsulation material via API.

PipeInsulation and PipeInsulationType don't have a Material property or GetMaterial method. The Materials property has zero size.

By the way, why are so many differences accessing materials from pipe and pipe insulation compared to other elements? It seems for me as if the MEP version has been created by other developers :-)

Answer: As you are aware and point out, the pipe material is defined by the type and not the instance, so you would obviously query the type and not the instance for it.

Pipe insulation is a completely separate element from the pipe, so you have to access the insulation material from the insulation element, not from the pipe. Here is the relevant section from the Revit API 2012 help file What's New section:

Duct and pipe insulation and lining

The new classes

• DuctInsulation
• PipeInsulation
• DuctLining

and related types support read/write and create access to duct and pipe insulation and lining. In Revit 2012, these objects are now accessible as standalone elements related to their parent duct, pipe, or fitting.

Yes, you are correct in that the access to materials for pipes is different and more difficult compared to other elements such as walls.

There is actually on-going work in this area, and it is not yet complete; prior to 2013, pipes didn't have 'normal' materials, but rather just a string property. We are aware that materials for Walls and other elements in general are directly API accessible from the Element, instead of having to dig into the type, and would like pipe and pipe insulation material access to be just as easy.

Again, as you saw, RevitLookup displays the pipe insulation with a MaterialSet which is not displayed in bold like it is for other elements, because it is empty:

Still, we found a solution to your issue by using alternative access routes.

You can retrieve the parameter named 'Material' off the PipeInsulationType object from the PipeInsulation object. The parameter is an ElementId.

This little difficulty is compounded by the fact that we did not immediately find any easy way to get the PipeInsulationType from a pipe.

One way that we found to achieve this is to use a filter to retrieve all PipeInsulation elements in the document and compare the HostElementId of each one to that of the original pipe. When the matching one is found, you have the PipeInsulation element corresponding to that pipe, you can get the PipeInsulationType from that, and then get the material from the parameter.

We implemented the following helper classes and methods to demonstrate this:

• PipeFilter: Restrict user selection to pipe element only.
• GetSelectedElement: Return first pre-selected element or prompt user to select a pipe.
• GetPipeInslationFromPipe: Return pipe insulation from given pipe.
• GetMaterialFromPipeInsulation: Return material from given pipe insulation.
• GetInsulationFromSelection: Prompt user to select a pipe, retrieve its insulation and insulation material, and report the results.

Here is the entire sample code exercising these:

const string _caption = "Pipe Insulation Info";
 
/// <summary>
/// Restrict user selection to pipe element only
/// </summary>
class PipeFilter : ISelectionFilter
{
  public bool AllowElement( Element e )
  {
    return e is Pipe;
  }
 
  public bool AllowReference( Reference r, XYZ p )
  {
    return true;
  }
}
 
/// <summary>
/// Return first pre-selected element or 
/// prompt user to select a pipe.
/// </summary>
Element GetSelectedElement( UIDocument uidoc )
{
  Element e = null;
 
  SelElementSet elements = uidoc.Selection.Elements;
 
  if( null == elements || elements.IsEmpty )
  {
    try
    {
      Reference r = uidoc.Selection.PickObject(
        ObjectType.Element,
        new PipeFilter(),
        "Please pick a pipe" );
 
      e = uidoc.Document.GetElement( r.ElementId );
    }
    catch( RvtOperationCanceledException )
    {
    }
  }
  else if( null != elements && !elements.IsEmpty )
  {
    IEnumerator it = elements.GetEnumerator();
 
    if( it.MoveNext() )
    {
      e = it.Current as Element;
    }
  }
  return e;
}
 
/// <summary>
/// Return pipe insulation from given pipe.
/// </summary>
PipeInsulation GetPipeInslationFromPipe(
  Pipe pipe )
{
  if( pipe == null )
  {
    throw new ArgumentNullException( "pipe" );
  }
 
  Document doc = pipe.Document;
 
  FilteredElementCollector fec
    = new FilteredElementCollector( doc )
      .OfClass( typeof( PipeInsulation ) );
 
  PipeInsulation pipeInsulation = null;
 
  foreach( PipeInsulation pi in fec )
  {
    // Find the pipe that has this inulation
 
    if( pi.HostElementId == pipe.Id )
      pipeInsulation = pi;
  }
  return pipeInsulation;
}
 
/// <summary>
/// Return material from given pipe insulation.
/// </summary>
Material GetMaterialFromPipeInsulation(
  PipeInsulation pipeInsulation )
{
  if( pipeInsulation == null )
  {
    throw new ArgumentNullException( "pipeInsulation" );
  }
 
  Document doc = pipeInsulation.Document;
 
  PipeInsulationType pipeInsulationType
    = doc.GetElement( pipeInsulation.GetTypeId() )
      as PipeInsulationType;
 
  Parameter p = pipeInsulationType.get_Parameter(
    "Material" );
 
  return null == p
    ? null
    : doc.GetElement( p.AsElementId() ) as Material;
}
 
/// <summary>
/// Prompt user to select a pipe, retrieve its 
/// insulation and insulation material, 
/// and report the results.
/// </summary>
void GetInsulationFromSelection(
  UIDocument uidoc )
{
  Element e = GetSelectedElement( uidoc );
 
  if( null != e )
  {
    if( e is Pipe )
    {
      PipeInsulation pi
        = GetPipeInslationFromPipe( e as Pipe );
 
      if( null == pi )
      {
        TaskDialog.Show( _caption,
          "Insulation not found" );
      }
      else
      {
        Material material
          = GetMaterialFromPipeInsulation( pi );
 
        if( null == material )
        {
          TaskDialog.Show( _caption,
            "Material not found" );
        }
        else
        {
          TaskDialog.Show( _caption,
            string.Format( "Material '{0}' <{1}>",
            material.Name, material.Id ) );
        }
      }
    }
    else
    {
      TaskDialog.Show( _caption, "Not a pipe" );
    }
  }
}

Here is PipeInsulationMaterial.zip containing the full Visual Studio solution, source code, and add-in manifest for this external command.

Many thanks to Steven Mycynek for researching and creating this solution!

Later, Martin Schmid pointed out that the GetPipeInslationFromPipe method using a filtered element collector and comparing all pipe insulation element HostElementId properties with the target pipe can be simplified by calling the InsulationLiningBase GetInsulationIds method instead. It takes the pipe element id and returns all pipe insulation element ids associated with it directly like this:

  ICollection<ElementId> pipeInsulationIds 
    = InsulationLiningBase.GetInsulationIds( 
      doc, pipe.Id );

Not so easy to find, though :-)

I updated the code in the zip file above to take this approach into account as well, simply adding an assertion to verify that the result is the same.

Create a Pipe Cap

Happily mixing the different Revit versions, let me follow up my work on the Revit MEP 2013 API and the updated AdnRme sample by another MEP related topic.

Before getting to that, though, here is a brief heads-up for a new technology preview on Autodesk Labs:

BIM Coordinator

The effective organization of project data in shared or related coordinates is essential to effective collaboration across disciplines and good quality project information. BIM Coordinator for AutoCAD Civil 3D and Revit is a technology preview that assists project team members with building and site grids.

Here is a brief overview taken from the labs:

Building grids are generally selected based on the layout and shape of the building, usually using the lower left corner of the selected orientation as a reference point. Building grids are established by the lead designer of a project for use by all members of the building design team. This grid ensures that different disciplines' building designs use the same reference for purposes of building analyses, drawing production, and other tasks requiring coordinated building data.

Site grids are generally based on Northing and Easting coordinates. They are usually established for a region; although arbitrary grids can be established for a single project or site. For example, in the UK most sites are related to the Ordinance Survey (OS) grid. Site elevations (levels) are also based on an OS benchmark or other site/project benchmark.

BIM Coordinator automates the more error-prone manual steps in the coordination of site and building grids between the AutoCAD and Revit environments, currently for the 2012 versions. The tool specifies one common XYZ point and its orientation in the XY plane between the two coordinate systems. This reference point defines the relationship between the building and site grid.

Miroslav Schonauer will be explaining some background and sharing source code from this utility at the upcoming AEC DevCamp in Waltham June 6-7.

Create a Pipe Cap

Back to the Revit MEP API, I presented an example to create a pipe cap in Revit 2011 over a year ago.

Now Mick Kulik of Hydratec, Inc. discovered that the existing sample code did not work in his case, and worked together with Saikat Bhattacharya at the AutoCAD DevLab in San Rafael to fix this issue for Revit 2012.

Here is the original problem and its solution:

Question: Following the post about creating a pipe cap, I was not able to get a cap to connect to a pipe in Revit MEP 2012. The Error is "Line is too short". Is there a new way to connect caps to pipes in Revit MEP 2012?

Answer: Saikat came down to give us a hand last week at the AutoCAD DevLab in San Rafael. He had some sample code to attach caps to sloping pipes. I was able to massage his code to fit our needs, and have attached his CapAtStartOfPipe.zip containing the entire source code and Visual Studio solution implementing this command.

Saikat's code worked on all the cases we tested except when trying to connect the cap to a non-sloped vertical pipe, so I built in a case to handle it which worked for my test cases:

  // rotate the cap if necessary
 
  // rotate about Z first

  XYZ pipeHorizontalDirection 
    = new XYZ( dir.X, dir.Y, 0.0 ).Normalize();
 
  ConnectorSet c2 
    = fi.MEPModel.ConnectorManager.Connectors;
 
  Connector capConnector = null;
 
  foreach( Connector c in c2 )
  { 
    capConnector = c; 
  }
 
  XYZ connectorDirection 
    = -capConnector.CoordinateSystem.BasisZ;
 
  double zRotationAngle 
    = pipeHorizontalDirection.AngleTo( 
      connectorDirection );
 
  Transform trf = Transform.get_Rotation( 
    start, XYZ.BasisZ, zRotationAngle );
 
  XYZ testRotation = trf.OfVector( 
    connectorDirection ).Normalize();
 
  if( Math.Abs( testRotation.DotProduct( 
    pipeHorizontalDirection ) - 1 ) > 0.00001 )
  {
    zRotationAngle = -zRotationAngle;
  }
 
  Line axis = doc.Application.Create.NewLineBound( 
    start, start + XYZ.BasisZ );
 
  ElementTransformUtils.RotateElement( 
    doc, fi.Id, axis, zRotationAngle );
 
  // Need to rotate vertically?
 
  if( Math.Abs( dir.DotProduct( XYZ.BasisZ ) ) 
    > 0.000001 )
  {
    // if pipe is straight up and down, 
    // kludge it my way else
 
    if( dir.X == 0 && dir.Y == 0 && dir.Z != 0 )
    {
      XYZ yaxis = new XYZ( 0.0, 1.0, 0.0 );
 
      double rotationAngle = dir.AngleTo( yaxis );
 
      if( dir.Z == 1 )
      {
        rotationAngle = -rotationAngle;
      }
 
      axis = doc.Application.Create.NewLine( 
        start, yaxis, false );
 
      ElementTransformUtils.RotateElement( 
        doc, fi.Id, axis, rotationAngle );
    }
    else
    {
      #region sloped pipes
 
      double rotationAngle = dir.AngleTo( 
        pipeHorizontalDirection );
 
      XYZ normal = pipeHorizontalDirection
        .CrossProduct( XYZ.BasisZ );
 
      trf = Transform.get_Rotation( 
        start, normal, rotationAngle );
 
      testRotation = trf.OfVector( dir ).Normalize();
 
      if( Math.Abs( testRotation.DotProduct( 
        pipeHorizontalDirection ) - 1 ) < 0.00001 )
      {
        rotationAngle = -rotationAngle;
      }
 
      axis = doc.Application.Create.NewLineBound( 
        start, start + normal );
 
      ElementTransformUtils.RotateElement( 
        doc, fi.Id, axis, rotationAngle );
 
      #endregion
    }
  }
 
  doc.Regenerate();
 
  // pick connector on cap:
 
  ConnectorSet connectors 
    = fi.MEPModel.ConnectorManager.Connectors;
 
  Debug.Assert( 1 == connectors.Size, 
    "expected only one connector on pipe cap element" );
 
  Connector cap_end = null;
 
  foreach( Connector c in connectors )
  { 
    cap_end = c; 
  }
 
  // pick closest connector on pipe:
 
  connectors = pipe.ConnectorManager.Connectors;
 
  Connector pipe_end = null;
  double dist = double.MaxValue;
  foreach( Connector c in connectors )
  {
    XYZ p = c.Origin;
    double d = p.DistanceTo( start );
    if( d < dist )
    {
      dist = d;
      pipe_end = c;
    }
  }
  pipe_end.ConnectTo( cap_end );
 
  doc.Regenerate();
 
  // After ConnectTo, the cap size is double, so 
  // need to change the nominal radius to half.
 
  if( fi != null )
  {
    ConnectorSet pipeConnectors 
      = pipe.ConnectorManager.Connectors;
 
    Connector pipeEnd = null;
 
    foreach( Connector c in pipeConnectors )
    {
      pipeEnd = c;
    }
    double radius = pipeEnd.Radius;
 
    Parameter para = fi.get_Parameter( 
      "Nominal Radius" );
 
    if( para != null && !para.IsReadOnly )
    {
      para.Set( radius );
    }
  }

Here is a screen capture of the result of testing caps on a vertical pipe:

Many thanks to Saikat and Mick for providing this new sample!

The ADN MEP Sample AdnRme for Revit MEP 2013

Yesterday I discussed the Revit 2013 MEP API and the external services framework.

In preparation for my Revit MEP API presentation at the upcoming AEC DevCamp in Boston in June, I also migrated the ADN MEP API sample AdnRme to Revit MEP 2013.

The initial flat migration was extremely straightforward with zero code changes required.

I obviously had to change the Revit API assembly references, which forces an update of the .NET framework version to 4.0. After bumping the framework version, the whole solution immediately compiled with zero errors and warnings. I must admit I was a bit surprised.

New One-box Product Type

On loading it, though, I was surprised again, because the add-in ribbon panel was simply not displayed.

Debugging the external application OnStartup method revealed that since I was running and testing it in a one-box flavour of Revit, the product type was not 'MEP' but simply 'Revit'. To fix this, I had to add support for both of those enumeration values to my product type test:

public Result OnStartup( UIControlledApplication a )
{
  // only create a new ribbon panel in Revit MEP:
 
  ProductType pt = a.ControlledApplication.Product;
 
  //if( ProductType.MEP == pt ) // 2012
 
  if( ProductType.MEP == pt 
    || ProductType.Revit == pt ) // 2013
  {
    AddRibbonPanel( a );
    return Result.Succeeded;
  }
  return Result.Cancelled;
}

With that little change in place, everything works fine and my ribbon panel shows up as expected:

Actually, for full-fledged support of the new runtime discipline switching, I could add more flexible enabling and disabling of my buttons, if I wanted to, for instance by dynamically hiding this application when the MEP discipline is not enabled.

Here is the 'About' box, automatically populated with properties harvested from the .NET assembly company, copyright, description, product, title and version and attributes, explaining briefly what this sample is about:

History and Functionality

By the way, although I have been demonstrating and using this sample for many years now, I have still not described its functionality in detail here in the blog, so maybe that is something I should do right now.

Several descriptions have been made publicly available in the past, though, for instance in the materials for my Autodesk University 2011 virtual class CP4453 Everything in Place with Autodesk Revit MEP Programming, covering both the Revit MEP 2012 API features and the Revit MEP API in general.

Before that, I already published the code here on the blog for Revit MEP 2012 and previous versions, and at previous Autodesk University and AEC DevCamp events.

The AdnRme sample demonstrates several Revit MEP API aspects, in two separate main areas:

• HVAC air terminal analysis and sizing.
• Hierarchical display of an electrical system.

It also demonstrates some Revit and .NET API aspects not directly related to the MEP API, such as:

• External application implementation.
• About box, automatically populated using .NET assembly properties.
• Progress bar.

AdnRme implements an external application to define a custom user interface to access the sample commands, as you can see from the ribbon panel shown above. The about box is also shown above.

The progress bar may be useful in a large project, since the processing of a large number of elements may take a noticeable amount of time, and is implemented using a standard .NET modeless form:

HVAC Air Terminal Analysis and Sizing Sample

The HVAC part of the MEP sample was originally implemented based on Revit 2008, before the advent of any MEP-specific API at all, using pure generic Revit element and parameter access to analyse and modify the HVAC duct system.

It supports a typical HVAC engineering workflow including the following tasks:

• Placement and sizing of air distribution ducts and terminals.
• Analysis and verification of results.

In a little more detail, the workflow might look like this:

• Manually lay out air terminals.
• Run heating and cooling load analysis.
• Based on load analysis, assign flow to terminals.
• Based on terminal flow, size air terminals.
• Validate design; a common check figure uses air flow per surface area.

The MEP HVAC sample was originally implemented for Revit 2008 and based on room elements, since spaces had not yet been introduced back then. It was modified for RME 2009 to use spaces.

It implements the following four commands to support the HVAC engineering workflow described above. The first three support the actual workflow itself, the fourth cleans up and resets the data manipulated by them:

• Assign flow to terminals.
• Change air terminal size.
• Calculate and display flow density as colour fill to verify design by air flow per surface area.
• Reset demo.

This workflow is exercised in the following simple office building sample model with a place holder duct system in place:

Here it is in plan view:

The progress of the steps is displayed by four schedules set up in the sample model:

Initially, all the 51 diffusers are the same:

The 33 spaces have calculated and specified supply air flows defined, but no actual flow:

The CFM per SF parameter in the right-hand column is defined to generate a colour schema at the end to verify the results visually at a glance, and is currently still set to zero.

The air terminals have not yet been properly analysed and sized:

Their flow and actual supply air flow is still zero:

Executing the commands in the proper sequence fixes all this:

• Assign flow to terminals: calculate the required flow per terminal by dividing the required flow for the space by the number of terminals, and assigning the resulting value to each terminal via its Flow parameter.
• Change air terminal size: for each diffuser type, determine its minimum and maximum flow. Select the type that ensures that the actual flow lies between these two.
• Calculate and display flow density as colour fill to verify design by air flow per surface area: calculate the CFM per SF using the built-in parameters ROOM_ACTUAL_SUPPLY_AIRFLOW_PARAM and ROOM_AREA and set the "CFM per SF" parameter accordingly.

The schedules are all updated, and the predefined colour fill displays and enables visual verification of the results:

Electrical Hierarchy Sample

Later during the lifetime of this sample, the electrical hierarchy functionality was added, initially based on non-MEP-specific analysis of parameter values to determine the system structure, later rewritten and significantly simplified by accessing the MEP connectors for this task instead.

In a way, the electrical hierarchy part is closely related to the TraverseSystem duct system SDK sample, which traverses a duct system by moving through its elements from predecessor to successor element through the connectors and storing the resulting tree data in an HTML file.

The AdnRme electrical sample does the same and displays the result in a tree view form instead:

It actually determines and displays the hierarchical structure of the electrical systems in the model in several different ways. Its focus is to:

• Traverse the electrical system
• Reproduce the system browser data structure in a tree view
• Determine and display the complete connection hierarchy in a tree view

The standard RME system browser displays electrical components in a three-level flat list, and the complete hierarchical structure of the connection tree is not immediately apparent. This sample inspects the electrical systems and reproduces the structure and information displayed by the system browser as well as the full connection hierarchy. It implements the following commands:

• CmdElectricalConnectors
• CmdElectricalSystemBrowser
• CmdUnhostedElements

The first two analyse the electrical system hierarchical structure and present it to the user in a tree view in a modeless dialogue, either in the full hierarchical structure, or in the three-tier structure used by the system browser; the third detects and lists un-hosted elements.

The form displaying the full electrical system hierarchical structure is shown above. Besides the hierarchical structure, it also presents a list of panels and devices on the left-hand side and highlights them in bold in the hierarchical tree display.

Clicking on a panel node in the left-hand list redisplays the tree on the right, with all the tree nodes except the selected panel or device collapsed. Here we select the panel H-2:

Here, transformer T1 is selected instead:

Being modeless, the form remains visible and can be navigated after the command has terminated. You can leave the form open and switch back and forth between it and Revit to explore the electrical system simultaneously from both points of view. Note, however, that updates to the model will not be reflected in the dialogue until the command is re-executed. A sample model elec_project.rvt is provided. Also note that this was originally implemented a long time ago and does not take all of Arnošt's recent advice on interaction with a modeless dialogue and avoiding too much use of the Idling event into account. On the other hand, the modeless form never attempts to make any use whatsoever of the Revit API, so there should be nothing to worry about in this case.

Besides the connection hierarchy tree, the electrical sample also implements these other commands:

• Obsolete pre-connector approach
• Three-tier system browser structure
• Find un-hosted elements

The obsolete pre-connector parameter-based approach is still included in the source code, in the C# module CmdElectricalHierarchy2.cs, but has been removed from the user interface.

The system browser three-tier structure is also displayed in a tree structure, like this:

The un-hosted element command simply displays a Windows message box listing all elements, which may well overflow the screen in a large untidy model:

As said, I documented some other aspects of this sample in the last few years' Revit MEP API classes at Autodesk University and the AEC DevCamp two years back, so if you really want to know still more, you might be lucky there. I think this just about covers it, though, actually more than enough.

Here is adn_rme_2013.zip containing the full Visual Studio solution, source code, add-in manifest and electrical and HVAC sample models to run this and play with. Enjoy.

Many thanks once again to Martin Schmid for motivating and helping me set up the HVAC sample back then, many years ago, and many other inspiring impulses since!

US Army Corps of Engineers Revit Templates

Here is a little piece of news that just happened to come past my way and might be of interest to you as well, even though it is not API related:

The US Army Corps of Engineers ASACE has released version 1 of their Revit Architecture, Structure, MEP templates.

These templates were developed to standardize MILCON production documentation and deliverables created by in-house USACE staff to reduce project start-up and configuration lead times, improve the quality and consistency of the contract deliverables and increase the adoption of BIM in general.

If you are interested in this fiscal year's opportunities with USACE, here are some interesting links:

• Federal Business Opportunities
• Federal procurement bidding opportunity search
• USACE FY12 Acquisition Forecast – Military Construction

The Revit 2013 MEP API and External Services

I mentioned a few MEP-specific enhancements in the Revit 2013 API. To recap, the enhancements include:

• Access to routing preferences, selection of pipe sizes, materials, fitting types, and the RoutingPreferenceTools SDK sample demonstrating its use
• Pipe and duct friction factors
• MEPSection base class for duct and pipe sections
• Viscosity and density at specified temperatures, new FluidType and enhanced FluidTemperature classes
• Read and write access to panel schedule spare circuit values
• Access to localized user-visible display strings for enumeration values via new LabelUtils.GetLabelFor overloads
• ConnectorProfileType and PartType enumeration changes
• ConnectorElement changes in the family environment, and new static creation methods replacing the obsolete ones on the FamilyItemFactory class.
• A new ThermalProperties class, thermal material assets, thermal information in gbXML
• New calculation functionality and the external services framework
• MEP piping, system routing and centre line functionality
• A new Light and Light Group API
• ReferenceIntersector class

For more information on these and many other Revit API enhancements, please refer to the What's New section of the Revit API help file RevitAPI.chm.

Here are some additional notes on the external services framework:

External Services Framework

The new External Services framework wraps external service functionality, enabling certain services such as analysis or calculations to be encapsulated and replaced, providing a basis for future MEP calculations and structural code checking. The following excerpt from the Revit API help file RevitAPI.chm description of the new ExternalService class provides a pretty good idea of its use:

This is a base class from which SingleServerService and MultiServerService classes are inherited. It implements all basic methods, and the inherited classes add more specific methods. Use this base class to get information about a service and its servers, and the inherited classes to set or get active servers. Functionality:

• Add and remove a server to and from a service
• Query information about a service
• Access servers currently registered for a service
• Get and set active server (or servers) for a service

Although the framework is in place and fully functional in Revit 2013, no in-house external services making use of external servers have yet been implemented. For this reason, no examples of this framework have yet been provided.

The next thing I intend to do regarding Revit MEP is migrate my trusty old AdnRme sample and MEP sample code for Revit 2012 to Revit 2013.

New Revit 2013 SDK Samples

Revit 2013 has been released, and I presented an overview of the Revit 2013 API two days ago.

As always, the use of most of the API features is demonstrated by various SDK samples. For a better understanding of the use and contents of the Revit SDK in general, please refer to the getting started and self-preparation guides.

Here is an overview of the new samples:

• ModelessForm_ExternalEvent and ModelessForm_IdlingEvent (ModelessDialog)
• ProgressNotifier (Events)
• RoutingPreferenceTools
• UIAPI
• WorkThread (MultiThreading)

These samples are all related to the new add-in integration functionality, except for the RoutingPreferenceTools which obviously demonstrate some of the MEP related enhancements.

By the way, the 'VSTA Samples' folder was renamed to 'Macro Samples' since VSTA was replaced by the open source SharpDevelop IDE.

ModelessForm_ExternalEvent and ModelessForm_IdlingEvent

Both of these display and show how to interact with a modeless form. One way to do this is to use the Idling event initially provided in Revit 2012, which we have discussed so much and in such depth in the past.

The ModelessForm_IdlingEvent sample should clarify many of the issues we dealt with, and is also related the material presented by Arnošt Löbel in his Autodesk University 2011 class CP5381 on asynchronous interactions and managing modeless UI.

The ModelessForm_ExternalEvent sample demonstrates an easier way to implement this interaction using the new external event interface.

ProgressNotifier

The ProgressNotifier sample displays progress information for an action in a stack data structure for easier analysis. It demonstrates how to subscribe to the ProgressNotify related events, access properties in the event handler arguments, and organize the subtransaction progress information into a stack.

RoutingPreferenceTools

The RoutingPreferenceTools sample provides a number of MEP pipe routing preference tools.

This sample contains three commands, one for analysis and reporting purposes, two for importing and exporting routing preferences to XML:

• Routing Preference Analysis: Analyze the routing preferences of a given pipe type to check for common problems, using the routing preferences API to look at all rules and criteria for a given PipeType.
• Routing Preference Builder with its two commands CommandReadPreferences and CommandWritePreferences: Set pipe type, fitting, and routing preferences in a project from data in an XML file and export these preferences to XML for archival, documentation, and collaboration purposes, allowing a user to work with routing preference data in a shareable XML format suitable for reuse in a wide variety of BIM management environments.

UIAPI

The UIAPI sample demonstrates a number of the new add-in integration API features that I already listed, including embedding a Revit view as WPF control inside its own dialogue, the new drag and drop API, and the Options dialogue support for custom extensions using arbitrary WPF components. This sample was also shown at the DevDays 2011 conferences.

WorkThread

The WorkThread sample demonstrates utilizing the Idling event in a multi-threaded application to communicate with the Revit API from an external work thread.

Retrieve Geometry in Element Coordinate System

I am travelling rather further afield than usual today, and actually have been doing so all day yesterday as well. My normal paths remain inside of Europe, with occasional trips once or twice a year to the USA, for AEC DevCamp and Autodesk University. Now, exceptionally, I am on my way to Melbourne, Australia, to present a Revit API training and DevCamp next week.

Meanwhile, here is an interesting little issue brought up by Olli Kattelus, software developer of MagiCAD for Progman Oy in the context of IFC export of MEP ducts and pipes. It is a teeny weeny bit tricky and can yet be solved quite easily using the geometrical tools provided by the Revit API.

Question: My problem in brief:

I can't get positions of the geometry primitives of the duct/pipe etc. in the instance's own coordinate system. Or is it possible?

More in-depth explanation:

For standard family instances such as air terminal, fitting, etc., I CAN retrieve the geometry primitives (faces etc.) and their coordinates in the symbol's own coordinate system. I also can transform them to the global coordinate system by using the transform provided by the GeometryInstance class.

For system families, however, things are different. The first obstacle is that ducts/pipes etc. don't have any GeometryInstance as their geometry. When I fetch their geometry primitives, they are returned in the global coordinate system.

I would really need to get them also in the "symbols" own coordinate system.

The reason I need this is that I'm working on an IFC export. In IFC, the geometry is exported only once per object type, or at least that is much preferred. The coordinates of geometry must be therefore be given in the element coordinate system because when the IFC file is read, the location and orientation of the object tells the IFC interpreter where to place the resulting geometry.

If the geometry is exported using the global coordinate system, things go wrong. Some geometry transformation methods are provided by the ExporterIFCUtils classes, but unfortunately I can't use them because I'm not using the Revit API to create the export.

Answer: Here is a suggestion for an approach:

1. Determine the duct or pipe start and end points in the global coordinate system GCS.
2. Define what you mean by "instance's own coordinate system" ICS, for instance start point equals origin, duct or pipe direction equals X axis, something or other equals the Z axis etc.
3. Determine the transformation T from the GCS to the ICS.
4. Obtain the duct or pipe geometry primitives and apply T to them to place them in ICS.

Probably the easiest way to determine the transform from GCS to ICS is to first create the inverse one from ICS to GCS.

This can then easily be inverted using the Revit API Transform.Inverse property.

To create the transformation from ICS to GCS is also normally easy, since you can decide for yourself how you consider it should be set up. For instance, for a duct, you could say that the ICS is located at its origin and has cardinal X, Y and Z axes.

To define the appropriate Revit API Transform instance, you just have to plug in the coordinates of the GCS start and end points appropriately into the Transform basis properties, cf. the description of the Transform.Basis property in the Revit API help file. You may have to fiddle around a bit to get it right, but it should work.

Response: Thanks A LOT for your instructions! I had kind of tried this at some previous point but I wasn't sure whether it could work this way. After your encouragement I had enough 'faith' to try until it worked :-)

As you said, I had to 'fiddle' a little bit with those but eventually managed to get it work in most of the cases.

I ended up with this kind of scenario:

For all the objects (generally system families) whose geometry primitives are required in ICS, I define origin, direction and normal as follows similar to the approach used in IFC, using the given element and its 'end connector' coordinate system:

  coordSys = m_revElem
    ->endConnectors[0]
    ->CoordinateSystem;

  org = coordSys->Origin;
  dir = coordSys->BasisZ->Negate();
  norm = coordSys->BasisY->Negate();

Sorry that this is not pure Revit API code, but as said 'm_revElem->endConnectors[0]' simply means some connector on the element.

To get the geometry to work correctly in our IFC output, I created the following transform:

  Transform ^tf = Transform::Identity;
  tf->BasisX = coordSys->BasisZ->Negate();
  tf->BasisY = coordSys->BasisX;
  tf->BasisZ = coordSys->BasisY->Negate();
  tf->Origin = coordSys->Origin;
  tf = tf->Inverse;

So this really DID help a lot. Thanks again for this!!

Split a Duct or Pipe

Here is another short and sweet answer to a question that keeps popping up regularly:

Question: How can I change the length of a pipe using the Revit MEP API?

I am actually interested in programmatically splitting the pipe, but I cannot see any support for this in the API.

I tried to change the length of the pipe to indirectly cause a split, but the LocationCurve.Length property is read-only, so I cannot simply modify it.

Answer: I touched briefly on the topic of splitting a duct or pipe a long time ago, back in 2009.

As stated there, there is no built-in ready-made method to split a pipe or duct.

You can however create as many new ducts and pipes as you like using the NewDuct and NewPipe methods.

Also, although the LocationCurve.Length property is read-only, you can still modify it by simply assigning a completely new curve to the element Location property itself. We already discussed samples of doing so for a beam and a wall. The same approach can be used on a pipe as well, and obviously replacing the location curve can also change its length.

Finally, the whole operation of splitting pipes and ducts both by changing their lengths and by creating new elements is demonstrated by the Revit SDK samples, especially the AutoRoute and AvoidObstruction ones:

• AutoRoute: Route a set of ducts and fittings between a base air supply equipment and two terminals.
• AvoidObstruction: Detect and resolve obstructions between ducts, pipes, and beams.

Hosting a Light Fitting on a Reference Plane

It is sometimes a challenge to determine which of the numerous overloads of the NewFamilyInstance method to use to achieve a desired effect. Here is a question on using it to host a light fitting by Simon Jones, with an initial answer by Saikat Bhattacharya, followed by lots more research by Simon to nail down the right solution that really works.

Question: How can I host a light fitting onto a reference plane?

I tried several different ways without any luck so far.

When I use the following, the light is hosted by the reference plane but doesn't move with it:

  mRevitDoc.Document.Create.NewFamilyInstance(
    pt, mFamilySymbol, refDir, mReferencePlane,
    StructuralType.NonStructural);

What should I use instead to make the fitting remain attached to the plane at all times?

Answer: The following modification to your code addresses your requirement.

It uses the overload of NewFamilyInstance taking a reference, point, vector and symbol to insert a new instance of a family onto a face referenced by the input Reference instance, using a location and reference direction.

This creates a family instance which moves when the ReferencePlane is moved.

For simplicity, I have hard coded the element id of the ReferencePlane of my test project.

Before running this code, please select the lighting instance on the base work plane. This code then creates a lighting instance on the reference plane (along with the existing lighting fixture on the reference).

Now you can move the reference plane to the other side of the wall and confirm that the new lighting fixture instance moves along with it too.

  Selection sel = uidoc.Selection;
 
  ElementSet elemSet = sel.Elements;
 
  Transaction trans = new Transaction( doc );
  trans.Start( "Lights Camera Action!" );
 
  IEnumerator iter = elemSet.ForwardIterator();
 
  Element element;
 
  ReferencePlane mReferencePlane = null;
  FamilyInstance mFamilyInstance = null;
  FamilySymbol mFamilySymbol = null;
 
  while( iter.MoveNext() )
  {
    element = iter.Current as Element;
 
    FamilyInstance fi = element as FamilyInstance;
 
    mFamilyInstance = fi;
    mFamilySymbol = fi.Symbol;
  }
 
  mReferencePlane = doc.get_Element(
    new ElementId( 615738 ) ) as ReferencePlane;
 
  XYZ pt = XYZ.Zero;
  XYZ refDir = XYZ.BasisZ;
 
  uidoc.Document.Create.NewFamilyInstance(
    mReferencePlane.Reference, pt, refDir,
    mFamilySymbol );
 
  trans.Commit();

Response: Perfect, got it working now.

The issue was that I was trying to place the light on a horizontal reference plane and it seems that the argument was set incorrectly. To begin with, strangely enough, it seemed that I needed to use a null vector for the reference direction for a horizontal reference plane:

  XYZ refDir = new XYZ(0,0,0);

Before that, I was using:

  XYZ refDir = new XYZ(0,0,1);

That caused my error.

Here is a current snapshot of my C# code and some sample input data. The code will read a TXT file and place lights on a named reference plane.

I explored the effect of the reference direction used in more detail. Here are my findings:

The reference direction required obviously depends on the orientation of the reference plane. So I guess the sensible thing to do is to use a direction relative to the plane's normal.

However, my solution requires taking ceiling layouts from AutoCAD and reading them into Revit via a txt file exported from AutoCAD. Within Revit we use horizontal reference planes drawn from right to left (as even with manual insertion that effects the orientation of the light); therefore, this is the solution I require and am happy that I have.

From what I can work out, the reference direction needs to point in the direction the reference plane is drawn; therefore 0,0,1 works for vertical planes, and 1,0,0 for horizontal ones. For a quick hack, the following works for both vertical and horizontal ref planes:

  XYZ refDir = new XYZ(
    rp.Normal.Z, rp.Normal.X, rp.Normal.Y );

Here are the results of my tests prior to adding the above hack:

Vertical Reference Plane along the End Wall

1. Vertical RP +ve Y (drawn bottom to top), RefDir 0,0,1:

2. Vertical RP -ve Y (drawn top to bottom), RefDir 0,0,1:

Result: The lights have been placed on the other side of the reference plane.

3. Vertical RP -ve Y (drawn top to bottom), RefDir 0,0,0:

Result: Same side of ref plane, but now they're rotated around 90 degrees.

Horizontal Reference Plane along the Underside of the Ceiling

4. Horizontal RP -ve X (drawn right to left), RefDir 0,0,0:

Result: Attached to the underside of the reference plane (as required).

5. Horizontal RP +ve X (drawn left to right), RefDir 0,0,0:

Result: Attached to the topside of the reference plane (not as required).

6. Horizontal RP +ve X (drawn left to right), RefDir 0,0,1 & Horizontal RP -ve X (drawn right to left), RefDir 0,0,1:

Result: 'Error code: 5'.

7. Horizontal RP -ve X (drawn right to left), RefDir 1,0,0:

Result: Look OK.

8. Horizontal RP -ve X (drawn right to left), RefDir 0,1,0:

Result: Lights rotated 90 degrees.

Many thanks to Simon and Saikat for this example and all the research!

Access Wire Sizes

Here is an interesting question that came up regarding the access to wire sizes. Using a filtered element collector to retrieve a TemperatureRatingType instance and attempting to read its wire sizes produces a problem that is in fact documented in the Revit API help file RevitAPI.chm, but the workaround is still worth pointing out.

Question: I'm trying to access the wire size settings in a Revit model without success.

The following code throws an exception saying "Object reference not set to an instance of an object" from the call to the TemperatureRatingType WireSizes property:

  FilteredElementCollector col 
    = new FilteredElementCollector( doc )
      .OfClass( typeof( TemperatureRatingType ) );
 
  IEnumerable<TemperatureRatingType> trEnumerable 
    = col.ToElements().Cast<TemperatureRatingType>();
 
  var TempRatingReturn 
    = from rtelement in trEnumerable
      where rtelement.Name == "60"
      select rtelement;
 
  foreach( TemperatureRatingType rt 
    in TempRatingReturn )
  {
    WireSizeSet wsset = rt.WireSizes;
  }

Answer: You are absolutely right, and this is actually the documented and expected behaviour, although it may not be completely obvious from the API documentation. The description of the TemperatureRatingType class states the following:

Temperature rating type is defined based on corresponding wire material type. It includes type information such as wire size, insulation type, correction factor, etc. Only the temperature rating types which are retrieved from WireMaterialType can work well, so don't retrieve it from Revit document directly.

What this actually means is that the TemperatureRatingType object is not supported when retrieved through an ElementFilter. It can be retrieved from the document electrical settings WireMaterialTypes collection instead. In fact, you must retrieve it from there in able to access the wire sizes. This may seem odd, but is currently a fact. The workaround is thus very simple:

  foreach( WireMaterialType wt in doc.Settings
    .ElectricalSetting.WireMaterialTypes )
  {
    foreach( TemperatureRatingType trt in 
      wt.TemperatureRatings )
    {
      WireSizeSet ws = trt.WireSizes;
    }
  }

I implemented an add-in named ReadWireSizes which demonstrates both the exception being thrown and the workaround to retrieve the desired wire size settings from the electrical settings instead.

Here is the complete implementation of the external command Execute method:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  // Retrieve TemperatureRatingType from
  // filtered element collector; their
  // wire sizes cannot be accessed:
 
  FilteredElementCollector col 
    = new FilteredElementCollector( doc )
      .OfClass( typeof( TemperatureRatingType ) );
 
  IEnumerable<TemperatureRatingType> trEnumerable 
    = col.ToElements().Cast<TemperatureRatingType>();
 
  var TempRatingReturn 
    = from rtelement in trEnumerable
      where rtelement.Name == "60"
      select rtelement;
 
  // The wire sizes we are searching for:
 
  WireSizeSet wsset = null;
 
  // Keep track of the target TemperatureRatingType:
 
  ElementId rtId = null;
 
  foreach( TemperatureRatingType rt 
    in TempRatingReturn )
  {
    try
    {
      rtId = rt.Id;
 
      // This call fails:
 
      wsset = rt.WireSizes;
    }
    catch( NullReferenceException ex )
    {
      Debug.Print( ex.GetType().ToString() 
        + ": " + ex.Message );
 
      Debug.Assert( ex.Message.Equals( 
        "Object reference not set to an instance of an object." ), 
        "expected null reference exception" );
    }
  }
 
  // Iterate over the electrical settings 
  // wire material types and use the target 
  // element id to identify the proper
  // TemperatureRatingType:
 
  WireMaterialTypeSet wts = doc.Settings
    .ElectricalSetting.WireMaterialTypes;
 
  foreach( WireMaterialType wt in wts )
  {
    foreach( TemperatureRatingType rt 
      in wt.TemperatureRatings )
    {
      if( rtId == rt.Id )
      {
        wsset = rt.WireSizes;
      }
    }
  }
 
  int n = wsset.Size;
 
  Debug.Print( string.Format(
    "{0} wire size{1} stored on temperature "
    + "rating type with element id {2}",
    n, ( 1 == n ? "" : "s" ), rtId ) );
 
  return Result.Succeeded;

Running this command in the rme_advanced_sample_project.rvt sample project provided with Revit 2012 MEP generates the following output in the Visual Studio debug output window:

A first chance exception of type 'System
  .NullReferenceException' occurred in RevitAPI.dll
System.NullReferenceException: Object reference 
  not set to an instance of an object.
28 wire sizes stored on temperature rating type 
  with element id 293221

Here is ReadWireSizes.zip containing the complete source code, Visual Studio solution and add-in manifest for this external command.