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?

Basic File Info and RVT File Version

I presented an initial solution in Python for determining the version of an RVT file on disk from outside Revit making use of its OLE document Structured Storage format back in 2008. David Echols later shared a more full-fledged C# Revit OLE Storage viewer listing more information and displaying the preview image.

Since then, the Revit API added support for reading basic RVT file info through the BasicFileInfo class.

Victor Chekalin now presents another C# console application showing how some of this data can be accessed independently of the Revit API.

Before looking at that, here are some other topics that also came up in the past day or two:

• Building Setout Points used commercially
• Screen recording with Camtasia on the Mac
• Sustainable Autodesk Offices
• Reading the RVT file version without using the Revit API

Building Setout Points Used in a Commercial Application

I am glad to say that one of the sample add-ins I am particularly happy with now made its way into a commercial application.

Here is an excerpt from the current Australian ARSoftwareSolutions newsletter:

A recent meander through the TheBuildingCoder website led me to a routine for marking the corners of structural concrete corners. Once marked the points could be scheduled and provided to the builder as a file of set out point coordinates. These can then be established on site using various surveying tools. This seemed like something a lot of companies could benefit from so I set about including it in my software. (Please refer to http://thebuildingcoder.typepad.com/blog/rst for more complete details. Thank you to both Paul Hellawell of GHD and Jeremy Tammik for the idea and some of the coding.)

Of course I couldn't just leave it the way it was so I expanded on the concept, added extra functionality, and this now forms a part of ARUtils - Leader.

The basic concept is to mark all structural concrete corners with a "SetoutPoint" family. Critical setout points can then use a "Major" type of that family to indicate they are a critical point. Alternatively other points can be automatically designated as minor, centre points of curves, control points of splines, or just intermediate points along curves. Points can be promoted to Major or demoted to Minor as required for construction or changing needs.

When automatically placed at a point, each marker has the X,Y, and Z coordinates assigned to the marker. Once this has been done, the families can be scheduled and the points exported for use by the builder. The routine also keeps track of the item that generated the points so points can be grouped on a generating object basis.

Points marked. Diagram shows Major, Minor, Centre, Control and Curve following points.

Tagged points

Scheduled Keypoints

Schedule - All points

The interface

Note: You can automatically mark all structural concrete items, or pick specific items of any type to have markers placed.

Note: Should the project location change the coordinates can be automatically synchronised using the "Renumber / Update" option.

I am happy to see my efforts helping people and making their way out into the world :-)

Screen Recording on the Mac

On a completely different topic, I have been struggling a bit the past few days to set up a proper screen recording environment for myself to create a canned presentation.

I want to show some Powerpoint slides, record my narration, and also make use of Revit and Visual Studio for add-in demonstrations.

I planned to use Camtasia for this, as I have past experience with it and it does a good job.

The Revit and Visual Studio requirements led me to believe that I had to install Camtasia in my Windows virtual machine.

When I did that, I discovered that the Windows version that I had installed was European and therefore lacked the Windows Media Player, which caused Camtasia to fail. It took a while to find out, though.

I went off and downloaded a US version of Windows, created a new virtual machine, installed Revit, Visual Studio, Camtasia, and some other bits and pieces on it.

After doing all that, I discovered that the Camtasia output quality from this setup is suboptimal, and there are often problems with the audio getting lost completely.

After struggling a bit more with that, a colleague told me that the easiest thing to do is just to use Camtasia in the native Mac system and record the full screen. I can display the Powerpoint slides in full screen, record my narration, and switch back and forth to a full-screen virtual Windows machine at any time. So I wasted a lot of time there. Now I can get going with my recording just as soon as I finish this post.

Sustainable Autodesk Offices

Back to the architectural realm, two new case studies on the green office design of the Autodesk offices in Milan and Farnborough are now live on the Autodesk Sustainable Design Center:

• Farnborough
• Milano

These projects were implemented by Morgan Lovell plc and Goring & Straja Architects, respectively. The case studies describe the projects, challenges, solutions, results and learning experiences made.

I hope you find this interesting, useful and feel inspired to pursue the same kind of greening efforts in your own company :-)

Determining the RVT File Version Without Revit

Back to the main topic that I started discussing above.

This came up again prompted by a comment by Victor Chekalin, or Виктор Чекалин, on the original post.

He points to a stackflow discussion thread: How can I get the Revit file version using the Revit API?

Question: In the Revit API I know that I can get the version of the Revit instance that is currently running:

• ControlledApplication.VersionBuild
• ControlledApplication.VersionName
• ControlledApplication.VersionNumber

However, I would like to get the version of a Revit file itself before I open it. This way I could stop the automatic upgrade dialog that shows when a user opens an older Revit file in a newer version of Revit. I'm using Revit 2013 and expecting files from 2011, 2012, and 2013.

Answer from skeletank: I took a closer look at the discussion group posting from my question and found that the version information is actually human readable among the other gibberish of the file. The ".rvt" file is stored in OLE format so you can see the content if you use a tool like Structured Storage Viewer. It will be located under BasicFileInfo.

If you wanted to then you could probably use an OLE library for .NET to read the data but I used a StreamReader and a Regex instead.

Here is the regular expression:

Revit\sArchitecture\s(?\d{4})\s(Build:\s(?\w*)\((?\w{3})\)\)

Here is the code:

private void ControlledApplication_DocumentOpening(
  object sender,
  DocumentOpeningEventArgs e )
{
  FileInfo revitFileToUpgrade
    = new FileInfo( e.PathName );
 
  Regex buildInfoRegex = new Regex(
    @"Revit\sArchitecture\s(?<Year>\d{4})\s"
    +@"\(Build:\s(?<Build>\w*)\((<Processor>\w{3})\)\)" );
 
  using( StreamReader streamReader =
    new StreamReader( e.PathName, Encoding.Unicode ) )
  {
    string fileContents = streamReader.ReadToEnd();
 
    Match buildInfo = buildInfoRegex.Match( fileContents );
    string year = buildInfo.Groups["Year"].Value;
    string build = buildInfo.Groups["Build"].Value;
    string processor = buildInfo.Groups["Processor"].Value;
  }
}

This will allow you to get the year, build number, and the type of processor. Notice, however, that my version checks specifically for Architecture so you will need to modify it for MEP or Structural.

Answer from Victor Chekalin:

As you said, Revit file format is a Structured Storage document and information you need is stored in the BasicFileInfo stream.

Within the Revit 2013 API you can use the SavedInVersion method of the BasicFileInfo class.

Here is the full console application demonstrating how to extract BasicFileInfo data without the Revit API.

Unfortunately I don't now the format of the BasicFileInfoStream. But if you read it as string you can get version in which file was created.

Reading only the BasicFileInfo is much better than reading the whole file. Imagine if the Revit project is over 500 MB. You will read the whole file into memory when you call

  string fileContents = streamReader.ReadToEnd();

Also, Regular expression on the huge file works slow.

I think you should use

  var rawString = System.Text.Encoding.Unicode
    .GetString( rawData );

from my sample and use Regex in the rawString instead the whole file.

For your convenience, here is the full source code of Victor's solution:

using System;
using System.IO;
using System.IO.Packaging;
using System.Reflection;
using System.Runtime.InteropServices;
 
namespace ConsoleApplication1
{
  class Program
  {
    private const string StreamName = "BasicFileInfo";
 
    static void Main( string[] args )
    {
      string pathToRevitFile = ( 1 == args.Length )
        ? args[0]
        : @"pathToRevitFile";
 
 
      if( !StructuredStorageUtils.IsFileStucturedStorage(
        pathToRevitFile ) )
      {
        throw new NotSupportedException(
          "File is not a structured storage file" );
      }
 
      var rawData = GetRawBasicFileInfo( pathToRevitFile );
 
      var rawString = System.Text.Encoding.Unicode.GetString(
        rawData );
 
      var fileInfoData = rawString.Split(
        new string[] { "\0", "\r\n" },
        StringSplitOptions.RemoveEmptyEntries );
 
      foreach( var info in fileInfoData )
      {
        Console.WriteLine( info );
      }
    }
 
    private static byte[] GetRawBasicFileInfo(
      string revitFileName )
    {
      if( !StructuredStorageUtils.IsFileStucturedStorage(
        revitFileName ) )
      {
        throw new NotSupportedException(
          "File is not a structured storage file" );
      }
 
      using( StructuredStorageRoot ssRoot =
          new StructuredStorageRoot( revitFileName ) )
      {
        if( !ssRoot.BaseRoot.StreamExists( StreamName ) )
          throw new NotSupportedException( string.Format(
            "File doesn't contain {0} stream", StreamName ) );
 
        StreamInfo imageStreamInfo =
            ssRoot.BaseRoot.GetStreamInfo( StreamName );
 
        using( Stream stream = imageStreamInfo.GetStream(
          FileMode.Open, FileAccess.Read ) )
        {
          byte[] buffer = new byte[stream.Length];
          stream.Read( buffer, 0, buffer.Length );
          return buffer;
        }
      }
    }
  }
 
  public static class StructuredStorageUtils
  {
    [DllImport( "ole32.dll" )]
    static extern int StgIsStorageFile(
      [MarshalAs( UnmanagedType.LPWStr )]
      string pwcsName );
 
    public static bool IsFileStucturedStorage(
      string fileName )
    {
      int res = StgIsStorageFile( fileName );
 
      if( res == 0 )
        return true;
 
      if( res == 1 )
        return false;
 
      throw new FileNotFoundException(
        "File not found", fileName );
    }
  }
 
  public class StructuredStorageException : Exception
  {
    public StructuredStorageException()
    {
    }
 
    public StructuredStorageException( string message )
      : base( message )
    {
    }
 
    public StructuredStorageException(
      string message,
      Exception innerException )
      : base( message, innerException )
    {
    }
  }
 
  public class StructuredStorageRoot : IDisposable
  {
    StorageInfo _storageRoot;
 
    public StructuredStorageRoot( Stream stream )
    {
      try
      {
        _storageRoot
          = (StorageInfo)InvokeStorageRootMethod(
            null, "CreateOnStream", stream );
      }
      catch( Exception ex )
      {
        throw new StructuredStorageException(
          "Cannot get StructuredStorageRoot", ex );
      }
    }
 
    public StructuredStorageRoot( string fileName )
    {
      try
      {
        _storageRoot
          = (StorageInfo)InvokeStorageRootMethod(
            null, "Open", fileName, FileMode.Open,
            FileAccess.Read, FileShare.Read );
      }
      catch( Exception ex )
      {
        throw new StructuredStorageException(
          "Cannot get StructuredStorageRoot", ex );
      }
    }
 
    private static object InvokeStorageRootMethod(
      StorageInfo storageRoot,
      string methodName,
      params object[] methodArgs )
    {
      Type storageRootType
        = typeof( StorageInfo ).Assembly.GetType(
          "System.IO.Packaging.StorageRoot",
          true, false );
 
      object result = storageRootType.InvokeMember(
        methodName,
        BindingFlags.Static | BindingFlags.Instance
        | BindingFlags.Public | BindingFlags.NonPublic
        | BindingFlags.InvokeMethod,
        null, storageRoot, methodArgs );
 
      return result;
    }
 
    private void CloseStorageRoot()
    {
      InvokeStorageRootMethod( _storageRoot, "Close" );
    }
 
    #region Implementation of IDisposable
 
    public void Dispose()
    {
      CloseStorageRoot();
    }
 
    #endregion
 
    public StorageInfo BaseRoot
    {
      get { return _storageRoot; }
    }
  }
}

For your even greater convenience, I am also providing RevitBasicFileInfo.zip containing the full Visual Studio solution that I created to test it.

Here is the result of running this on a sample model on my system:

Many thanks to Victor for his clear explanation and solution!

Addendum: To get access to the StreamInfo class you need reference the WindowsBase.dll assembly.

The question marks displayed in the result console above are due to the fact that one part of BasicFileInfo is encoded in Unicode and another in BigEndianUnicode.

The second part is rendered legible by accessing it like this instead:

  var rawString = System.Text.Encoding
    .BigEndianUnicode.GetString( rawData );

Here is the same file information presented twice, once in standard little endian and once in big endian decoding:

This is a summary of the resulting readable text fields:

• Little-endian:
• Autodesk Revit 2013 (Build: 20120716_1115)
• C:\j\tmp\rvt\floor_slab.rvt
• Big-endian:
• 00000000-0000-0000-0000-000000000000
• Worksharing: Not enabled
• Username:
• Central Model Path:
• Revit Build: Autodesk Revit 2013 (Build: 20120716_1115)
• Last Save Path: C:\j\tmp\rvt\floor_slab.rvt
• Open Workset Default: 3
• Project Spark File: 0
• Central Model Identity: 00000000-0000-0000-0000-000000000000
• Locale when saved: ENU

