{"id":1,"date":"2023-08-15T13:54:14","date_gmt":"2023-08-15T11:54:14","guid":{"rendered":"http:\/\/easyrevitapi.com\/?p=1"},"modified":"2023-10-22T14:24:32","modified_gmt":"2023-10-22T12:24:32","slug":"revit-transformations-made-easy","status":"publish","type":"post","link":"https:\/\/easyrevitapi.com\/index.php\/2023\/08\/15\/revit-transformations-made-easy\/","title":{"rendered":"Revit transformations made easy"},"content":{"rendered":"\n

<\/p>\n\n\n\n

Although Revit transformations may appear as a complex topic at first sight, they focus on simple and elementary geometric concepts employed programmatically. Essentially, they serve as methods for relocating a point or an object in the 3D space, based on a predefined logic.<\/p>\n\n\n\n

Transformations are indeed tools that give us more freedom when programming for Revit. They help with tasks such as comparing geometries, positioning them to one another, or determining their locations within a new coordinate system.<\/p>\n\n\n\n

We will explain these geometry concepts, and how the Revit API allows us to use them according to the object-oriented paradigm. We will focus on two transformations : translations and rotations. The given code examples are written in C#.<\/p>\n\n\n\n

Translations<\/h4>\n\n\n\n

Translations involve moving a point using a vector. This point moves based on the vector\u2019s direction and length. Let\u2019s see how we can do this programmatically using the Revit API :<\/p>\n\n\n\n

<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

<\/p>\n\n\n\n

\n
\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
public<\/span> <\/span>class<\/span> <\/span>Transformations<\/span><\/span>\n    {<\/span><\/span>\n        <\/span>public<\/span> <\/span>void<\/span> <\/span>MakeTranslation<\/span>() <\/span><\/span>\n        {<\/span><\/span>\n            <\/span>XYZ<\/span> pointA <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>10<\/span>, <\/span>10<\/span>, <\/span>0<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> translationVector <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>5<\/span>,<\/span>10<\/span>,<\/span>0<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>Transform<\/span> transform_Translation <\/span>=<\/span> <\/span>Transform<\/span>.<\/span>CreateTranslation<\/span>(<\/span>translationVector<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> pointA_Translated <\/span>=<\/span> <\/span>transform_Translation<\/span>.<\/span>OfPoint<\/span>(<\/span>pointA<\/span>);                      <\/span><\/span>\n            \/\/ pointA_Translated coordinates will be : 15,20,0<\/span><\/span>\n        }<\/span><\/span>\n    }<\/span><\/span><\/code><\/pre><\/div>\n<\/div>\n<\/div>\n\n\n\n
<\/p>\n\n\n\n
Both pointA<\/strong> and translationVector<\/strong> are of the XYZ<\/mark> type. In the Revit API, an XYZ <\/mark>type represents both a point in the 3D space and the vector going from the origin (0,0,0)<\/mark> to that point.<\/p>\n\n\n\n
We will then create a Transform<\/mark> object called transform_Translation<\/strong>, holding the instructions for moving pointA.<\/strong> Instead of using a constructor, new Transform<\/mark> objects may be instantiated using static methods. For our purpose, we\u2019ll use Transform.CreateTranslation()<\/mark> and provide the translationVector<\/strong> as an argument.<\/p>\n\n\n\n
When inspecting our newly instantiated transform_Translation<\/strong> object using Visual Studio, we get the following information:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
The first highlighted field IsTranslation<\/span> confirms the transformation type. The field Origin<\/span> represents the translation Vector as an XYZ<\/mark> type.<\/p>\n\n\n\n
Finally, we apply the intended transformation to pointA<\/strong> using the transform_Translation<\/strong> object. The transform_Translation.OfPoint()<\/mark> method applies the transformation to its argument, translating the pointA<\/strong> and returning a new XYZ<\/mark> object at the coordinates (15,20,0)<\/mark>.<\/p>\n\n\n\n
Rotations<\/h4>\n\n\n\n
Rotations involve moving a point along a defined circle and following a rotation angle. As in the previous example, this transformation could be done programmatically. We will discuss two cases: Rotating around the coordinate system’s origin, and rotating around another specific point.

<\/p>\n\n\n\n
Rotations around the coordinate system\u2019s origin

<\/h5>\n\n\n\n
<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
public<\/span> <\/span>class<\/span> <\/span>Transformations<\/span><\/span>\n    {<\/span><\/span>\n        <\/span>public<\/span> <\/span>void<\/span> <\/span>MakeRotation<\/span>()<\/span><\/span>\n        {<\/span><\/span>\n            <\/span>XYZ<\/span> pointA <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>10<\/span>, <\/span>10<\/span>, <\/span>0<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> rotationAxis <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>0<\/span>, <\/span>0<\/span>, <\/span>1<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>double<\/span> rotationAngle <\/span>=<\/span> <\/span>1.5707963268<\/span>;<\/span><\/span>\n            \/\/ The angle unit is in Radian, and corresponds to 90 degrees.<\/span><\/span>\n<\/span>\n            <\/span>Transform<\/span> transform_Rotation <\/span>=<\/span> <\/span>Transform<\/span>.<\/span>CreateRotation<\/span>(<\/span>rotationAxis<\/span>, <\/span>rotationAngle<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> pointA_Rotated <\/span>=<\/span> <\/span>transform_Rotation<\/span>.<\/span>OfPoint<\/span>(<\/span>pointA<\/span>);<\/span><\/span>\n            \/\/ pointA_Rotated coordinates will be : -10,10,0<\/span><\/span>\n        }<\/span><\/span>\n    }<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
<\/p>\n\n\n\n
After defining pointA<\/strong>, we need to specify which plane the rotation will take place on. In this case, we’re opting for the horizontal plane.<\/p>\n\n\n\n
One way of specifying the chosen plane is by defining its normal. In our case, the plane\u2019s normal is a perfectly vertical vector, starting from the origin (0,0,0)<\/mark> and heading upwards to point (0,0,1)<\/mark>. Let\u2019s call this vector rotationAxis<\/strong>.<\/p>\n\n\n\n
rotationAngle<\/strong> is defined in Radian unit. If the angle\u2019s value is positive, the rotation goes counter-clockwise; if negative, it goes clockwise. However, please note that this rule is reversed if rotationAxis<\/strong> points downwards to the point (0,0,-1)<\/mark><\/span>.<\/p>\n\n\n\n
Similar to the translation example, we will use a static method to instantiate the transform_Rotation<\/strong> object, holding the logic to rotate pointA.<\/strong> To rotate around the origin of the coordinate system at point (0,0,0)<\/mark>, we\u2019ll use Transform.CreateRotation()<\/mark> method. This method takes two arguments : rotationAxis<\/strong> and rotationAngle.<\/strong><\/p>\n\n\n\n
When inspecting our newly instantiated transform_Rotation<\/strong> object using Visual Studio, we get the following information:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
This transformation is obviously not a translation, as shown by the IsTranslation<\/span> field\u2019s value. However, what is interesting here is the value of the BasisX<\/span> and BasisY<\/span> fields.<\/p>\n\n\n\n
These values indicate the rotation angle of the recently instantiated transform_Rotation<\/strong> object. They represent the coordinate system axes as if they were rotated by this angle. The following scheme will help us better understand this principle :<\/p>\n\n\n\n
<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
Finally, we implement the rotation on pointA<\/strong> using the transform_Rotation.OfPoint()<\/mark> method. This returns a new XYZ<\/mark> object representing the pointA_Rotated<\/strong> at coordinates (-10,10,0)<\/mark>.<\/p>\n\n\n\n

<\/p>\n\n\n\n
Rotations around a specific point<\/h5>\n\n\n\n

<\/p>\n\n\n\n
<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
public<\/span> <\/span>class<\/span> <\/span>Transformations<\/span><\/span>\n    {<\/span><\/span>\n        <\/span>public<\/span> <\/span>static<\/span> <\/span>void<\/span> <\/span>MakeRotationAtPoint<\/span>()<\/span><\/span>\n        {<\/span><\/span>\n            <\/span>XYZ<\/span> pointA <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>30<\/span>,<\/span>30<\/span>,<\/span>0<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> pointO <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>20<\/span>,<\/span>20<\/span>,<\/span>0<\/span>); <\/span><\/span>\n            <\/span><\/span>\n            <\/span>XYZ<\/span> rotationAxis <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>0<\/span>, <\/span>0<\/span>, <\/span>1<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>double<\/span> rotationAngle <\/span>=<\/span> <\/span>1.5707963268<\/span>;<\/span><\/span>\n            \/\/ The angle unit is in Radian, and corresponds to 90 degrees.<\/span><\/span>\n<\/span>\n            <\/span>Transform<\/span> transform_Rotation <\/span>=<\/span> <\/span>Transform<\/span>.<\/span>CreateRotationAtPoint<\/span>(<\/span>rotationAxis<\/span>, <\/span>rotationAngle<\/span>, <\/span>pointO<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> pointA_Rotated <\/span>=<\/span> <\/span>transform_Rotation<\/span>.<\/span>OfPoint<\/span>(<\/span>pointA<\/span>);<\/span><\/span>\n            \/\/ pointA_Rotated coordinates will be : 10,30,0<\/span><\/span>\n        }<\/span><\/span>\n    }<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
<\/p>\n\n\n\n
In this example, pointA<\/strong> will rotate around pointO.<\/strong> Therefore, we\u2019ll employ another static method to create our Transform object : Transform.CreateRotationAtPoint()<\/mark>, taking an additional argument : the rotation\u2019s origin. For the rest, the code remains very similar to the previous case where the rotation was centered around the origin of the coordinate system.<\/p>\n\n\n\n
Once we apply the transform_Rotation.OfPoint()<\/mark> method. The result is a new XYZ<\/mark> object representing the pointA_Rotated<\/strong> at coordinates (10,30,0)<\/mark>.<\/p>\n\n\n\n
<\/p>\n\n\n\n
Translations + Rotations<\/h4>\n\n\n\n
As we saw previously, a Transform <\/mark>object in Revit can hold the instructions for translating or rotating a point. However, these objects can also blend multiple transformations together.<\/p>\n\n\n\n
Transform <\/mark>objects describing multiple transformations are quite common when working with some Revit objects. For example, each FamilyInstance <\/mark>object contains a Transform <\/mark>object that informs us about the family instance position in space. Meaning : how far it has been translated starting from the coordinate system\u2019s origin, and to which angle it has been rotated in relation to the coordinate system\u2019s axes.<\/p>\n\n\n\n
Let\u2019s see how the previous examples of translation and rotation operations could be combined to form one single Transform <\/mark>object and used to move a specific point.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
public<\/span> <\/span>static<\/span> <\/span>void<\/span> <\/span>MakeRotationAtPointPlusTranslation<\/span>()<\/span><\/span>\n        {<\/span><\/span>\n            <\/span>XYZ<\/span> pointA <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>30<\/span>, <\/span>30<\/span>, <\/span>0<\/span>);<\/span><\/span>\n<\/span>\n<\/span>\n            \/\/ Defining the rotation transformation <\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> pointO <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>20<\/span>, <\/span>20<\/span>, <\/span>0<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> rotationAxis <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>0<\/span>, <\/span>0<\/span>, <\/span>1<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>double<\/span> rotationAngle <\/span>=<\/span> <\/span>1.5707963268<\/span>;<\/span><\/span>\n<\/span>\n            <\/span>Transform<\/span> transform_Rotation <\/span>=<\/span> <\/span>Transform<\/span>.<\/span>CreateRotationAtPoint<\/span>(<\/span>rotationAxis<\/span>, <\/span>rotationAngle<\/span>, <\/span>pointO<\/span>);<\/span><\/span>\n<\/span>\n<\/span>\n            \/\/ Defining the translation transformation <\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> translationVector <\/span>=<\/span> <\/span>new<\/span> <\/span>XYZ<\/span>(<\/span>5<\/span>, <\/span>10<\/span>, <\/span>0<\/span>);<\/span><\/span>\n<\/span>\n            <\/span>Transform<\/span> transform_Translation <\/span>=<\/span> <\/span>Transform<\/span>.<\/span>CreateTranslation<\/span>(<\/span>translationVector<\/span>);<\/span><\/span>\n<\/span>\n<\/span>\n            \/\/ Combining the rotation and translation transformations <\/span><\/span>\n<\/span>\n            <\/span>Transform<\/span> transform_RotationPlusTranslation <\/span>=<\/span> <\/span>transform_Translation<\/span>.<\/span>Multiply<\/span>(<\/span>transform_Rotation<\/span>);<\/span><\/span>\n<\/span>\n<\/span>\n            \/\/ Applying the combined transformation on the point A<\/span><\/span>\n<\/span>\n            <\/span>XYZ<\/span> pointA_RotatedAndTranslated <\/span>=<\/span> <\/span>transform_RotationPlusTranslation<\/span>.<\/span>OfPoint<\/span>(<\/span>pointA<\/span>);<\/span><\/span>\n            \/\/ pointA_RotatedAndTranslated coordinates are 15,40,0<\/span><\/span>\n        }<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Combining two transformation has been made possible using the Transform.Multiply()<\/mark> method. It is important to note that the order in which the two transformations are multiplied determines which of them will execute first. The transformation passed as an argument to the Multiply()<\/mark> method executes first ( here : transform_Rotation<\/strong> ), and the one calling the method executes last (here : transform_Translation<\/strong> )<\/p>\n\n\n\n
In summary : PointA<\/strong> is first rotated to coordinates (10,30,0)<\/mark>, then it is translated using the translationVector<\/strong> from that position to point (15,40,0)<\/mark>.<\/p>\n\n\n\n
Conclusion<\/h4>\n\n\n\n
As we\u2019ve seen, Revit Transformations are quite simple concepts to catch. Using them will give you greater flexibility when handling Revit objects, and a better understanding of the transition between the global coordinate system and an object’s local coordinate system.<\/p>\n\n\n\n
My advice is to really get familiar with the Transform <\/mark>objects : do not hesitate to inspect their properties each time you come across them. Don’t hesitate to examine their properties whenever you encounter them. They’ll provide insights into how Revit objects have been positioned and arranged within the 3D space.\u201d<\/p>\n","protected":false},"excerpt":{"rendered":"
Although Revit transformations may appear as a complex topic at first sight, they focus on simple and elementary geometric concepts employed programmatically. Essentially, they serve as methods for relocating a point or an object in the 3D space, based on a predefined logic. Transformations are indeed tools that give us more freedom when programming for […]<\/p>\n","protected":false},"author":1,"featured_media":1027,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[8],"tags":[],"class_list":["post-1","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-geometry"],"blocksy_meta":[],"_links":{"self":[{"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/posts\/1","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/comments?post=1"}],"version-history":[{"count":36,"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/posts\/1\/revisions"}],"predecessor-version":[{"id":1246,"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/posts\/1\/revisions\/1246"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/media\/1027"}],"wp:attachment":[{"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/media?parent=1"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/categories?post=1"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/easyrevitapi.com\/index.php\/wp-json\/wp\/v2\/tags?post=1"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}