Contour
This object represents a single vector within the application. Open and closed vectors, arcs, circles, all are based on a Contour with one or more spans. The Contour is represented as a list of spans, with a span being either a Line, Arc or Bezier.
Constructors
Contour(tolerance)
A new contour is created within a Lua script using this constructor method e.g
local contour = Contour(0.0)
Tolerance - double - tolerance to use when performing operations - use 0.0 for default
Properties
.Area
Read Only - double - unsigned area of contour
.BoundingBox2D
Read Only - Box2D - 2D bounding box for contour
.BoundingBox3D
Read Only - - Box3D - 3D bounding box for contour
.Count
Read Only - integer - number of spans in the contour
.ContainsArcs
Read Only - bool - true if contour contains 1 or more arcs - may contain other span types as well.
.ContainsBeziers
Read Only - bool - true if contour contains 1 or more beziers - may contain other span types as well.
.CentreOfGravity
Read Only - Point2D - the centre of gravity for the contour
.EndPoint3D
Read Only - Point3D - the 3D position of the contour end point - if contour is closed this will be the same as the start point.
.EndPoint2D
Read Only - Point2D - the 2D position of the contour end point - if contour is closed this will be the same as the start point.
.IsClockwise
Read Only - bool - Direction of the contour, this is found from the signed area of the contour. For an open contour, it is assumed to be closed with a straight line when calculating the area.
.IsAntiClockwise
Read Only - bool - Direction of the contour, this is found from the signed area of the contour. For an open contour, it is assumed to be closed with a straight line when calculating the area.
.IsCW
Read Only - bool - Direction of the contour, this is found from the signed area of the contour. For an open contour, it is assumed to be closed with a straight line when calculating the area.
.IsCCW
Read Only - bool - Direction of the contour, this is found from the signed area of the contour. For an open contour, it is assumed to be closed with a straight line when calculating the area.
.IsClosed
Read Only - bool - True if the contour is closed
.IsEmpty
Read Only - bool - true if contour is empty - no spans
.IsOpen
Read Only - bool - True if contour is open
.IsSinglePoint
Read Only - bool - true if contour is just a single point
.Length
Read Only - double - length of contour
.StartPoint3D
Read Only - Point3D - the 3D position of the contour start point
.StartPoint2D
Read Only - Point2D - the 2D position of the contour start point
.Tolerance
Read Write - double - the tolerance value used when polygonising beziers and arcs. This should not be changed without very good reason.
Methods
:AppendPoint(double x, double y)
Set the 2D starting point for the contour. Returns true if point set OK else false. This method should only be called on an EMPTY contour. The Z value for the point defaults to 0.0
- x - double - X value for start point of contour
- y - double - Y value for start point of contour
:AppendPoint(double x , double y, double z)
Set the 3D starting point for the contour. Returns true if point set OK else false. This method should only be called on an EMPTY contour.
- x - double - X value for start point of contour
- y - double - Y value for start point of contour
- z - double - Z value for start point of contour
:AppendPoint(Point2D pt2d)
Set the 2D starting point for the contour. Returns true if point set OK else false. This method should only be called on an EMPTY contour. The Z value for the point defaults to 0.0
- Pt2d - Point2D - 2D coordinate for start point of contour
:AppendPoint(Point3D pt3d)
Set the 3D starting point for the contour. Returns true if point set OK else false. This method should only be called on an EMPTY contour.
- Pt2d - Point3D - 3D coordinate for start point of contour
:ArcTo (Point2D end_pt2d, Point2D center_pt2d, boolccw)
Append an arc span from the current end point of the contour to the passed position. Returns true if span added t OK else false. The arc is defined by the existing end point in the contour, the center point of the arc and the direction of rotation. Arcs > 180 degrees will be split into two arcs.
- end_pt2d - Point2D - 2D coordinate for end point of arc
- center_pt2d - Point2D - 2D coordinate for center point of arc
- ccw - bool - true if arc is counter clockwise from start point else clockwise
:ArcTo (Point2D end_pt2d, bool bulge)
Append an arc span from the current end point of the contour to the passed position. Returns true if span added t OK else false. This method should only be called on a non-empty contour. Arcs > 180 degrees will be split into two arcs.
- end_pt2d - Point2D - 2D coordinate for end point of arc bulge - double - signed bulge factor for arc
:ArcTo( Point3D end_pt3d, bool bulge)
Append an arc span from the current end point of the contour to the passed position. Returns true if span added OK else false. This method should only be called on a non-empty contour. Arcs > 180 degrees will be split into two arcs.
- end_pt3d - Point3D - 3D coordinate for end point of arc - arcs must be in XY plane
- bulge - double - signed bulge factor for arc
:AppendContour( Contour ctr)
Append passed contour to the end of this contour. Returns true if contour appended OK, false if contour wouldn’t append within tolerance
- ctr - Contour - Contour to append
:AppendSpan( Span span)
Append passed span to the end of this contour. Returns true if span appended OK, false if span wouldn’t append within tolerance
- span - Span – Span to append
:AppendSpanAsLines( Span span, double tolerance)
Append passed span as line spans - passed span is NOT modified or adopted. Returns true if span appended OK, false if span wouldn’t append within tolerance
- span - Span - Span to append polygonised version of
- tolerance - double - tolerance to use when converting span to lines
:BezierTo( Point2D end_pt2d, Point2D ctrl_1_2d, Point2D ctrl_2_2d)
Append a bezier span from the current end point of the contour to the passed position. Returns true if span added OK else false. All points must have same z value
- end_pt2d - Point2D - 2D coordinate for end point of bezier
- ctrl_1_2d - Point2D - 2D coordinate for first control point of bezier
- ctrl_2_2d - Point2D - 2D coordinate for second control point of bezier
:BezierTo( Point3D end_pt3d, Point2D ctrl_1_2d, Point2D ctrl_2_2d)
Append a bezier span from the current end point of the contour to the passed position. Returns true if span added OK else false. All points must have same z value
- end_pt3d - Point3D - 3D coordinate for end point of bezier
- ctrl_1_2d – Point2D - 2D coordinate for first control point of bezier
- ctrl_2_2d – Point2D - 2D coordinate for second control point of bezie
:CanAppendContour( Contour ctr)
Return true if passed contour can be appended onto the end of this contour
- ctr - Contour - Contour to check if can append
:CanAppendSpan( Span span)
Return true if passed span can be appended onto the end of this contour
- span - Span - Span to check if can append
:Clone()
Return a new Contour which is an exact copy of this one.
:CreateTolerancedCopy(double tolerance)
Return a new Contour which has been toleranced (simplified) to the passed value.
- NOTE: The contour must consist of just line spans, it must NOT contain beziers or arcs, the properties .ContainsBeziers and .ContainsArcs must be false.
- tolerance - double - tolerance to use when simplifying contour.
:CreatePolygonizedCopy( double tolerance, double max_line_len)
Return a new Contour which has been toleranced (simplified) to the passed value. Any bezier or arc spans are polygonized before tolerancing. The max_line_len parameter can be used to limit the maximum length of a tolerance span.
- tolerance - double - tolerance to use when simplifying contour.
- 0.0 means use default max_line_len - double - maximum length of a tolerance span, 0.0 means no limit
:GetFirstSpan()
Return the first Span in the contour
:GetLastSpan()
Return the last Span in the contour
:GetHeadPosition()
Returns a POSITION variable to allow access to the head of the list of spans in the contour
:GetTailPosition()
Returns a POSITION variable to allow access to the head of the list of spans in the contour
:GetNext( POSITION pos)
Returns the Span at the current position AND a new value for position pointing to the next item in the list (or nil if at end of list).
- E.g
- cur_span, pos = offset_vector:GetNext(pos)
- pos - POSITION - current position in list
:GetPrev( POSITION pos)
Returns the Span at the current position AND a new value for position pointing to the previous item in the list (or nil if at start of list). E.g
- cur_span, pos = offset_vector:GetPrev(pos)
- pos - POSITION - current position in list
=== :GetAt( POSITION pos)
Returns the Span at the current position in the list.
- E.g. - cur_span = offset_vector:GetAt(pos)
- pos - POSITION - current position in list
:IsPointInside( Point2D point, double tolerance)
Return true if passed point is inside this contour. Beziers and arcs are polygonized for this calculation. If passed tolerance = 0.0 the default tolerance is used, else the specified tolerance. If this is called for an open contour the return value is undefined.
- point - Point2D - 2D coordinate if point to check
- tolerance - double - tolerance for polygonisation - 0.0 means default
:InvalidateBoundingBox()
If you modify the data in the contour, you must call this method to invalidate the cached bounding box.
:LineTo(double x , double y)
Append a line span from the current end point of the contour to the passed position. Returns true if span added OK else false. This method should only be called on a non-empty contour (use :AppendPoint() to start the contour if you want to create a contour consisting of a series of line segments). The Z value for the point defaults to 0.0
- x - double - X value for point
- y - double - Y value for point
:LineTo(double x , double y, double z)
Append a line span from the current end point of the contour to the passed position. Returns true if span added OK else false. This method should only be called on a non-empty contour (use :AppendPoint() to start the contour if you want to create a contour consisting of a series of line segments).
- x - double - X value for point
- y - double - Y value for point
- z - double - Z value for point
:LineTo( Point2D end_pt2d )
Append a line span from the current end point of the contour to the passed position. Returns true if span added t OK else false. This method should only be called on a non-empty contour. The Z value for the point defaults to 0.0
- end_pt2d - Point2D - 2D coordinate for point
:LineTo( Point3D end_pt3d)
Append a line span from the current end point of the contour to the passed position. Returns true if span added OK else false. This method should only be called on a non-empty contour.
- end_pt3d - Point3D - 3D coordinate for point
:MakeOffsetsSquare( double offset_dist, double offset_out, double max_dist)
Process contour and change any arcs which match the passed radius into 'square' offset if arc matches passed parameters. This is called AFTER a normal offset offset operation to change normal rounded corners into ‘sharp’ corners.
- offset_dist - double - the distance contour was offset by - corners will have this radius offset_out - bool - true if contour was offset outwards
- max_dist - double - maximum distance to allow square offset to extend (acute corners can have square offsets which extend a LONG way out)
:OffsetInZ( double z_offset)
Add the passed z value to the Z coordinates for all spans in the contour
- z_val - double - z value to add to all span heights
:ReorderStartPoint( Point2D point)
Reorder the start point of a closed contour to be as close as possible to the passed point. No points are inserted into the contour, the existing spans are just reordered.
- point - Point2D - 2D coordinate of point to define contour start
:ReorderStartPoint( integer span_index, double parameter)
Reorder a closed the contour, inserting a point (and hence splitting a span if necessary).
- span_index - integer - index of span holding new start point parameter - double - parameter in range 0-1.0 of point on span
:Reverse()
Reverse the direction of the contour - the start becomes the end and the direction of all spans are reversed.
:SetZHeight( double z_val)
Set the Z coordinates for all spans in contour to the passed value
- z_val - double - z height for contour
:Smash( double tolerance, bool preserve_arcs)
Smash beziers (and optionally arcs) into straight lines within the passed tolerance.
- tolerance - double - tolerance to use when polygonizing beziers and arcs preserve_arcs - bool - if true arcs aren’t smashed, only beziers
:Transform( Matrix2D xform)
Transform the contour using the passed transformation matrix. The transformation matrix can move (translate), scale or rotate or a combination of all 3.
- matrix - Matrix2D - the transformation matrix to apply to the contour
:RemoveHead()
Remove the first span in the contour and return it
:RemoveTail()
Remove the last span in the contour and return it
References
Please Note: The base material for the contents found in this WiKi was sourced from Vectric Lua Interface for Gadgets, version 2.05, published September 12, 2018. by Vectric Ltd. Most current document from Vertric can be downloaded at Vertric Developer Information