Set Detail Curve Visibility

Mostly, the Revit API limits an add-in to pretty high-level operations, encapsulating and protecting the parametric BIM from reckless modifications. For the nonce, here is a little bit of nitty-gritty bit manipulation anyway, in a utility method provided by Scott Conover:

Question: Why is there no DetailCurve.SetVisibility method exposed, similar to ModelCurves.SetVisibility?

The UI has this functionality, and I would find very good use for it in reinforcement detailing.

I want to programmatically create a detail family representing a certain rebar shape. The family instance should reflect the visibility states, single line in coarse, double line in fine.

Answer: The ModelCurve.SetVisibility method taking a FamilyElementVisibility argument is available for visibility of curve elements in families when the families are placed. Similarly we have a SymbolicCurve.SetVisibility method. Detail curves don't have the exact same functionality in the UI. Generally, detail curves are visible only in a single view in which they are placed. The access you describe is partially enabled for detail families, however.

Here is a workaround to access this functionality: the visibility settings for the curve are stored in the integer GEOM_VISIBILITY_PARAM built-in parameter as bit flags. You can therefore request the desired display by setting the appropriate bits in that parameter value.

The SetFamilyVisibility method presented below turns off the modes you do not want for visibility. It can be called either from an external command or a macro.

It makes use of a simple selection filter to restrict the user selection to detail curves:

class DetailCurveSelectionFilter : ISelectionFilter
{
  public bool AllowElement( Element e )
  {
    CurveElementFilter filter
      = new CurveElementFilter(
        CurveElementType.DetailCurve );
 
    return filter.PassesFilter( e );
  }
 
  public bool AllowReference( Reference r, XYZ p )
  {
    return false;
  }
}

Here is the method implementation itself:

public void SetFamilyVisibility( UIDocument uidoc )
{
  Document doc = uidoc.Document;
 
  Reference r = uidoc.Selection.PickObject(
    ObjectType.Element,
    new DetailCurveSelectionFilter(),
    "Select detail curve" );
 
  Element elem = doc.GetElement( r );
 
  Parameter visParam = elem.get_Parameter(
    BuiltInParameter.GEOM_VISIBILITY_PARAM );
 
  int vis = visParam.AsInteger();
 
  using( Transaction t = new Transaction( doc ) )
  {
    t.Start( "Set curve visibility" );
 
    // Turn off the bit corresponding
    // to the unwanted modes
 
    vis = vis & ~( 1 << 13 ); // Coarse
    //vis = vis & ~(1 << 14); // Medium
    //vis = vis & ~(1 << 15); // Fine
 
    visParam.Set( vis );
 
    t.Commit();
  }
}

Remember that all three modes cannot be turned off simultaneously – a posted error will result.

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

Many thanks to Scott for this tricky hint!

Roll Your Own Toggle Button

Today I took my first stab at creating, compiling and debugging a new Revit add-in on the Mac.

I cannot run Revit or Visual Studio natively on the Mac, of course, so those have to remain in Windows, hosted by the Parallels environment on the Mac.

I had to fiddle around quite a bit with the Parallels synchronisation, which seems to be breaking more things than it fixes, for me at least. I managed in the end in spite of that, though.

The opportunity to implement a new sample add-in was provided by the following question:

Question: Is there a way to create a ribbon button that can be toggled, e.g. a sort of on/off switch like the Modify > Properties button?

Answer: Yes, sure.

You will have to roll your own, though.

The Revit API just provides radio buttons.

Here is a description of radio buttons from Saikat Bhattacharya's upcoming Autodesk University class CP3272 Snapshot of the Autodesk Revit User Interface API:

Radio Buttons

A radio button group helps toggle between options by letting users select only one ribbon item at a time. After adding a RadioButtonGroup to a panel, use the AddItem and AddItems methods to add radio buttons, which are basically normal PushButtons, to the group. The RadioButtonGroup.Current property can be used to access the currently selected button. Just like SplitButton, tooltips do not apply to radio button groups; instead the tooltip for each toggle button is displayed.

  RadioButtonGroupData radioData =
    new RadioButtonGroupData( "radioGroup" );
 
  RadioButtonGroup radioButtonGroup =
    panel.AddItem( radioData ) as RadioButtonGroup;
 
  ToggleButtonData tb1 = new ToggleButtonData(
    "OverrideCommand1",
    "Override Cmd: Off",
    assemblyPath + "\\" + assemblyName,
    "SnapshotRevitUI_CS.OverrideOff" );
 
  ToggleButtonData tb2 = new ToggleButtonData(
    "OverrideCommand2",
    "Override Cmd: On",
    assemblyPath + "\\" + assemblyName,
    "SnapshotRevitUI_CS.OverrideOn" );
 
  tb2.ToolTip = "Override the Wall Creation command";
 
  tb2.LargeImage = new BitmapImage(
    new Uri( imageFolder + "globe_32.png" ) );
 
  radioButtonGroup.AddItem( tb1 );
  radioButtonGroup.AddItem( tb2 );

However, this is still not quite what you want, is it?

You would really like one single button that changes its state each time it is clicked.

A Real Toggle Button

Well, as said, this can easily be achieved by implementing your own custom button.

Note that the RibbonButton Image, LargeImage and ItemText properties are all read-write.

Therefore, there is nothing to stop you from changing the button appearance any way you like at any time you like. For instance, if you change these properties appropriately each time the button is clicked, it will appear like a toggle button such as you describe.

I implemented a minimal sample illustrating this using just the ItemText property:

It would look more impressive if I switched the image as well, of course. I leave that as a simple exercise to the reader.

The basic framework to achieve this consists of a very small external application and a single-line external command.

The external application sets up the ribbon panel and button, saves a reference to the latter, and provides a public method Toggle that uses the button reference to toggle its text:

class App : IExternalApplication
{
  static string _path = typeof( App ).Assembly.Location;
 
  RibbonItem _button;
 
  /// <summary>
  /// Singleton external application class instance.
  /// </summary>
  internal static App _app = null;
 
  /// <summary>
  /// Provide access to singleton class instance.
  /// </summary>
  public static App Instance
  {
    get { return _app; }
  }
 
  public Result OnStartup( 
    UIControlledApplication a )
  {
    _app = this;
 
    RibbonPanel panel = a.CreateRibbonPanel( 
      "ToggleButton" );
 
    PushButtonData data = new PushButtonData( 
      "Toggle", "On", _path, 
      "ToggleButton.Command" );
 
    data.AvailabilityClassName
      = "ToggleButton.Availability";
 
    _button = panel.AddItem( data );
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown( UIControlledApplication a )
  {
    return Result.Succeeded;
  }
 
  public void Toggle()
  {
    string s = _button.ItemText;
 
    _button.ItemText = s.Equals( "On" ) ? "Off" : "On";
  }
}

The button images could be toggled in a similar fashion.

The Toggle method is public, and used by the command to toggle the button state each time it is launched:

  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.Toggle();
 
    return Result.Succeeded;
  }

Probably one of the simplest command implementations you have ever seen, isn't it?

This command was initially read-only, and that makes sense, but I had to change it to manual transaction mode for reasons explained below.

Zero Document State Support

I made the whole sample a little bit more complicated in order to enable its use in a zero document context as well as when a project is opened.

I implemented a trivial availability class that I use to set the button availability. In this case, I want it to be available always:

  public class Availability
    : IExternalCommandAvailability
  {
    public bool IsCommandAvailable(
      UIApplication a,
      CategorySet b )
    {
      return true;
    }
  }

Enabling the command in zero document context also requires changing its transaction mode from read-only to manual, because Revit only allows manual transaction mode commands in zero document state. Violation of this rule causes the following error:

As you can see from the recording above, all is well now, and this is a viable solution.

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

While I've been having fun creating this sample, let's look at some examples of cool stuff other people are doing as well.

IDAT Revit Structure Slab Add-In

The German company IDAT presents a neat example of using the Revit API implement an add-in for the design, fabrication and construction logistics of precast hollow core slabs. This video shows their precast module for hollowcore slabs inside Revit Structure:

Ab in den Hafen by Allerdings

Completely unrelated to Revit and its API, but closely related to me, my son Christopher aka Allerdings has been composing and publishing music on SoundCloud for some time now.

Here is his most recent oevre, Ab in den Hafen:

Enjoy.

AUGI Wish List

Another cool and important thing, albeit more administrative, is the AUGI wish list providing a unified independent voice back to Autodesk on how to improve its products.

Please vote now for your most important wish.

Drive Revit through a WCF Service

Today, a special titbit for you:

How can I access Revit functionality from an external process?

As we have underlined many times in the past, the Revit API does not support any kind of asynchronous access.

The Idling event, however, provides a possibility to work around this limitation.

Daren Thomas, the author or RevitPythonShell, even presented a neat and clean pattern for semi asynchronous Idling API access.

Now Victor Chekalin, aka Виктор Чекалин, presents another very neat sample providing such an access. He says:

I have an idea how to access Revit from an external application.

The only official way to achieve this is through the Idling event and external events, of course.

The main idea:

• Inside Revit I create a service which receives queries from a stand-alone external process.
• The service receives a command from the external process and pushes it to the command pool.
• The Idling event handler looks at the command pool; if a command is waiting in the pool, it will be executed in the Idling event handler.

There is no risk. All commands are executed in the one and only Revit thread.

Here is the scheme of work:

In this implementation, I am using a WCF service. It would be equally possible to use any other technology or framework to handle the inter-application communication.

Everything you need to know about creating and using a WCF service is described in the WCF Getting Started Tutorial.

I created a simple demonstration project to test this idea. It implements the following minimal service demonstrating that we can access the Revit API, both to query it for information and execute and action that modifies the current BIM:

namespace RevitExternalAccessDemo
{
  [ServiceContract]
  public interface IRevitExternalService
  {
    [OperationContract]
    string GetCurrentDocumentPath();
 
    [OperationContract]
    bool CreateWall( XYZ startPoint, XYZ endPoint );
  }
}

It further requires:

• An external application to manage the Idling event subscription.
• An implementation of the service defined above.
• Two helper classes:
  • One to contain the queued up tasks and handle locking issues.
  • The other to redefine an own representation of the Revit API XYZ point class.

Here is a short video showing how it works:

I am happy to make the project available for everyone in its current state.

The source code is available on Github, both directly and as a Github zip archive file.

It is just a demo and provided as is.

To launch it on your computer, you must run Revit as administrator, because this is required by the WCF service.

Remember, Revit must be idling to launch a command from the external application.

In this kind of situation, calling the SetRaiseWithoutDelay method is of utmost importance. Without the call, the demo pauses. Even with it, some delay exists, and the CPU load grows to over 25% even if no operations are active in Revit.

A better solution exists – follow Arnošt Löbel suggestion: subscribe to the Idling event only when you really need it, and unsubscribe immediately afterwards, as soon as possible.

Obviously, we need to handle Idling only when we have a request queued up from the WCF service. The idea would be to subscribe to the Idling event when we receive a request from the WCF Service and unsubscribe when it has been processed.

Unfortunately, I have not yet implemented this idea in the code presented here.

Here are some sample code snippets from the current implementation.

First, here is the main external application implementation including:

• OnStartup, which creates the WCF service and subscribes to the Idling event.
• OnIdling, the Idling event handler, which dequeues and executes the next task.
• OnShutdown, unsubscribing and cleaning up.

class App : IExternalApplication
{
  private const string serviceUrl =
    "http://localhost:56789/RevitExternalService";
 
  private ServiceHost serviceHost;
 
  public Result OnStartup( 
    UIControlledApplication a )
  {
    a.Idling += OnIdling;
 
    Uri uri = new Uri( serviceUrl );
 
    serviceHost = new ServiceHost( 
      typeof( RevitExternalService ), uri );
 
    try
    {
      serviceHost.AddServiceEndpoint( 
        typeof( IRevitExternalService ), 
        new WSHttpBinding(), 
        "RevitExternalService" );
 
      ServiceMetadataBehavior smb 
        = new ServiceMetadataBehavior();
 
      smb.HttpGetEnabled = true;
 
      serviceHost.Description.Behaviors.Add( smb );
 
      serviceHost.Open();
    }
    catch( Exception ex )
    {
      a.ControlledApplication.WriteJournalComment( 
        "Could not start WCF service.\r\n" 
        + ex.ToString(),
        true );
    }
    return Result.Succeeded;
  }
 
