Point/Vector/Matrix/Transform Concepts for Microstation VBA

Point/Vector/Matrix/TransformConcepts

for Microstation VBA

Earlin LutzBentley Systems, Inc.

for BDC 2003

Outline

Basic concepts– Point– Vector– Matrix– Transform

Common Conceptual Problems– Point ?? vector– Multiple Representations of vector

xyz angle & magnitude pair of points

– Matrix vs Transform– Role of “origin” in transform– Special properties of 3D rotations

Ground Rules

Enough concepts (theory) to address common questions (confusion) about matrices, transforms, points, vectors

No equations unless accompanied by a picture.(this is not a math text)

VBA Programming(this is not a programming cookbook)

– Name useful functions– no multi-line programming examples– limited reference to corresponding mdl struct types

Warning: Expect Term Mismatch

(Good Thing) Point/VectorMatrix/Transform concepts are universally useful.

(Side effect of intelligent life) If you work in a specialized discipline, you have specialized terminology

(Bad Thing) Your discipline’s terms probably won’t match your neighbor’s/– Your specialized idioms will be a subset of general mathematics– Occasional outright mismatch

Microstation VBA Types ..

Point3d– Anything (point or vector!!!!) described as having x,y,z parts is

called a Point3d.– Yes, use the same type (Point3d) for both point and vector– Read documentation documentation to see if a particular argument

of “programming language type Point3d” is geometrically acting as a “point” or “vector”

Matrix3d– 9 doubles arranged as 3 rows, 3 columns– Each row, column is a vector

Transform3d– 12 doubles arranged as 3 rows, 4 columns– Conceptually, first 3 columns are a Matrix3d, 4th column could be a

point or vector depending on context.

MDL ( C ) types DPoint3d

– Anything (point or vector!!!!) described as having x,y,z parts is called a DPoint3d.

– Yes, use the same type (DPoint3d) for both point and vector– Read documentation documentation to see if a particular argument

of “programming language type DPoint3d” is geometrically acting as a “point” or “vector”

RotMatrix– 9 doubles arranged as 3 rows, 3 columns– Each row, column is a vector– In C, “row major” order is visible to address arithmetic

Transform– 12 doubles arranged as 3 rows, 4 columns– Conceptually, first 3 columns are a RotMatrix, 4th column could be a

point or vector depending on context.– Beware that due to C “row major” C ordering the conceptual

RotMatrix is not present as leading 9 doubles

Main Issues…

Intro/Goals Point vs vector

– Abstractly different– programming form of each is x,y,z– curiously interchangeable in practice

Matrix and Transform

UU

V

W

“Point” and “Vector”

A point is a place– In cartesian (rectangular) coordinate system, the place is fully

described by “coordinates” relative to an origin and axes

B

A

G D

C

F

E

U B= -= -= -= -

A

D C

V F E

W G A

A vector is ….– a displacement– the difference between 2 points– a magnitude and direction

ummm … Are points different from vectors?

In symbolic, abstract, conceptual, coordinate free analysis of geometry, a point and vector are carefully defined as separate things.

At mid- and low- programming level, things get blurred

– a point is “represented” by its coordinates – x,y,z

– a vector is “represented” by 3 “components”, also named x,y,z

– At programmer level, Microstation follows common practice (insert profuse apologies?) of tossing anything that goes by x,y,z into a single “type” (in VBA, “Point3d”).

– xyz of a point is also xyz for a vector from the origin to that point. So maybe everything is a vector and all points are imaginary?

Vector Confusion:xyz vs “angle+magnitude” vs “pair of points” In non-programming setting, a vector might be …

– “difference of two points” – two distinct points (or array of 2 points) as working form of “vector”

– “direction and magnitude” – or “angle” and “length”

These are fine for input and output, but intermediate vectors computations “always” use xyz form

A

BU=B-A

A

B

cosr

ABU xxx

sinr

ABU yyy

Addition and scaling of “points”presumes implicit conversion to/from“vectors from origin”

Point/Vector Confusion –Barycentric Coordinates

“point plus point???”

“scale factor times point???”

“point minus point”

