1. TRANSFORMATIONS

2. Transformations What is this section going to cover?
Different types of Transformations
Implementation of Transformations in MicroStation
Constructing Transformation Matrices
The Current Transform

3. What are Transformations?
Analytical equations to manipulate points or elements in 3D space
Stored in matrix form
Used for generating or modifying elements, displaying dynamics, or orientating views

4. Types of Transformations
Translation
Scaling
Rotation
Other...

5. Types of Transformations
Translation
Translation is the movement of an object from one position to another along a straight line. The coordinates of the object at x, y, z are translated by the distances Tx, Ty, Tz resulting in the new coordinates at x’, y’, z’.

6. Types of Transformations
Translation - Matrix Form
Above, the transformation equations for translation are represented in matrix form.

7. Types of Transformations
Notes on Matrix Form:
MicroStation’s convention
The fourth row in the matrix is introduced to make the matrix square
Fourth row results in 1 = 1
MicroStation’s matrix convention requires the coordinate positions in column format as opposed to row format. Based on this convention we will see that matrices need to be multiplied in reverse order during concatenation.
The fourth row of the transformation matrix is not stored by MicroStation.

8. Types of Transformations
Scaling
Scaling is the altering of an object’s size about a fixed point. The coordinates of the object at x, y, z are scaled by the scale factors Sx, Sy, Sz resulting in the new coordinates at x’, y’, z’. Scaling is relative to the global origin at 0, 0, 0.

9. Types of Transformations
Scaling - Matrix Form
Above, the transformation equations for scaling are represented in matrix form.

10. Types of Transformations
Rotation about the Z-axis
Rotation is the transformation of an object along a circular path about a pivot point. In this diagram the coordinates of the object at x, y, z are rotated about the Z-axis by angle theta resulting in the new coordinates at x’, y’ z’. Like scaling, rotation is relative to the global origin at 0, 0, 0.

11. Types of Transformations
Rotation about Z - Matrix Form
Above, the transformation equations for rotation about the Z-axis are represented in matrix form.

12. Types of Transformations
Notes on Rotation
Stored separately in MicroStation in a 3x3 matrix
We’ve seen only rotation about the Z-axis
Values in the 3x3 matrix can represent angles about all three axi
Usually only need to deal with rotation about the Z-axis when constructing matrices

13. Types of Transformations
Mirroring
Mirroring has the effect of producing a mirror image of the object relative to an axis of reflection. In the above case the object is mirrored about the X-axis. Mirroring about an arbitrary line can be accomplished with a sequence of transformations.

14. Types of Transformations
Shearing
Shearing has the effect of distorting an object as if the object were composed of multiple layers that can slide over one another. In the above case, each point on the object is displaced horizontally by shearing factor SHx proportional to the y-coordinate values.

15. Types of Transformations
Matrix Summary
Visualize an element transformation as the result of all points on the element being manipulated by the transformation matrix
Composite transformations will be discussed later...

16. MDL Transformation Matrices
How MicroStation stores Matrices
Transform union holds a 3 x 4 matrix for 3D files or a 2 x 3 matrix for 2D files
RotMatrix union holds a 3 x 3 matrix for 3D files or a 2 x 2 matrix for a 2D files
MDL functions will access the appropriate matrix in the union
Basetype.h
typedef union rotMatrix {
double form2d[2][2];
double form3d[3][3];
} RotMatrix;
typedef union transform
double form2d[2][3];
double form3d[3][4];
} Transform;

17. MDL Transformation Matrices
Transform matrix can have all elements of translation, scaling, and rotation
Represents a complete transformation in 3D space
RotMatrix can hold both rotation and scaling
A rotation matrix consisting of pure rotation is an orthogonal matrix
NOTE: Orthogonal is referred to here in the strict mathematical sense, meaning that the transpose of the matrix equals its inverse. This is discussed on the following slides.

18. MDL Transformation Matrices
What is an orthogonal matrix?
By definition, a matrix is orthogonal if its transpose is equal to its inverse
Thus, the transpose of the matrix multiplied by the original matrix will equal the identity matrix
Transposing a matrix can be accomplished by interchanging the rows and columns of the matrix.
The inverse of a matrix is such a matrix that when multiplied by the original matrix will yield the identity matrix. If the transpose of a matrix equals its inverse the matrix is orthogonal.

