Functions

Functions

int mdlMeasure_elmDscrArea (double *area, double *perimeter, MSElementDescrP edP)
 Gets the area and perimeter of a closed element. More...
 
StatusInt mdlMeasure_closestPointOnElement (DPoint3dP pClosePoint, ElementHandleCP pHandle, DisplayPathCP pPath, DPoint3dCP pSpacePoint)
 Find the closest point-on-element for given space point. More...
 
int mdlMeasure_polygonArea (double *area, double *perimeter, DPoint3dP points, int numPoints)
 gets the area and perimeter of a polygon. More...
 
int mdlMeasure_polygonProperties (double *perimeterP, double *areaP, DPoint3dP normalP, DPoint3dP centroidP, DPoint3dP momentP, double *iXYP, double *iXZP, double *iYZP, DPoint3dP points, int nPoints)
 Gets the basic area properties of a polygon. More...
 
int mdlMeasure_areaProperties (double *perimeterP, double *areaP, DPoint3dP normalP, DPoint3dP centroidP, DPoint3dP momentP, double *iXYP, double *iXZP, double *iYZP, DPoint3dP principalMomentsP, DPoint3dP principalDirectionsP, MSElementDescrP edP, double tolerance)
 Gets the basic area properties, principal moments, and principal axes of the area enclosed by an element. More...
 
int mdlMeasure_areaPropertiesXY (double *pArea, double *pPerimeter, DPoint3dP pCentroid, DPoint3dP pMoments, double *pIxy, Dpoint3d *pPrincipalMoments, Dpoint3d *pPrincipalDirections, MSElementDescrP edP)
 Compute area, perimeter, centroid, and 2nd moments for the region enclosed by an element. More...
 
int mdlMeasure_linearProperties (double *lengthP, DPoint3dP centroidP, DPoint3dP momentP, double *iXYP, double *iXZP, double *iYZP, DPoint3dP principalMomentsP, DPoint3dP principalDirectionsP, MSElementDescrP edP, double tolerance)
 Gets the basic linear properties of an element. More...
 
int mdlMeasure_linearPropertiesXY (double *lengthP, DPoint3dP centroidP, double *iXXP, double *iYYP, double *iXYP, Dpoint3d *principalMomentsP, Dpoint3d *principalDirectionsP, MSElementDescrP edP)
 Compute length, centroid, and 2nd moments of the curve, treated as a WIRE of uniform density at z coordinate equal to the minimim z on the element. More...
 
int mdlMeasure_surfaceProperties2 (double *areaP, DPoint3dP centroidP, DPoint3dP momentP, double *iXYP, double *iXZP, double *iYZP, DPoint3dP principalMomentsP, DPoint3dP principalDirectionsP, MSElementDescrP edP, DgnModelRefP resultModelRef, double tolerance)
 Gets the basic surface and area properties, the principal moments and principal axes of an element. More...
 
int mdlMeasure_surfaceProperties (double *areaP, DPoint3dP centroidP, DPoint3dP momentP, double *iXYP, double *iXZP, double *iYZP, DPoint3dP principalMomentsP, DPoint3dP principalDirectionsP, MSElementDescrP edP, double tolerance)
 Gets the basic surface and area properties, the principal moments and principal axes of an element. More...
 
int mdlMeasure_volumeProperties (double *volumeP, double *areaP, double *closureErrorP, DPoint3dP centroidP, DPoint3dP momentP, double *iXYP, double *iXZP, double *iYZP, DPoint3dP principalMomentsP, DPoint3dP principalDirectionsP, MSElementDescrP edP, double tolerance)
 Gets the basic volume properties, the principal moments, and the principal axes of the volume enclosed by an element. More...
 
int mdlMinDist_betweenElms (DPoint3dP point1, DPoint3dP point2, double *distance, MSElementDescrCP edP1, MSElementDescrCP edP2, DPoint3dCP closestPoint, double inputTolerance)
 Gets the minimum distance and the closest points between two curve element edges. More...
 

Detailed Description

Function Documentation