  private void OnIdling( 
    object sender, 
    IdlingEventArgs e )
  {
    var uiApp = sender as UIApplication;
 
    Debug.Print( "OnIdling: {0}", 
      DateTime.Now.ToString( "HH:mm:ss.fff" ) );
 
    // Be careful! This loads the CPU:
 
    e.SetRaiseWithoutDelay();
 
    if( !TaskContainer.Instance.HasTaskToPerform )
      return;
 
    try
    {
      Debug.Print( "Start execute task: {0}", 
        DateTime.Now.ToString( "HH:mm:ss.fff" ) );
 
      var task = TaskContainer.Instance.DequeueTask();
 
      task( uiApp );
 
      Debug.Print( "Ending execute task: {0}", 
        DateTime.Now.ToString( "HH:mm:ss.fff" ) );
    }
    catch( Exception ex )
    {
      uiApp.Application.WriteJournalComment(
        "RevitExternalService. An error occured "
        + "while executing the OnIdling event:\r\n"
        + ex.ToString(), true );
 
      Debug.WriteLine( ex );
    }
  }
 
  public Result OnShutdown( UIControlledApplication a )
  {
    a.Idling -= OnIdling;
 
    if( serviceHost != null )
    {
      serviceHost.Close();
    }
    return Result.Succeeded;
  }
}

Secondly, here is part of the RevitExternalService definition including one of its method implementations:

class RevitExternalService : IRevitExternalService
{
  private string currentDocumentPath;
 
  private static readonly object _locker 
    = new object();
 
  private const int WAIT_TIMEOUT = 10000; // 10 seconds timeout
 
  public string GetCurrentDocumentPath()
  {
    Debug.Print( "Push task to the container: {0}", 
      DateTime.Now.ToString( "HH:mm:ss.fff" ) );
 
    lock( _locker )
    {
      TaskContainer.Instance.EnqueueTask( GetDocumentPath );
 
      // Wait when the task is completed
 
      Monitor.Wait( _locker, WAIT_TIMEOUT );
    }
 
    Debug.Print( "Finish task: {0}", 
      DateTime.Now.ToString( "HH:mm:ss.fff" ) );
 
    return currentDocumentPath;
  }
 
  private void GetDocumentPath( 
    UIApplication uiapp )
  {
    try
    {
      currentDocumentPath 
        = uiapp.ActiveUIDocument.Document.PathName;
    }
    finally
    {
      // Always release locker in finally block
      // to ensure to unlock locker object.
 
      lock( _locker )
      {
        Monitor.Pulse( _locker );
      }
    }
  }
 
  public bool CreateWall( 
    XYZ startPoint, 
    XYZ endPoint )
  {
    // . . .
  }
}

For completeness' sake, here is also VCRevitExternalAccessDemo.zip containing my personal version of the code, mainly for my own convenience :-)

Many thanks to Victor for very clear and efficient sample implementation!

By the way, don't miss the additional neat little feature demonstrated by the sample code above, the use of the Application WriteJournalComment method to add a comment to the Revit journal file.

Programmatic Creation of a Structural Engineering Plan

Saikat Bhattacharya discusses the details and provides sample code to create a new Revit EngineeringPlan view using the static ViewPlan.Create method and a ViewFamily.StructuralPlan ViewFamilyType.

Beam Bottom Endpoint

Here is a nice little example illustrating different approaches to find the end point of the bottom centre line of an inclined beam.

Question: I am trying to find the coordinates of the end points of the bottom centre line of an inclined beam. Depending on the beam angle, these coordinates will change.

Here is a 3D view of the kind of situation I am looking at:

The front view looks like this with the beam end points marked in orange. The desired bottom line end points are marked by red points within the circled areas:

I am currently using the following code to retrieve the beam location line start and end points:

  LocationCurve location = beam.Location as LocationCurve;
  Curve c = location.Curve;
  XYZ p = c.get_EndPoint( 0 );
  XYZ q = c.get_EndPoint( 1 );

Answer: There are an infinite number of ways to achieve this. Here are three to start with, in order of increasing purely personal preference:

• Face iteration and project
• Parameter values and trigonometry
• Perpendicular vector

Face Iteration and Project

One way to approach this is to use the beam solid faces and projection methods provided by the Revit geometry API to calculate the desired points.

You can determine the bottom face of the beam by querying the beam for its solid, iterating over its faces, and searching for the face whose normal vector has a minimal Z value, i.e. points downward the most. I provided source code samples implementing this for the bottom and top faces of a wall.

You can then project the beam location line end points onto that face using the Face.Project method to obtain the desired bottom line end points.

Parameter Values and Trigonometry

A second solution is based on querying some of the beam parameter values and using a little bit of trigonometry.

It calculates the sides of the right angle triangle using the beam direction vector, vertical delta and insertion value and returns the beam bottom coordinate as follows in C#:

void GetBeamInsertionAndVertDelta(
  Element beam,
  double sideLength,
  out double beamInsertion,
  out double beamVertDelta )
{
  // sideLength is beam height. 
  // If there is any other element like plate to 
  // be attached to beam bottom then 
  // sideLength = beam height + plate thickness
 
  beamInsertion = 0.0;
  beamVertDelta = 0.0;
 
  if( null != beam && _eps < Math.Abs( sideLength ) )
  {
    Parameter cutLength = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_FRAME_CUT_LENGTH );
 
    Parameter stOffset = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_BEAM_END0_ELEVATION );
 
    Parameter endOffset = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_BEAM_END1_ELEVATION );
 
    double hypotenuse = cutLength.AsDouble();
 
    double side = Math.Abs( stOffset.AsDouble() 
      - endOffset.AsDouble() );
 
    double angle = Math.Acos( side / hypotenuse );
 
    beamInsertion = ( sideLength / Math.Tan( angle ) );
    beamVertDelta = ( sideLength / Math.Sin( angle ) );
  }
}

Perpendicular Vector

The simplest solution may possibly be to avoid using the beam geometry as well as the tan and sin functions and just calculate straight away based on the beam location line.

You can determine the vector perpendicular to the beam location line and pointing downward as much as possible, i.e. lying in the plane P defined by the (non-vertical!) location line and the global Z axis.

Let's say the beam location line top two endpoints are stored in 'p' and 'q'. To determine the bottom points, we just need to know the height 'h' of the beam cross section and calculate a vector 'v' of length 'h' pointing downward and perpendicular to the beam location line. The desired points are given by p + v and q + v.

I used a similar calculation to determine the wall width or thickness vector 'w' to display the wall compound layers, except that it is horizontal, i.e. has a zero Z component, instead of lying in the plane P, with a minimal (negative) Z component.

Something like this untested snippet should do the job, given the beam location curve start point 'p', end point 'q' and height 'h' as defined above:

  XYZ u = q - p;
  XYZ w = XYZ.BasisZ.Cross( u );
  XYZ v = h * w.Cross( u ).Normalized;

As said, the desired points are then given by p + v and q + v.

Determine Hosted Family Host Type

On a different topic, in his latest AEC DevBlog post, Saikat Bhattacharya explains how you can determine the base host type of a hosted family via the Host parameter on the family document owner family property, which stores the following integer values corresponding to the FamilyHostingBehavior enumeration:

0. None
1. Wall
2. Floor
3. Ceiling
4. Roof
5. Face

The parameter value is zero, i.e. None, for families created using line and pattern based templates, so their host type cannot be determined using this method.

Note that if you have a face-based family instance, you can query its Host and HostFace properties to retrieve the host element and a reference to the hosting face, respectively.

Two more interesting methods to explore in this context are the FamilyCanConvertToFaceHostBased and ConvertFamilyToFaceHostBased methods provided by the FamilyUtils class.

Wall Footing Relationship Revisited

In the far distant past, I looked at various ways to programmatically determine relationships between associated objects (also in VB), including references between a host object and its hosted dependent elements, e.g. determining the relationship between a wall and its footing.

That was back in the year 2009, using Revit 2010.

A few things have changed and been added since then, but the more things change, the more they stay the same, don't they?

Anyway, this very question was raised again:

Question: Is there a way to obtain a reference to a wall footing from the wall attached to it?

Answer: Yes, sure, there are several different possibilities to achieve this.

You could start off by determining the bottom face of the wall.

Using that, you could set up an ElementIntersectsSolidFilter for a filtered element collector to retrieve all foundation elements touching or intersecting that face, as described for retrieving all touching beams. You would obviously want to apply as many quick filters as possible before taking recourse to the slow geometric filtering, e.g. check for level, category, type, etc. first.

Another way to determine adjacency of Revit BIM elements is to make use of the ray casting functionality provided by the FindReferencesByDirection method, FindReferencesWithContextByDirection method and the ReferenceIntersector class, e.g. cast a ray downwards from the wall and detect the first foundation hit by it.

Last but not least, another way to determine relationships between associated objects such as a wall and its footing is to temporarily delete the host object, causing the dependent objects to be deleted as well. The deleted element ids can be determined, and the whole operation undone to leave the model unchanged.

I described this principle several times, e.g. looking at object relationships (in VB), and specifically determining the wall footing of a given wall.

I cannot tell off-hand which of these methods is most useful and efficient in your specific case, although I would be very interested in seeing the results of some comparisons and benchmarks evaluating this.

Anyway, I note that The Building Coder sample command CmdWallFooting implementing the latter approach is pretty much out of date, having been simply flat ported across several Revit API releases in the past few years.

I therefore updated it for and tested it with Revit 2013, and can now confirm that it still works.

Here is the updated implementation:

[Transaction( TransactionMode.Manual )]
class CmdWallFooting : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    UIDocument uidoc = app.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    Wall wall = Util.SelectSingleElementOfType(
      uidoc, typeof( Wall ), "a wall", false ) 
        as Wall;
 
    if ( null == wall )
    {
      message 
        = "Please select a single wall element.";
 
      return Result.Failed;
    }
 
    ICollection<ElementId> delIds = null;
 
    using( Transaction t = new Transaction( doc ) )
    {
      try
      {
        t.Start( "Temporary Wall Deletion" );
 
        delIds = doc.Delete( wall );
 
        t.RollBack();
      }
      catch ( Exception ex )
      {
        message = "Deletion failed: " + ex.Message;
        t.RollBack();
      }
    }
 
    ContFooting footing = null;
 
    foreach ( ElementId id in delIds )
    {
      footing = doc.GetElement( id ) as ContFooting;
 
      if( null != footing )
      {
        break;
      }
    }
 
    string s = Util.ElementDescription( wall );
 
    Util.InfoMsg( ( null == footing )
      ? string.Format( "No footing found for {0}.", s )
      : string.Format( "{0} has {1}.", s,
        Util.ElementDescription( footing ) ) );
 
    return Result.Succeeded;
  }
}

I ran this command on a minimal sample model containing just one structural wall with its footing:

The command reports the expected relationship:

It says:

Wall Walls <164432 Generic - 200mm> has 
ContFooting Structural Foundations <164470 
Retaining Footing - 300 x 600 x 300>.

Here is version 2013.0.99.3 of The Building Coder samples including the updated CmdWallFooting external command.

Structural Concrete Setout Point Add-in

I am back from my vacation now, having spent a wonderful relaxing time doing all kinds of things not related to the Revit API or computers at all, such as talking, walking, singing, playing music, painting, swimming, meditating, climbing, caving, canoeing and sharing time with friends...

Meanwhile, a whole bunch of interesting issues to share with you have been piling up, new ones keep pouring in, and I still have some long-standing pending posts to get around to as well.

One important utility that I have been wanting to publish for months now is for the automatic placement and management of structural concrete setout points which I implemented together with Paul Hellawell of GHD at the Melbourne DevLab back in March, thus also finally answering Ishfak's request for the full Revit 2013 source code to retrieve real world concrete coordinates.

This is a full-blown end-user-capable little application for the automatic creation of setout points for on-site location and construction of structural elements.

One of the most fascinating aspects of the implementation for me was the amount of choices that we were forced to make between implementing something ourselves programmatically versus discovering the proper way to use built-in Revit functionality to do it automatically for us instead with no work at all on our part.

For instance, we originally defined one single setout point marker type, and started implementing API functionality to select the main points and change their colour.

Happily, we soon found a much simpler solution which requires no programming at all: simply define two separate family types for the minor and major setout point markers with different colours, and let the user select which one to use through the standard Revit user interface. Several other equally important design decisions cropped up, demonstrating the importance of knowing the product well, which Paul luckily does.

They really highlighted the fact how important it is to know the user interface and best standard practices in depth before embarking on a serious programming project, however simple it may seem.

Let's start at the beginning, and reiterate the motivation for this undertaking:

Almost every construction professional has experienced the following kind of situation at some time in their career:

A large complex structure is constructed off-site. When assembled on site, it does not fit exactly. The workers continue nonetheless and force it into place. The error is discovered later and corrected using brute force and post adaption. Overall cost of exercise: days or weeks of delay and painful cost overruns.

