Revit BHoM conversion

Revit_Toolkit provides bi-directional conversion between Revit and BHoM. This conversion is an integral part of Push and Pull Adapter actions - besides simply translating Revit elements into BHoM objects, it ensures correctness of the units and, in general, allows representing Revit objects outside of Revit context.

Sections below explain the practicalities of that process, while its code mechanics is discussed in Push details and Pull details sections.

Conversion from Revit

Due to multidisciplinarity of both BHoM and Revit, conversion from Revit is not always a singular problem: some elements can be converted into multiple BHoM types, depending on user's discipline preference set in RevitPullConfig. Table below contains a matrix of possible converts organized by discipline.

Revit Category	Revit Type	BHoM Physical	BHoM Structural	BHoM Envinronments	BHoM Architecture
Grids	Autodesk.Revit.DB.Grid	BH.oM.Geometry.SettingOut.Grid	BH.oM.Geometry.SettingOut.Grid	BH.oM.Geometry.SettingOut.Grid	BH.oM.Geometry.SettingOut.Grid
Levels	Autodesk.Revit.DB.Level	BH.oM.Geometry.SettingOut.Level	BH.oM.Geometry.SettingOut.Level	BH.oM.Geometry.SettingOut.Level	BH.oM.Geometry.SettingOut.Level
Walls	Autodesk.Revit.DB.Wall	BH.oM.Physical.Elements.Wall	BH.oM.Structure.Elements.Panel	BH.oM.Environment.Elements.Panel	BH.oM.Physical.Elements.Wall
Floors / Foundation Slabs	Autodesk.Revit.DB.Floor	BH.oM.Physical.Elements.Floor	BH.oM.Structure.Elements.Panel	BH.oM.Environment.Elements.Panel	BH.oM.Physical.Elements.Floor
Roofs	Autodesk.Revit.DB.RoofBase	BH.oM.Physical.Elements.Roof	BH.oM.Structure.Elements.Panel	BH.oM.Environment.Elements.Panel	BH.oM.Physical.Elements.Roof
Structural Columns	Autodesk.Revit.DB.FamilyInstance	BH.oM.Physical.Elements.Column	List<BH.oM.Structure.Elements.Bar>		BH.oM.Physical.Elements.Column
Structural Framing	Autodesk.Revit.DB.FamilyInstance	BH.oM.Physical.Elements.Beam / BH.oM.Physical.Elements.Bracing	List<BH.oM.Structure.Elements.Bar>		BH.oM.Physical.Elements.Beam / BH.oM.Physical.Elements.Bracing
Windows	Autodesk.Revit.DB.FamilyInstance	BH.oM.Physical.Elements.Window		BH.oM.Physical.Elements.Window	BH.oM.Physical.Elements.Window
Doors	Autodesk.Revit.DB.FamilyInstance	BH.oM.Physical.Elements.Door		BH.oM.Physical.Elements.Door	BH.oM.Physical.Elements.Door
Curtain Panels	Autodesk.Revit.DB.Panel	BH.oM.Physical.Elements.Window		BH.oM.Physical.Elements.Window	BH.oM.Physical.Elements.Window
Ceilings	Autodesk.Revit.DB.Ceiling	BH.oM.Architecture.Elements.Ceiling		BH.oM.Environment.Elements.Panel	BH.oM.Architecture.Elements.Ceiling
Spaces / Rooms	Autodesk.Revit.DB.SpatialElement	BHoM.Architecture.Elements.Room		BH.oM.Environment.Elements.Space	BHoM.Architecture.Elements.Room
Project Information	Autodesk.Revit.DB.ProjectInfo			BH.oM.Environment.Elements.Building
Analytical Surfaces	Autodesk.Revit.DB.Analysis.EnergyAnalysisSpace	BH.oM.Environment.Elements.Space		BH.oM.Environment.Elements.Space	BH.oM.Environment.Elements.Space
Interior, Exterior, Shades	Autodesk.Revit.DB.Analysis.EnergyAnalysisSurface	BH.oM.Environment.Elements.Panel		BH.oM.Environment.Elements.Panel	BH.oM.Environment.Elements.Panel
Opening	Autodesk.Revit.DB.Analysis.EnergyAnalysisOpening	BH.oM.Environment.Elements.Panel		BH.oM.Environment.Elements.Panel	BH.oM.Environment.Elements.Panel
Families	Autodesk.Revit.DB.Family	BH.oM.Adapters.Revit.Elements.Family	BH.oM.Adapters.Revit.Elements.Family	BH.oM.Adapters.Revit.Elements.Family	BH.oM.Adapters.Revit.Elements.Family
Materials	Autodesk.Revit.DB.Material	BH.oM.Physical.Materials.Material	BH.oM.Structure.MaterialFragments.IMaterialFragment	BH.oM.Environment.MaterialFragments.SolidMaterial	BH.oM.Physical.Materials.Material
Sheets	Autodesk.Revit.DB.Sheet	BH.oM.Adapters.Revit.Elements.ViewSheet	BH.oM.Adapters.Revit.Elements.ViewSheet	BH.oM.Adapters.Revit.Elements.ViewSheet	BH.oM.Adapters.Revit.Elements.ViewSheet
Viewports	Autodesk.Revit.DB.Viewport	BH.oM.Adapters.Revit.Elements.Viewport	BH.oM.Adapters.Revit.Elements.Viewport	BH.oM.Adapters.Revit.Elements.Viewport	BH.oM.Adapters.Revit.Elements.Viewport
Views (Plan)	Autodesk.Revit.DB.ViewPlan	BH.oM.Adapters.Revit.Elements.ViewPlan	BH.oM.Adapters.Revit.Elements.ViewPlan	BH.oM.Adapters.Revit.Elements.ViewPlan	BH.oM.Adapters.Revit.Elements.ViewPlan