19. MDL Transformation Matrices
What is the identity matrix?
a square matrix consisting of zeros with unity along the diagonal
represents no change to points or elements manipulated by it

20. MDL Transformation Matrices
Proof:
Matrix multiplication is accomplished by multiplying the rows of the first matrix with the columns of the second to obtain the resulting matrix members.

21. MDL Transformation Matrices
Benefits of an orthogonal matrix
Points that are transformed by an orthogonal matrix can be returned to their original state by transforming the resulting points by the transpose of the original matrix
Transposition is not computationally intensive compared to full matrix inversion

22. MDL Transformation Matrices
Orthogonal rotation matrices
Stored with cells, arcs, text, etc. representing 3D rotation from an unrotated definition
Elements can be rotated back to their unrotated orientation by applying the transpose of the element’s rotation matrix
The element’s rotation matrix is very useful when you need to compute coordinates or generate other elements based on an element in 3D space. Since it is easier to compute the new points relative to an unrotated X,Y plane, you can first unrotate the in-memory element using the transpose of the element’s rotation matrix. Once the new points or elements are created they can be transformed to the original element orientation by using the original element rotation matrix.
If the base element does not store a rotation matrix or if multiple elements are being considered, mdlRMatrix_from3Points can be used to obtain the existing orientation.

23. MDL Transformation Matrices
View rotation matrices
MicroStation also stores a RotMatrix on each view defining its orientation or viewing plane
Design file elements are transformed by the view rotation matrix for display on screen
mdlRMatrix_fromView

24. MDL Transformation Matrices
View rotation matrix
Represents a rotation from the World coordinate system to the View coordinate system
An element flat to a view will obtain a plan view orientation when physically transformed by the view’s rotation matrix
The transpose of the view rotation matrix is required to physically rotate elements from a world orientation to the view
View rotation matrices represent an opposite rotation from element rotation matrices. Instead of physically rotating the elements, the view coordinate system is rotated.
An example of applying view rotation matrices is the interactive placement of graphic cells in a 3D file. Since graphic cells will be placed flat to a view, the cell will need to be rotated by the transpose of the view rotation matrix.

25. MDL Transformation Matrices
Standard view rotation matrices

26. MDL Functions
Functions are available to construct matrices and manipulate points or elements
Operate on RotMatrix, Transform, MSElement, and MSElementDesr
Of the form mdlRMatrix_… and mdlTMatrix_…

27. MDL Functions mdlRMatrix_getIdentity mdlRMatrix_invert
mdlRMatrix_getinverse
mdlRMatrix_normalize
void mdlRMatrix_getIdentity (
RotMatrix *rMatrix /* <= rotation matrix */ );
mdlRMatrix_getIdentity sets the rotation matrix pointed to by rMatrix to the identity matrix.
void mdlRMatrix_invert
RotMatrix *outRMatrix, /* <= */
RotMatrix *inRMatrix /* => */
mdlRMatrix_invert sets the rotation matrix pointed to by outRMatrix to the transpose of the rotation matrix pointed to by inRMatrix.
void mdlRMatrix_getInverse
mdlRMatrix_getInverse sets the rotation matrix pointed to by outRMatrix to the inverse of the rotation matrix pointed to by inRMatrix.
void mdlRMatrix_normalize
RotMatrix *inRMatrix /* => */
mdlRMatrix_normalize normalizes each column of the rotation matrix pointed to by inRMatrix and puts the result in the rotation matrix pointed to by outRMatrix.