This leads to the following important prophylactic task:

The Challenge: Provide a way to find the real world coordinates of the corners of potential elements to be set out in the field, automatically extracting relevant setout points from the model. In this example, we are dealing with concrete structural elements. Ideally, we would like to display these points in a Revit schedule, so that they can be formatted and placed on a drawing sheet. We would like to then define which of the points should be used as main setout points and list them in a schedule, preferably numbered sequentially for readability.

In Practice: Retrieved all the concrete corner point data via the API is not hard, and I presented the solution to retrieve real world concrete coordinates separately in the following three steps:

• Filtering for structural concrete elements.
• Retrieving their corners, i.e. geometry traversal to retrieve unique vertices.
• Converting from Revit model to real-world coordinates.

However, transferring this information directly into a schedule proved to be impossible. Instead we created a family definition containing shared parameters to hold the data required for scheduling. We then place instances of the family at the points extracted from the geometry. Through the API it is now possible to populate the parameters with the X, Y, Z coordinates extracted from the geometry, and add these values to the extracted project location, to convert them to real world coordinates.

Initially, we defined a setout point family with one single type in it. This did not enable the ability to select which points to schedule as main setout points. For this, we created two different family types, SetoutPoint_Major and SetoutPoint_Minor. This allows two separate schedules to be created, one capturing all the points, the other only points defined as major points for use on a drawing sheet for setout.

The schedule listing all points is useful, e.g. for export to a CSV file and subsequent import into a surveying device such as a Trimble, allowing site set-out directly from the model.

The setout point tool extracts the X, Y, Z coordinates of all concrete edges. The generated points can then be interactively marked as Major points (setout point) and renumbered sequentially to provide a schedule of key setout points. The remaining point are schedules as well, e.g. to be saved as a comma delimitated file CSV file to be sent to surveying equipment for site setout.

Usage

Ensure your project contains some elements whose structural material is set to concrete or precast concrete.

You can then click the Get Concrete Corners tool:

The tool automatically analyses al the concrete structural elements' geometry and placed setout point family instances representing a 3D pointer on all the concrete element corner vertices:

The family is defined using the Generic Model family template. The green indicators represent general setout points. You can select the ones you want to change to main setout points, also known as major or key, by simply selecting them and swapping their type to SetoutPoint_Major:

Major setout points are displayed in red instead of green:

The sample project provided below defines two schedules. One of them is populated with all setout points, marking every corner of every piece of concrete:

The second schedule lists only the selected main or major setout points and their coordinates:

Once you have all your key setout points defined, a separate 'Renumber setout Points' external command renumbers them sequentially and adds a SOP (Set Out Point) prefix to their number to differentiate them from the minor points.

The renumbered schedule can now be used on a drawing sheet.

Many thanks to Paul for our initiating this project, his deep Revit knowledge and experience, all the support he provided during the Melbourne Revit API training, and the great evening we had together in Melbourne after the training!

Implementation Details

I already pointed to the discussion of the main technical underpinnings for the retrieval of the concrete corners above, i.e.

• Filtering for structural concrete elements.
• Retrieving their corners, i.e. geometry traversal to retrieve unique vertices.
• Converting from Revit model to real-world coordinates.

Now let's look at some of the aspects of putting this functionality to use and wrapping it into a full-blown end-user application:

• External application and CmdData class
• Shared parameters
• Importance of product usage experience, content and best practices
• Marking all geometry vertices
• Major setout point renumbering

External Application and CmdData Class

The application defines two commands:

• CmdGeomVertices: filter for all relevant concrete structural elements, analyse their geometry, create the setout point markers, and populate their shared parameters to be reflected in the predefined schedules.
• CmdRenumber: renumber the main or major setout points consecutively.

They are presented in a custom ribbon panel defined by an external application.

In order to encapsulate all the information required to populate the ribbon panel push buttons, I define the following CmdData class defining the external command implementation class name, description and tool tip text:

  class CmdData
  {
    public CmdData( 
      string name, 
      string text, 
      string tip )
    {
      Name = name;
      Text = text;
      Tip = tip;
    }
    public string Name { get; set; }
    public string Text { get; set; }
    public string Tip { get; set; }
  }

The two instances can be populated like this:

  static CmdData[] data = new CmdData[] {
 
    new CmdData( 
      "GeomVertices", 
      "Mark Concrete Corners",
      "Place a setout point marker on every concrete corner." ),
 
    new CmdData( 
      "Renumber", 
      "Renumber major", 
      "Renumber major setout points" )
  };

The external application OnStartup method making use of this ends up very simple:

  public Result OnStartup( 
    UIControlledApplication a )
  {
    string path = System.Reflection.Assembly
      .GetExecutingAssembly().Location;
 
    // Create ribbon panel
 
    RibbonPanel p = a.CreateRibbonPanel( Caption );
 
    // Create buttons
 
    List<PushButtonData> buttonData 
      = new List<PushButtonData>( 
        data.Length );
 
    foreach( CmdData cd in data )
    {
      PushButtonData pbd = new PushButtonData(
        cd.Name, cd.Text, path,
        _class_name_prefix + cd.Name );
 
      pbd.ToolTip = cd.Tip;
 
      buttonData.Add( pbd );
    }
 
    p.AddStackedItems( buttonData[0], 
      buttonData[1] );

    return Result.Succeeded;
  }

Lacking icons, my panel does not look quite as impressive as Paul's one shown above, but it does the job:

Shared Parameters

As mentioned above, the functionality to retrieve the concrete corners geometry data has already been described in previous posts.

The question is how to handle this information in order to make it available to the user, populate schedules, etc. We ended up inserting family instances marking all concrete corners as minor setout points, and populating shared parameters on each to encapsulate the required data specifying the host element and its point coordinates. Here is the shared parameter file, slightly simplified for readability:

# This is a Revit shared parameter file.
# Do not edit manually.
*META VERSION MINVERSION
META 2 1
*GROUP ID NAME
GROUP  1 SetOut
*PARAM GUID NAME             DATATYPE ... GROUP VISIBLE
PARAM  .... Key_Setout_Point YESNO        1     1
PARAM  .... Host_Type        TEXT         1     1
PARAM  .... Host_Id          INTEGER      1     1
PARAM  .... X                LENGTH       1     1
PARAM  .... Y                LENGTH       1     1
PARAM  .... Z                LENGTH       1     1
PARAM  .... Point_Number     TEXT         1     1

Shared parameter access is implemented using their GUIDs throughout the code.

Importance of Product Usage Experience, Content and Best Practices

We initially defined a parameter in the setout point family to distinguish between minor and major points, and started working on a separate user interface to toggle between the two and change the family instance colour depending on its current setting.

At a certain point, we discovered that it was vastly simpler to define two separate types within the family instead and use the standard Revit user interface to toggle between those.

It is so important for every add-in developer to know the standard Revit possibilities and best-practice workflows.

That can save huge amounts of unnecessary programming effort, sometimes wasted to fight against the product and its standard paradigms instead of making optimal use of it.

Marking All Geometry Vertices

As said, most of the underlying functionality to retrieve the concrete corner geometry was already presented and discussed.

One additional helper method GetFamilySymbols loads the setout point family, if it is not already present, and retrieves the major and minor setout point symbols:

public static FamilySymbol [] GetFamilySymbols( 
  Document doc, 
  bool loadIt )
{
  FamilySymbol [] symbols = null;
 
  Family family 
    = new FilteredElementCollector( doc )
      .OfClass( typeof( Family ) )
      .FirstOrDefault<Element>( 
        e => e.Name.Equals( FamilyName ) ) 
      as Family;
 
  // If the family is not already loaded, do so:
 
  if( null == family && loadIt )
  {
    // Load the setout point family
 
    using( Transaction tx = new Transaction( 
      doc ) )
    {
      tx.Start( "Load Setout Point Family" );
 
      if( doc.LoadFamily( _family_path, 
        out family ) )
      {
        tx.Commit();
      }
      else
      {
        tx.RollBack();
      }
    }
  }
 
  if( null != family )
  {
    symbols = new FamilySymbol[2];
 
    int i = 0;
 
    foreach( FamilySymbol s in family.Symbols )
    {
      symbols[i++] = s;
    }
 
    Debug.Assert( 
      symbols[0].Name.EndsWith( "Major" ), 
      "expected major (key) setout point first" );
 
    Debug.Assert( 
      symbols[1].Name.EndsWith( "Minor" ), 
      "expected minor setout point second" );
  }
  return symbols;
}

Then, finally, here is the external command mainline pulling it all together, i.e.

• Determine project location transformation to real world coordinates.
• Load or retrieve setout point family symbols.
• Retrieve the relevant structural concrete elements.
• Retrieve element geometry.
• Place a setout point marker family instance on each geometry vertex.
• Check to see whether the required shared parameters have been bound.

Setout points are numbered starting at one each time the command is run with no decoration or prefix.

Here is Execute method implementation performing these tasks:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  Transform projectLocationTransform 
    = GetProjectLocationTransform( doc );
 
  // Load or retrieve setout point family symbols:
 
  FamilySymbol [] symbols 
    = GetFamilySymbols( doc, true );
 
  if( null == symbols )
  {
    message = string.Format(
      "Unable to load setout point family from '{1}'.",
      _family_path );
 
    return Result.Failed;
  }
 
  FilteredElementCollector col 
    = GetStructuralElements( doc );
 
  // Retrieve element geometry and place a
  // setout point on each geometry corner.
 
  // Setout points are numbered starting at 
  // one each time the command is run with
  // no decoration or prefix whatsoever.
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Place Setout Points" );
 
    Options opt = app.Create.NewGeometryOptions();
 
    // On the very first attempt only, run an error 
    // check to see whether the required shared 
    // parameters have actually been bound:
 
    bool first = true;
 
    foreach( Element e in col )
    {
      Solid solid = GetSolid( e, opt );
 
      string desc = ElementDescription( e );
 
      if( null == solid )
      {
        Debug.Print(
          "Unable to access element solid for element {0}.",
          desc );
 
        continue;
      }
 
      Dictionary<XYZ, int> corners
        = GetCorners( solid );
 
      int n = corners.Count;
 
      Debug.Print( "{0}: {1} corners found:", desc, n );
 
      foreach( XYZ p in corners.Keys )
      {
        ++_point_number;
 
        Debug.Print( "  {0}: {1}",
          _point_number, PointString( p ) );
 
        FamilyInstance fi
          = doc.Create.NewFamilyInstance( p,
            symbols[1], StructuralType.NonStructural );
 
        // Add shared parameter data immediately 
        // after creating the new family instance.
        // The shared parameters are indeed added 
        // immediately by Revit, so we can access and
        // populate them.
        // No need to commit the transaction that 
        // added the family instance to give Revit 
        // a chance to add the shared parameters to 
        // it, nor to regenerate the document, we 
        // can write the shared parameter values 
        // right away.
 
        if( first )
        {
          Parameter q = fi.get_Parameter(
            _parameter_x );
 
          if( null == q )
          {
            message = 
              "The required shared parameters "
              + "X, Y, Z, Host_Id, Host_Type and "
              + "Point_Number are missing.";
 
            tx.RollBack();
 
            return Result.Failed;
          }
          first = false;
        }
 
        // Transform insertion point by applying
        // project location transformation.
 
        XYZ r2 = projectLocationTransform.OfPoint( p );
 
        fi.get_Parameter( _parameter_host_type ).Set(
          GetHostType( e ).ToString() );
 
        fi.get_Parameter( _parameter_host_id ).Set(
          e.Id.IntegerValue );
 
        fi.get_Parameter( _parameter_point_nr ).Set(
          _point_number.ToString() );
 
        fi.get_Parameter( _parameter_x ).Set( r2.X );
        fi.get_Parameter( _parameter_y ).Set( r2.Y );
        fi.get_Parameter( _parameter_z ).Set( r2.Z );
      }
    }
 
    tx.Commit();
  }
  return Result.Succeeded;

That's about it... one more little thing:

Major Setout Point Renumbering

Such irrational creatures, these human beings.

Users apparently insist on consecutive numbering of items they deal with.

We therefore implemented a second command named CmdRenumber to renumber the major points.

They are basically renumbered randomly, since all major points are selected using a filtered element collector. We iterate over the result, assign a consecutive number to each instance, and store it in the Point_Number text-valued shared parameter with a "SOP " prefix string _sop_prefix.

The key setout points are family instances with the generic model category and the major setout point type.