int mdlMeasure_areaProperties ( double *  perimeterP,
double *  areaP,
DPoint3dP  normalP,
DPoint3dP  centroidP,
DPoint3dP  momentP,
double *  iXYP,
double *  iXZP,
double *  iYZP,
DPoint3dP  principalMomentsP,
DPoint3dP  principalDirectionsP,
MSElementDescrP  edP,
double  tolerance 
)

Gets the basic area properties, principal moments, and principal axes of the area enclosed by an element.

Parameters
[out]perimeterPthe perimeter of the area enclosed by the element in the units of the inverse currtrans.
[out]areaPthe area enclosed by the element, measured in the units of the inverse currtrans squared.
[out]normalPa unit vector normal to the plane of the element.
[out]centroidPthe world coordinate system location of the centroid of the area, in the units of the inverse currtrans.
[out]momentPsecond moments of area, {Ixx, Iyy, Izz}, about axes through the centroid and parallel to the world x, y and z axes.
[out]iXYPproduct of inertia (xy)
[out]iXZPproduct of inertia (xz)
[out]iYZPproduct of inertia (yz)
[out]principalMomentsPthe principal second moments. Principal moments are defined as the extreme values of moments, about the principal axes of the area.
[out]principalDirectionsPan array of three direction vectors which define the principal axes of the area, relative to the centroid. By definition, the principal moments are defined about the principal axes. The principal axes define a plane which is parallel to the plane of the element (and possibly rotated about the element's normal).
[in]edPelement to measure.
[in]tolerancethe stroke tolerance. For curved elements, area properties are computed from a polygonal approximation to the original. tolerance is the maximum distance between the actual curve and the approximating vectors.
Returns
SUCCESS if the area properties are successfully calculated, MDLERR_BADELEMENT if the element and cannot be stroked, or MDLERR_INSFMEMORY if there is insufficient memory to stroke the element.
Remarks
The tolerance and all outputs are measured in units of the inverse current transform. To obtain results in Master Units, call mdlCurrTrans_begin and mdlCurrTrans_masterUnitsIdentity before this function, and mdlCurrTrans_end afterwards.
If a particular property is not of interest, pass NULL for the corresponding output parameter.
The element is assumed to be closed, but this is not checked. Area properties are undefined if the element is not closed.
The element is assumed to be planar, but this is not checked and the element is not projected to a plane if nonplanar. Area properties are not defined if the element is not planar. See mdlMeasure_surfaceProperties.
See also
mdlMeasure_polygonProperties mdlMeasure_linearProperties mdlMeasure_elmDscrArea mdlMeasure_surfaceProperties
int mdlMeasure_areaPropertiesXY ( double *  pArea,
double *  pPerimeter,
DPoint3dP  pCentroid,
DPoint3dP  pMoments,
double *  pIxy,
Dpoint3d pPrincipalMoments,
Dpoint3d pPrincipalDirections,
MSElementDescrP  edP 
)

Compute area, perimeter, centroid, and 2nd moments for the region enclosed by an element.

Z coordinates of the element are ignored – the integrals use only the xy parts of the curves of the element.

Parameters
[out]pAreacomputed area
[out]pPerimetercomputed perimeter
[out]pCentroidcomputed centroid. The z coordinate of this point is at the minimum z of the element.
[out]pMomentssecond moments, in inertia tensor convention, i.e. x,y,z parts are (considering that all z coordiantes are zero for integrations) integrals of (yy dA, xx dA, (xx+yy)dA)
[out]pIxycomputed product of inertia (xy). The additional products IXZ and IYZ are implicitly zero
[out]pPrincipalMomentsthe principal second moments. These are the moments (yydA,xxdA, (xx+yy)dA) relative to axes rotated so mixed moment IXY is zero.
[out]pPrincipalDirectionscomputed directions (unit vectors) for the principal moment x,y,z directions. (The z is always (0,0,1))
[in]edPelement to measure.
Returns
SUCCESS if the area properties are successfully calculated, MDLERR_BADELEMENT if the element and cannot be stroked, or MDLERR_INSFMEMORY if there is insufficient memory to stroke the element.
Remarks
All outputs are measured in units of the inverse current transform. To obtain results in Master Units, call mdlCurrTrans_begin and mdlCurrTrans_masterUnitsIdentity before this function, and mdlCurrTrans_end afterwards.
If a particular property is not of interest, pass NULL for the corresponding output parameter.
The element is assumed to be closed, but this is not checked. Area properties are undefined if the element is not closed.
See also
mdlMeasure_polygonProperties mdlMeasure_linearProperties mdlMeasure_elmDscrArea mdlMeasure_surfaceProperties
StatusInt mdlMeasure_closestPointOnElement ( DPoint3dP  pClosePoint,
ElementHandleCP  pHandle,
DisplayPathCP  pPath,
DPoint3dCP  pSpacePoint 
)

Find the closest point-on-element for given space point.

Parameters
[out]pClosePointcomputed point on element.
[in]pHandlehandle of element.
[in]pPathdisplay path (optional) whose transforms are to be applied to the element to place it for calculation.
[in]pSpacePointspace point.
Returns
ERROR if non-geometric element.
int mdlMeasure_elmDscrArea ( double *  area,
double *  perimeter,
MSElementDescrP  edP 
)

Gets the area and perimeter of a closed element.

Parameters
[out]areaarea of element
[out]perimeterperimeter of element
[in]edPelement to measure
Returns
SUCCESS if the element is successfully measured and MDLERR_NONCLOSEDELM if the element is not closed.
Remarks
Valid closed elements include shapes, ellipses, complex shapes and closed B-spline curves. If a nonplanar element is measured, the area of the elements projection to a plane is returned.
int mdlMeasure_linearProperties ( double *  lengthP,
DPoint3dP  centroidP,
DPoint3dP  momentP,
double *  iXYP,
double *  iXZP,
double *  iYZP,
DPoint3dP  principalMomentsP,
DPoint3dP  principalDirectionsP,
MSElementDescrP  edP,
double  tolerance 
)

Gets the basic linear properties of an element.

Note that "linear" properties are different from "area" properties. Linear properties are the properties of a "wire" along the boundary, not the properties of the area.

Parameters
[out]lengthPthe length of the element in the units of the inverse currtrans.
[out]centroidPthe (x,y,z) location of the centroid of the element, in the units of the inverse currtrans. in the world coordinate system. The centroid will not generally be on the element.
[out]momentPmomentP holds the second moments of the element, {Ixx, Iyy, Izz}, about axes through the centroid and parallel to the world x, y and z axes.
[out]iXYPproduct of inertia (xy)
[out]iXZPproduct of inertia (xz)
[out]iYZPprodudt of inertia (yz)
[out]principalMomentsPthe principal second moments. Principal moments are defined as the extreme values of moments, about the principal axes of the curve.
[out]principalDirectionsPis an array of three direction vectors which define the principal axes of the element in the world coordinate system, relative to the centroid. By definition, the principal moments are defined about the principal axes.
[in]edPelement to measure.
[in]tolerancethe stroke tolerance. For curved elements, area properties are computed from a polygonal approximation to the original. tolerance is the maximum distance between the actual curve and the approximating vectors.
Returns
SUCCESS.
Remarks
The tolerance and all outputs are measured in units of the inverse current transform. To obtain results in Master Units, call mdlCurrTrans_begin and mdlCurrTrans_masterUnitsIdentity before this function, and mdlCurrTrans_end afterwards.
The element is assumed to be non-closed, but is not required to be.
edP is not required to be planar.
If a particular property is not of interest, pass NULL for the corresponding output parameter.
See also
mdlMeasure_areaProperties
int mdlMeasure_linearPropertiesXY ( double *  lengthP,
DPoint3dP  centroidP,
double *  iXXP,
double *  iYYP,
double *  iXYP,
Dpoint3d principalMomentsP,
Dpoint3d principalDirectionsP,
MSElementDescrP  edP 
)

Compute length, centroid, and 2nd moments of the curve, treated as a WIRE of uniform density at z coordinate equal to the minimim z on the element.

Parameters
[out]lengthPlength
[out]centroidPcentroid
[out]iXXPproduct of xx relative to centroid
[out]iYYPproduct of yy relative to centroid.
[out]iXYPproduct of x,y relative to centroid
[out]principalMomentsP2nd moments wrt principal diretions
[out]principalDirectionsPprincipal directions
[in]edPcurve geometry
Remarks
All outputs are measured in units of the inverse current transform. To obtain results in Master Units, call mdlCurrTrans_begin and mdlCurrTrans_masterUnitsIdentity before this function, and mdlCurrTrans_end afterwards.
All integrals are computed to high precision.
The element is assumed to be non-closed, but is not required to be.
edP is not required to be planar.
If a particular property is not of interest, pass NULL for the corresponding output parameter.
See also
mdlMeasure_areaProperties
Returns
SUCCESS.
int mdlMeasure_polygonArea ( double *  area,
double *  perimeter,
DPoint3dP  points,
int  numPoints 
)

gets the area and perimeter of a polygon.

Parameters
[out]areaarea of element
[out]perimeterperimeter of element
[in]pointsarray of points that comprise the polygon
[in]numPointsnumber of points
Returns
SUCCESS if the area is successfully calculated and MDLERR_NONCLOSEDELM if the polygon is not closed.
Remarks
The polygon must be closed (first and last points identical). If the polygon is nonplanar, the area of the polygon's projection to a plane is calculated.
int mdlMeasure_polygonProperties ( double *  perimeterP,
double *  areaP,
DPoint3dP  normalP,
DPoint3dP  centroidP,
DPoint3dP  momentP,
double *  iXYP,
double *  iXZP,
double *  iYZP,
DPoint3dP  points,
int  nPoints 
)

Gets the basic area properties of a polygon.

Parameters
[out]perimeterPthe perimeter of the area enclosed by the polygon in master units.
[out]areaPthe area enclosed by the polygon, measured in master units squared.
[out]normalPa unit vector normal to the plane of the polygon.
[out]centroidPthe (x, y, z) location of the centroid of the area, in master units in the world coordinate system.
[out]momentPthe second moments of area, {Ixx, Iyy, Izz}, about axes through the centroid and parallel to the world x, y and z axes. The fundamental units are master units.
[out]iXYPproduct of inertia (xy)
[out]iXZPproduct of inertia (xz)
[out]iYZPproduct of inertia (yz)
[in]pointspoints defining closed polygon
[in]nPointsnumber of points
Returns
SUCCESS
Remarks
If a particular property is not of interest, pass NULL for the corresponding output parameter.
The polygon is assumed to be closed, but that is not checked. Area properties are undefined if the polygon is not closed.
The polygon is assumed to be planar, but this is not checked and the polygon is not projected to a plane if nonplanar. Area properties are not defined if the polygon is not planar.
int mdlMeasure_surfaceProperties ( double *  areaP,
DPoint3dP  centroidP,
DPoint3dP  momentP,
double *  iXYP,
double *  iXZP,
double *  iYZP,
DPoint3dP  principalMomentsP,
DPoint3dP  principalDirectionsP,
MSElementDescrP  edP,
double  tolerance 
)

Gets the basic surface and area properties, the principal moments and principal axes of an element.

The element need not be planar (but it can be) and need not be closed.

Remarks
This function is the same as mdlMeasure_surfaceProperties2 with ASSUMED resultModelRef as ACTIVEMODEL.
Parameters
[out]areaPsurface area of the element.
[out]centroidPlocation of the centroidPof the surface. The centroid will not generally be on the surface.
[out]momentPthe second moments, {Ixx, Iyy, Izz}, about axes through the centroid and parallel to the world x, y and z axes. The iXYP, iXZP and iYZP parameters are the Ixy, Ixz and Iyz products of inertia with respect to these axes. Together, these six parameters define the element's inertia tensor (which is symmetric).
[out]iXYPproduct of inertia (xy)
[out]iXZPproduct of inertia (xz)
[out]iYZPproduct of inertia (yz)
[out]principalMomentsPthe principal second moments.
[out]principalDirectionsPprincipal axes
[in]edPelement to measure.
[in]tolerancethe meshing tolerance. For curved elements, area properties are computed from a polygonal approximation to the original. tolerance is the maximum distance between the actual curve and the approximating vectors. The accuracy of the properties improves as the tolerance becomes smaller.
Returns
SUCCESS if the surface properties are successfully calculated, MDLERR_BADELEMENT if the element cannot be meshed, or MDLERR_INSFMEMORY if there is insufficient memory to mesh the element.
Remarks
The tolerance and all outputs are measured in units of the inverse current transform. To obtain results in Master Units, call mdlCurrTrans_begin and mdlCurrTrans_masterUnitsIdentity before this function, and mdlCurrTrans_end afterwards.
If a particular property is not of interest, pass NULL for the corresponding output parameter.
Principal moments are defined as the extreme values of the second moments about the principal axes of the surface. By definition, the products of inertia become zero about the principal axes. principalDirectionsP is an array of three direction vectors which define the principal axes of the volume in the world coordinate system, relative to the centroid. The principal axes are mutually orthogonal and describe how the inertia tensor is rotated to its diagonalized, extreme form.
The prototype for the stopFunc is int (*stopFunc)(int, int). Pass 0 for both ints. Return zero to continue, any other value to abort.
See also
mdlMeasure_volumeProperties
int mdlMeasure_surfaceProperties2 ( double *  areaP,
DPoint3dP  centroidP,
DPoint3dP  momentP,
double *  iXYP,
double *  iXZP,
double *  iYZP,
DPoint3dP  principalMomentsP,
DPoint3dP  principalDirectionsP,
MSElementDescrP  edP,
DgnModelRefP  resultModelRef,
double  tolerance 
)

Gets the basic surface and area properties, the principal moments and principal axes of an element.

The element need not be planar (but it can be) and need not be closed.

Parameters
[out]areaPsurface area of the element.
[out]centroidPlocation of the centroidPof the surface. The centroid will not generally be on the surface.
[out]momentPthe second moments, {Ixx, Iyy, Izz}, about axes through the centroid and parallel to the world x, y and z axes. The iXYP, iXZP and iYZP parameters are the Ixy, Ixz and Iyz products of inertia with respect to these axes. Together, these six parameters define the element's inertia tensor (which is symmetric).
[out]iXYPproduct of inertia (xy)
[out]iXZPproduct of inertia (xz)
[out]iYZPproduct of inertia (yz)
[out]principalMomentsPthe principal second moments.
[out]principalDirectionsPprincipal axes
[in]edPelement to measure.
[in]resultModelRefmodelref where results are needed. Only affects Brep scaling.
[in]tolerancethe meshing tolerance. For curved elements, area properties are computed from a polygonal approximation to the original. tolerance is the maximum distance between the actual curve and the approximating vectors. The accuracy of the properties improves as the tolerance becomes smaller.
Returns
SUCCESS if the surface properties are successfully calculated, MDLERR_BADELEMENT if the element cannot be meshed, or MDLERR_INSFMEMORY if there is insufficient memory to mesh the element.
Remarks
The tolerance and all outputs are measured in units of the inverse current transform. To obtain results in Master Units, call mdlCurrTrans_begin and mdlCurrTrans_masterUnitsIdentity before this function, and mdlCurrTrans_end afterwards.
If a particular property is not of interest, pass NULL for the corresponding output parameter.
Principal moments are defined as the extreme values of the second moments about the principal axes of the surface. By definition, the products of inertia become zero about the principal axes. principalDirectionsP is an array of three direction vectors which define the principal axes of the volume in the world coordinate system, relative to the centroid. The principal axes are mutually orthogonal and describe how the inertia tensor is rotated to its diagonalized, extreme form.
The prototype for the stopFunc is int (*stopFunc)(int, int). Pass 0 for both ints. Return zero to continue, any other value to abort.
See also
mdlMeasure_volumeProperties
int mdlMeasure_volumeProperties ( double *  volumeP,
double *  areaP,
double *  closureErrorP,
DPoint3dP  centroidP,
DPoint3dP  momentP,
double *  iXYP,
double *  iXZP,
double *  iYZP,
DPoint3dP  principalMomentsP,
DPoint3dP  principalDirectionsP,
MSElementDescrP  edP,
double  tolerance 
)

Gets the basic volume properties, the principal moments, and the principal axes of the volume enclosed by an element.

Parameters
[out]volumePthe volume enclosed by the element.
[out]areaPthe surface area of the volume enclosed by the element.
[out]closureErrorPset to a quantitative measurement ranging from zero to one of element closure error.
[out]centroidPthe location of the centroid of the volume. The centroid will not necessarily be inside the volume.
[out]momentPmomentP returns the second moments, {Ixx, Iyy, Izz}, about axes through the centroid and parallel to the world x, y and z axes. The iXYP, iXZP and iYZP parameters are the Ixy, Ixz and Iyz products of inertia with respect to these axes. Together, these six parameters define the element's inertia tensor (which is symmetric).
[out]iXYPproduct of inertia (xy)
[out]iXZPproduct of inertia (xz)
[out]iYZPproduct of inertia (yz)
[out]principalMomentsPthe principal second moments.
[out]principalDirectionsPprincipal axes
[in]edPthe element to measure.
[in]toleranceFor curved elements, volume properties are computed from a polygonal approximation to the original. tolerance is the maximum distance between the actual surface and the approximating vectors. The accuracy of the volume properties therefore improves as the tolerance becomes smaller.
Returns
SUCCESS if the volume properties are successfully calculated, MDLERR_BADELEMENT if the element cannot be meshed, MDLERR_INSFMEMORY if there is insufficient memory to mesh the element, or MDLERR_NONCLOSEDELM if the element is not closed.
Remarks
The tolerance and all outputs are measured in units of the inverse current transform. To obtain results in Master Units, call mdlCurrTrans_begin and mdlCurrTrans_masterUnitsIdentity before this function, and mdlCurrTrans_end afterwards.
If a particular property is not of interest, pass NULL for the corresponding output parameter.
Volume properties are not defined if the element is not closed. In most cases, this function returns an error status and does not return any output parameters if the element is not closed. If the returned status is SUCCESS, check the value returned in closureErrorP for a confidence measure. Note that a "flat" (planar) element is not closed, so that mdlMeasure_volumeProperties is mutually exclusive with mdlMeasure_areaProperties.
The closure error is essentially a "no-confidence" statistic for the output parameters. Loosely defined, closureError is the proportion of the volume's total surface area which is perforated by gaps or openings. A zero or insignificant closure error indicates that the element should be considered closed, while a significant closure error indicates that the element is not closed and no volume properties can be calculated for it. Specifically, if the closure error is less than or equal to 0.1, the function will return the output parameters and report SUCCESS; otherwise, if the closure error is greater than 0.1, the function will return an error status of MDLERR_NONCLOSEDELM and will not return the output parameters. As a rule of thumb, even when the function returns SUCCESS, a closure error greater than 0.01 suggests that the element is not closed and suggests low confidence in the returned volume properties.
Principal moments are defined as the extreme values of the second moments about the principal axes of the surface. By definition, the products of inertia become zero about the principal axes. principalDirectionsP is an array of three direction vectors which define the principal axes of the volume in the world coordinate system, relative to the centroid. The principal axes are mutually orthogonal and describe how the inertia tensor is rotated to its diagonalized, extreme form.
See also
mdlMeasure_surfaceProperties
int mdlMinDist_betweenElms ( DPoint3dP  point1,
DPoint3dP  point2,
double *  distance,
MSElementDescrCP  edP1,
MSElementDescrCP  edP2,
DPoint3dCP  closestPoint,
double  inputTolerance 
)

Gets the minimum distance and the closest points between two curve element edges.

Parameters
[out]point1minimum point on element 1
[out]point2minimum point on element 2
[out]distanceminimum distance
[in]edP1first element
[in]edP2second element
[in]closestPointpoint close to minima
[in]inputToleranceUNUSED. Formerly tolerance for approximating curved elements. All calculations are currently done to maximium precision.
Remarks
The distance value is the distance between point1 and point2. If the elements intersect, the intersection points are returned and distance is zero.
This function was previously named mdlMeasure_minimumDistance. Only the name has changed; the functionality is unchanged.
This function does not support surface and solid geometry; only elements that represent open/closed paths and planar regions are supported.
Returns
SUCCESS if the minima is successfully calculated.
See also
mdlBspline_minimumDistanceToCurve mdlBspline_minimumDistanceToSurface

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.