28. MDL Functions mdlRMatrix_fromView mdlRMatrix_from3Points
mdlRMatrix_fromAngle
mdlRMatrix_rotate
void mdlRMatrix_fromView (
RotMatrix *outRMatrix, /* <= */
int viewNumber, /* => view number */
int allowAuxCoord /* => if TRUE, use aux coords */ );
The mdlRMatrix_fromView function copies the rotation matrix for view viewNumber to the rotation matrix pointed to by outRMatrix. If allowAuxCoord is TRUE and there is an active ACS, the function copies the ACS's rotation matrix.
void mdlRMatrix_from3Points
RotMatrix *outRMatrix, /* <= */
Dpoint3d *origin, /* => point 1 */
Dpoint3d *xAxis, /* => point 2 */
Dpoint3d *point /* => point 3 */
mdlRMatrix_from3Points generates a rotation matrix from three points that define a plane. The vector from origin to xAxis defines the plane's X-axis and point3 defines its orientation.
void mdlRMatrix_fromAngle
double angle /* => rotation angle */
The mdlRMatrix_fromAngle function generates a rotation matrix in outRMatrix from the angle given by angle in radians.
void mdlRMatrix_rotate
RotMatrix *inRMatrix, /* => original RMatrix */
double xAngle, /* => x rotation angle */
double yAngle, /* => y rotation angle */
double zAngle /* => z rotation angle */
The mdlRMatrix_rotate function rotates the rotation matrix pointed to by inRMatrix by the angles specified in xAngle, yAngle and zAngle in radians. The result is placed in the rotation matrix pointed to by outRMatrix.

29. MDL Functions mdlRMatrix_rotatePoint mdlRMatrix_rotatePointArray
mdlRMatrix_unrotatePoint
mdlRMatrix_unrotatePointArray
void mdlRMatrix_rotatePoint (
Dpoint3d *point, /* <=> point to rotate */
RotMatrix *rMatrix /* => rotation matrix */ );
The mdlRMatrix_rotatePoint function rotates point by the rotation matrix pointed to by rMatrix.
void mdlRMatrix_rotatePointArray
Dpoint3d *point, /* <=> array to rotation */
RotMatrix *rMatrix, /* => rotation matrix */
int numPoints /* => number of points */
The mdlRMatrix_rotatePointArray function is identical to mdlRMatrix_rotatePoint except that it rotates an array of numPoints points.
void mdlRMatrix_unrotatePoint
The mdlRMatrix_unrotatePoint function rotates point by the inverse of the rotation matrix pointed to by rMatrix.
void mdlRMatrix_unrotatePointArray
The mdlRMatrix_unrotatePointArray function is identical to mdlRMatrix_unrotatePoint except that it unrotates an array of numPoints points.

30. MDL Functions mdlRMatrix_fromTMatrix mdlTMatrix_fromRMatrix
void mdlRMatrix_fromTMatrix (
RotMatrix *outRMatrix, /* <= rotation matrix */
Transform *tMatrix /* => transformation matrix */ );
mdlRMatrix_fromTMatrix extracts the rotation and scaling portions of the transformation matrix pointed to by tMatrix. The function then copies the rotation and scaling portions to rMatrix.
void mdlTMatrix_fromRMatrix
Transform *outTMatrix, /* <= */
RotMatrix *inRMatrix /* => */
The mdlTMatrix_fromRMatrix function sets the square portion of the transformation matrix pointed to by outTMatrix to the rotation matrix pointed to by inRMatrix.

31. MDL Functions mdlTMatrix_getIdentity mdlTMatrix_setTranslation
mdlTMatrix_scale
mdlTMatrix_rotateByAngles
void mdlTMatrix_getIdentity (
Transform *tMatrix );
The mdlTMatrix_getIdentity function sets the transformation matrix pointed to by tMatrix to the identity matrix.
void mdlTMatrix_setTranslation
Transform *tMatrix, /* <=> */
Dpoint3d *point /* => translation */
The mdlTMatrix_setTranslation function sets the translation column of the transform tMatrix to the values specified in point.
void mdlTMatrix_scale
Transform *outTMatrix, /* <= */
Transform *inTMatrix, /* => original matrix */
double xScale, /* => x scale */
double yScale, /* => y scale */
double zScale /* => z scale */
The mdlTMatrix_scale function scales the transformation matrix pointed to by inTMatrix by the scale factors xScale, yScale and zScale. The result is placed in the transformation matrix pointed to by outTMatrix.
void mdlTMatrix_rotateByAngles
double xAngle, /* => x angle */
double yAngle, /* => y angle */
double zAngle /* => z angle */
The mdlTMatrix_rotateByAngles function rotates the transformation matrix pointed to by inTMatrix by the angles specified in xAngle, yAngle and zAngle in radians. The result is placed in the transformation matrix pointed to by outTMatrix.

