Making a Revit Converter

Preflight Overview Writing Converters Sample Converter Code Debugging Converters Generate types Additional Resources

Preflight

You need the following items installed to successfully follow this guide:

Hypar CLI version 0.9.11-alpha.0 or later

Update using dotnet tool update --global Hypar.CLI --version 0.9.11-alpha.0

Hypar Revit plugin

Download latest release here https://github.com/hypar-io/Hypar-Revit-Installers/releases

If you haven’t used the Hypar Revit plug-in before, it’s worth getting familiar with it before trying to write your own converter. See

Hypar for Revit for details.

Overview

To create a converter, you’ll use the Hypar CLI to quickly get up and running. Run the following command, providing whatever converter name you like:

hypar converter new -n "MyConverterName"

This sets up a project for you with all the necessary references to build and debug a new converter. In VS Code, open the folder that was created. (The folder will be given the name you supplied in the previous step — MyBestConverter in this example).

Inside you’ll see these items:

.vscode contains pre-configured settings for debugging your converter.

MyBestConverter.cs is the converter class file — this is where we’ll do most of our editing.

MyBestConverter.csproj is the converter project file.

Writing Converters

Each Converter is a class that implements the IRevitConverter interface. A converter is responsible for converting model elements between Hypar and Revit.

A converter can convert from Revit to Hypar, from Hypar to Revit or in both directions. It’s up to you to decide which direction(s) to implement for your converter. Each direction has a set of associated properties and methods that you are responsible for writing. The Hypar Revit plug-in will take care of running your converter code on all the correct elements when a user imports or exports a model.

From Revit

`bool CanConvertFromRevit`	This method determines whether or not your converter supports converting from Revit elements to Hypar elements.
`DB.FilteredElementCollector AddElementFilters(DB.FilteredElementCollector collector)`	This method lets you pre-filter the elements in the Revit model, to limit them to only those your converter can handle.
`Elements.Element[] FromRevit(ADSK.Element revitElement, ADSK.Document document)`	This method handles creating one or more new Hypar elements from a supplied Revit element.

To Revit

`bool CanConvertToRevit`	This method determines whether or not your converter supports converting from Hypar elements to Revit elements.
`Elements.Element[] OnlyLoadableElements(Elements.Element[] allElements)`	This method lets you pre-filter the elements in the Hypar model, to limit them to only those your converter can handle.
`DB.ElementId[] ToRevit(Elements.Element element, LoadContext context)`	This method handles creating one or more new Revit elements from a supplied Hypar element.

Sample Converter Code

You can view sample converter code here

ElementConverterSamples

hypar-io • Updated Jan 9, 2022

Debugging Converters

We recommend using VSCode, and the project has been setup to be very easy to test using VSCode’s built in debugger. In the debug section of VSCode you have two debug options set up:

Launch Revit 202x - Most of the time you’ll use the Launch Revit option which will build your converter, copy it to the correct location, and then launch the corresponding version of Revit in a debug session.

Attach to Revit - Attach to an already running instance of Revit.

💡

You do not need to do anything to “install” your converter when debugging. It will automatically be copied to the correct location and ready to load for you.

Choose the debug option you want and then press F5 to run in your preferred mode.

You should now be setup to hit breakpoints in your converter code from within VSCode.

Generate types

If you’re creating a converter for a type that is not built in to elements, you’ll need to use the Hypar CLI command to generate a class file from a schema url:

hypar generate-types -u https://raw.githubusercontent.com/hypar-io/Schemas/master/Envelope.json

Additional Resources

A video tutorial on how to make Revit Converters. A little old now, but mostly accurate. https://www.youtube.com/watch?v=si__iV6oJKw&t=666s

Hypar Live if you want a long winded, but entertaining deep dive into converters

https://www.youtube.com/watch?v=-ZoHgwNi4yU&t=1026s

Some sample converters created by another developer

https://github.com/ParallaxTeam/HyparElementConverters