Transform
References[StructLayout(LayoutKind.Sequential, Pack = 8, Size = 128)]
[Serializable]
public struct Transform : IComparable<Transform>, IEquatable<Transform>, ICloneable
Represents the values in a 4x4 transform matrix.
This is parallel to C++ ON_Xform.
Constructors
Initializes a new transform matrix with a specified value along the diagonal.
Parameters:
| diagonalValue (double) | Value to assign to all diagonal cells except M33 which is set to 1.0. |
Properties
Gets a new identity transform matrix. An identity matrix defines no transformation.
Tests for an affine transformation. A transformation is affine if it is valid and its last row is [0, 0, 0, 1]. An affine transformation can be broken into a linear transformation and a translation.
Return true if this Transform is the identity transform
Tests for a linear transformation. A transformation is affine if it is valid and its last row is [0, 0, 0, 1]. If in addition its last column is ( 0, 0, 0, 1)^T then it is linear. An affine transformation can be broken into a linear transformation and a translation.
Gets a value indicating whether or not this Transform is a valid matrix. A valid transform matrix is not allowed to have any invalid numbers.
True if matrix is Zero4x4, ZeroTransformation, or some other type of zero. The value xform[3][3] can be anything.
True if all values are 0, except for M33 which is 1.
Gets a value indicating whether or not the Transform is rigid. A rigid transformation can be broken into a proper rotation and a translation, while an isometry transformation could also include a reflection.
Gets a value indicating whether or not the Transform maintains similarity. The easiest way to think of Similarity is that any circle, when transformed, remains a circle. Whereas a non-similarity Transform deforms circles into ellipses.
Gets an XForm filled with RhinoMath.UnsetValue.
Indexers
this[]
#Gets or sets the matrix value at the given row and column indices.
Methods
public void Affineize()
Replaces the last row with (0 0 0 1), discarding any perspective part of this transform
Gets a change of basis transformation. The change of basis transformation is not the same as the rotation transformation that rotates one orthonormal frame to another. If you have geometry defined with respect to planes, this method takes two planes and computes the transformation to change coordinates from one plane to another.
Remarks: Change of basis transformations and rotation transformations are often confused. This is a change of basis transformation. If Q = P0 + a0*X0 + b0*Y0 + c0*Z0 = P1 + a1*X1 + b1*Y1 + c1*Z1, then this transform will map the coordinates (a0,b0,c0) to (a1,b1,c1).
Parameters:
| plane0 (Plane) | Coordinate system in which the geometry is currently described. |
| plane1 (Plane) | Target coordinate system in which we want the geometry to be described. |
Returns: A change of basis transformation if success, Unset on failure.
public static Transform ChangeBasis(Point3d P0, Vector3d X0, Vector3d Y0, Vector3d Z0, Point3d P1, Vector3d X1, Vector3d Y1, Vector3d Z1)
Gets a change of basis transformation. The change of basis transformation is not the same as the rotation transformation that rotates one orthonormal frame to another.
Remarks: Change of basis transformations and rotation transformations are often confused. This is a change of basis transformation. If Q = P0 + a0*X0 + b0*Y0 + c0*Z0 = P1 + a1*X1 + b1*Y1 + c1*Z1, then this transform will map the point (a0,b0,c0) to (a1,b1,c1).
Parameters:
| P0 (Point3d) | Initial center. |
| X0 (Vector3d) | Initial basis X (can be any 3d basis). |
| Y0 (Vector3d) | Initial basis Y (can be any 3d basis). |
| Z0 (Vector3d) | Initial basis Z (can be any 3d basis). |
| P1 (Point3d) | Final center. |
| X1 (Vector3d) | Final basis X (can be any 3d basis). |
| Y1 (Vector3d) | Final basis Y (can be any 3d basis). |
| Z1 (Vector3d) | Final basis Z (can be any 3d basis). |
Returns: A change of basis transformation if success, Unset on failure.
public static Transform ChangeBasis(Vector3d X0, Vector3d Y0, Vector3d Z0, Vector3d X1, Vector3d Y1, Vector3d Z1)
Gets a change of basis transformation. The change of basis transformation is not the same as the rotation transformation that rotates one orthonormal frame to another.
Remarks: Change of basis transformations and rotation transformations are often confused. This is a change of basis transformation. If Q = a0*X0 + b0*Y0 + c0*Z0 = a1*X1 + b1*Y1 + c1*Z1, then this transform will map the point (a0,b0,c0) to (a1,b1,c1).
Parameters:
| X0 (Vector3d) | Initial basis X (can be any 3d basis). |
| Y0 (Vector3d) | Initial basis Y (can be any 3d basis). |
| Z0 (Vector3d) | Initial basis Z (can be any 3d basis). |
| X1 (Vector3d) | Final basis X (can be any 3d basis). |
| Y1 (Vector3d) | Final basis Y (can be any 3d basis). |
| Z1 (Vector3d) | Final basis Z (can be any 3d basis). |
Returns: A change of basis transformation if success, Unset on failure.
Returns a deep copy of the transform. For languages that treat structures as value types, this can be accomplished by a simple assignment.
Returns: A deep copy of this data structure.
Compares this transform with another transform.
M33 has highest value, then M32, etc..
Parameters:
| other (Transform) | Another transform. |
Returns: -1 if this < other; 0 if both are equal; 1 otherwise.
Decomposes an affine transformation. A transformation is affine if it is valid and its last row is [0, 0, 0, 1]. An affine transformation can be broken into a linear transformation and a translation. Note, a perspective transformation is not affine.
Remarks: If X.DecomposeAffine(L, T) is true then X == L* Translation(T). DecomposeAffine(L, T) may fail for affine transformations if L is not invertible, and is more computationally expensive then X.DecomposeAffine(T, L).
Parameters:
| linear (out Transform) | Linear transformation. |
| translation (out Vector3d) | Translation vector. |
Returns: True if successful decomposition.
Decomposes an affine transformation. A transformation is affine if it is valid and its last row is [0, 0, 0, 1]. An affine transformation can be broken into a linear transformation and a translation. Note, a perspective transformation is not affine.
Remarks: If X.DecomposeAffine(T, L) is true then X == Translation(T)*L. DecomposeAffine(T,L) succeeds for all affine transformations and is a simple copying of values.
Parameters:
| translation (out Vector3d) | Translation vector. |
| linear (out Transform) | Linear transformation. |
Returns: True if successful decomposition.
[ConstOperation]
public bool DecomposeAffine(out Vector3d translation, out Transform rotation, out Transform orthogonal, out Vector3d diagonal)
An affine transformation can be decomposed into a Symmetric, Rotation and Translation. Then the Symmetric component may be further decomposed as non-uniform scale in an orthonormal coordinate system.
[ConstOperation]
public TransformRigidType DecomposeRigid(out Vector3d translation, out Transform rotation, double tolerance)
Decomposes a rigid transformation. The transformation must be affine.
Remarks: If X.DecomposeRigid(T, R) is 1, then X ~ Translation(T)*R. If X.DecomposeRigid(T, R) is -1, then X ~ Transform(-1) * Translation(T)*R. DecomposeRigid will find the closest rotation to the linear part of this transformation.
Parameters:
| translation (out Vector3d) | Translation vector. |
| rotation (out Transform) | Proper rotation transformation, where R*Transpose(R)=I and det(R)=1. |
| tolerance (double) | The evaluation tolerance. |
Returns: The rigid type.
[ConstOperation]
public TransformSimilarityType DecomposeSimilarity(out Vector3d translation, out double dilation, out Transform rotation, double tolerance)
Decomposes a similarity transformation. The transformation must be affine. A similarity transformation can be broken into a sequence of a dilation, translation, rotation, and a reflection.
Remarks: If X.DecomposeSimilarity(T, d, R, tol) !=0 then X ~ Translation(T)*Diagonal(d)*R note when d gt;0 the transformation is orientation preserving. If dilation lt; 0 then Diagonal(dilation) is actually a reflection combined with a true dilation, or Diagonal(dilation) = Diagonal(-1) * Diagonal(|diagonal|).
Parameters:
| translation (out Vector3d) | Translation vector. |
| dilation (out double) | Dilation, where dilation lt; 0 if this is an orientation reversing similarity. |
| rotation (out Transform) | A proper rotation transformation, where R*Transpose(R)=I and Determinant(R)=1. |
| tolerance (double) | The evaluation tolerance. |
Returns: The similarity type.
A Symmetric linear transformation can be decomposed A = Q * Diag * Q ^ T, where Diag is a diagonal transformation. Diag[i][i] is an eigenvalue of A and the i-th column of Q is a corresponding unit length eigenvector. Note, this transformation must be Linear and Symmetric.
Remarks: If success, this== Q*Diagonal(diagonal) * QT, where QT == Q.Transpose(). If L.IsLinear and LT==L.Transpose then LT*L is symmetric and is a common source of symmetric transformations.
Parameters:
| matrix (out Transform) | An orthonormal matrix of eigenvectors (Q). |
| diagonal (out Vector3d) | A vector of eigenvalues. |
Returns: true if successful, false otherwise.
[ConstOperation]
public void DecomposeTextureMapping(out Vector3d offset, out Vector3d repeat, out Vector3d rotation)
Decomposition of a uvw transform into components
Constructs a new transformation with diagonal (d0,d1,d2,1.0).
Constructs a new transformation with diagonal (d0,d1,d2,1.0).
Parameters:
| diagonal (Vector3d) | The diagonal values. |
Returns: A transformation with diagonal (d0,d1,d2,1.0).
Equals
#Determines if another object is a transform and its value equals this transform value.
Parameters:
| obj (object) | Another object. |
Returns: true if obj is a transform and has the same value as this transform; otherwise, false.
Overrides: ValueType.Equals
Determines if another transform equals this transform value.
Parameters:
| other (Transform) | Another transform. |
Returns: true if other has the same value as this transform; otherwise, false.
Find the Euler angles for a rotation transformation.
Remarks: Note, alpha and gamma are in the range (-pi, pi] while beta in the range [0, pi]
Parameters:
| alpha (out double) | Angle of rotation, in radians, about the Z axis. |
| beta (out double) | Angle of rotation, in radians, about the Y axis. |
| gamma (out double) | Angle of rotation, in radians, about the Z axis. |
Returns: If true, then this = RotationZYZ(alpha, beta, gamma) = R_z(alpha) * R_y(beta) * R_z(gamma) where R_*(angle) is rotation of angle radians about the corresponding *-world coordinate axis. If false, then this is not a rotation.
GetHashCode
#Gets a non-unique hashing code for this transform.
Returns: A number that can be used to hash this transform in a dictionary.
Overrides: ValueType.GetHashCode
If this transform is a proper rotation, then find the equivalent quaternion.
Parameters:
| quaternion (out Quaternion) | Quaternion that represents this rotation transformation. |
Returns: true if this transform is a proper rotation, false otherwise.
Find the Tait-Byran angles (also loosely called Euler angles) for a rotation transformation.
Parameters:
| yaw (out double) | Angle of rotation, in radians, about the Z axis. |
| pitch (out double) | Angle of rotation, in radians, about the Y axis. |
| roll (out double) | Angle of rotation, in radians, about the X axis. |
Returns: If true, then this = RotationZYX(yaw, pitch, roll) = R_z(yaw) * R_y(pitch) * R_x(roll) where R_*(angle) is rotation of angle radians about the corresponding world coordinate axis. If false, then this is not a rotation.
Gets a value indicating whether or not the Transform is rigid. A rigid transformation can be broken into a proper rotation and a translation, while an isometry transformation could also include a reflection.
Parameters:
| tolerance (double) | The evaluation tolerance. |
Returns: The rigid type.
Gets a value indicating whether or not the Transform maintains similarity. A similarity transformation can be broken into a sequence of a dilation, translation, rotation, and a reflection.
Parameters:
| tolerance (double) | The evaluation tolerance. |
Returns: The similarity type.
Determines if this transform is uniformly scaled - that is, a similarity transformation that scales all directions equally and preserves angles, mapping circles to circles. This includes pure rotations, translations and mirroring.
Returns: True if uniformly scaled, false otherwise.
True if all values are 0 within tolerance, except for M33 which is exactly 1.
Parameters:
| zeroTolerance (double) | The tolerance for 0 elements. |
Returns: True if the transformation matrix is ON_Xform::ZeroTransformation, with xform[3][3] equal to 1: 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 An element x of the matrix is "zero" if fabs(x) ≤ zeroTolerance. IsZeroTransformation is the same as IsZeroTransformationWithTolerance(0.0)
[EditorBrowsable(EditorBrowsableState.Never)]
[ConstOperation]
public bool IsZeroTransformaton(double zeroTolerance)
obsoleteThis method remains with a typo in its name for backwards compatibility. Use IsZeroTransformationWithTolerance instead.
True if all values are 0 within tolerance, except for M33 which is exactly 1.
Parameters:
| zeroTolerance (double) | The zero tolerance. |
Returns: Returns true if all values are 0 within tolerance, except for M33 which is exactly 1.
public void Linearize()
Affinitize() and replaces the last column with (0 0 0 1)^T, discarding any translation part of this transform.
Constructs a new Mirror transformation.
Parameters:
| mirrorPlane (Plane) | Plane that defines the mirror orientation and position. |
Returns: A transformation matrix which mirrors geometry in a specified plane.
Create mirror transformation matrix The mirror transform maps a point Q to Q - (2*(Q-P)oN)*N, where P = pointOnMirrorPlane and N = normalToMirrorPlane.
Multiplies (combines) two transformations.
This is the same as the * operator between two transformations.
Force the linear part of this transformation to be a rotation (or a rotation with reflection). Use DecomposeRigid(T,R) to find the nearest rotation.
Parameters:
| tolerance (double) | The evaluation tolerance |
Returns: true if successful, false otherwise.
Constructs a projection transformation.
Parameters:
| plane (Plane) | Plane onto which everything will be perpendicularly projected. |
Returns: A transformation matrix which projects geometry onto a specified plane.
Create a rotation transformation that orients plane0 to plane1. If you want to orient objects from one plane to another, use this form of transformation.
Construct a projection onto a plane along a specific direction.
Constructs a new rotation transformation with specified angle and rotation center. The axis of rotation is Vector3d.ZAxis.
public static Transform Rotation(double angleRadians, Vector3d rotationAxis, Point3d rotationCenter)
Constructs a new rotation transformation with specified angle, rotation center and rotation axis.
public static Transform Rotation(double sinAngle, double cosAngle, Vector3d rotationAxis, Point3d rotationCenter)
Constructs a new rotation transformation with specified angle, rotation center and rotation axis.
public static Transform Rotation(Vector3d startDirection, Vector3d endDirection, Point3d rotationCenter)
Constructs a new rotation transformation with start and end directions and rotation center.
public static Transform Rotation(Vector3d x0, Vector3d y0, Vector3d z0, Vector3d x1, Vector3d y1, Vector3d z1)
Constructs a transformation that maps X0 to X1, Y0 to Y1, Z0 to Z1. The frames should be right hand orthonormal frames (unit vectors with Z = X x Y). The resulting rotation fixes the origin (0,0,0), maps initial X to final X, initial Y to final Y, and initial Z to final Z.
Create rotation transformation From Tait-Byran angles (also loosely known as Euler angles).
Remarks: RotationZYX(yaw, pitch, roll) = R_z(yaw) * R_y(pitch) * R_x(roll) where R_*(angle) is rotation of angle radians about the corresponding world coordinate axis.
Parameters:
| yaw (double) | Angle, in radians, to rotate about the Z axis. |
| pitch (double) | Angle, in radians, to rotate about the Y axis. |
| roll (double) | Angle, in radians, to rotate about the X axis. |
Returns: A transform matrix from Tait-Byran angles.
Create rotation transformation From Euler angles.
Remarks: RotationZYZ(alpha, beta, gamma) = R_z(alpha) * R_y(beta) * R_z(gamma) where R_*(angle) is rotation of angle radians about the corresponding *-world coordinate axis. Note, alpha and gamma are in the range (-pi, pi] while beta in the range [0, pi]
Parameters:
| alpha (double) | Angle, in radians, to rotate about the Z axis. |
| beta (double) | Angle, in radians, to rotate about the Y axis. |
| gamma (double) | Angle, in radians, to rotate about the X axis. |
Returns: A transform matrix from Euler angles.
public static Transform Scale(Plane plane, double xScaleFactor, double yScaleFactor, double zScaleFactor)
Constructs a new non-uniform scaling transformation with a specified scaling anchor point.
Parameters:
| plane (Plane) | Defines the center and orientation of the scaling operation. |
| xScaleFactor (double) | Scaling factor along the anchor plane X-Axis direction. |
| yScaleFactor (double) | Scaling factor along the anchor plane Y-Axis direction. |
| zScaleFactor (double) | Scaling factor along the anchor plane Z-Axis direction. |
Returns: A transformation matrix which scales geometry non-uniformly.
Constructs a new uniform scaling transformation with a specified scaling anchor point.
Constructs a Shear transformation.
Construct a UVW Transform from components.
Return the matrix as a linear array of 16 double values.
Parameters:
| rowDominant (bool) | If true, returns { M00, M01, M02...}. If false, returns { M00, M10, M20...}. |
Returns: An array of 16 doubles.
Return the matrix as a linear array of 16 float values.
Parameters:
| rowDominant (bool) | If true, returns { M00, M01, M02...}. If false, returns { M00, M10, M20...}. |
Returns: An array of 16 floats.
ToString
#Returns a string representation of this transform.
Returns: A textual representation.
Overrides: ValueType.ToString
Computes a new bounding box that is the smallest axis aligned bounding box that contains the transformed result of its 8 original corner points.
Parameters:
| bbox (BoundingBox) |
Returns: A new bounding box.
Given a list, an array or any enumerable set of points, computes a new array of transformed points.
Parameters:
| points (IEnumerable<Point3d>) | A list, an array or any enumerable set of points to be left untouched and copied. |
Returns: A new array.
Constructs a new translation (move) transformation. Right column is (dx, dy, dz, 1.0).
Parameters:
| dx (double) | Distance to translate (move) geometry along the world X axis. |
| dy (double) | Distance to translate (move) geometry along the world Y axis. |
| dz (double) | Distance to translate (move) geometry along the world Z axis. |
Returns: A transform matrix which moves geometry with the specified distances.
Constructs a new translation (move) transformation.
Parameters:
| motion (Vector3d) | Translation (motion) vector. |
Returns: A transform matrix which moves geometry along the motion vector.
Attempts to get the inverse transform of this transform.
Parameters:
| inverseTransform (out Transform) | The inverse transform. This out reference will be assigned during this call. |
Returns: true on success. If false is returned and this Transform is Invalid, inserveTransform will be set to this Transform. If false is returned and this Transform is Valid, inverseTransform will be set to a pseudo inverse.
Operators
| Operation | Result | Description | ||
|---|---|---|---|---|
| Transform | == | Transform | bool | Determines if two transformations are equal in value. |
| Transform | != | Transform | bool | Determines if two transformations are different in value. |
| Transform | * | Point3d | Point3d | Multiplies a transformation by a point and gets a new point. |
| Transform | * | Transform | Transform | Multiplies (combines) two transformations. |
| Transform | * | Vector3d | Vector3d | Multiplies a transformation by a vector and gets a new vector. |