Transformation Matrix in Revit API

In the world of Revit, where elements dance in 3D space, the transform matrix plays a critical role as the choreographer. It's a mathematical marvel that defines an element's location and orientation within the model's coordinate system. In this article, BIMCAD Vietnam will help you understand this matrix empowers so that you can precisely manipulate elements using Revit API, bringing your automation dreams to life.

Understanding Transformation Matrices

A transformation matrix is a mathematical representation that encapsulates the translation, rotation, and scaling of an element. Transforms are limited to 3x4 transformations in the Revit application, transforming an object's place in the model space relative to the rest of the model space and other objects. The transforms are built from the position and orientation in the model space. The matrix formed by the four values is as follows:

Imagine you have a box. The transform matrix tells you exactly where that box sits and how it's tilted. Key components of a Transformation Matrix:

• Translation: How far the box is shifted from the origin (0, 0, 0) in X, Y, and Z directions. Think of it as picking up the box and moving it around.
• Rotation: How the box is twisted around its X, Y, and Z axes. Picture yourself rotating the box to different angles.
• Scaling: This component determines the element's size relative to its original dimensions.

Accessing Family Instance Transforms

Revit API provides the Transform class, your gateway to the matrix. You can access this class through various element properties, like GetTransform() or GetTotalTransform() methods. This method retrieves the complete transformation, including both location and orientation. 

Three direction Vectors (BasisX, BasisY and BasisZ properties) and Origin point provide all of the transform information:

• BasisX, BasisY, BasisZ: These properties act like arrows, pointing in the direction of the element's X, Y, and Z axes after transformation. Think of them as the box's new "up," "right," and "forward" directions.
• Origin: This property tells you the XYZ coordinates of the box's center point after the transformation has been applied.

Transform class properties and methods are identified in the following sections.

Identity

The identity transformation.

CreateReflection()

Reflect a specified plane.

As the above picture shows, one wall is mirrored by a reference plane. The CreateReflection() method needs the geometry plane information for the reference plane.

CreateRotation() and CreateRotationAtPoint()

Rotate by a specified angle around a specified axis at (0,0,0) or at a specified point.

CreateTranslation()

Translate by a specified vector. Given a vector XYZ data, a transformation is created as follow:

Determinant

Transformation determinant.

HasReflection

This is a Boolean value that indicates whether the transformation produces a reflection.

Scale

A value that represents the transformation scale.

Inverse

An inverse transformation. Transformation matrix A is invertible if a transformation matrix B exists such that A*B = B*A = I (identity).

IsIdentity

Boolean value that indicates whether this transformation is an identity.

IsTranslation

Boolean value that indicates whether this transformation is a translation.

IsConformal

The boolean value that indicates whether this transformation is conformal.

Multiply

Multiplies a transformation by a specified transformation and returns the result.

Operator* - Multiplies two specified transforms.

ScaleBasis

Scales the basis vectors and returns the result.

ScaleBasisAndOrigin

Scales the basis vectors and the transformation origin returns the result.

OfPoint

Applies the transformation to the point. The Origin property is used.

OfVector

Applies the transform to the vector. The Origin property is not used.

AlmostEqual

Compares two transformations within the tolerance (1.0e-09). 

Common Transformation Operations

// get location curve from selected element which is structural framing category

FamilyInstance beamInst = selectedElem as FamilyInstance;

LocationCurve locCurve = beamInst.Location as LocationCurve;

1. Translation:

// translates the element by 1000 units in the X direction, 5000 units in the Y direction, and 0 units in the Z direction.

XYZ translationVector = new XYZ(1000, 5000, 0);
Transform translationTransform = Transform.CreateTranslation(translationVector);
locCurve.Curve = locCurve.Curve.CreateTransformed(translationTransform);

2. Rotation:

// This code rotates the element by 45 degrees around the Z-axis at origin (0,0,0)

double rotationAngle = Math.PI / 4; // 45 degrees

Transform rotationTransform = Transform.CreateRotationAtPoint(XYZ.BasisZ, rotationAngle, XYZ.Zero);

locCurve.Curve = locCurve.Curve.CreateTransformed(rotationTransform);

3. Combining Transformations:

You can combine multiple transformations by multiplying them together. For example, to translate and rotate an element:

Transform totalTransform = translationTransform.Multiply(rotationTransform);

locCurve.Curve = locCurve.Curve.CreateTransformed(totalTransform);

Summary

Understanding transform matrices unlocks a world of possibilities in Revit API. You can:

• Precisely position elements: Want to place a family instance at a specific location with a particular orientation? The transform matrix is your key.
• Align elements: Need to ensure elements are perfectly aligned with each other? Use the transformation information to achieve this.

Develop custom tools: Build powerful tools for manipulating elements based on complex criteria using the transform matrix as your guide.