32. MDL Functions mdlTMatrix_transformPoint mdlTMatrix_transformPointArray
mdlTMatrix_rotateScalePoint
void mdlTMatrix_transformPoint (
Dpoint3d *point, /* <=> point to be transformed */
Transform *tMatrix /* => transformation matrix */ );
The mdlTMatrix_transformPoint function transforms point by the transformation matrix pointed to by tMatrix.
void mdlTMatrix_transformPointArray
Dpoint3d *point, /* <=> points to be transformed */
Transform *tMatrix, /* => transformation matrix */
int numPoints /* => number of points */
The mdlTMatrix_transformPointArray function is identical to mdlTMatrix_transformPoint except it transforms an array of numPoints points.
void mdlTMatrix_rotateScalePoint
The mdlTMatrix_rotateScalePoint function rotates and scales point by the transformation matrix pointed to by tMatrix. It does not translate point by the translation portion of tMatrix.

33. MDL Functions mdlTMatrix_referenceToMaster
mdlTMatrix_masterToReference
void mdlTMatrix_referenceToMaster (
Transform *outTMatrix, /* <= */
int fileNumber /* => file number */ );
The mdlTMatrix_referenceToMaster function returns a transformation matrix in outTMatrix. This matrix can be used to transform elements in reference file fileNumber to the master design file's coordinate system.
void mdlTMatrix_masterToReference
The mdlTMatrix_masterToReference function returns a transformation matrix in outTMatrix. This matrix can be used to transform elements in the master file to the reference file fileNumber's coordinate system.

34. MDL Functions mdlElement_transform mdlElmdscr_transform
int mdlElement_transform (
MSElement *out, /* <= transformed element */
MSElement *in, /* => original element */
Transform *tMatrix /* => transformation matrix */ );
The mdlElement_transform function transforms the element in by the transformation matrix tMatrix and places the result in out. in and out can point to the same element. The transformation matrix relates to the current coordinate system if one exists.
void mdlElmdscr_transform
MSElementDescr *elemDscrP, /* <=> element descriptor */
Transform *tMatrix /* => transformation matrix */
The mdlElmdscr_transform function transforms the element descriptor pointed to by elemDscrP by the transformation matrix tMatrix. The transformation matrix relates to the current coordinate system if one exists.

35. Multiple Transformations
A complete element transformation may require scaling, rotation, and translation
Rotation and scaling is usually relative to a fixed point on the element
This would require translation of the element so that the fixed point resides at 0,0,0

36. Multiple Transformations
EXAMPLE: Rotating a cell about its origin
Using this example we will discuss the different ways of applying the individual transformations required to rotate a cell about its origin at Ox, Oy, Oz.

37. Multiple Transformations
STEP 1: Translation to the global origin
Before rotation is applied the cell should be translated so that its origin, originally at Ox, Oy, Oz, resides at 0, 0, 0.

38. Multiple Transformations:
STEP 2: Rotation about the global origin
With our pivot point residing at 0, 0, 0, rotation by angle theta is applied about the Z-axis.

39. Multiple Transformations
STEP 3: Translation back to point in space
The rotated cell is now translated back to its original position at Ox, Oy, Oz.

40. Multiple Transformations
Transformations can be applied in succession..
mdlTMatrix_getIdentity(&tMatrix);
mdlTMatrix_setTranslation(&tMatrix, &transTo);
mdlElmdscr_transform(edP, &tMatrix);
mdlTMatrix_rotateByAngles(&tMatrix, &tMatrix, fc_zero, fc_zero, angle_rad);
mdlTMatrix_setTranslation(&tMatrix, &transBack);
In this case the cell element descriptor is transformed in memory as each individual transformation matrix is constructed.

41. Multiple Transformations
…or concatenated into a composite matrix
There exists a single matrix representing a complete transformation
Multiplying the individual matrices will result in the composite matrix
Rather than transforming the cell element descriptor multiple times we can construct a single matrix representing the composite transformation.

