Introduction
The MicroStation Development Library (MDL) and MicroStationAPI provide APIs for developers wanting to create custom applications for MicroStation® from Bentley Systems. We create a MicroStation application as a DLL, written using C++ and built with the Microsoft C++ compiler and linker provided with Visual Studio.
When editing your source code, you can choose whether to use Microsoft Visual Studio, Microsoft Visual Studio Code, or one of your favourite text editors.
When building your app, you can use Visual Studio or the Bentley Systems make (bmake) tools.
3D Geometry in the MicroStationAPI
When writing code to generate or manipulate geometry using the MicroStationAPI,
we deal with 3D points (DPoint3d), 3D vectors (DVec3d) and other structures.
Angles are expressed in radians.
They all use double-precision floating-point numbers (C++ double) to specify values.
For example, look in header file Geom/dpoint3d.h to see the definition of DPoint3d …
struct DPoint3d
{
double x;
double y;
double z;
…
};
It's often necessary to compare points and vectors. For reasons well-known to computer science, there are pitfalls if we attempt to compare floating-point numbers directly …
double x = 3.0;
double y = 9.0 / 3.0;
if (x == y) { … }
That if statement may or may not succeed, depending on the exact result of the division
9.0 / 3.0.
It's usually preferable to compare the difference of two numbers to a tolerance, like this …
double x { 3.0 };
double y { 9.0 / 3.0 };
constexpr double Tolerance { 1.0e-8 }; // 1.0 / 100000000.0
if (fabs (x - y) < Tolerance) { … }
Comparing two structs, such as a pair of DPoint3ds, is more complex …
DPoint3d p1 { 1.0, 2.0, 3.0 };
DPoint3d p2 { 2.0 / 2.0, 4.0 / 2.0, 6.0 / 2.0 };
constexpr double Tolerance { 1.0e-8 };
if (fabs (p1.X - p2.X) < Tolerance
&&
fabs (p1.Y - p2.Y) < Tolerance
&&
fabs (p1.Z - p2.Z) < Tolerance)
{ … }
I hope you'll agree that that is rather messy code, which you don't want to see sprinkled through your own well-structured source code. Fortunately, the MicroStationAPI helps with point, vector and angle comparison.
MicroStationAPI Tolerance
The comparison of points, vectors and angles is commonplace. The MicroStationAPI provides methods that encapsulate the above test for various geometry classes. For example, if you want to compare two points, you can do this …
DPoint3d p1 { 1.0, 2.0, 3.0 };
DPoint3d p2 { 2.0 / 2.0, 4.0 / 2.0, 6.0 / 2.0 };
const double Tolerance = 1.0e-8;
if (p1.IsEqual (p2, Tolerance)) { … }
If you want to compare two vectors, you can do this …
DVec3d v1 { 1.0, 2.0, 3.0 };
DVec3d v2 { 2.0 / 2.0, 4.0 / 2.0, 6.0 / 2.0 };
const double Tolerance = 1.0e-8;
if (v1.IsEqual (v2, Tolerance)) { … }
The MicroStationAPI further simplifies such calculations by using a built-in tolerance …
DVec3d v1 { 1.0, 2.0, 3.0 };
DVec3d v2 { 2.0 / 2.0, 4.0 / 2.0, 6.0 / 2.0 };
if (v1.IsEqual (v2)) { … }
Unfortunately, the value of that built-in tolerance is not stated. There's also the following, somewhat vague, method …
DVec3d v1 { 1.0, 2.0, 3.0 };
DVec3d v2 { 2.0 / 2.0, 4.0 / 2.0, 6.0 / 2.0 };
if (v1.AlmostEqual (v2)) { … }
MicroStationAPI help tells us: points are equal if squared distance between is less than (squared abstol) plus (squared relTol) * sum of cmponent squares
MicroStationAPI SmallAngle
Most scientific and engineering applications measure angles in radians. Angles are. like points and vectors, measured using floating-point numbers. The same problems of comparison occur in those calculations.
The MicroStationAPI provides constant SmallAngle.
MicroStationAPI help tells us: Small angle used in toleranced angle comparisons.
You'll find it in header file Geom/Angle.h.
See also SmallCoordinateRelTol in the DoubleOps section.
SmallAngle is used in these and other methods …
NearlyEqualIsNearZeroIsFullCircle
SmallAngle is also used in some vector methods, including …
IsParallelToIsPositiveParallelToIsPerpendicularTo
DoubleOps Class
The MicroStationAPI provides the curiously-named DoubleOps class,
which is packed with intriguingly-named functions.
#include <Geom/DPoint3dOps.h>
DoubleOps provides a number of limit values and ways to test them.
For example, WithinTolerance tests if two doubles are equal within tolerance.
SmallCoordinateRelTol is a relative tolerance for coordinate tests.
This is 1e-10, and is coarser than Angle::SmallAngle
.
Acknowlegements
Some of the above is not immediately obvious when browsing MicroStationAPI help.
The detail of SmallAngle was revealed by Bentley Developer Network technical manager
Robert Hook
on the Be Communities
Programming Forum.
MDL Library
If you're writing code for MicroStation CONNECT, prefer to use the classes described above for geometric algebra.
However, you may want to support a legacy application written using the MicroStation Development Library (MDL).
MDL remains viable with MicroStation CONNECT, and you can continue to use the mdlVec_api.
For example, when calculating whether two vectors are parallel, you can use these functions …
mdlVec_areParallel()Tests if two vectors are parallel, with loose tolerance (roughly 1e-4 radians)mdlVec_areParallelTight ()Tests if two vectors are parallel, with tight tolerance/ (roughly 1e-12 radians)
In addition to the MicroStation SDK, you need the following to be installed on your development computer …
- Visual Studio 2015 in order to compile and link this code for MicroStation CONNECT Update 8 or later
Return to MicroStationAPI articles index.
Questions
Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.