The external command Execute implementation thus ends up looking like this:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  FamilySymbol[] symbols
    = CmdGeomVertices.GetFamilySymbols( 
      doc, false );
 
  if( null == symbols )
  {
    TaskDialog.Show( "Setout Points",
      "Setout point family not loaded, "
      + "so no setout points present." );
 
    return Result.Succeeded;
  }
 
  FamilyInstanceFilter instanceFilter
    = new FamilyInstanceFilter( doc, symbols[0].Id );
 
  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .OfCategory( BuiltInCategory.OST_GenericModel )
      .OfClass( typeof( FamilyInstance ) )
      .WherePasses( instanceFilter );
 
  Guid guid = CmdGeomVertices._parameter_point_nr;
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Renumber Setout Points" );
 
    int i = 0;
    string s;
 
    foreach( Element p in col )
    {
      s = _sop_prefix + ( ++i ).ToString();
 
      p.get_Parameter( guid ).Set( s );
    }
 
    tx.Commit();
  }
  return Result.Succeeded;

For all further details, please refer to the one and only really trustworthy reference, the full source code.

Here is SetoutPoints.zip including the complete source code, Visual Studio solution, add-in manifest and setout point marker family.

For easier testing, here is also a sample project based on the standard rst_basic_sample_project.rvt with a non-standard project location and the setout point schedules added.

Real-World Concrete Corner Coordinates

I mentioned that I worked together with Paul Hellawell of GHD on a full-blown end-user-capable little application for the automatic creation of setout points for on-site location and construction of structural elements at the Melbourne DevLab.

Paul provided a description of the task and the initial idea for an implementation approach.

We got the application to a useful working state in the two days during the DevLab, and Paul has provided it to his designers to use in real projects ever since.

Before we look at the full-fledged application, let's explore the core API functionality required:

• Filtering for structural concrete elements.
• Retrieving their corners, i.e. geometry traversal to retrieve unique vertices.
• Converting from Revit model to real-world coordinates.

Once this is all in place, we can explain how to use the core functionality to implement the real-world end-user application.

Filtering for Structural Concrete Elements

We already looked at retrieving structural elements.

Just like there, we check for certain specific classes like Wall and Floor, and also for generic family instances with categories from our list of interest, including structural columns, framing, foundation, floors and ramps.

In this case, we are only interested in concrete elements, so we apply two structural material type filters as well, for concrete and precast concrete.

This is the method we ended up with to suit our purposes:

/// <summary>
/// Retrieve all structural elements that we are 
/// interested in using to define setout points.
/// We are looking at concrete for the moment.
/// This includes: columns, framing, floors, 
/// foundations, ramps, walls. 
/// </summary>
FilteredElementCollector GetStructuralElements(
  Document doc )
{
  // What categories of family instances
  // are we interested in?
 
  BuiltInCategory[] bics = new BuiltInCategory[] {
    BuiltInCategory.OST_StructuralColumns,
    BuiltInCategory.OST_StructuralFraming,
    BuiltInCategory.OST_StructuralFoundation,
    BuiltInCategory.OST_Floors,
    BuiltInCategory.OST_Ramps
  };
 
  IList<ElementFilter> a
    = new List<ElementFilter>( bics.Length );
 
  foreach( BuiltInCategory bic in bics )
  {
    a.Add( new ElementCategoryFilter( bic ) );
  }
 
  LogicalOrFilter categoryFilter
    = new LogicalOrFilter( a );
 
  // Filter only for structural family 
  // instances using concrete or precast 
  // concrete structural material:
 
  List<ElementFilter> b
    = new List<ElementFilter>( 2 );
 
  b.Add( new StructuralMaterialTypeFilter( 
    StructuralMaterialType.Concrete ) );
 
  b.Add( new StructuralMaterialTypeFilter( 
    StructuralMaterialType.PrecastConcrete ) );
 
  LogicalOrFilter structuralMaterialFilter 
    = new LogicalOrFilter( b );
 
  List<ElementFilter> c
    = new List<ElementFilter>( 3 );
 
  c.Add( new ElementClassFilter( 
    typeof( FamilyInstance ) ) );
 
  c.Add( structuralMaterialFilter );
  c.Add( categoryFilter );
 
  LogicalAndFilter familyInstanceFilter
    = new LogicalAndFilter( c );
 
  IList<ElementFilter> d
    = new List<ElementFilter>( 6 );
 
  d.Add( new ElementClassFilter(
    typeof( Wall ) ) );
 
  d.Add( new ElementClassFilter(
    typeof( Floor ) ) );
 
  //d.Add( new ElementClassFilter(
  //  typeof( ContFooting ) ) );
 
#if NEED_LOADS
  d.Add( new ElementClassFilter(
    typeof( PointLoad ) ) );
 
  d.Add( new ElementClassFilter(
    typeof( LineLoad ) ) );
 
  d.Add( new ElementClassFilter(
    typeof( AreaLoad ) ) );
#endif
 
  d.Add( familyInstanceFilter );
 
  LogicalOrFilter classFilter
    = new LogicalOrFilter( d );
 
  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .WherePasses( classFilter );
 
  return col;
}

Geometry Traversal to Retrieve Unique Vertices

Once the required elements have been retrieved, we analyse their geometry to determine all corners, i.e. geometry vertices.

This goes back to the second day of the Melbourne Revit API training, where we looked at retrieving unique geometry vertices from a selected element.

This involves comparing XYZ points, i.e. real number equality testing.

First of all, we need an equality comparer for points:

/// <summary>
/// Define equality for Revit XYZ points.
/// Very rough tolerance, as used by Revit itself.
/// </summary>
class XyzEqualityComparer : IEqualityComparer<XYZ>
{
  const double _sixteenthInchInFeet 
    = 1.0 / ( 16.0 * 12.0 );
 
  public bool Equals( XYZ p, XYZ q )
  {
    return p.IsAlmostEqualTo( q, 
      _sixteenthInchInFeet );
  }
 
  public int GetHashCode( XYZ p )
  {
    return PointString( p ).GetHashCode();
  }
}

With that in hand, we can retrieve all unique vertices of a given solid retrieved from the element geometry:

/// <summary>
/// Return all the "corner" vertices of a given solid.
/// Note that a circle in Revit consists of two arcs
/// and will return a "corner" at each of the two arc
/// end points.
/// </summary>
Dictionary<XYZ,int> GetCorners( Solid solid )
{
  Dictionary<XYZ, int> corners 
    = new Dictionary<XYZ, int>( 
      new XyzEqualityComparer() );
 
  foreach( Face f in solid.Faces )
  {
    foreach( EdgeArray ea in f.EdgeLoops )
    {
      foreach( Edge e in ea )
      {
        XYZ p = e.AsCurveFollowingFace( f )
          .get_EndPoint( 0 );
 
        if( !corners.ContainsKey( p ) )
        {
          corners[p] = 0;
        }
        ++corners[p];
      }
    }
  }
  return corners;
}

The solid is retrieved by traversing the element geometry and picking the first non-empty one found.

Special handling is required for family instances, of course, since they have an additional transformation that we have to take account of. The family definition defines its own local coordinate system, and we need to transform the solid from that to the Revit model space.

This implementation processes all the cases we have run into so far correctly and elegantly:

/// <summary>
/// Retrieve the first non-empty solid found for 
/// the given element. In case the element is a 
/// family instance, it may have its own non-empty
/// solid, in which case we use that. Otherwise we 
/// search the symbol geometry. If we use the 
/// symbol geometry, we have to keep track of the 
/// instance transform to map it to the actual
/// instance project location.
/// </summary>
Solid GetSolid( Element e, Options opt )
{
  GeometryElement geo = e.get_Geometry( opt );
 
  Solid solid = null;
  GeometryInstance inst = null;
  Transform t = Transform.Identity;
 
  // Some columns have no solids, and we have to 
  // retrieve the geometry from the symbol; 
  // others do have solids on the instance itself 
  // and no contents in the instance geometry 
  // (e.g. in rst_basic_sample_project.rvt).
 
  foreach( GeometryObject obj in geo )
  {
    solid = obj as Solid;
 
    if( null != solid
      && 0 < solid.Faces.Size )
    {
      break;
    }
 
    inst = obj as GeometryInstance;
  }
 
  if( null == solid && null != inst )
  {
    geo = inst.GetSymbolGeometry();
    t = inst.Transform;
 
    foreach( GeometryObject obj in geo )
    {
      solid = obj as Solid;
 
      if( null != solid
        && 0 < solid.Faces.Size )
      {
        break;
      }
    }
  }
  return solid;
}

Transforming Revit Model Coordinates to the Real World

After the solid vertices have been retrieved in Revit model space, we convert them to real-world coordinates using the project location.

We initially tried to achieve this piecewise by fiddling with the base point offset and manually rotating to project north. This was both complicated and returned incorrect results.

The correct solution is very simple and was already discussed a couple of times in the past:

• Transformations
• Project location
• Transformed family instance geometry

This led us to implement the following GetProjectLocationTransform method:

/// <summary>
/// Return the project location transform.
/// </summary>
Transform GetProjectLocationTransform( Document doc )
{
  // Retrieve the active project location position.
 
  ProjectPosition projectPosition
    = doc.ActiveProjectLocation.get_ProjectPosition(
      XYZ.Zero );
 
  // Create a translation vector for the offsets
 
  XYZ translationVector = new XYZ(
    projectPosition.EastWest,
    projectPosition.NorthSouth,
    projectPosition.Elevation );
 
  Transform translationTransform
    = Transform.get_Translation(
      translationVector );
 
  // Create a rotation for the angle about true north
 
  Transform rotationTransform 
    = Transform.get_Rotation( XYZ.Zero, 
      XYZ.BasisZ, projectPosition.Angle );
 
  // Combine the transforms 
 
  Transform finalTransform
    = translationTransform.Multiply(
      rotationTransform );
 
  return finalTransform;
}

Making use of the resulting transform later is trivial:

  Transform projectLocationTransform 
    = GetProjectLocationTransform( doc );
 
  for each concrete corner point XYZ p:
  {
    // Transform insertion point by applying
    // project location transformation.
 
    XYZ r2 = projectLocationTransform.OfPoint( p );
  }

Now I just need to find some more time to discuss how this can all be put together and wrapped into a useful real-world end-user application.

The Revit 2013 Structure API

I migrated the ADN Revit Structure API training material to Revit 2013, which led me to put together the following summary of the structural API enhancements and some details of the migration steps:

• API enhancements
• RstLabs migration
• NewRstLab migration
• RstAvfDmu migration
• Materials

Revit Structure 2013 API Enhancements

I mentioned a few structure specific enhancements in the Revit 2013 API. They are discussed in somewhat more detail in the DevDays Online presentation on What's New in Revit 2013 and the complementary Revit 2013 API webcast, of which the first half provides an introduction to the Revit API in general, and the second covers some new 2013 specific features in more depth.

Actually, it was the webcast preparation that prompted me to start performing the migration described below, which in turn prompted me to publish the result and summarise the changes.

To recap, the structural enhancements include:

Structural Product Related Enhancements

Before we get to the detailed API changes, here are some notes on the main product goals and features:

Reinforcement detailing to help extend the BIM lifecycle from design to construction through detailing and fabrication:

• Area/path reinforcement to host real rebar and set
• Welded wire mesh
• Reinforcement fillets and hooks
• Additional reinforcement units
• Rebar cover

Structural analysis in BIM moving towards delivering structural analysis in the cloud and supporting partner ecosystem growth by

• Results storage, visualization and exploration in RST
• Improved analytical models for surface elements
• Seamless workflow between RST/RSA
• Improved rigid links

Structural analysis web service and visualisation to democratize analysis and make it more accessible, easy to both use and provide. Long term, we would like to deliver structural analysis in the cloud and thus support partner ecosystem growth. Support for modal and deformation analysis, enhanced results visualization.

Enhanced physical properties to centralize analysis workflows around BIM data and improve the efficiency of BIM-based analysis workflows.

• Extended thermal and structural properties of building envelope
• Material authoring and library management workflows
• Foundation for material ecosystem
• Data flow with key Building Performance and Structural Analysis applications

Now let's look at how these changes affect the API:

Reinforcement

The Rebar class provides a number of new methods and properties:

• CreateFromCurvesAndShape
• GetBarPositionTransform
• GetBarExistsAtPosition
• GetHookTypeId/SetHookTypeId
• RebarShapeMatchesCurvesAndHooks
• ScheduleMark
• TotalLength
• Volume

The Rebar.GetCenterlineCurves method takes new arguments to control

• Adjustment for self-intersection
• Inclusion of hooks
• Inclusion of bend radius curves (fillets)

The BarDescription class is now obsolete and replaced by the new RebarInSystem class representing a bar in an AreaReinforcement or PathReinforcement system, providing access to individual rebars in a system and the ability to switch back and forth between system and individual elements.