42. Multiple Transformations
EXAMPLE: Order of Transformations

43. Multiple Transformations
MicroStation’s matrix convention requires the matrices to be multiplied in reverse order

44. Multiple Transformations
Matrix multiplication is associative but not commutative
Any two adjacent matrices can be multiplied together
Must adhere to reverse order of multiplication

45. Multiple Transformations
EXAMPLE: The Composite Transformation Matrix
The composite matrix above is the result of the individual transformation matrices being multiplied in reverse order. You will notice that the cell origin at Ox, Oy, Oz remains unchanged when manipulated by this matrix. All other points transformed by this matrix represent a rotation about this point.

46. Composite Transformations
MDL functions accepting an input matrix usually construct a composite transformation matrix
Passing NULL will initialize the input matrix to the identity matrix
But difficult to predict the order in which matrices are multiplied

47. Composite Transformations
Can explicitly multiply individual matrices...
mdlRMatrix_multiply
mdlTMatrix_multiply
void mdlRMatrix_multiply (
RotMatrix *outRMatrix, /* <= */
RotMatrix *rMatrix1, /* => */
RotMatrix *rMatrix /* => */ );
mdlRMatrix_multiply sets the rotation matrix pointed to by outRMatrix to the product of rMatrix1 and rMatrix2.
void mdlTMatrix_multiply
Transform *outTMatrix, /* <= T1 x T2 */
Transform *tMatrix1, /* => T1 */
Transform *tMatrix /* => T2 */
The mdlTMatrix_multiply function sets the transformation matrix pointed to by outTMatrix to the product of tMatrix1 and tMatrix2.

48. Composite Transformations
EXAMPLE: Explicit Matrix Multiplication
mdlTMatrix_translate(&tMatrixTo, NULL, -origin.x, -origin.y, -origin.z)
mdlTMatrix_rotateByAngles(&tMatixRot, NULL, fc_zero, fc_zero, angle_rad)
mdlTMatrix_translate(&tMatrixBack, NULL, origin.x, origin.y, origin.z)
mdlTMatrix_multiply(&tMatrixTmp, &tMatrixBack, &tMatrixRot)
mdlTMatrix_multiply(&tMatrix, &tMatrixTmp, &tMatrixTo)
mdlElmdscr_transform(edP, &tMatix)
In this approach three separate transformation matrices are constructed and explicitly multiplied in reverse order to obtain the composite matrix.

49. Composite Transformations
…or use the functions that accept an input matrix
mdlTMatrix_rotateByAngles(&tMatrix, NULL, fc_zero, fc_zero, angle_rad);
mdlTMatrix_setOrigin (&tMatrix, &origin);
mdlElmdscr_transform (edP, &tMatrix);
The following list shows the order of matrix multiplication for composite matrix functions. IN denotes an input matrix and NEW denotes a matrix created from other input parameters.

50. Transformations Summary
In constructing transformation matrices first list the required individual transformations
Adhere to the rules of matrix multiplication and convention
Implement MDL functions conveniently

51. Transformations EXERCISE:
Edit dimarc.mc, adding the necessary code to generate three points defining a radial dimension to the inside of an arc. Your instructor will discuss the steps required.

52. The Current Transformation
A transformation matrix that MicroStation maintains for every MDL application.
Coordinate or distance arguments to MDL functions are transformed by this matrix
Set to the identity matrix by default

53. The Current Transformation
Allows a localized change of the coordinate system
Behaves as a stack
Transformation matrices can be pushed or popped
The current transformation can allow rotation, scaling, or translation (a shift of the origin) of the global coordinates system relative to an MDL application. They can be pushed (added to the end of the current transformation stack) or popped (removed from the end of the stack).

54. Current Transformation Functions
mdlCurrTrans_begin - push a copy of the current transform matrix
mdlCurrTrans_end - pop the last pushed transformation matrix

55. Current Transformation Functions
mdlCurrTrans_masterUnitsIdentity - replace the current transformation matrix with the identity matrix and set the scales by the number of UORs per master unit
mdlCurrTrans_… manipulate the current transformation matrix or point and distance arrays