In case of conversion to structural BHoM types, Revit element is first queried for its analytical model, and its physical representation is used only if the former does not exist.

If a Revit element is requested to be pulled and there is no explicit convert method for its type and given discipline, it will get converted into a ModelInstance, DraftingInstance or InstanceProperties. If that fails too, a BHoMObject with only basic information is returned. The conversion procedure is shown in the flowchart below (full size).

Conversion to Revit

Conversion from BHoM to Revit is rather simple: the BHoM object is coming through BH.UI.Revit.Engine.Convert.IToRevit, which points it to the appropriate ToRevit method that creates an element in the active Revit document. Table below contains a list of BHoM types that can be converted, together with their relevant Revit types. As a general rule, analytical objects (of types that belong to namespaces BH.oM.Structure or BH.oM.Environment) are not allowed to be pushed to Revit - their physical equivalents (objects of types from BH.oM.Physical namespace) should be used instead. So far, the only exception from that rule is BH.oM.Environment.Elements.Space.

BHoM type	Revit Category	Revit Type
BH.oM.Geometry.SettingOut.Grid	Grids	Autodesk.Revit.DB.Grid
BH.oM.Geometry.SettingOut.Level	Levels	Autodesk.Revit.DB.Level
BH.oM.Physical.Elements.Wall	Walls	Autodesk.Revit.DB.Wall
BH.oM.Physical.Elements.Floor	Floors	Autodesk.Revit.DB.Floor
BH.oM.Physical.Elements.Roof	Roofs	Autodesk.Revit.DB.RoofBase
BH.oM.Physical.Elements.Column	Structural Columns	Autodesk.Revit.DB.FamilyInstance
BH.oM.Physical.Elements.Beam	Structural Framing	Autodesk.Revit.DB.FamilyInstance
BH.oM.Environment.Elements.Space	Spaces	Autodesk.Revit.DB.Mechanical.Space
BH.oM.Adapters.Revit.Elements.ViewPlan	Views (Plan)	Autodesk.Revit.DB.ViewPlan
BH.oM.Adapters.Revit.Elements.Viewport	Viewports	Autodesk.Revit.DB.Viewport
BH.oM.Adapters.Revit.Elements.ViewSheet	Sheets	Autodesk.Revit.DB.Sheet

Conversion of BHoM object properties such as Construction or FramingProperties to Revit is currently not supported - Revit element type is applied based on name matching with BHoM property. Therefore, to create a Revit element of given family type, one needs to set BHoM object's property name to same value. Example of Push using this approach is available in samples.

It is possible to push almost any Revit element using ModelInstance and DraftingInstance, explained in more detail below.

ModelInstance, DraftingInstance and InstanceProperties

There are three powerful generic types in Revit_Adapter that can wrap any Revit element. These are:

• ModelInstance - any Revit view independent element that has Location property
• DraftingInstance - any Revit view dependent element that has Location property
• InstanceProperties - any Revit ElementType or GraphicsStyle

