Command: polyclip

Syntax

{<entity> = } polyclip <elist>

or

{<entity> = } polyclip <elist> {
    <pcommand>
    ...
}

Description

Create one or more polygon graphic entities from the result of 2-D boolean polygon operations.

Parameters

• <entity>
  An entity or gstructure identifier. The resulting polygon entities will be given this name. This can be an entity array for multiple entity assignment.

• <elist>
  A group/entity list defining the operands of the boolean operation. Only polygon entities are considered.

• <pcommand>
  When included, this is a command line containing either:

  A language command to be executed normally, which may or may not generate polygon vertices.

  A series of point expressions separated by commas defining polygon vertices.

  The resulting polygon provides the mask for the boolean operation.

Switches

• -alph=<num>
  An alpha transparency factor between 0 and 1. A value 1 implies fully opaque, 0 means fully transparent (therefore invisible). The default is 1.

• -br=<num>
  A brightness factor between -1 and +1. A value 0 means normal, -1 means very dark (black), +1 means very bright (white). The default is 1.

• -col=<color>
  The color of the polygons. If included, this will override any color defined in the linestyle (-ls) or fillstyle (-fil). If omitted, the value no_change is used.

• -dif
  Defines the boolean operation to be difference.

• -els=<linestyle | color>
  The linestyle of the polygon edges in the resulting polygons which were derived solely from the mask polygon(s). If this is omitted, then the linestyles of the mask polygon(s) are used.

• -ff
  Fix the fill color of created polygons so that they are unaffected by subsequent modifications to the entity color.

• -fil=<fillstyle>
  The fill characteristics of the polygon interiors. If omitted, the polygons are not filled. Note: <fillstyle> can be a fillstyle, color, tile, hatchstyle or graduation.

• -fr=<num>
  Define a fragment number for the entity. If omitted, the default fragment def_fragment is used.

• -g=<groups>
  The graphic groups of which the entities are to be part.

• -int
  Defines the boolean operation to be intersection.

• -k=
  By default, when new polygons are created, vertices between consecutive parallel edges are automatically removed to create one single edge. The addition of this switch will suppress this action thus retaining original vertices.

• -ls=<linestyle | color>
  The linestyle of the polygon edges. This can be a linestyle or a color. If omitted, the current modeling color (def_color) is used. When present, the -ls switch overrides any -els definition.

• -mask=<elist>
  A group/entity list providing the mask polygon(s) for the boolean operation. When the mask is defined like this, the language block (containing <pcommands>) should be omitted. Only polygon entities within <elist> are considered.

• -pc
  Compute the para-centroid of any created polygon and make it the polygon’s origin.

• -ra=<num>
  Define a rank for the entity. If omitted, the default rank def_rank is used.

• -sub
  Create any resulting polygons which are islands within holes as sub-polygons of the holes. This is the default behavior. To create islands within holes as top-level polygons use -no_sub.

• -th=<num>
  The thickness of the polygon edges. If included, this will override any thickness defined in the linestyle (-ls) or fillstyle (-fil) if applicable.

• -tol=<num>
  A closeness tolerance for edge and vertex matching. If omitted, the default is 1.

• -un
  Defines the boolean operation to be union. If none of the -un, -dif, -int or -xor switches are present, union is the default.

• -xor
  Defines the boolean operation to be exclusive or.

Notes

This command creates one or more graphic entities of type polygon. Any input or mask polygons with coincident or crossover edges will produce undefined (probably incorrect) results.

The boolean operation should be considered as: <result> = <elist> <op> <mask>

Any holes resulting from the boolean operation will be created as unnamed child holes.

Polygons which reduce to a line for one reason or another are ignored.

All polygons created by a polyclip command (including holes and islands) become the new contents of the "these" group, replacing anything which was in the "these" group.

During vertex definition in the mask polygon language block (if included), a point phrase beginning with @ will indicate an invisible edge.

The system numeric found records the number of polygons created by the polyclip command. Holes and islands are excluded from the count.

Examples

Create the union of two squares.

polygon { gc, e:100, n:100, w:100, r }
polyclip this { (50,50), e:100, n:100, w:100, r }

Create the difference of two squares.

entity f1 = polygon { gc, e:100, n:100, w:100, r }
entity f2 = polygon { (20,20), e:30, n:30, w:30, r }
entity f3 = polyclip f1, -mask=f2, -els=green, -dif

See Also