Flip, Mirror, Transform and Transient Graphics

Richard RPThomas108 Thomas continues providing numerous invaluable solutions and explanations in the Revit API discussion forum:

• Flip, mirror and transform
  • Motivation and chilling example
• Transient elements hack
• Temporary incanvas graphics API video
• Shared versus non-shared parameter creation
• Direct PDF export and DA4R

Before diving into these topics, a nice quote of the week from Quincy Larson's freecodecamp newsletter:

There are only two kinds of programming languages: the ones people complain about and the ones nobody uses.

– Bjarne Stroustrup, creator of C++

Flip, Mirror and Transform

A careful analysis by Richard in the thread on GetTransform does not include reflection into the transformation clarifies the effects of rotation and reflection achieved by mirroring and flipping on the BIM element transform:

Question: The Instance.GetTransform method does not include reflection, e.g., the family mirrored property into its transformation. Below a family instance which is mirrored and outputs the equivalent GetTansform values:

Here is the python code:

import sys
import clr
clr.AddReference('ProtoGeometry')
from Autodesk.DesignScript.Geometry import *
data= UnwrapElement(IN[0])

output=[]
for i in data:
    output.append(i.Location.Point)
    output.append(i.GetTransform().BasisX)
    output.append(i.GetTransform().BasisY)
    output.append(i.GetTransform().BasisZ)
    output.append("")
OUT = output

That is expected and intentional in Revit.

However, from a mathematical perspective, it should not be expected. The Wikipedia article on Transformation matrix shows clearly that an element that is reflected around the X axis should have a different transformation matrix:

Can you please share any explanation and why this intentional for Revit?

Answer: I found results that indicate Revit uses a combination of reflection and rotation for the various mirror and flip operations:

One thing that stands out is the difference between horizontal double flip control and mirror command about same axis (noted red). These operations are almost identical apart from the horizontal one that results in opposite facing and handed state. Graphically, it appears the same, but not according to facing/handed orientation.

It has been noted previously that single flip control is more like rotating rather than mirroring (it doesn't result in reflected geometry). We see by transform that it is reflected but facing/handed state is also set to true.

Generally, I think of the facing/handed state as being an internal to the family state, i.e., the internal geometry may be reflected but the family itself isn't (unless it is by transform).

You probably need to look at flip state/rotation and transform to get a definitive idea of the situation. These controls long ago I believe were introduced for doors, which side they are hung and swing direction. As they started being used for other things, the ambiguities crept in, i.e., double negative (same ultimate representation but two definitions for it).

Motivation and Chilling Example

I think everyone has probably fallen foul of these geometric aspects at some point. I recall we had a pile cap with four piles and we marked one of the corners so that we could identify the edges numerically in a clockwise order around this square cap (which had double symmetry). The idea was that we would have a table of parameters which noted the edge distances (edge of cap to edge of pile). What we didn't count on was the fact sometimes people mirrored these caps, so although the corner marker flipped from one side to the other as expected the numbering of edges was no longer clockwise. So, numbered edge distances in table didn't correspond with what was counted clockwise from corner marker.

The question is why would someone mirror a symmetrical object? The answer was that this cap was one of many and there was a line of symmetry across the site. Therefore, they had filled half the site with pile caps and mirrored them for completion (perfectly acceptable). An important lesson from this is that the flip state of the symmetrical object was a hidden feature with subtle implications (when identifying parametric relationships).

Many thanks to Richard for this very helpful explanation!

Transient Elements Hack

Back in 2018, the development team clearly stated that the interesting-looking Document.MakeTransientElements method is 'half-finished' work that should not have been exposed to the public API and will probably be removed again.

It has not been removed yet, though, so Moustafa Khalil and Richard discussed a hacky approach to make it do something at all in the Revit API discussion forum thread on Document.MakeTransientElements, in case you are interested in taking a further look yourself.

Just for the sake of completeness, some other officially supported approaches to display non-BIM-geometry include AVF, DirectContext3D and, new in Revit 2022, the temporary incanvas graphics API (below).

Here are some AVF samples:

• AVF Displays Intersections and Highlights Rooms
• Sphere Creation for AVF and Filtering
• Apollonian Sphere Packing via Web Service and AVF
• RvtFader, AVF, Ray Tracing and Signal Attenuation

I have not explored the direct context 3D functionality myself yet, but here are some bits and pieces on that:

• RevitLookup and DevDays Online API News
• What's New in the Revit 2018 API → DirectContext3D for display of externally managed 3D graphics in Revit
• Revit 2017 and 2018 SDK Samples → DuplicateGraphics
• Transient Graphics

Temporary InCanvas Graphics API Video

Bobby the 3rd Dimension Developer shared a video tutorial on making use of the new Revit 2022 temporary in-canvas graphics functionality in his thread on temporary incanvas graphics image colors

I created a video on the awesome new Temporary InCanvas Graphics API. That raises a question on the image colours. As you can see, they are... off... What are the rules the images, and colours, we can use in this feature? ...

Many thanks to Bobby for this nice introduction!

Unfortunately, his question on the colour mapping currently still remains unresolved.

Shared versus Non-Shared Parameter Creation

Finally, some further useful clarification by Richard on shared versus non-shared parameters, their use and creation in the Revit API discussion forum thread on creating project parameter (not shared parameter).

Direct PDF Export and DA4R

The Revit 2022 API provides built-in direct export to PDF functionality.

This new functionality obviously enables the Forge Design Automation API for Revit 2022 now to support exporting to PDF directly, as documented by my colleague Zhong Wu.

Thanks to Zhong for testing and pointing this out.