Polygon Operations Extension

This add-on calculates result polygons based on the input polygons and the operation that is carried out on them.

Compatibility: introduced in ARCHICAD 21: There are operations for polylines as well.

Input polygons are identified by a name when passed to the add-on and are stored in a previously defined container.
Result polygons are automatically named by the add-on and are stored in a second, target container.
Input and result polygons are thus stored in different containers.

Multiple polygons, possibly with an even greater number of contours, can be created by a single operation.
These will be administered as individual polygons in the target container.
As a result, these polygons can be accessed in subsequent polygon operations.
The principle is the same as with the Solid Geometry Commands (see in the section called “Solid Geometry Commands”).
Input polygons must be contiguous.

A polygon is defined by several contours, each of which is an uninterrupted sequence of connected vertices.
The first contour is the outer boundary.
The subsequent contours must all be inside the first, they may not overlap, and they create cutouts of the first polygon.

Polylines don’t have to be closed, but can’t have multiple contours.

Opening a channel

ch = INITADDONSCOPE ("PolyOperations ", "", "")

Opens a channel. The return value is the ID of the opened channel.

Container management

CreateContainer

Creates a new container.

PREPAREFUNCTION ch, "CreateContainer", "myContainer", ""

DeleteContainer

Delete an existing container.

PREPAREFUNCTION ch, "DeleteContainer", "myContainer", ""

EmptyContainer

Emptying an existing container.

PREPAREFUNCTION ch, "EmptyContainer", "myContainer", ""

SetSourceContainer

Set container as source container.

PREPAREFUNCTION ch, "SetSourceContainer", "mySourceContainer", ""

SetDestinationContainer

Set container as destination container.

PREPAREFUNCTION ch, "SetDestinationContainer", "myDestinationContainer", ""

Polygon / polyline management

Store

Stores the polygon “poly1” with the given parameters in the actual source container.

PREPAREFUNCTION ch, "Store", "poly1", nVertices, nContours,
        vertArray, contourArray [, defaultInhEdgeInfo, inhEdgeInfosArray]

poly1: name of the stored polygon

nVertices: number of vertices

nContours: number of contours

vertArray: Array containing exactly nVertices items that describes all contours of the polygon. Two dimension array of (x, y, angle)
records where x, y, and angle is real value. The angle parameter is the view-angle (deflection) in case of arched edges.
This is a signed value, reflecting the orientation. Zero value means straight edge.

contourArray: An array which contains the index of the last vertex of the i-th contour. It must have exactly nContours items.

defaultInhEdgeInfo: One piece of inherited edge information.
To the brand new edges (not created with split) this information will be attached in operations performed.
This data helps tracing newly created edges after complex operations. (Optional)

inhEdgeInfosArray: Array containing information attached to edges. It must of contain exactly nVertices integer type items.
If an edge splits into more than one new edge in an operation, this information will be inherited without change to all new edges created.
Can be used to store the side angles of a roof, for example. (Optional)

Remarks:

  • Polygons can have holes and curved edges though these curved edges can be only circle-arcs.

  • The polygon can link to additional data for every edge.

  • The first vertex must be always repeated in the last for all contours.
    So in this representation, a triangle have four vertices, where the first and the last vertex is identical.

  • The first contour is the main contour, and it must contain the others.

StorePolyline

Stores the polyline “polyline1” with the given parameters in the actual source container.

PREPAREFUNCTION ch, "StorePolyline", "polyline1", nVertices,
            vertArray, [, defaultInhEdgeInfo, inhEdgeInfosArray]

polyline1: name of the stored polyline

nVertices: number of vertices

vertArray: Array containing exactly nVertices items that describes the polyline. Two dimension array of (x, y, angle)
records where x, y, and angle is real value. The angle parameter is the view-angle (deflection) in case of arched edges.
This is a signed value, reflecting the orientation. Zero value means straight edge.

defaultInhEdgeInfo: One piece of inherited edge information.
To the brand new edges (not created with split) this information will be attached in operations performed.
This data helps tracing newly created edges after complex operations. (Optional)

