One important Revit 2014 API highlight is the new custom exporter framework providing direct API access to the rendering output pipeline, including geometry and material properties.
The What's New section of the Revit API help file describes it in more detail like this:
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 – 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 exposed:
CustomExporter
A class that allows exporting 3D views via a custom export context. The Export method of this class triggers the 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.
Usage Outline
Here is minimal code snippet outlining the main components' interaction:
// Instantiate custom context MyExportContext context = new MyExportContext( document ); // Instantiate custom exporter CustomExporter exporter = new CustomExporter( document, context ); // Specify exporter settings exporter.IncludeFaces = false; exporter.ShouldStopOnError = false; // Launch export process exporter.Export( view3D );
Example Exporters
I would like to present several different examples and ideas for making use of this functionality:
The first two of these are discussed below; the latter two are currently just ideas for future projects.
Custom Exporter to XML
Arnošt Löbel provided a sample add-in demonstrating and exercising just about all possible aspects of the custom exporter functionality.
It initially presents a user interface in which the different available options can be manually selected for testing purposes:
On validating the dialogue, the custom export is started and the data it receives is logged to an XML file.
I adapted Arnošt's original code slightly to ensure that spaces in the asset names and properties are replaced by underscore characters in order to define valid XML tags.
Here is rac_basic_sample_project.xml containing the XML output generated from the {3D} view of the standard Revit architectural basic sample project with that replacement in place, so you can see directly for yourself what the exact output generated by this system looks like. Actually, maybe you cannot, because it is a rather unwieldy 41 MB in size. Here is family_api_kitchen.xml instead, just over 4 MB, making it a bit more manageable, generated from the family API kitchen sample model.
I can see you are raring to go and explore this for yourself, so without further ado I hereby present CustomExporterXml.zip containing the complete source code, Visual Studio solution and add-in manifest for the XML custom exporter external command add-in.
Since the goal of this XML exporter sample is to present and test all possible custom exporter functionality, it is rather more complex than an average simple exporter, e.g. the following one to the Collada file format.
Thank you, Arnošt, for providing this powerful full-fledged exploration and testing tool!
Custom Exporter to Collada
A much simpler custom exporter example than the full-featured export to XML described above is this real-world Revit Collada exporter by Artur Brzegowy of Act-3D B.V. supporting export to the Collada model visualisation format.
The external command mainline is very simple, basically just matching the outline presented above.
All the work resides in the custom exporter implementation and its numerous methods:
Here is CustomExporterCollada.zip containing the complete source code, Visual Studio solution and add-in manifest for the Collada custom exporter external command add-in.
Many thanks to Artur for sharing this!
Custom Exporter to OBJ
Another custom exporter candidate that I might return to later would be a replacement for my OBJ exporter for Revit 2013.
That implementation and its detailed description show the complications required to determine and traverse all the solids of all relevant model elements and export their graphics prior to the custom exporter API. Additional work was required to determine their colour and other properties:
Almost of all of that complexity is now provided for free by the custom exporter API.
Yet another example of the significant simplification provided by the custom exporter is the handling of hidden elements from a linked file in the host view. For instance, the API provides no external method to whether a specific wall in a linked file is hidden in the host 3D view. The custom export support in 2014, however, will respect this and not pass elements which are hidden, whether locally, in links, or any of the other 40 or so possible ways to hide an element. Of course, this support is only available for 3D views and 3D exports, and restricted to Revit 2014 and later.
Custom Exporter to JSON
Philippe Leefsma recently presented an online 3D WebGL viewer for both mobile and desktop devices implemented using JavaScript, WebGL and the threejs library.It displays graphics stored in the same custom JSON format that Philippe already defined for his initial cloud based viewer and for which Adam Nagy in turn implemented a Revit 2013 exporter.
I would love to create a Revit exporter for this format based on the new custom exporter API, for fun and comparison.
As you can see, this framework provides powerful new functionality with many important applications.
I am looking forward to hearing what you make use of it for.
