Computed Properties of Polylines

The parameter of a two-dimensional or three-dimensional polyline is the relative factor measured from 0.0 to 1.0 for each segment. The value 0.0 defines the start point, and the value 1.0 defines the end point of a segment. A value between 0.0 and 1.0 defines a point within the segment. When a segment is linear or a spline, the parameter defines the distance related to the segment length. When a segment is circular, the parameter defines the angle related to the segment total angle. The parameter determines the significant properties computed at its value (features). In the following examples, the pPL variable stores a pointer to the two-dimensional or three-dimensional polyline object.

Start and end parameters

The start and end parameters define the available range of variation. The start parameter defines the start point of the first segment of the polyline and equals 0.0. The end parameter defines the final point of the last segment of the polyline and equals the number of segments multiplied by 1.0. When a polyline curve is open, the final point is the last vertex. When a polyline curve is closed, the final point is the first vertex. A value between the start and end parameters defines a point on the polyline curve. Each integer parameter value (1, 2, 3, etc.) defines the corresponding vertex.

To get the start parameter, use the getStartParam() method which requires a reference to a variable of the double type in which the start parameter value must be saved as an argument and returns the start value through this argument or an error code as a result. For example:


double vStartParam;
OdResult eRes = pPL->getStartParam(vStartParam);
if(eRes == eOk)
  odPrintConsoleString(L"\nStart parameter = %g", vStartParam);

To get the end parameter, use the getEndParam() method which requires a reference to a variable of the double type in which the end parameter value must be saved as an argument and returns the end value through this argument or an error code as a result. For example:


double vEndParam;
OdResult eRes = pPL->getEndParam(vEndParam);
if(eRes == eOk)
  odPrintConsoleString(L"\nEnd parameter = %g", vEndParam);

Start and end points

The start and end points are computed at a parameter in three-dimensional coordinates. The start point is computed at the start parameter and coincides with the first vertex. The end point is computed at the end parameter and coincides with the last vertex when the polyline is open, or it coincides with the first vertex when the polyline is closed.

To get the start point, use the getStartPoint() method which requires a reference to a variable of the OdGePoint3d type in which the start point instance must be saved as an argument and returns the computed three-dimensional point through this argument or an error code as a result. For example:


OdGePoint3d start;
OdResult eRes = pPL->getStartPoint(start);
if(eRes == eOk)
  odPrintConsoleString(L"\nStart point = (%g,%g,%g)", start.x, start.y, start.z);

To get the end point, use the getEndPoint() method which requires a reference to a variable of the OdGePoint3d type in which the end point instance must be saved as an argument and returns the computed three-dimensional point through this argument or an error code as a result. For example:


OdGePoint3d end;
OdResult eRes = pPL->getEndPoint(end); 
if(eRes == eOk)
  odPrintConsoleString(L"\nEnd point = (%g,%g,%g)", end.x, end.y, end.z);

First and second derivatives

The first and second derivatives for a point of a polyline curve are computed at a parameter as vectors in three-dimensional coordinates. Derivatives are changed along the curve relative to the linear, circular or spline segments. The parameter must be between the start and end values. When the parameter value is out of range, errors occur.

To get the first derivative, use the getFirstDeriv() method which requires a parameter value specifying a point on the polyline curve as the first argument (double type), requires a reference to a variable (OdGeVector3d type) in which the first derivative vector instance must be saved as the second argument, and returns the computed three-dimensional vector through the second argument or an error code as a result. For example:


double vParam;
OdResult eRes;
OdGeVector3d vecFirst;
for(vParam = vStartParam ; vParam <= vEndParam ; vParam += 0.1)
{
  eRes = pPL->getFirstDeriv(vParam, vecFirst);
  if(eRes == eOk) 
    odPrintConsoleString(L"\nFirst derivative vector (at %g) = (%g,%g,%g)", vParam, ecFirst.x, vecFirst.y, vecFirst.z);
}

To get the second derivative, use the getSecondDeriv() method which requires a parameter value specifying a point on the polyline curve as the first argument (double type), requires a reference to a variable (OdGeVector3d type) in which the second derivative vector instance must be saved as the second argument, and returns the computed three-dimensional vector through the second argument or an error code as a result. For example:


double vParam;
OdResult eRes;
OdGeVector3d vecSecond;
for(vParam = vStartParam ; vParam <= vEndParam ; vParam += 0.1)
{
  eRes = pPL->getSecondDeriv(vParam, vecSecond);
  if(eRes == eOk)
    odPrintConsoleString(L"\nSecond derivative vector (at %g) = (%g,%g,%g)", vParam, vecSecond.x, vecSecond.y, vecSecond.z);
}

Distance and parameter