A new class ReinforcementSettings is provided. When ReinforcementSettings.HostStructuralRebar is true, area and path reinforcement elements create individual rebar elements that participate in views and schedules. The individual RebarInSystem elements have the same graphical representation and parameters as Rebar elements, and have the same API methods for inquiry. Since the RebarInSystem elements are almost entirely controlled by their area or path system element, they lack most of the modification methods of the Rebar class.

These two system classes now have types, and provide new members to retrieve system members, curve boundaries, remove an element and convert its bars into standard rebar via the new methods GetRebarInSystemIds, RemoveAreaReinforcementSystem, and RemovePathReinforcementSystem.

Welded Wire Mesh

• FabricSheet
  • Planar sheet of welded wire mesh
  • Created and cut by FabricArea
  • Option to automatically add symbols and tags
• FabricArea
  • Creates and manages a distribution of FabricSheets
  • Allows sketched welded wire mesh objects
  • Planar hosts only, identical criteria to Area and Path Reinforcement
• Related type classes
  • FabricAreaType provides identity data
  • FabricSheetType includes uncut dimensions, wire sizes and layouts
  • FabricWireType defines wire diameter

Physical Properties

• Structural family instances support additional structural material element
• Structural and thermal material assets can be shared and set on materials

Structural Analytical Model

• New element type AnalyticalLink
• Created between two analytical elements, e.g. a beam and a column
• Two kinds of links: user-defined and automatically generated
• Access link properties like "fixity state"

Analysis Visualization Framework

• Support for deformed shapes as part of AVF display
• AnalysisDisplayStyleDeformedShapeTextLabelType
• AnalysisDisplayDeformedShapeSettings input argument to new CreateAnalysisDisplayStyle override

Revit Structure Labs RstLabs Migration

As said, I migrated the Revit Structure API material from 2012 to 2013, starting with the labs RstLabs. The standard steps are getting to be a habit, after already completing the The Building Coder samples, ADN Revit API training labs, AdnRme Revit MEP API and extensible storage samples:

• Updated the Revit API assembly references.
• Set the target .NET framework version to 4.
• Removed the warnings caused by calls to the Element property in VB, represented as a call to the get_Element method n C#, replacing them by the new Revit 2013 GetElement method, which has the advantage of looking identical in both languages.

After that, no warnings remain.

There are four errors, though, which all are caused by the removal of the LOAD_USE_LOCAL_COORDINATE_SYSTEM_HOSTED built-in parameter.

Since the parameter value retrieved is not used anywhere and the call is just to demonstrate the retrieval of a parameter value in general, I simply commented out the offending statements.

New Revit Structure Labs NewRstLab Migration

Standard stuff, same as before: change the Revit API assembly references, .NET framework version, and replace the use of the Element property by calls to GetElement.

I also replaced the test for a concrete column by new code, since the MaterialConcrete class no longer exists in Revit 2013. Here is the old code I replaced:

  MaterialSet materials = column.Materials;
 
  MaterialConcrete matConcrete = null;
 
  foreach( Material mat in materials )
  {
    // cast it to concrete material
    matConcrete = mat as MaterialConcrete; 
    break;
  }
  if( null == matConcrete )
  {
    messages = "The selected column is not concrete";
    trans.RollBack();
    return Result.Failed;
  }

The new code is much clearer and simpler:

  if( StructuralMaterialType.Concrete 
    != column.StructuralMaterialType )
  {
    messages = "The selected column is not concrete";
    trans.RollBack();
    return Result.Failed;
  }

Revit Structure AVF and DMU Sample RstAvfDmu Migration

RstAvfDmu is a dual sample by Saikat Bhattacharya on using the analysis visualisation framework AVF and the dynamic model update DMU in the context of Revit Structure.

The only significant change required is due to the GetCenterlineCurves method taking some additional arguments in Revit 2013:

  // For this we first access 
  // the rebar line geometry
 
  //Line rebarLine = rebar.Curves.get_Item( 
  //  0 ) as Line; // 2011
 
  //Line rebarLine = rebar.GetCenterlineCurves( 
  //  false )[0] as Line; // 2012
 
  Line rebarLine = rebar.GetCenterlineCurves(
    false, true, true )[0] as Line; // 2013

Materials

Here is rst_2013_2012-06-12.zip containing the result of my efforts so far, the Revit Structure 2013 versions of RstLabs, NewRstLab and RstAvfDmu.

The Revit Structure link sample RstLink is not yet completed, nor have I yet updated the Revit Structure API slide deck.

Create Structural Plan View

Today is the last day of the last week before the AEC DevCamp in Waltham. Here are the complete session list and descriptions. I have to submit my material today. Before doing so, one last post on a pure API topic:

I mentioned that Revit 2013 introduced a new view API and now includes the possibility to create schedules and section views.

Here is a question that came up regarding the new view creation and Onebox and leads to a couple of interesting migration points:

Question: I have a plug-in developed for Revit Structure which is currently working on the versions 2009 to 2012.

Part of the plug-in involves creation of levels and a corresponding floor plan for each.

I now ran into the following problem in Revit 2013 Onebox: after creating all Levels with their respective floor plans, they are displayed in the wrong subnode of the Views tree in the Project Browser. The default Level 'Level 1' is shown under the 'Structural Plans' node, and the newly created floor plans are located under 'Floor Plans' instead.

In spite of the unexpected result in the GUI, all levels are actually created and all floor plans correctly assigned.

I also noticed that the NewViewPlan method to create floor plans is marked obsolete in the 2013 API, so I tried using the new ViewPlan.Create method instead. The result is the same using both methods.

Here is the code using both of these methods:

/// <summary>
/// Create FloorPlan for Level using NewViewPlan
/// </summary>
public Level CreateLevel2012( 
  Document doc, 
  double elevation, 
  string name )
{
  Autodesk.Revit.Creation.Document createdoc 
    = doc.Create;
 
  Level level = createdoc.NewLevel( elevation );
  level.Name = name;
  ElementId nid = level.Id;
 
  createdoc.NewViewPlan( name, level, 
    ViewPlanType.FloorPlan );
 
  return level;
}
 
/// <summary>
/// Create FloorPlan for Level using ViewPlan.Create
/// </summary>
public Level CreateLevel2013(
  Document doc,
  double elevation,
  string name )
{
  Level level = doc.Create.NewLevel( elevation );
  level.Name = name;
  ElementId nid = level.Id;
 
  IEnumerable<ViewFamilyType> viewFamilyTypes
    = from elem in new FilteredElementCollector( doc )
        .OfClass( typeof( ViewFamilyType ) )
      let type = elem as ViewFamilyType
      where type.ViewFamily == ViewFamily.FloorPlan
      select type;
 
  ViewPlan floorPlan = ViewPlan.Create( doc, 
    viewFamilyTypes.First().Id, nid );
 
  return level;
}

Answer: I created a sample application to test the structural plan creation in Revit 2013 Onebox. It initially displayed the newly created floor plans under the 'Floor Plan' node, just as you describe. I wondered whether the behaviour might depend on whether you run this in a structural or architectural project, how the template file is set up, and what discipline is assigned to the view, but that does not seem to make any difference, as I soon found out.

I started up a new structural project in Revit Onebox and ran the command there, and note that the new level also appears in the Floor Plans node.

I next used RevitLookup to examine the default views listed in the Structural Plans node in more detail, using Add-Ins > Revit Lookup > Snoop DB... > ViewPlan > Level 1 70032.

One thing I immediately note is that the ViewFamilyType of the default Level 1 in the structural project is Structural Plan 53969, and not 'Floor Plan' like the one you are referencing in your code:

I therefore modified the creation code to use ViewFamily.StructuralPlan instead of ViewFamily.FloorPlan. There is no need to set the view discipline, since that happens anyway automatically.

With that in place, the newly created views now show up in the right place in the project browser:

Here is the complete code that I ended up with:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Create Floor Plan" );
 
    Autodesk.Revit.Creation.Document createdoc
      = doc.Create;
 
    string name = "Findus";
 
    // Create Level
 
    double elevation = 10;
    Level level = createdoc.NewLevel( elevation );
    level.Name = name;
    ElementId nid = level.Id;
 
    bool use_obsolete_code = false;
 
    if( use_obsolete_code )
    {
      // Create FloorPlan for the 
      // Level using NewViewPlan
 
      createdoc.NewViewPlan( name, level,
        ViewPlanType.FloorPlan );
    }
    else
    {
      // Create FloorPlan for the 
      // Level using ViewPlan.Create
 
      ViewFamilyType vft
        = new FilteredElementCollector( doc )
          .OfClass( typeof( ViewFamilyType ) )
          .Cast<ViewFamilyType>()
          .FirstOrDefault<ViewFamilyType>( x =>
            ViewFamily.StructuralPlan == x.ViewFamily );
 
      ViewPlan floorPlan = ViewPlan.Create(
        doc, vft.Id, nid );
 
      //floorPlan.Discipline 
      //  = ViewDiscipline.Structural;
    }
    tx.Commit();
  }
  return Result.Succeeded;

I hope you appreciate that you have a lot more control over the view creation using the new method rather than the old one. There is a heaps more functionality in the new Revit 2013 view API that we have not touched on yet...

Here is CreateStructuralPlan.zip including the entire Visual Studio solution, source code and add-in manifest.

Section View Geometry Not Cropped

Here is a nice little chat with some interesting resulting hints that I had with an Australian programmer Bo that clarify the retrieval of geometry from a section view. The main point is that the cutting plane of the section view does affect the retrieved geometry, whereas the view's bounding box does not. Here is the path we took to clarify this in all its gory detail:

Question: I am working on a structural concrete design application and would like to export Revit projects to it for analysis. I read your recent discussion of the curved analytical model approximation and ETABS structural link, which gives me a very good direction, since I intend to do something very similar.

However, the definition of floors in my application is such that the floor data exported cannot be just a list of lines. It has to be cut by section planes into series of 2D cross section shapes. Here is an example of a floor (white colour) and series of red section planes cutting it:

The cross section on each red plane would normally be rectangular. It might also be a very complex polygon with void holes in it, however.

The question is: how do I programmatically retrieve those cross section shapes?

Answer: You can easily extract the cross section shapes from the floor geometry by defining appropriate section views in Revit and asking the floor for its geometry in that specific view, as described by Saeed Karshenas in the note on section view geometry.

Response: I followed your suggestion and made some progress. I also have a couple of more questions:

Question 1: I drew a very rough floor with some beans and columns. I want to create a section view that is in the mid of the floor, half of the floor width (X), 1/10 of the floor height (Y) and the whole floor thickness (Z), like this:

This 'Detail 0' view looks correct. It does cut the floor into a flat rectangular:

However, when I was query the geometry from this view, the result gives me the whole floor, not just the portion within the view.

I verified this with the following lines of code:

  // Create the 'Details 0' view
 
  BoundingBoxXYZ boundingBox 
    = GetFrontBoundingBox( slab, doc );
 
  ViewSection viewSection 
    = doc.Create.NewViewSection( boundingBox );
 
  // Retrieve the element geometry within the view;
  // this returns the whole slab (floor)
 
  Options options = application.Create
    .NewGeometryOptions();
 
  options.View = viewSection;
 
  GeometryElement geo1 = slab.get_Geometry( 
    options );
 
  DumpLines( geo1 );
 
  // Retrieve the geometry of the whole slab;
  // this returns the same result
 
  GeometryElement geo2 = slab.get_Geometry( 
    new Options() );
 
  DumpLines( geo2 );

Both geo1 and geo2 have exactly the same surface area and volume. They contain exactly the same lines (same end points and length). I must be missing something here.

Question 2: This is not a programming question, rather a usage question. In Revit, how can I show the 'Detail 0' view's bounding box in the 3D views so that I can see its location and size?

Answer 1: Maybe regenerating the model before retrieving the geometry will help?

Answer 2: Maybe you can use the solution suggested to crop a 3D view to a room?

Response: I assume you are talking about the Document.Regenerate method. I tried this method and it got me a bit further.

Now the geometry volume I retrieve is about 1/2 of the floor geometry. It should however be 1/20 as defined by the view boundary. I am pretty sure the view's boundary is 1/20 of the floor as shown in the screen shot above.

  BoundingBoxXYZ boundingBox 
    = GetFrontBoundingBox( slab, doc );
 
  ViewSection viewSection 
    = doc.Create.NewViewSection( boundingBox );
 
  //viewSection.CropBox = boundingBox;
 
  Options options 
    = doc.Application.Create.NewGeometryOptions();
 
  options.View = viewSection;
 
  doc.Regenerate();
 
  GeometryElement geo1 = slab.get_Geometry( 
    options );
 
  DumpLines( geo1 );
 
  GeometryElement geo2 = slab.get_Geometry( 
    new Options() );
 
  DumpLines( geo2 );

