MicroStation .NET: Rotate an Element

MstnPlatformNet

Introduction

This article is for C# developers who want to write an application for MicroStation CONNECT. It describes a tool that provides a locate function and then rotates the chosen element.

Be Communities

If you want to ask questions about C# development for MicroStation CONNECT, post your question to the MicroStation Programming Forum.

Matrices

This article is a response to question on the MicroStation Programming Forum about element rotation.

Mathematical Matrices

Matrices were invented in the 19^th century. They have evolved into a versatile mathematical tool used for many purposes from 2D to multi-dimensional applications.

For the purpose of computational geometry, matrices can be 2D, 3D or 4D (when time is involved). For manipulating MicroStation elements, the DMatrix3d covers both 2D and 3D operations.

The DMatrix3d class has many methods, which you can find in the Bentley.GeometryNET.structs help document. That document, along with several others that concern MicroStation's .NET API, is delivered when you install the MicroStation CONNECT SDK.

Matrices in the MicroStation APIs

Rotation of an element, using the MicroStation APIs, invariably follows this idiom …

Pick an element (Bentley.DgnPlatformNet.Elements.Element)
Get the element's rotation (or orientation)
- Rotation is expressed as a rotation matrix (Bentley.GeometryNET.DMatrix3d)
Get a desired rotation
- Rotation could be derived from MicroStation's Active Angle
- Rotation could be obtained interactively from a user Datapoint
Convert the rotation to a general transform
Apply the transform to the element
Rewrite the element to persist the change

RotateElementTool Project

The RotateElementTool is a project in a Visual Studio solution written using C#. It demonstrates the above idiom by implementing a tool that inherits from DgnElementSetTool, which you will find in the DgnPlatformNet documentation. The tool has several commands, specified in commands.xml. They are chosen to illustrate various ways of rotating a text element...

Rotate Element Tool Commands
Command	Result	Comment
ROTATEELEMENTEXAMPLE ROTATE ACTIVE	Rotates an element by the Active Angle
ROTATEELEMENTEXAMPLE ROTATE USER	Rotates an element by a user-supplied angle	Angle (in degrees) follows key-in
ROTATEELEMENTEXAMPLE ROTATE SPIN	Rotates an element to the user's cursor position	Uses dynamics
ROTATEELEMENTEXAMPLE HELP VERSION	Displays the AddIn's version no.	Uses .NET reflection to get information from the DLL

Each ROTATE command prompts the user to pick an element. Where the rotation angle is fixed (ACTIVE & USER) the element is rotated immediately. The SPIN command requires a second Datapoint to determine the rotation, and displays the rotated element dynamically while awaiting that second Datapoint.

DMatrix3d

The code shows how to obtain an element's rotation (also called orientation) in a DMatrix3d. Some element types, including TextElement, have a built-in rotation. If implementing your own tool, you must decide whether to include or ignore that built-in rotation when transforming the element to its new orientation.

C# Implementation

//  Compute the normal vector as the cross-product of the X-axis
//  and the vector from the element origin to user input point
DVector3d vector = DVector3d.Subtract(new DVector3d(spinVector), new DVector3d(origin));
DVector3d xAxis = new DVector3d(1.0, 0.0);
DVector3d normal = xAxis.CrossProduct(vector);
//  Calculate the angle between the X-axis and the user input
Angle angle = xAxis.PlanarAngleTo(vector, normal);
DMatrix3d rotation = DMatrix3d.Rotation(normal, angle);
//  Create a transformation matrix from the rotation matrix
DTransform3d transform = DTransform3d.FromMatrixAndFixedPoint(rotation, origin);

The SPIN command shows how to take account of a TextElement's built-in rotation when calculating the response to the user's Datapoint. The tool first unrotates the element (computes its inverse matrix), then applies the user-supplied rotation. When you want to compute the result of two DMatrix3d rotations, you must multiply those matrices.

Once the rotation matrix is computed, it is converted to a DTransform3d. Then that transform is applied to the element via an intermediate TransformInfo object. Finally, the element is replaced in the DGN model.

Download the Rotate Text Example

The C# source code is available in this project. The tool was developed using MicroStation CONNECT Update 13 and Visual Studio 2019. Unpack the ZIP archive and copy the code to a suitable location.

Inspect the project Properties. You will probably need to change some settings, notably the output location, to match your preferences. Build the Visual Studio project. It should work with Viz Studio 2017 and later.

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.