Editing Segments of Polylines

A set of lines and arcs that forms the shape of a polyline are called segments. A polyline consists of connected segments, so that the end of the current segment is the start of the next segment. The number of segments either equals the number of vertices for a closed polyline or the number of vertices minus one for an open polyline.

Two-dimensional polylines use the following parameters for specifying a segment: getting and setting the bulge, getting and setting the start and end widths, getting and setting the tangent, and switching and checking the tangent used for circular segments. A three-dimensional polyline does not use bulges, tangents, and widths. The available properties depend on the segment type.

Structurally, a two-dimensional or three-dimensional polyline contains parameters for its segments in independent two-dimensional or three-dimensional vertex entities that are stored in their own containers and provide access to a segment using an iterator. To work with segments of a two-dimensional or three-dimensional polyline, the program must first find a segment in the container by the vertex that begins the segment, then get a pointer to its instance, and then change its properties using the interface of the corresponding two-dimensional or three-dimensional vertex entity.

In the following examples, the p2dPL variable stores a pointer to a two-dimensional polyline object.

Segment bulge

A bulge is a parameter that specifies the curvature of circular arcs as the ratio between the length (D) of the linear segment from the start point to the end point and the length (H) of the perpendicular segment from the middle point of the linear segment to the middle point on the circular segment (B = 2H/D). A positive bulge rotates the arc from the start point to the end point counterclockwise. A negative bulge rotates the arc from the start point to the end point clockwise.

When a bulge is zero (0.0), the segment is a straight line. When a bulge is one (1.0), the segment is a half-circle.

The property defines a bulge for each segment of a polyline. A value other than zero specifies a circular segment. A linear segment either has a zero bulge value or does not use it according to the segment type. The initial value is zero by default.

To get the bulge for a segment of a two-dimensional polyline, get the two-dimensional vertex entity using an iterator or object ID, and use the bulge() method of this vertex which returns the bulge value as a double type. For example:


double  bulge;
OdInt16 index;
OdDbObjectIteratorPtr itVertex = p2dPL->vertexIterator();

for(itVertex->start(), index = 0 ; !itVertex->done() ; index++, itVertex->step())
{
  bulge = ((OdDb2dVertexPtr)itVertex->entity())->bulge();

  odPrintConsoleString(L"\nBulge(%d) = %g", index, bulge);
}

To set the bulge for a segment of a two-dimensional polyline, get the two-dimensional vertex entity using an iterator or object ID, and use the setBulge() method of this vertex which requires a bulge value as an argument of a double type. For example:


OdInt16 sign;
OdDbObjectIteratorPtr itVertex = p2dPL->vertexIterator();

itVertex->start();
p2dPL->openVertex(itVertex->objectId(), OdDb::kForWrite)->setBulge(0.5);

for(itVertex->step(), sign = (-1) ; !itVertex->done() ; sign *= (-1), itVertex->step())
{
  p2dPL->openVertex(itVertex->objectId(), OdDb::kForWrite)->setBulge(sign * 0.5);
}

Segment width

Segments of a planar polyline can have a constant or variable width. The segment shape is defined by the start width and end width. When the start and end widths are equal, the segment has a consistent shape. When the start and end widths are different, the segment has a taper shape. When the start and end widths are zero, the segment is a thin line. Three-dimensional polylines do not have this feature.

The property defines the widths for each segment of a polyline. The initial values are zero by default.

To get the widths for a segment of a two-dimensional polyline, get the two-dimensional vertex entity using an iterator or object ID and use the startWidth() method and endWidth() method of this vertex, which return the width value as a double type. For example:


double  width_start, width_end;
OdInt16 index;
OdDbObjectIteratorPtr itVertex = p2dPL->vertexIterator();

for(itVertex->start(), index = 0 ; !itVertex->done() ; index++, itVertex->step())
{
  width_start = ((OdDb2dVertexPtr)itVertex->entity())->startWidth();
  width_end = ((OdDb2dVertexPtr)itVertex->entity())->endWidth();

  odPrintConsoleString(L"\nWidth (%d) from (%g) to (%g)", index, width_start, width_end);
}

To set the widths for a segment of a two-dimensional polyline, get the two-dimensional vertex entity using an iterator or object ID and use the setStartWidth() method and setEndWidth() method of this vertex, which require a width value as an argument of a double type. For example:


double  start, end, width;
OdDbObjectIteratorPtr itVertex = p2dPL->vertexIterator();

itVertex->start();
OdDb2dVertexPtr pVertex = p2dPL->openVertex(itVertex->objectId(), OdDb::kForWrite);

pVertex->startWidth(0.5);
pVertex->endWidth(0.2);