inhEdgeInfosArray: Array containing information attached to edges. It must of contain exactly nVertices integer type items.
If an edge splits into more than one new edge in an operation, this information will be inherited without change to all new edges created.
Can be used to store the side angles of a roof, for example. (Optional)

Remarks:

  • The polyline can link to additional data for every edge.

  • To define a closed polyline, the last vertex coordinates has to be the same as the first. Open and closed polylines behave differently when being offset or split.

Dispose

Deletes the polygon / polyline “poly1” from the container “myContainer”.

PREPAREFUNCTION ch, "Dispose", "poly1", "myContainer"

Polygon / polyline operation settings

HalfPlaneParams

Set the half plane in 2D to be used in the “PolyCut” operation.

PREPAREFUNCTION ch, "HalfPlaneParams", "", ca, cb, cc

Defining inequality for the half plane: ca * x + cb * y > cc.

ca: Coefficient of x

cb: Coefficient of y

cc: Constant

OffsetParams

Set the offset parameters used in “OffsetEdge”, “ResizeContour” and “PolylineOffsetVectors” operations.

PREPAREFUNCTION ch, "OffsetParams", "", itemIdx, offsetValue

itemIdx: Index of the edge to be translated for “OffsetEdge” operation. Index of the resizable contour
for “ResizeContour” operation. Always 1 for “PolylineOffsetVectors” operation.

offsetValue: Distance of the translation. Negative and positive offset values make the edge move inside and outside,
respectively. If the offset is big, the neighboring vertices can be cut out.

MultipleEdgeOffsetParams

Set the offset parameters used in “OffsetMultipleEdges” and “PolylineOffsetVectors” operations.

PREPAREFUNCTION ch, "MultipleEdgeOffsetParams", "", nOffset, offsetArray

nOffset: Number of edges to offset.

offsetArray: Array containing nOffset items that describe edges to offset. Two dimensional array of (edgeIndex, offsetValue) records,
where edgeIndex is 1-based index of the edge, offsetValue is the distance of translation.
For open polylines, it is positive to the left, negative to the right (viewed in the direction of the edge).

PolylineOffsetVectors

Set the end offset parameters used in “OffsetPolylineWithVectors” operation. “OffsetParams” or “MultipleEdgeOffsetParams” have to be set separately.

PREPAREFUNCTION ch, "PolylineOffsetVectors", "", sx, sy, ex, ey

sx, sy: Start vertex offset direction unit vector (length = 1.0 m).

ex, ey: End vertex offset direction unit vector (length = 1.0 m).

Polygon / polyline operations

In the following polygon operations the “poly1”, “poly2” source polygons and “polyline1” source polyline are located in the source container.
The resulting polygons / polylines are stored in the destination container with an unique name started with “resPolygonID” or “resPolylineID”,
where “ID” is a number. These names are generally returned in an array.

+ – /

Executes the “OP” operation with “poly1” and “poly2” polygons and puts the new values into the given parameters. The return value is the
number of the generated polygons

dim resPolyIDArray[]
nPgon = CALLFUNCTION (ch, "poly1 OP poly2", "", resPolyIDArray)

OP: can be:
+: Polygon addition
-: Polygon subtraction
/: Polygon intersection

resPolyIDArray: Array of resulting polygon identifiers.

ClipPolyline

Clip a polyline with a polygon

dim resPolyIDArray[]
nPline = CALLFUNCTION (ch, "ClipPolyline", "polyline1 poly1", resPolyIDArray)

polyline1: Name of the polyline in the source container.

poly1: Name of the clip polygon in the source container.

resPolyIDArray: Array of resulting polyline identifiers.

CopyPolygon

Copying a polygon / polyline from the source container to the destination container

dim resPolyIDArray[]
nPgon = CALLFUNCTION (ch, "CopyPolygon", "poly1", resPolyIDArray)

Regularize

Regularizing a polygon – Making it geometrically valid.

dim resPolyIDArray[]
nPgon = CALLFUNCTION (ch, "Regularize", "poly1", resPolyIDArray)

A polygon is valid if

  • Its first boundary contains all the others

  • Is oriented correctly (the main contour is a positively oriented curve, the rest is oriented negatively)

  • Has no self-intersections

  • Its area is not zero

  • Has no zero length edges