The above types can be used on Push to create Revit elements that do not have a correspondent BHoM type, e.g. mechanical equipment, generic annotations or filled regions - examples of these can be found in samples.

The usage of ModelInstance, DraftingInstance and InstanceProperties on Pull has been explained in Conversion from Revit paragraph.

Geometry conversion

The table below presents geometry conversion methods offered by Revit_Toolkit.

Revit type	Supported conversion direction	BHoM type
Autodesk.Revit.DB.XYZ	< - >	BH.oM.Geometry.Point
Autodesk.Revit.DB.XYZ	< - >	BH.oM.Geometry.Vector
Autodesk.Revit.DB.Plane	< - >	BH.oM.Geometry.CoordinateSystem.Cartesian
Autodesk.Revit.DB.Line	< - >	BH.oM.Geometry.Line
Autodesk.Revit.DB.Arc	< - >	BH.oM.Geometry.Arc / BH.oM.Geometry.Circle
Autodesk.Revit.DB.Ellipse	< - >	BH.oM.Geometry.Ellipse
Autodesk.Revit.DB.NurbSpline	< - >	BH.oM.Geometry.NurbsCurve
Autodesk.Revit.DB.HermiteSpline	- >	BH.oM.Geometry.NurbsCurve
Autodesk.Revit.DB.Analysis.Polyloop	- >	BH.oM.Geometry.Polyline
Autodesk.Revit.DB.PolyLine	- >	BH.oM.Geometry.Polyline
Autodesk.Revit.DB.CurveLoop	< - >	BH.oM.Geometry.PolyCurve
Autodesk.Revit.DB.Solid	< -	BH.oM.Geometry.ISurface
Autodesk.Revit.DB.Solid	< -	BH.oM.Geometry.BoundaryRepresentation

In a special case where Revit requires an unbound curve (e.g. in case of floor outlines) closed BHoM curves are split in half to create a continuous loop consisting of two unbound Revit curves.

It is worth noting that pushing BHoM geometries directly to Revit is not allowed - they always need to be wrapped into some type of object (if are meant to be pushed as primitives, ModelInstance or DraftingInstance is recommended. Similarly, on pull, each geometrical Revit element will be wrapped into a non-primitive BHoM type.

BHoM CustomData vs Revit Parameters

Each of the Revit elements and types has a range of parameters that define their characteristics. On convert these are matched with:

• property of the correspondent BHoM object - if the element's parameter name is matched with property of BHoM object's type via MapSettings
• key in BHoM object's CustomData - if the above does not apply

On Push each CustomData value gets copied to a matching parameter of correspondent Revit element (if such parameter exists), on Pull each parameter value gets copied to CustomData under key equal to parameter name.

On top of that, there is a couple of hardcoded CustomData keys being created on Pull in order to support manipulation and identification of correspondent Revit element. These are:

• Revit_id - Id of Revit Adapter
• Revit_elementId - Id of Revit element (Element.Id.IntegerValue)
• Revit_worksetId - Id of workset to which Revit element belongs (Element.WorksetId.IntegerValue)
• Revit_spaceId - Id of Revit space that encloses Revit element, also used to store information about bounding elements (if pulled from Revit Autodesk.Revit.DB.Analysis.EnergyAnalysisDetailModel)
• Revit_adjacentSpaceId - Id of adjacent Revit space (this information is included if pulled from Revit Autodesk.Revit.DB.Analysis.EnergyAnalysisDetailModel)
• Revit_familyName - family name of Revit element (stored in Revit built-in parameter BuiltInParameter.ELEM_FAMILY_PARAM)
• Revit_familyTypeName - family type name of Revit element (stored in Revit built-in parameter BuiltInParameter.ELEM_TYPE_PARAM)
• Revit_categoryName - category name of Revit element (stored in Revit built-in parameter BuiltInParameter.ELEM_CATEGORY_PARAM)
• Revit_edges - curves representing edges of Revit element (pulled only if RevitPullConfig.PullEdges is set to true)

Warning and error messages

It is likely that the adapter will generate warnings on converts. This is related to the fact that each Revit object consists of a multitude of information that often cannot be translated to BHoM one to one. It is important to read warning messages as they usually explain what issue has been found.

Error messages, on the other hand, usually mean that a serious issue occurred on convert: either the object has not been converted due to an error in the method, or the conversion method simply does not exist. Same as with warnings, error messages should provide detailed information about the problem.