I am not sure whether I should manually set the view CropBox to be the same as the bounding box. I tried that and it seems to give me a totally wrong result. I dumped the edges of geo1 and geo2 to a file and loaded that file into AutoCAD to verify:

geo1 is indeed half of geo2.

Answer: I thought you are not actually looking for a volume at all, just the cross section.

In that case, you need to eliminate all edges that do not lie exactly in the view plane, and create a boundary loop from the remaining ones that do.

Response: I was originally under the impression that the geometry of an element within a section view would be inside the view's bounding box, as suggested by this image from the Revit Developer Guide:

After I checked that assumption using the Revit SDK Object Viewer sample, I realized that the view's location and direction will affect the result of Element.get_Geometry, but the view's bounding box will not. The view will be treated as an infinite plane. This is OK with me. I will just have to manually cut the resulting lines so that they fit within the boundaries.

Many thanks to Bo for this discussion and his efficient research!

Curved Analytical Model Approximation and Etabs Link

Here is a note on how to retrieve approximate straight line segments for the analytical model of curved structural elements, and on a free Revit Structural link tool to the Computers and Structures, Inc. (CSI) ETABS building analysis and design environment.

A couple of weeks ago Nasser emailed me about a method he was trying to use for his Revit Structure link add-in. He was trying to export floor elements with curved edges to the structural analysis software ETABS. Like many other structural analysis applications, ETABS does not handle arcs and splines, so linear segmentation of curved elements is required.

The Revit API AnalyticalModel class provides an Approximate method which promises to achieve exactly that. Unfortunately, it is not yet implemented for this case.

A simple workaround is to use the Tessellate method instead. In addition, by skipping some of the intermediate points, the precision of the approximation can be lowered if needed.

Here is an example of how the Tessellate method can be used instead of the Approximate. The minimum line segment length required is defined by the LineSegmentLength argument:

  public IList<Curve> 
    GetStraightLineCurvesFromFloorAnalyticalModel(
      Document doc,
      AnalyticalModel analyticalmodel,
      double lineSegmentLength )
  {
    IList<Curve> Curves;
    IList<Curve> SegmentedCurves = new List<Curve>();
 
    // If no analytical model then skip
 
    if( analyticalmodel == null )
    {
      return null;
    }
 
    Curves = analyticalmodel.GetCurves( 
      AnalyticalCurveType.ActiveCurves );
 
    // This does not work:
    //Curves = analyticalmodel.GetCurves(
    //  AnalyticalCurveType.ApproximatedCurves);
 
    foreach( Curve curve in Curves )
    {
      IList<XYZ> pts = curve.Tessellate();
 
      int ibefore = 0;
 
      for( int i = 1; i < pts.Count; i++ )
      {
        double distance 
          = GeometryUtility.Get3DDistance( 
            pts[ibefore], pts[i] );
 
        if( pts.Count - 1 == i )
        {
          SegmentedCurves.Add( 
            doc.Application.Create.NewLineBound( 
              pts[ibefore], pts[i] ) );
        }
        else
        {
          if( distance < lineSegmentLength )
          {
            continue;
          }
          else
          {
            SegmentedCurves.Add( 
              doc.Application.Create.NewLineBound( 
                pts[ibefore], pts[i] ) );
 
            ibefore = i;
          }
        }
      }
    }
    return SegmentedCurves;
  }

This method is part of Nasser's Revit Tools, a Revit Structural link add-in to integrate with the Computers and Structures, Inc. (CSI) ETABS building analysis and design environment.

Nasser's add-in exports the following elements to ETABS: Columns, Braces, Beams, Walls, Slabs, Openings, Grids, Levels and Rigid Links. It recognizes most family elements. Custom created structural family instance elements will be exported as null, and their properties can later be adjusted in ETABS.

Here is a sample model in Revit:

This is the result of exporting it to ETABS:

Visit www.nassermarafi.com for more information or to access the free download. Feel free to contact Nasser directly for any questions or other issues.

REX Content Generator

I had an absolutely magical experience in Israel before leaving Tel Aviv Thursday afternoon. Among many others at the developer conference on Wednesday, we met with Dima Brickmann of Omnitech, and he suggested going for a short visit to Jerusalem before returning to the airport, which is located between Tel Aviv and Jerusalem. Partha and I decided to join him. Dima has a very special relationship with the city and a deep philosophical and photographical view of it, so he was a unique and wonderful guide. His tour focused more on feeling and experiencing the magic of this deeply religious place, which brings out so many extremes in all the different religions, and yet simultaneously enables them to coexist in an extremely confined area. I was really touched.

By the way, Dima has more recent photos with some short philosophical texts on the Russian photoreporting news web site newsru.co.il, e.g. this beautiful photo series on Jerusalem between black and white:

I went and installed a translation add-on for my browser to be able to read the Russian text. It works very well, and the photos are really and truly deep and beautiful.

Click on the link at the bottom saying 'ПРОДОЛЖЕНИЕ ФОТОРЕПОРТАЖА' to proceed to the rest of the photos in the series.

Thank you, Dima!

I would never have believed you could experience so much in such a short time, both in the three hours that we spent with Dima in Jerusalem and in the two days we spent in Israel.

On Friday we held another developer conference in Paris, and today we are already en route to Gothenburg in Sweden.

And my backlog of interesting blog posts is growing far faster than I can publish them.

REX Content Generator

One really astounding revelation at the DevLab at AU was the REX content generator sample.

It is provided with the REX framework and its other samples as part of the standard Revit SDK. I had not looked at it previously in any depth, since I have not used REX myself yet. I tend to avoid any additional frills, and the plain vanilla Revit API keeps me fully occupied all on its own. But this sample really bowled me over!

A DevLab participant showed me some of its features, and it looks like an astonishingly powerful tool. Here are a few notes I made from his demo:

The content generator provides the following functionality:

• Read existing families into a data structure.
• Create families from the data structure.
• Determine the section of a beam or column and display a shaded 3D preview of its solid extrusion.
• Interface to external structural databases to generate sections and families with these objects.
• Recognition which tries to match the current element to an existing database entry. If the user accepts the match, the content generator can switch the types by creating a new family based on the database record and replace all of the old instances by the new family.

Impressed?

I was!

The family API enables us to create new families step by step. In contrast, the content generator allows you to load an existing family, tweak and change it, and immediately generate a new family.

There is no need to install the Revit extensions to ensure that the basic REX framework is in place and the REX API is available. The content generator can be used even without Revit Extensions installed, since the framework is part of the regular Revit installation and is installed in a way transparent for the user.

To run the content generator sample, simply select a structural element, e.g. a column, and launch the command. It takes a little while to start up, because it reads the three databases: standard, steel and structural.

I asked Emmanuel Weyermann for a short description, and he provided the following brief yet full picture of Content Generator and this sample application:

What is Content Generator?

The Content Generator is a component which is part of the Revit Extensions Framework installed with Revit 2012.

It provides tools for content management. This component is strongly connected with standard databases shipped with Revit (over 130 databases).

Advantages of the Content Generator:

• Generation of Revit families: database sections, parametric sections, materials, user generic types.
• Interpretation of Revit families: database sections, parametric sections, materials.
• Getting data from standard databases.
• Searching elements in standard databases.
• Standard database browser dialogue.
• A mapping system.

More information may be found in the "User Manual for Extensions SDK.pdf".

Content Generator basic types

The idea of Content Generator is very simple. It provides its own representations of specific types (e.g. sections) and two converters which communicate with each other via these types:

• RVT Converter – responsible for communication with Revit
• REX Converter – responsible for communication with standard databases

Content Generator provides 4 types:

• Database section
• Parametric section
• Material
• Generic – defined by the user.

Code sample

The code below presents how to generate a particular section taken from the Rcatpro database:

  // Initializing the rex converter.
 
  REXFamilyConverter rex = new REXFamilyConverter();
 
  // Database identification data.
 
  string alias = "HEA 100";
 
  string directory = rex.GetDatabaseDirectory(
    ECategoryType.SECTION_DB );
 
  string dbName = "Rcatpro";
 
  // Getting the REXFamilyType from the database.
 
  REXFamilyType_DBSection famDBSection
    = rex.GetFamilyDBSection( EElementType.BEAM,
      EMaterial.STEEL, alias, dbName, directory );
 
  // Initializing the RVT converter.
 
  RVTFamilyConverter rvt = new RVTFamilyConverter(
    m_CommandData, true );
 
  // Getting Revit element.
 
  Autodesk.Revit.Element el = rvt.GetElement(
    famDBSection );
 
  FamilySymbol famSymbol = el as FamilySymbol;

Over twenty further samples are provided in the "User Manual for Extensions SDK.pdf".

ContentGeneratorWPF SDK sample

In Extensions SDK may be found the ContentGeneratorWPF sample. It allows examining a selected beam or column and changing its type to a new one (generated by Content Generator).

The sample demonstrates some of Content Generator key features:

• Revit FamilySymbol interpretation as:
  • Parametric section – shape is recognized and dimensions are calculated.
  • Database section – the element is recognized and match with appropriate section from database.
• Revit FamilySymbol generation:
  • Parametric section – there are three types available (in CG there are over 22): rectangle, angle and I section.
  • Database section – the user is able to point section from available databases.
• Database browsing.

The sample runs database browser which allows exploring available databases:

Where is Content Generator used?

• As a standalone application which generates different types of Revit content (part of Revit Extension for RAC and RST - Extensions ribbon->Tools).
• In different integration tools: Revit – Cloud computation (Storm), links Revit – RSA, Revit – ASD, and for some files import/export extensions Revit – CIS, Revit – SDNF.
• In different Revit Extensions: steel connections, reinforcements, timber framing, structure generator (recently mentioned) etc.

Many thanks to Emmanuel for this overview!

If you are interested in Revit Structure and structural databases, I strongly encourage you to take a deep look at this if you have not already done so.

Project Structure Generator on Autodesk Labs

I arrived safely in Las Vegas after a 12:40 hour flight to Los Angeles, 3:30 hour wait, und another flight of 1:05 hours. Pretty crazy. I had a headache after that, but not too bad, and I slept well out in the desert. Just like in previous years (08, 09, 09b, 10), my daytime jetlag therapy consists of climbing in Red Rock, this time with Sergio Colombo again, whom I first met and climbed with in 2008.

We did the Great Red Book trad climb, completing it this time, and I led two 5.9s in the black corridor.

Meanwhile, here is yet another Revit related project published on Autodesk Labs:

Project Structure Generator

Project Structure Generator for Revit Architecture and Revit Structure is available on Autodesk Labs.

It generates real structural models from mass objects.

Project Structure Generator is a technology preview that provides a connection between massing models and objects created during conceptual design and structural elements such as beams, column, walls, and plates. With Project Structure Generator, structural engineers and architects, from the earliest stages, can very quickly create and visualize a physical and analytical model of a structure based on the massing model. The technology preview will operate until April 1, 2012.

What does Project Structure Generator do?

It provides a connection between massing models and objects created during conceptual design, enabling structural engineers and architects to:

• Automatically create and visualize a physical model of the structure with mass objects.
• Generate variants of the physical and analytical model with structural systems based on the massing model.
• Predict volume and weight of materials used.
• Extend model to Revit Structure or Revit Architecture.
• Extend massing model to structural analysis with Project Storm, a cloud based static analysis technology preview, or Autodesk Robot Structural Analysis Professional.

Analytical Model IsEnabled Method and Parameter

I recently mentioned the changes in accessing the analytical model in the Revit Structure 2012 API.

We just discovered a little issue and an effective workaround related to the AnalyticalModel IsEnabled method, which reports whether the analytical model is currently enabled or disabled. Right now, it does not do that, but throws an exception for all members except walls. The Enable and CanDisable methods have similar problems. This will soon be resolved. Meanwhile, here is a simple workaround to avoid the issue by accessing the underlying data directly:

The correct "enable" parameter is on the physical element, not its analytical model, and accessible through the built-in parameter STRUCTURAL_ANALYTICAL_MODEL. To enable the analytical model, e.g. for a wall, simply set STRUCTURAL_ANALYTICAL_MODEL to true on the wall element, not on the analytical wall element.

Bevelled Steel Beams

I recently mentioned a couple of options for performing Boolean operations. Here is another question which initially seemed related to that, from Simon Jones of Autodesk UK, on creating a mitre joint between steel beams, i.e. bevelling the two parts to be joined. It turns out to have a satisfyingly simple and automatic answer with no need for any explicit Boolean operations after all.

