[CONNECT C++] DVec3d::IsParallelTo()

Hi Bruce Reeves SRNS

Yes. If an Angular tolerance is mentioned in most cases this equates to:

Angle::SmallAngle(); /* small angle tolerance (in radians) */

REFERENCE (A few mentions/use cases):

C:\PROGRA~1\Bentley\MICROS~2\include>s SmallAngle *
Geom\Angle.h:68://! Return true if {fabs(radians)} is within {Angle:SmallAngle} of 2PI.
Geom\Angle.h:71://! Test if {radians} is {SmallAngle} or smaller.
Geom\Angle.h:73://! Test if {radians} is {SmallAngle} or smaller.
Geom\Angle.h:76://! Test if two angles are within {SmallAngle} (NOT allowing 2pi shift!!)
Geom\Angle.h:78://! Test if two angles are within {SmallAngle}, allowing 2pi shift.
Geom\Angle.h:82:static double SmallAngle ();
Geom\Angle.h:153:static void Rotate90UntilSmallAngle (double &x1, double &y1, double x0, double y0);
Geom\Angle.h:273://! The degrees form of the system small angle (for radians, Angle::SmallAngle ())
Geom\Angle.h:274:static AngleInDegrees SmallAngleInDegrees ();
Geom\DPoint3dOps.h:126://! Near equality test with default Angle::SmallAngle absolute and relative tolerances.
Geom\DPoint3dOps.h:569://! Relative tolerance for coordinate tests.  This is 1e-10, and is coarser than Angle::SmallAngle.
Geom\MSBsplineSurface.h:201:    //! Check whether the B-spline surface is bilinear and each face of the control polygon is planar, with tight system tolerance (Angle::SmallAngle (

Robert Hook said:

If an Angular tolerance is mentioned

Thanks for pointing out that dusty corner of the MicroStationAPI.  I've summarised vector tolerance and SmallAngle for future reference.

While researching that, it became apparent that some things are not documented.  For example, what is the tolerance used when comparing points and vectors?

Jon Summers said:

While researching that, it became apparent that some things are not documented.  For example, what is the tolerance used when comparing points and vectors?

If the method says it's testing exact equality there is no tolerance used. Both DPoint3d and DVec3d have an IsEqual method that allows you to specify a tolerance, for examples, from DPoint3d.h:

//! @description Test for exact equality between all components of two points or vectors.
//! @param [in] point2 The second point or vector
//! @return true if the points are identical.
bool IsEqual (DPoint3dCR point2) const;

//! @description Test if the x, y, and z components of two points or vectors are
//! equal within tolerance.
//! Tests are done independently using the absolute value of each component differences
//! (i.e. not the magnitude or sum of squared differences)
//! @param [in] point2 The second point or vector.
//! @param [in] tolerance The tolerance.
//! @return true if all components are within given tolerance of each other.
bool IsEqual (DPoint3dCR point2, double tolerance) const;

Those two (DPoint3d.IsEqual with and without tolerance) are clear.  Other methods are less clear.  For example...

• DVec3d.AlmostEqual, where help tells us confusingly: Uses library "small angle" as both absolute and relative tolerance. points are equal if squared distance between is less than (squared abstol) plus (squared relTol) * sum of cmponent squares. Does that test really use SmallAngle?
• DVec3d.IsParallelTo true if the vectors are parallel within tolerance. Bob Hook tells us that the tolerance is SmallAngle
• DVec3d.IsPerpendicularTo true if vectors are perpendicular within tolerance SmallAngle again?

Contrast the above with the mdlVec_api, where the tolerance used is specified in the documentation...

• 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)

Hi Jon,

Is ParallelTo is a use case that certainly implements SmallAngle.  However there are other use cases where a higher tolerance may work fine/better (e.g. AlmostEqual) and the "relative tolerance" equates to using DoubleOps::SmallCoordinateRelTol, documented with the comment:

Relative tolerance for coordinate tests. This is 1e-10, and is coarser than Angle::SmallAngle.

HTH,
Bob