“scale factor times vector”

“point plus vector”

Conceptually wrong(but universally understood)

)(5.0 BAM A M

B

)(5.0 ABAM A M

B Conceptually correct

“Angle + Magnitude” is a bad form for vector calculations!!!

Add two vectors – xy form:

“direction and magnitude” form– first, last step are conversions to/from xy!!!

U

V

VUW yyy

xxx

VUW

VUW

22

yx

yx

2atanW

sinVcosV

sinUcosU

yxrx

y

yyy

xxx

rr

rr

WWWW

W

VUW

VUW

VVVV

UUUU

Main Issues…

Intro/Goals Point vs vector

Matrices and Transforms– “Transform as coordinate frame”– “Transform as action”– Decomposing a transform is tricky!!!

Angles, scales, origin all buried

“Matrix” and “(affine) Transform”

U

VW

A

WVU

WVU

WVU

WVU

zzz

yyy

xxx

Matrix3d(RotMatrix)

AWVU

AWVU

AWVU

AWVU

zzzz

yyyy

xxxx

Transform3d(Transform)

“Matrix part”“Point part”

What is a transform?

Answer 1: Origin and axis directions for a coordinate system

– In this interpretation the transform is an inert thing.– Multiplying a “transform times point” changes coordinates from one

coordinate frame to another, but leaves the geometry intact.

Answer 2: Scaling, translation, and rotation

– In this interpretation, the transform is an active thing.– Multiplying “transform times point” performs moves the geometry

from one place to another within the same parent coordinate system.

Q: What is a transform?A1: “A Transform is a Coordinate Frame”

U V W A

Axis Column of Matrix Part

Origin translation part

1

w

v

u

wWvVuUA

z

y

x

* In this “interpretation” the 4th column of the transform is a point!!

U

VW

A

B

Building a “transform as a coordinate frame”

Applicable when your are given– origin (as a point)– axis orientations

collect as columns of a matrix, e.g.Matrix3dFromPoint3dColumns

(colX,colY,colZ)

Assemble as a transform

Transform3dFromMatrix3dPoint3d(matrix,origin)

Q: What is a transform?A2: “A transform is an action”

“Translation” “Uniform Scale” “Rotate”

“Mirror” “Non-uniform scale” “skew”

Q: What is a transform?A2: “A transform is an action”

To do: Translate geometry by vector U

U

0P

1PUPP 01

Point/Vector Equation:

UP

UP

PUP

0

0

01

I

ITransform Equation:

* In this “interpretation” the 4th column of the transform is a vector!!

Is the “point” column in my Transform3d the “origin” of my analysis?

Here’s my transform:

Answer 1: Of course. The transform defines a local coordinate system: origin A, axis directions U and V. The origin A appears directly as the “point” part of the transform.

Answer 2: No!! In an “action” transform with a “fixed point”, the fixed point does not directly appear.

y

x

yy

xx

A

A

VU

VU

A

UV

The “center of the interesting activity” is not always the “point” in your transform!!!

A

B

Point A … is the ‘fixed point’ of the rotation is the “origin of the local coordinate

system” appears twice (once negated!) in the

transform construction does not appear numerically in the

composite transform!!

cossincossin

sincossincos

10

01

0cossin

0sincos

10

01

yxy

yxx

y

x

y

x

AAA

AAA

A

A

A

AT

cossincossin

sincossincos

10

01

0cossin

0sincos

10

01

yxy

yxx

y

x

y

x

AAA

AAA

A

A

A

AT

cossincossin

sincossincos

10

01

0cossin

0sincos

10

01

yxy

yxx

y

x

y

x

AAA

AAA

A

A

A

AT

A -A

B

Building “action transforms”

Single step initializers for hardest common cases– Transform3dFromLineAndRotationAngle– Transform3dFromMirrorPlane

Two steps for rotate or scale “about fixed point”– Step 1: Build matrix part– Step 2: combine with fixed point

Transform3dFromMatrix3dAndFixedPoint– “Point” column is computed so that applying the transform

leaves given point where it is.– Don’t confuse with

Transform3dFromMatrix3dPoint3din which “Point” part of transform is direct copy of given point

General Case– Construct multiple transforms– Multiply together to achieve compound effects– Common case: “sandwich”

Sandwich Transform

1 SAST

Strategy to build the transform Convert coordinates from world to local Do the local-to-local transform Convert back to world coordinates

Frequent observation: If my geometry is in this particularly convenient local coordinate system, the transform A is obvious

dInverse)Transform3 (see of inverse

transformworld-to- worlddesired

transformlocal-to-localknown

system local some of axes origin,

1 SS

T

A

S

worldworld

locallocal

worldlocal

Order of Transformation

PSASPT 1

world-to-

localcoordinate

change

Point P passes through transforms from right to left !!!

local-to-

localgeometry

modification

local-to-

worldcoordinate

change

originalworldcoords

originallocal

coords

modifiedlocal

coords

modifiedworldcoords

How was a transform constructed?

Many different combinations/sequences of translate, scale, rotate, mirror, skew can produce same final result

No individual number is directly identifiable as “the” scale, “the” rotation etc.

==

Mirror about X? Mirror Y, then rotate 180 CW ? Rotate 90, then mirror around line at –45? ….

“What is the rotation angle in my matrix?”

If …… you are absolutely, positively sure that your matrix was constructed with only …– rotation– uniform scale (no mirror!!!!)

then ….. (and only then)– the matrix clearly separates into “scale and rotation”– in pure 2D, the rotation is just 1 angle– in 3D, the rotation has 3 degrees of freedom, variously (and

badly) expressed as “euler angles” or a quaternion. Even if you meet these conditions, describing a matrix via

angles is awkward for computation

Recognizing special forms

Matrix3dIsIdentityTransform3dIsIdentity

Matrix3dIsOrthogonal Just rotation and mirroring.(determinant > 0 means just rotation; determinant < 0 means rotation with mirroring)

Matrix3dIsRigid Just rotation. No mirror, no scale.

Matrix3dIsXYRotation Just rotation around Z.

Transform3dIsTranslate Just translation

Transform3dIsUniformScale

Inverses ‘R Easy

If you conceive of a matrix or transform as …

then its inverse ….

the axes of a local coordinate system, as seen from the world system…

is the axes of the world coordinate system, as seen from the local system.

An action which “moves” geometry ….

moves it back.

Matrix3dInverse

Transform3dInverse

Q: Is there a performance issue?

To do… Multiply/add count

Transform * Point 12

Transform * Transform 30

Invert Transform 100-200

Probably not significant compared to other VBA costs Don’t be afraid of “invert”. It works.

Interpreting a matrix (advanced)

Matrix3d has 9 numbers Lacking specific knowledge of how constructed, most

general “decoupling” into scaling and rotation has …– 3 scale factors– 6 rotational degrees of freedom, arranged as

Common request to decompose as 3 scales + onerotation matrix only covers 6 degrees of freedom!!!

GeneralMatrix(9 dof)

PureRotation(3 dof)

a 0 00 b 00 0 c

PureRotation(3 dof)

= * *

END OF EDL SLIDES

“Transform” and “Matrix” are (loosely) ..

Used for

– placing elements

– moving elements

– orienting views

Ways to describe coordinate systems.

Stored in “rows” and “columns”

2 Step “Action Transform” Construction

Step 1: Construct a Matrix3d with the desired effect relative to the origin

Matrix3dFromScaleFactors – mirror, nonuniform scale

Matrix3dFromScale

Matrix3dFromVectorAndRotationAngle

Matrix3dFromAxisAndRotationAngle

Step 2: Use Transform3dFromMatrix3dAndFixedPoint to make your fixed point act as local origin.

Data Shapes

z

y

x

P

P

P

P

Point

z

y

x

U

U

U

U

Vector

222120

121110

020100

QQQ

QQQ

QQQ

Q

3x3 Matrix

3x4 (“affine”) Transformation

z

y

x

PQQQ

PQQQ

PQQQ

T

222120

121110

020100

Q P

“Matrix part” “Point part”

Types of Transformations

Translation


Translation - Matrix Form

11000

100

010

001

1

z

y

x

Tz

Ty

Tx

z

y

x


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


Scaling


Scaling - Matrix Form

11000

000

000

000

1

z

y

x

Sz

Sy

Sx

z

y

x


Rotation about the Z-axis


Rotation about Z - Matrix Form

11000

0100

00cossin

00sincos

1

z

y

x

z

y

x


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


Mirroring

1000

0100

0010

0001


Shearing

1000

0100

0010

001 SHx


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...

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


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


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


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

100

010

001


Proof:

100

010

001

100

0cossin

0sincos

100

0cossin

0sincos

x

MatrixMatrixMatrixofRotationIdentityTransposeOrthogonal


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


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


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


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


Standard view rotation matrices

001

100

010

010

100

001

577.0577.0577.0

816.0408.0408.0

0707.0707.0

100

010

001

RightFront

IsoTop

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_…

MDL Functions

mdlRMatrix_getIdentity

mdlRMatrix_invert

mdlRMatrix_getinverse

mdlRMatrix_normalize

MDL Functions

mdlRMatrix_fromView

mdlRMatrix_from3Points

mdlRMatrix_fromAngle

mdlRMatrix_rotate

MDL Functions

mdlRMatrix_rotatePoint

mdlRMatrix_rotatePointArray

mdlRMatrix_unrotatePoint

mdlRMatrix_unrotatePointArray

MDL Functions

mdlRMatrix_fromTMatrix

mdlTMatrix_fromRMatrix

MDL Functions

mdlTMatrix_getIdentity

mdlTMatrix_setTranslation

mdlTMatrix_scale

mdlTMatrix_rotateByAngles

MDL Functions

mdlTMatrix_transformPoint

mdlTMatrix_transformPointArray

mdlTMatrix_rotateScalePoint

MDL Functions

mdlTMatrix_referenceToMaster

mdlTMatrix_masterToReference

MDL Functions

mdlElement_transform

mdlElmdscr_transform

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


EXAMPLE: Rotating a cell about its origin


STEP 1: Translation to the global origin

1000

100

010

001

Oz

Oy

Ox

TTo

Multiple Transformations:

STEP 2: Rotation about the global origin

1000

0100

00

00

cossin

sincos

R


STEP 3: Translation back to point in space

1000

100

010

001

Oz

Oy

Ox

TBACK


Transformations can be applied in succession..mdlTMatrix_getIdentity(&tMatrix);mdlTMatrix_setTranslation(&tMatrix, &transTo);mdlElmdscr_transform(edP, &tMatrix);

mdlTMatrix_getIdentity(&tMatrix);mdlTMatrix_rotateByAngles(&tMatrix, &tMatrix, fc_zero,

fc_zero, angle_rad);mdlElmdscr_transform(edP, &tMatrix);

mdlTMatrix_getIdentity(&tMatrix);mdlTMatrix_setTranslation(&tMatrix, &transBack);mdlElmdscr_transform(edP, &tMatrix);


…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


EXAMPLE: Order of Transformations

BACKTO TRT


MicroStation’s matrix convention requires the matrices to be multiplied in reverse order

TOθBACK TxRxT


Matrix multiplication is associative but not commutative

Any two adjacent matrices can be multiplied together

Must adhere to reverse order of multiplication


EXAMPLE: The Composite Transformation Matrix

11000

0100

)1(0

)1(0

1

z

y

x

OxSinCosOyCosSin

OySinCosOxSinCos

z

y

x

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


Can explicitly multiply individual matrices...

• mdlRMatrix_multiply

• mdlTMatrix_multiply


EXAMPLE: Explicit Matrix MultiplicationmdlTMatrix_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)


…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);

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

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.

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

The Current Transformation

Allows a localized change of the coordinate system

Behaves as a stack

Transformation matrices can be pushed or popped

Current Transformation Functions

mdlCurrTrans_begin - push a copy of the

current transform matrix

mdlCurrTrans_end - pop the last pushed

transformation matrix

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

Point/Vector/Matrix/Transform Concepts for Microstation VBA

Documents