Simon returned to a technical role in consulting after a period as Technical Sales Manager of Autodesk UK. Even in his non-technical role, he always remained very interested and productive in technical aspects as well, for instance creating the UK Electrical Schedule Sample before the introduction of the electrical panel schedule API in Revit 2011.

Question: Through the user interface, it is possible to cut back the end of a beam at an angle using the Cut tool and selecting a reference plane.

Within the API I see there is a SolidSolidCutUtils class but I can't find anything to cut a solid using a reference plane.

Is this possible in the Revit Structure 2011 API? Or is there any other way of trimming back a beam?

What I actually wish to achieve is to enable a better workflow for creating steel staircases in RST2011.

One solution I'm considering is automating the creation of a structural frame to represent the stair stringers, treads and landing. Something that can be done manually but not very efficiently!

I saw the SolidSolidCut utility but didn't think this could help me as I want to edit beams within a project.

Answer: As I mentioned, there are a number of ways of performing Boolean operations in the Revit API. All of the options performing a Boolean operation in the project environment place a significant burden on the project, so the optimal approach is definitely to apply the cut in the family context, especially if it is something like a standard operation to shorten or add an angle to all the beam ends.

Response: It actually worked out much easier than I was expecting. If the beam endpoints touch, Revit cleans them up on its own accord:

Answer: I used Simon's sample code to create a new external command CmdSteelStairBeams for The Building Coder samples.

Simon encapsulated the beam creation functionality in an own prototyping class named SteelStairs. It defines the following helper method CreateBeam to implement the beam creation:

FamilyInstance CreateBeam( 
  FamilySymbol familySymbol,
  Level level,
  XYZ startPt, 
  XYZ endPt )
{
  StructuralType structuralType 
    = StructuralType.Beam;
 
  Line line = _doc.Application.Create.NewLineBound( 
    startPt, endPt );
 
  FamilyInstance beam = _doc.Create
    .NewFamilyInstance( startPt, familySymbol, 
      level, structuralType );
 
  LocationCurve beamCurve 
    = beam.Location as LocationCurve;
 
  if( null != beamCurve )
  {
    beamCurve.Curve = line;
  }
  return beam;
}

This helper method is called by the main Run method to create a series of three connected steel beams between four hard-wired 3D points in the XZ plane, with Y equal to zero:

public void Run()
{
  View view = _doc.ActiveView;
 
  Level level = view.GenLevel;
 
  if( null == level )
  {
    throw new Exception( "No level associated with view" );
  }
 
  XYZ pt1 = Util.MmToFoot( new XYZ( 0, 0, 1000 ) );
  XYZ pt2 = Util.MmToFoot( new XYZ( 1000, 0, 1000 ) );
  XYZ pt3 = Util.MmToFoot( new XYZ( 2000, 0, 2500 ) );
  XYZ pt4 = Util.MmToFoot( new XYZ( 3000, 0, 2500 ) );
 
  FamilySymbol familySymbol = Util.FindFamilySymbol(
    _doc,
    CmdSteelStairBeams.FamilyName,
    CmdSteelStairBeams.SymbolName );
 
  if( familySymbol == null )
  {
    throw new Exception( "Beam Family not found" );
  }
 
  CreateBeam( familySymbol, level, pt1, pt2 );
  CreateBeam( familySymbol, level, pt2, pt3 );
  CreateBeam( familySymbol, level, pt3, pt4 );
}

The class constructor does nothing more than initialise the one and only class data member for the current document:

Document _doc;
 
public SteelStairs( Document doc )
{
  _doc = doc;
}

The SteelStairs helper class is driven by the following external command mainline Execute method, which mainly fusses about to manage a transaction and ensure that the appropriate rectangular hollow section steel beam family and symbol is loaded. The family and symbol names to use depend on the exact flavour of Revit content that you have installed. The rectangular hollow section steel beam family is provided in both the architectural and structural libraries. In my case, I am loading it from the architectural content.

I hope you enjoy my use of the generic Any template method to check whether a family of the specified name has already been loaded. By the way, I just noticed a flaw in my logic: while I ensure that the family is available, I do not check for the specific symbol as well. This command will fail if some other symbols have been loaded, but not the one required. I leave that as an exercise to the reader to clear up, though.

Once the beam symbol is loaded, all that is needed is to call the SteelStairs constructor and Run method:

[Transaction( TransactionMode.Manual )]
class CmdSteelStairBeams : IExternalCommand
{
  public const string FamilyName
    = "RHS-Rectangular Hollow Section";
 
  public const string SymbolName
    = "160x80x4RHS";
 
  const string _extension
    = ".rfa";
 
  const string _directory
    = "C:/ProgramData/Autodesk/RAC 2012/Libraries"
    + "/US Metric/Structural/Framing/Steel/";
 
  const string _family_path
    = _directory + FamilyName + _extension;
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
 
    Transaction t = new Transaction( doc );
 
    t.Start( "Create Steel Stair Beams" );
 
    // Check whether the required family is loaded:
 
    FilteredElementCollector collector
      = new FilteredElementCollector( doc )
        .OfClass( typeof( Family ) );
 
    // If the family is not already loaded, do so:
 
    if( !collector.Any<Element>(
      e => e.Name.Equals( FamilyName ) ) )
    {
      FamilySymbol symbol;
 
      if( !doc.LoadFamilySymbol(
        _family_path, SymbolName, out symbol ) )
      {
        message = string.Format(
          "Unable to load '{0}' from '{1}'.",
          SymbolName, _family_path );
 
        t.RollBack();
 
        return Result.Failed;
      }
    }
 
    try
    {
      // Create a couple of connected beams:
 
      SteelStairs s = new SteelStairs( doc );
 
      s.Run();
 
      t.Commit();
 
      return Result.Succeeded;
    }
    catch( Exception ex )
    {
      message = ex.Message;
 
      t.RollBack();
 
      return Result.Failed;
    }
  }
}

This is the result of running this command in Revit Architecture instead of Revit Structure:

Here is version 2012.0.90.0 of The Building Coder samples including the new command CmdSteelStairBeams.

Reference to Analytical Curve

The Autodesk University 2011 Class Catalog is now live and includes a full listing of both AU Las Vegas and AU Virtual Classes. Here are the my three classes:

• Lecture CP4451: Extensible Storage in the Revit 2012 API
• Hands-On Lab CP6760-L: Revit 2012 API Extensible Storage
• Virtual CP4453: Everything in Place with Revit MEP Programming

So I have lots to prepare. For a full list of the classes presented by my colleagues in the ADN team, please refer to Kean's post.

Meanwhile, here is a structural issue for a change:

The Revit Structure API has undergone significant changes in every release lately. Once the whole rebar functionality was updated, and in the last release it was the analytical model. This obviously causes some complexity and upheaval.

In Revit Structure 2012, the analytical component was separated into its own independent Element, the AnalyticalModel element. This is different from previous releases, where AnalyticalModel was a proxy for the analytical portion of the physical Element. The interface to the AnalyticalModel was not changed, so the AnalyticalModel.getCurve method still works, for instance.

Therefore, each Structural Column and Structural Beam actually has two Elements in RST 2012: the physical portion, which is a FamilyInstance, and the analytical portion, the AnalyticalModel.

One consequence of this is that the reference on the analytical model will be different than the reference on the physical element, because it is not on the physical element any more.

Here is a question concerning this raised and also answered by Elizabeth Shulok of Structural Integrators, LLC on obtaining a stable geometric reference to the end point of the analytical curve of a structural member element that highlights some of these changes:

Question: I am trying to add a new point boundary condition to a Revit project via the API. It requires a geometry reference to a beam, brace or column analytical line end. In my code, after adding beams and columns and calling Regenerate, I find the column whose end coincides with the point of the boundary condition I want to add using a BoundingBoxContainsPointFilter ANDed with a StructuralInstanceUsageFilter. The problem is that I cannot get a stable reference from the column's curve which I am getting from the AnalyticalModel. Calling get_EndPointReference(0) returns null. What could cause the curve of a newly added column not to have a reference? Another alternative approach that I also tried instead of calling GetCurve or Curve on the analytical model was to call get_Geometry on the Element itself with the option argument ComputeReferences property set to true. I was then able to obtain the curve from the GeometryElement returned from get_Geometry, but that did not help either.

Answer: In versions prior to 2012, you could get the analytical model curve from the Element Geometry property (using the get_Geometry method in C#). However, in Revit 2012, the analytical model curves cannot be retrieved this way. They can only be obtained from the AnalyticalModel class.

In this case, you can use the AnalyticalModelSelector.

We just added a new code sample using AnalyticalModelSelector to the Revit API help wiki; look at the 29-15 NewPointLoad() sample at the bottom of the page.

Getting the geometric reference to the analytical curve start point like this works well:

  AnalyticalModel analyticalModel = fiColumn
    .GetAnalyticalModel() as AnalyticalModel;
 
  Reference startReference = null;
 
  if( null != analyticalModel )
  {
    Curve curveCol = analyticalModel.GetCurve();
    if( null != curveCol )
    {
      AnalyticalModelSelector amSelector 
        = new AnalyticalModelSelector( curveCol );
 
      amSelector.CurveSelector 
        = AnalyticalCurveSelector.StartPoint;
 
      startReference = analyticalModel
        .GetReference( amSelector );
    }
  }

Many thanks to Elizabeth for her research and sharing this solution!

Retrieving Materials

Some people have reported issues using the Document.Settings.Materials collection. For instance, its Contains method may throw an exception when used with Revit Structure 2012, while it works fine with Revit Architecture 2012.

The problem actually probably has nothing to do with the flavour of Revit being used, but is caused by the template file that the project is based on. If you retrieve materials in a project based on the architectural template in Revit Structure, it also works fine.

In any case, here is a workaround you can use instead. Simply retrieve the materials using a filtered element collector instead of the Materials collection, for example like this:

  FilteredElementCollector collector 
    = new FilteredElementCollector( document )
      .OfClass( typeof( Material ) );
 
  IEnumerable<Material> materialsEnum 
    = collector.ToElements().Cast<Material>();
 
  var materialReturn1 
    = from materialElement in materialsEnum
      where materialElement.Name == "Default"
      select materialElement;

No Multithreading in Revit

I repeatedly hear from developers asking whether multithreading can be used in conjunction with the Revit API. The short answer is no.

To our surprise, we just noticed that the Truss SDK sample does demonstrate a use of multithreading. That is an oversight and you should not rely on this working properly.

Here is the considered statement of Scott Conover, Software Development Manager of the Revit API, on the current state of multithreading and Revit:

"Revit's internals make use of multiprocessing in only a few select isolated locations. None of these locations currently encompass the code in the Revit API, or any part of it. Thus Autodesk does not recommend making any calls to the Revit API from within simultaneously executing parallel threads. It may be that some part of the Revit API is isolated enough to be able to execute successfully from within such threading code in a test environment; this should not be taken to be a guarantee that the same source code will function for any model or situation, or that a future change in Revit will not cause this code to cease to function."

I hope this clarifies the situation.

Truss SDK Sample Enhancement

The Truss SDK sample contains the following code and comments:

  // get all the beam types
  // because GetBeamTypes() takes a long
  // time, so call it in a new thread
 
  Thread newThread = new Thread(
    new ThreadStart( GetBeamTypes ) );
 
  newThread.Start();

Here, GetBeamTypes is using the Revit API methods FilteredElementCollector and parameter access methods.

As said, this is not supported; Revit API access is required to be single threaded. It is an interesting side note that it apparently works, but this cannot be relied on and this code should definitely not be reused.

Actually, the sample would be faster if it made use of more of the FilteredElementCollector capabilities. The implementation of this sample predated the introduction of filtered element collectors in Revit 2011:

  m_beamTypes = from elem in
    new FilteredElementCollector( doc )
      .OfClass(typeof(FamilySymbol))
      .ToElements()
    let type = elem as FamilySymbol
    where type != null 
      && type.Category != null  
      && type.Category.Name == "Structural Framing"
    select type;

A better implementation might be:

  m_beamTypes 
    = from elem in new FilteredElementCollector( 
          m_activeDocument.Document )
        .OfClass( typeof( FamilySymbol ) )
        .OfCategory( BuiltInCategory.OST_StructuralFraming )
      let type = elem as FamilySymbol
      select type; 

This uses a quick category filter and avoids calling ToElements, which is unnecessary, as the filtered element collector itself is already an IEnumerable.

Other examples of using multithreading in perfectly valid ways in conjunction with the Revit API are provided by the APIAppStartup splash window and the AnalysisVisualizationFramework MultithreadedCalculation Revit SDK samples, where the separate threads do not make calls into Revit.