Revit Secondary Development: Starting with Revit

[#1]

In Revit's secondary development process, many developers typically first familiarize themselves with the Revit software before diving into development.  By mapping the structures and operations within Revit to code design, developers can more quickly understand the requirements and implement functionalities in the early stages of the project.  This article will introduce two common approaches to Revit secondary development and their thought processes, hoping to provide helpful insights and inspiration to the reader.

Map Revit Element Logic To Code

Custom Families Within the Revit API are represented by three objects: Family,FamilySymbol, and FamilyInstance.[1] Using this level will better control the element creation, placement, and configuration.

In program design, we can also adopt this hierarchical thinking to reduce the coupling between code components.

Typically, we would create multiple method classes within the same file, where, like in modeling, we gradually find the families (or components) that need to be created and build them step by step. For example, let's say we need to draw a wall in the code. We could write the code like this:

/ Build a location line for the wall creation

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

    XYZ end = new XYZ(10, 10, 0);

    Line geomLine = Line.CreateBound(start, end);

    // Create a wall using the location line

    Wall.Create(document, geomLine, level.Id, true);

In this code, we first define the start and end coordinates of the wall, then call the Wall.Create() method to create the wall. This is very similar to operations in Revit, reflecting how Revit concepts and operations can be directly mapped to programming logic.

This is a simple logical mapping, which might be a bit abstract. However, when we first encounter Revit while learning C#, we can bring some of the concepts from Revit into our learning process. This helps us gain a deeper understanding of program design and logic.

Switching from a "what-you-see-is-what-you-get" mindset

Many professionals or students in the engineering field, when learning programming, often apply the "what-you-see-is-what-you-get" mindset directly to their programming logic. A significant problem with this approach is that, while it may seem to work fine when testing models and scenes, errors may arise once the program enters a new project or environment. This situation usually occurs when beginners overlook potential issues and take some geometric display details for granted, assuming they are correct.

For example, the following case of stair section annotation:

Many beginners, when starting to write this program, will often structure the logic as follows:

1. Find the position where the designer clicks the left mouse button.
2. Map the 2D plane coordinates to Revit.
3. Place the marker and complete the entire functionality.

This logic usually doesn’t pose a problem in orthogonal views, but discrepancies may arise when dealing with oblique views. While the view we commonly see is two-dimensional, this is because a computer monitor is inherently a two-dimensional surface that can only display projections of objects, not the actual three-dimensional space. In reality, in architectural design and modeling, views are often created by projecting three-dimensional objects onto a plane, which leads to a discrepancy between the two-dimensional display and the three-dimensional space. When operating in an orthogonal view, the coordinate positions are accurate, but in oblique or three-dimensional sectional views, the mapping of coordinates is influenced by changes in the viewing angle, causing errors.

Here is a diagram: the left side shows the front view, and the right side shows the oblique view.

Therefore, in the actual coordinate transformation process, if the program design relies solely on the 2D display on the screen while ignoring the oblique viewing angle, it may result in a mismatch between the user-clicked position and the actual target location, leading to discrepancies.

This is a typical case of being misled by the "what-you-see-is-what-you-get" display mode. Although the view we see on the screen is orthogonal, the offset issue cannot be ignored in three-dimensional space.

Therefore, when designing the program, we not only need to draw on Revit’s operational concepts but also consider the actual 3D situation. We should avoid inferring coordinate transformation logic based solely on the 2D effects visible to the naked eye. This issue often arises in many geometric operations and determinations. To prevent various calculation errors, it is essential to anticipate this situation and take measures to avoid it, in order to write a more robust and accurate program.

Sources:

[1] revitapi.chm