The distance along a polyline curve can be computed from the first vertex to a point at a parameter. The object takes into account total lengths of those segments which are previous to the segment on which the point lies. The end parameter defines the total length of the polyline curve. An integer parameter value between the start and end parameter defines the total length of corresponding segments. Polylines calculate the line length, arc length, or spline length subject to the segment type. The polyline object allows calculating the distance at a parameter and the parameter at a distance.

To get the distance at a parameter, use the getDistAtParam() method which requires a parameter value specifying a point on the polyline curve as the first argument (double type), requires a reference to a variable (double type) in which the distance value must be saved as the second argument, and returns the distance through the second argument or an error code as a result. The parameter must be between the start and end values, otherwise errors occur. For example:


double vParam, vLength;
OdResult eRes;
for(vParam = vStartParam ; vParam <= vEndParam ; vParam += 0.1)
{
  eRes = pPL->getDistAtParam(vParam, vLength);
  if(eRes == eOk)
    odPrintConsoleString(L"\nLength (at %g) = %g", vParam, vLength);
}

To compute the total length, use the end parameter value. For example:


double vTotalLength;
OdResult eRes; 
eRes= pPL->getDistAtParam(vEndParam, vTotalLength);
if(eRes == eOk)
  odPrintConsoleString(L"\nPolyline length = %g", vTotalLength);

To compute the length of each segment, use integer parameter values. For example:


int vNum, vSegments;
double vLength, vSumLength;
OdResult eRes;
eRes = pPL->getDistAtParam(vEndParam, vLength);
if(eRes == eOk)
{
  vSegments = (int)vLength;
  for(vSumLength = 0.0, vNum = 1 ; vNum <= vSegments ; vNum++, vSumLength += vLength)
  {
    eRes = pPL->getDistAtParam((double)vNum, vLength);
    if(eRes == eOk)
      odPrintConsoleString(L"\nSegment(%d) length = %g", vNum, (vLength - vSumLength));
  }
}

To get the parameter at a distance, use the getParamAtDist() method which requires a positive double value specifying the displacement along a polyline curve as the first argument (double type), a reference to a variable (double type) in which the parameter value must be saved as the second argument, and returns the parameter value corresponding to the distance through the second argument or an error code as a result. The distance must be between zero and the total length, otherwise errors occur. For example:


double vParam, vLength;
OdResult eRes;
eRes = pPL->getEndParam(vParam);
if(eRes == eOk)
{
  eRes = pPL->getDistAtParam(vParam, vLength);
  if(eRes == eOk)
    while(vLength > 0.0)
    {
      odPrintConsoleString(L"\nParameter (at %g) = %g", vLength, vParam);
      vLength -= 0.3;
      eRes = pPL->getParamAtDist(vLength, vParam);
      if(eRes != eOk) break;
    }
}

Point and parameter

A point on a polyline curve can be computed at a parameter in three-dimensional coordinates. The polyline objects allow calculating the point at a parameter and the parameter at a point.

To get the point at a parameter, use the getPointAtParam() method which requires a parameter value as the first argument of the double type, requires a reference to a variable of the OdGePoint3d type in which the point instance must be saved as the second argument, and returns the computed three-dimensional point through the second argument or an error code as a result. When the parameter value is out of range, errors occur. For example:


double vParam;
OdResult eRes;
OdGePoint3d point;

for(vParam = 0.0 ; vParam <= 1.0 ; vParam += 0.1)
{
  if((eRes = pPL->getPointAtParam(vParam , point)) == eOk)
    odPrintConsoleString(L"\nPoint(%d) = (%g,%g,%g)", vParam, point.x, point.y, point.z);
}

To get the parameter at a point, use the getParamAtPoint() method which requires a point instance of the OdGePoint3d type as the first argument, a reference to a variable of the Double type in which the parameter value must be saved as the second argument, and returns the parameter corresponding to the point through the second argument or an error code as a result. When the point is not placed on a polyline curve, errors occur. For example:


double vParam;
OdResult eRes;
OdGePoint3d point;

pPL->getEndPoint(point); 
if((eRes = pPL->getParamAtPoint(point, vParam)) == eOk)
  odPrintConsoleString(L"\nParameter(end) = %g", vParam);

pPL->getStartPoint(point); 
if((eRes = pPL->getParamAtPoint(point, vParam)) == eOk)
  odPrintConsoleString(L"\nParameter(start) = %g", vParam);

Area

The two-dimensional polyline object calculates the area assuming that the curve is closed. When a polyline curve is open, the object calculates the area between the polyline curve and a line connecting the first and last vertex. The three-dimensional polyline object calculates the area if all vertices lie in the same plane (when it is planar).

To get the area, use the getArea() method which requires a reference to a variable of the double type in which the area value must be saved as an argument and returns the area value through this argument or an error code as a result. For example: