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

The geometry can be communicated in two data formats: arrays or dictionaries. Compatibility: introduced in ARCHICAD 23.

The same exact geometry can be stored/retrieved in both ways.

Array

contourArray: Only needed for polygons, not polylines. An array which contains the index of the last vertex of each contour in vertArray. Given with <a “ref=”#Store” target=”_blank” rel=”noopener noreferrer”>”Store”, returned from “GetContourEnds”.

 

vertArray: Array containing all vertices describing all contours of the polygon / polyline. Two-dimensional array to use with “Store” and “StorePolyline”, one-dimensional (flattened two-dimensional) array returned from “GetVertices” and “GetPolylineVertices”.

 

inhEdgeInfosArray: Optional array containing information attached to edges, defined by the caller. It must contain the same number of vertices as vertArray. Given with “Store” and “StorePolyline”, returned from “GetInhEdgeInfos” and “GetPolylineInhEdgeInfos”.

 

Dictionary

The dictionary format is more simple to handle (it can have any name, it is identified by its position in the function parameter list):

.isClosed: (boolean) 1 – polygon or closed polyline, 0 – open polyline (the last point given as an extra edge)

 

.useEdgeInfo: (boolean, optional) when set to 1, PolyOperations expects the .edgeInfo key, otherwise disregards it

 

.defaultInhEdgeInfo: (integer, optional) corresponds to the defaultInhEdgeInfo parameter of “Store”

 

.contour: (dictionary) contains data of the polygon contour, corresponding to vertArray

 

.contour.edges[n]: (array) contains an embedded dictionary for each edge of the polygon

 

.contour.edges[n].type: (integer) 0 – straight, 1 – curved (circular arc)

 

.contour.edges[n].begPoint: (dictionary) an embedded dictionary for the beginning point of the edge

 

.contour.edges[n].begPoint.x: (float)

 

.contour.edges[n].begPoint.y: (float)

 

.contour.edges[n].arcAngle: (angle) central angle of the edge curve, positive counter-clockwise, negative clockwise (not set for straight edges)

 

.contour.edges[n].edgeInfo: (integer, optional) information attached to the edge

 

.contour.holes[m]: (array, optional) contains data of inner holes, similar to .contour, only set when hole(s) exist

 

Some global variables use a dictionary structure that is compatible with PolyOperations (eg. OPENING_SYMBOL_GEOMETRY.polygon2D).

The same data format can be used for “StoreDictPolygon” and “StoreDictPolyline”.

Polylines never have .holes[], polygons are always .isClosed = 1

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 curved 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 curved 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.

StoreDictPolygon

Stores the polygon “poly1” described as a dictionary in the actual source container. Compatibility: introduced in ARCHICAD 23.

PREPAREFUNCTION ch, "StoreDictPolygon", "poly1", PolyOpPolygon

poly1: name of the stored polygon

 

PolyOpPolygon: polygon as dictionary

 

StoreDictPolyline

Stores the polyline “polyline1” described as a dictionary in the actual source container. Compatibility: introduced in ARCHICAD 23.

PREPAREFUNCTION ch, "StoreDictPolyline", "polyline1", PolyOpPolyline

polyline1: name of the stored polyline

 

PolyOpPolyline: polyline as dictionary

 

Dispose

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

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

Polygon / polyline operation settings

These commands work the same regardless whether data was given in dictionary or array format.

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

These commands work the same regardless whether data was given in dictionary or array format.

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)

CentreOfGravity

Computes the centre of gravity of a polygon. Compatibility: introduced in ARCHICAD 22 update 5003

n = CALLFUNCTION (ch, "CentreOfGravity", "poly1", x, y)

Returned values:

n: 1 on success, 0 if the centre of gravity is not well-defined, eg. the polygon was self-intersecting.

 

x, y: The coordinates of the centre of gravity.

 

Get resulting polygons / polylines

Array

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.

Dictionary

GetSourceDictPolygon, GetSourceDictPolyline

Getting the source polygon / polyline as a dictionary. Compatibility: introduced in ARCHICAD 23.

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

dict PolyOperationsPolygon, PolyOperationsPolyline
CALLFUNCTION (ch, "GetSourceDictPolygon", polygonID, PolyOperationsPolygon)
CALLFUNCTION (ch, "GetSourceDictPolyline", polylineID, PolyOperationsPolyline)
GetDestinationDictPolygon, GetDestinationDictPolyline

Getting the resulting polygon / polyline as a dictionary after any polygon / polyline operation call. Compatibility: introduced in ARCHICAD 23.

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

dict PolyOperationsPolygon, PolyOperationsPolyline
CALLFUNCTION (ch, "GetDestinationDictPolygon", polygonID, PolyOperationsPolygon)
CALLFUNCTION (ch, "GetDestinationDictPolyline", polylineID, PolyOperationsPolyline)

Closing channel

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

CLOSEADDONSCOPE (ch)