Class Offset

An encapsulation of the process of offsetting (inflating/deflating) both open and closed paths using a number of different join types and end types.

(Follow the first link for a nice visual example.)

Preconditions for offsetting:

  1. The orientations of closed paths must be consistent such that outer polygons share the same orientation, and any holes have the opposite orientation (i.e. non-zero filling). Open paths must be oriented with closed outer polygons.
  2. Polygons must not self-intersect.

Limitations:

When offsetting, small artefacts may appear where polygons overlap. To avoid these artefacts, offset overlapping polygons separately.

Methods

Offset:AddPath (path, join_type, end_type)
Adds a Path in preparation for offsetting.

Any number of paths can be added, and each has its own join and end types. All 'outer' paths must have the same orientation, and any 'hole' paths must have reverse orientation. Closed paths must have at least 3 vertices. Open paths may have as few as one vertex. Open paths can only be offset with positive deltas.

Parameters:

  • path Path
  • join_type string One of "Square", "Round", or "Miter".

    See here for some nice visual examples.)

  • end_type string One of:

    • "ClosedPolygon": Ends are joined according to join_type and the path filled as a polygon.
    • "ClosedLine": Ends are joined according to join_type and the path filled as a polyline.
    • "OpenButt": Ends are squared off with no extension.
    • "OpenSquare": Ends are squared off and extended delta units.
    • "OpenRound": Ends are rounded off and extended delta units.

    See here for some nice visual examples.)

Offset:AddPaths (paths, join_type, end_type)
Like Offset:AddPath, but adds a Paths.

Parameters:

Offset:Clear ()
Clear all paths, allowing new ones to be assigned.
Offset:Execute (solution, delta)
Apply the offset operation to the currently added paths.

This method can be called multiple times, offsetting the same paths by different amounts (i.e. using different deltas).

Parameters:

  • solution PolyTree or Paths Structure that will receive the result of the operation.
  • delta number Amount to which the supplied paths will be offset — negative delta values to shrink polygons and positive delta to expand them.

Returns:

    PolyTree or Paths solution.
Offset:Execute (delta)
Alternative signature of Execute.

Parameters:

  • delta number As before.

Returns:

    Paths Result of the operation, via a new object.
Offset:GetArcTolerance ()

Returns:

    number Current tolerance.

See also:

Offset:GetMiterLimit ()

Returns:

    number Current limit.

See also:

Offset:SetArcTolerance (tolerance)
Since flattened paths can never perfectly represent arcs, this field / property specifies a maximum acceptable imprecision ('tolerance') when arcs are approximated in an offsetting operation. Smaller values will increase 'smoothness' up to a point though at a cost of performance and in creating more vertices to construct the arc.

The default ArcTolerance is 0.25 units. This means that the maximum distance the flattened path will deviate from the 'true' arc will be no more than 0.25 units (before rounding).

Reducing tolerances below 0.25 will not improve smoothness since vertex coordinates will still be rounded to integer values. The only way to achieve sub-integer precision is through coordinate scaling before and after offsetting (see example below).

It's important to make ArcTolerance a sensible fraction of the offset delta (arc radius). Large tolerances relative to the offset delta will produce poor arc approximations but, just as importantly, very small tolerances will substantially slow offsetting performance while providing unnecessary degrees of precision. This is most likely to be an issue when offsetting polygons whose coordinates have been scaled to preserve floating point precision.

Example: Imagine a set of polygons (defined in floating point coordinates) that is to be offset by 10 units using round joins, and the solution is to retain floating point precision up to at least 6 decimal places.

To preserve this degree of floating point precision, and given that Clipper and Offset both operate on integer coordinates, the polygon coordinates will be scaled up by 10^8 (and rounded to integers) prior to offsetting. Both offset delta and ArcTolerance will also need to be scaled by this same factor. If ArcTolerance was left unscaled at the default 0.25 units, every arc in the solution would contain a fraction of 44 THOUSAND vertices while the final arc imprecision would be 0.25 × 10^-8 units (i.e. once scaling was reversed). However, if 0.1 units was an acceptable imprecision in the final unscaled solution, then ArcTolerance should be set to 0.1 × scaling_factor (0.1 × 10^8). Now if scaling is applied equally to both ArcTolerance and to Delta Offset, then in this example the number of vertices (steps) defining each arc would be a fraction of 23.

The formula for the number of steps in a full circular arc is: Pi / acos(1 - arc_tolerance / abs(delta))

The arc tolerance is relevant only when join_type is "Round" or end_type is "OpenRound"

Parameters:

  • tolerance number New tolerance.

See also:

Offset:SetMiterLimit (limit)
This property sets the maximum distance in multiples of delta that vertices can be offset from their original positions before squaring is applied. (Squaring truncates a miter by 'cutting it off' at 1 × delta distance from the original vertex.)

The default value for MiterLimit is 2 (i.e. twice delta). This is also the smallest MiterLimit that's allowed. If mitering was unrestricted (ie without any squaring), then offsets at very acute angles would generate unacceptably long 'spikes'. (See here for an example of such a spike.)

The miter limit is relevant only when join_type is "Miter", cf. Offset:AddPath.

Parameters:

  • limit number New limit, ≥ 2.

See also:

generated by LDoc 1.4.6 Last updated 2018-08-13 18:06:38