PolyCut

Intersecting the polygon with a halfplane.

The halfplane must be set with a “HalfPlaneParams” command. The result will be regularized.

dim resPolyIDArray[]
nPgon = CALLFUNCTION (ch, "PolyCut", "poly1", resPolyIDArray)

OffsetEdge

Translating an edge of a polygon perpendicularly to its direction.


The edge index and translation offset must be set with an “OffsetParams” command. The result will be regularized.

dim resPolyIDArray[]
nPgon = CALLFUNCTION (ch, "OffsetEdge", "poly1", resPolyIDArray)

OffsetMultipleEdges

Translating multiple edges of a polygon perpendicularly to its direction.


The edge indices and translation offsets must be set with an “MultipleEdgeOffsetParams” command. The result will be regularized.

dim resPolyIDArray[]
nPgon = CALLFUNCTION (ch, "OffsetMultipleEdges", "poly1", resPolyIDArray)

OffsetPolyline

Translating all edges of a polyline perpendicularly


The translation offset must be set with an “OffsetParams” command.

dim resPolyIDArray[]
nPline = CALLFUNCTION (ch, "OffsetPolyline", "polyline1", resPolyIDArray)

OffsetPolylineWithVectors

Translating all edges of an open polyline perpendicularly, and moving the endpoints along a vector


The translation vectors and offset must be set with “PolylineOffsetVectors” and “OffsetParams” commands.

dim resPolyIDArray[]
nPline = CALLFUNCTION (ch, "OffsetPolylineWithVectors", "polyline1", resPolyIDArray)

Gives Input argument error for closed polylines

ResizeContour

Enlarges or shrinks a contour of a polygon.


The contour index and translation offset must be set with an “OffsetParams” command. The result will be regularized.

dim resPolyIDArray[]
nPgon = CALLFUNCTION (ch, "ResizeContour", "poly1", resPolyIDArray)

Get resulting polygons / polylines

GetSourcePolygons, GetSourcePolylines

Getting all polygon / polyline names from the actual source container.

dim resPolyIDArray[], resPolylineIDArray[]
nPgon = CALLFUNCTION (ch, "GetSourcePolygons", "", resPolyIDArray
nPline = CALLFUNCTION (ch, "GetSourcePolylines", "", resPolylineIDArray

GetDestinationPolygons, GetDestinationPolylines

Getting all polygon / polyline names from the actual destination container.

dim resPolyIDArray[], resPolylineIDArray[]
nPgon = CALLFUNCTION (ch, "GetDestinationPolygons", "", resPolyIDArray)
nPline = CALLFUNCTION (ch, "GetDestinationPolylines", "", resPolylineIDArray

GetVertices, GetPolylineVertices

Getting the resulting polygon / polyline vertices after any polygon operation call.

The polygon / polyline with name “polygonID” or “polylineID” is located in the destination container.

dim resVertices[], resPolylineVertices[]
nVertices = CALLFUNCTION (ch, "GetVertices", polygonID, resVertices)
nVertices = CALLFUNCTION (ch, "GetPolylineVertices", polylineID, resPolylineVertices)

GetContourEnds

Getting the resulting polygon contour end indices after any polygon operation call.

The polygon with name “polygonID” is located in the destination container.

dim contArr[]
nContours = CALLFUNCTION (ch, "GetContourEnds", polygonID, contArr)

GetInhEdgeInfos, GetPolylineInhEdgeInfos

Getting the resulting polygon / polyline contour information after any polygon / polyline operation call.

dim inhEdgeInfosArr[], polylineInhEdgeInfosArr[]
nEdgeInfos = CALLFUNCTION (ch, "GetInhEdgeInfos", polygonID, inhEdgeInfosArr)
nEdgeInfos = CALLFUNCTION (ch, "GetPolylineInhEdgeInfos",
                                polylineID, polylineInhEdgeInfosArr)

The polygon / polyline with name “polygonID” or “polylineID” is located in the destination container.

Closing channel

Closes channel “ch”. Deletes all of the stored polygons / polylines.

CLOSEADDONSCOPE (ch)