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.
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:
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:
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).
// get location curve from selected element which is structural framing category
FamilyInstance beamInst = selectedElem as FamilyInstance;
LocationCurve locCurve = beamInst.Location as LocationCurve;
// 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);
// 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);
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);
Understanding transform matrices unlocks a world of possibilities in Revit API. You can:
Develop custom tools: Build powerful tools for manipulating elements based on complex criteria using the transform matrix as your guide.