for(itVertex->step(), start = 0.2, end = 1.2 ; !itVertex->done() ; itVertex->step())
{
  pVertex = p2dPL->openVertex(itVertex->objectId(), OdDb::kForWrite);
  pVertex->startWidth(start);
  pVertex->endWidth(end);
  width = start;  start = end;  end = width;
}

Default widths

A two-dimensional polyline stores the default start width and default end width and uses them for reading and writing the dxf-presentation in file operations when the corresponding group code in a two-dimensional vertex entity is absent. The initial values are zero by default. Three-dimensional polylines do not have this feature.

To get the default widths for segments of a two-dimensional polyline, use the defaultStartWidth() method and defaultEndWidth() method which return the start and end widths as a double type. For example:


double width_start = p2dPL-defaultStartWidth();
double width_end = p2dPL->defaultEndWidth();

odPrintConsoleString(L"\nDefault widths: start = %g, end = %g", width_start, width_end);

To set the default widths for segments of a two-dimensional polyline, use the setDefaultStartWidth() method and setDefaultEndWidth() method which require a width value as an argument (double type). For example:


p2dPL->setDefaultStartWidth(0.25);
p2dPL->setDefaultEndWidth(1.05);

Tangent

A tangent is an angle in radians between the polyline OCS X-axis and the tangent direction to the segment curve at the vertex position. A tangent is optionally used only for circular segments of a two-dimensional polyline. Three-dimensional polylines do not have tangents. A two-dimensional polyline can use the tangent together with bulge or ignore it in its segments. Tangents are applied by pairs of adjacent vertices for curve-fit approximation. When adjacent tangents are co-directional or opposite-directional to the OCS X-axis, segments are linear. When adjacent tangents are co-directional at a non-zero angle to the OCS X-axis, segments are circular and the angle influences the bulge (tangent = ±45º defines bulge = 0.5, tangent = ±90º defines bulge = 1.0 half-circle). The initial value is zero by default.

To get a tangent for a segment of a two-dimensional polyline, get the two-dimensional vertex entity using an iterator or object ID, and use the tangent() method of this vertex which returns a tangent value in radians as a double type. For example:


double  tangent;
OdInt16 index;
OdDbObjectIteratorPtr itVertex = p2dPL->vertexIterator();

for(itVertex->start(), index = 0 ; !itVertex->done() ; index++, itVertex->step())
{
  tangent = ((OdDb2dVertexPtr)itVertex->entity())->tangent();

  odPrintConsoleString(L"\nTangent(%d) = %g", index, tangent);
}

To set a tangent for a segment of a two-dimensional polyline, get the two-dimensional vertex entity using an iterator or object ID, and use the setTangent() method of this vertex which requires a tangent value in radians as an argument (double type). For example:


OdDbObjectIteratorPtr itVertex = p2dPL->vertexIterator();

for(itVertex->start() ; !itVertex->done() ; itVertex->step())
{
  p2dPL->openVertex(itVertex->objectId(), OdDb::kForWrite))->setTangent(0.25);
}

To check whether a segment of a two-dimensional polyline uses a tangent, get the two-dimensional vertex entity using an iterator or object ID, and use the isTangentUsed() method which returns "true" if this segment uses a tangent for fitting or "false" if this segment does not use a tangent. For example:


bool bUse;
OdInt16 index;
OdDbObjectIteratorPtr itVertex = p2dPL->vertexIterator();

for(itVertex->start(), index = 0 ; !itVertex->done() ; index++, itVertex->step())
{
  bUse = ((OdDb2dVertexPtr)itVertex->entity())->isTangentUsed();

  odPrintConsoleString(L"\nSegment(%d) %s the tangent", index, ((bUse) ? L"uses" : "ignores"));
}

To switch usage of a tangent for a segment of a two-dimensional polyline, get the two-dimensional vertex entity using an iterator or object ID, and use either the useTangent() method to enable tangent usage or use the ignoreTangent() method to disable the tangent (tangents are ignored). For example:


OdDbObjectIteratorPtr itVertex = p2dPL->vertexIterator();

// Enable tangents
for(itVertex->start() ; !itVertex->done() ; itVertex->step())
{
  p2dPL->openVertex(itVertex->objectId(), OdDb::kForWrite)->useTangent();
}

// Disable tangents
for(itVertex->start() ; !itVertex->done() ; itVertex->step())
{
  p2dPL->openVertex(itVertex->objectId(), OdDb::kForWrite)->ignoreTangent();
}

Note: A zero tangent value indicates the direction along the polyline OCS X-axis, and it is used.

Segment bulge

Segment width

Default widths

Tangent

See Also