Region

A region is a two-dimensional filled area enclosed by one or more closed boundary contours, commonly used to represent planar shapes that carry an area. Unlike ordinary curves, a region records the "area" rather than the "boundary line", so it supports geometric operations such as boolean operations, boundary offset and triangulation across multiple areas. We can create a region by instantiating an McDbMxRegion() object.

Click McDbMxRegion() for detailed property and method descriptions.

Creating a region

Use the addContour() method to add a boundary contour made of a set of points to the region, or use the addEntityContour() method to add a boundary contour based on an existing curve object (such as a circle, polyline, etc.). Multiple boundary contours can be added to the same region.

Click addContour() , addEntityContour() for detailed property and method descriptions.

import { MxCpp, McCmColor, McDbMxRegion, McDbCircle, McGePoint3d, McGePoint3dArray } from "mxcad"

const mxcad = MxCpp.getCurrentMxCAD()

// Create a rectangular region through a boundary contour of points
const region = new McDbMxRegion()
const points = new McGePoint3dArray()
points.append(new McGePoint3d(0, 0, 0))
points.append(new McGePoint3d(100, 0, 0))
points.append(new McGePoint3d(100, 80, 0))
points.append(new McGePoint3d(0, 80, 0))
region.addContour(points)
region.trueColor = new McCmColor(255, 0, 0)
mxcad.drawEntity(region)

// Create a circular region based on a circle object
const region_1 = new McDbMxRegion()
region_1.addEntityContour(new McDbCircle(250, 40, 0, 40))
region_1.trueColor = new McCmColor(0, 255, 0)
mxcad.drawEntity(region_1)

Boolean operations

booleanOption(type, other) performs a boolean operation between the current region and another region other, where the operation type is specified by BooleanOptionType. A boolean operation recalculates the coverage of the areas, and is the most core geometric operation of a region, commonly used for merging parts, finding common areas, drilling holes and cutting grooves, etc. The geometric meaning and implementation effect of the four operations are as follows:

Operation type	Enum value	Geometric meaning	Implementation effect
Union	1	Merge the entire area covered by the two regions, keeping the overlapping part only once	Combine adjacent or intersecting areas into one whole
Intersection	0	Keep only the common overlapping part of the two regions	Find the common area, which can be used for clipping and calculating the overlapping area
Difference	2	Subtract the part overlapping with other from the current region	Drill holes, cut grooves, or deduct from an area (directional, meaning "the current region minus other")
Xor	3	Keep the non-overlapping parts of the two regions and remove the common overlapping area	Find the symmetric difference of the two areas

Note that the result of a boolean operation may split into multiple disconnected areas (for example, the remaining parts after a difference operation may not be continuous), so booleanOption() returns an array of regions McDbMxRegion[], which needs to be traversed and drawn one by one. In addition, it is recommended to use brand new region objects for each operation to avoid the result of the previous operation affecting the next one.

Click booleanOption() for detailed property and method descriptions.

import { MxCpp, McDbMxRegion, McDbCircle, McGePoint3d, McGePoint3dArray, McDb } from "mxcad"

const mxcad = MxCpp.getCurrentMxCAD()

// Build a pair of partially overlapping regions: rectangle A and circle B
function createPair() {
  const regionA = new McDbMxRegion()
  const pointsA = new McGePoint3dArray()
  pointsA.append(new McGePoint3d(0, 0, 0))
  pointsA.append(new McGePoint3d(100, 0, 0))
  pointsA.append(new McGePoint3d(100, 80, 0))
  pointsA.append(new McGePoint3d(0, 80, 0))
  regionA.addContour(pointsA)

  const regionB = new McDbMxRegion()
  regionB.addEntityContour(new McDbCircle(100, 40, 0, 50))
  return [regionA, regionB]
}

// Union: merge the entire area covered by A and B
const [a1, b1] = createPair()
a1.booleanOption(McDb.BooleanOptionType.Union, b1).forEach(item => mxcad.drawEntity(item))

// Intersection: keep only the common overlapping part of A and B
const [a2, b2] = createPair()
a2.booleanOption(McDb.BooleanOptionType.Intersection, b2).forEach(item => mxcad.drawEntity(item))

// Difference: subtract the part overlapping with B from A (A minus B differs from B minus A)
const [a3, b3] = createPair()
a3.booleanOption(McDb.BooleanOptionType.Difference, b3).forEach(item => mxcad.drawEntity(item))

// Xor: keep the non-overlapping parts of A and B and remove the common area
const [a4, b4] = createPair()
a4.booleanOption(McDb.BooleanOptionType.Xor, b4).forEach(item => mxcad.drawEntity(item))

Boundary offset

inflatePaths(delta, joinType?, endType?) translates the boundary of a region inward or outward as a whole to generate a new region. Its geometric meaning is to perform an "equidistant dilation/shrink" on the area: delta is the offset distance, a positive value expands the boundary outward and enlarges the area, while a negative value shrinks the boundary inward and reduces the area. This operation is commonly used for generating equidistant offset lines of contours, reserving machining allowance, and creating area buffers, etc.

Among them, joinType controls how boundary corners are connected (such as square, miter, and round), with a default value of 2; endType controls how boundary endpoints are closed, with a default value of 0. Both are numeric types, and their specific value meanings can be found in the API documentation.

Click inflatePaths() for detailed property and method descriptions.

import { MxCpp, McCmColor, McDbMxRegion, McGePoint3d, McGePoint3dArray } from "mxcad"

const mxcad = MxCpp.getCurrentMxCAD()

// Create a rectangular region
const region = new McDbMxRegion()
const points = new McGePoint3dArray()
points.append(new McGePoint3d(0, 0, 0))
points.append(new McGePoint3d(100, 0, 0))
points.append(new McGePoint3d(100, 80, 0))
points.append(new McGePoint3d(0, 80, 0))
region.addContour(points)
region.trueColor = new McCmColor(255, 0, 0)
mxcad.drawEntity(region)

// Expand the boundary outward by 10 to get an enlarged new region
const inflated = region.inflatePaths(10)
inflated.trueColor = new McCmColor(255, 233, 0)
mxcad.drawEntity(inflated)

// Shrink the boundary inward by 10 to get a reduced new region
const shrunk = region.inflatePaths(-10)
shrunk.trueColor = new McCmColor(0, 255, 0)
mxcad.drawEntity(shrunk)

Triangulation

triangulate(useDelaunay?) splits a region into a set of triangles and returns a new region. Its geometric meaning is to discretize a polygon area of any shape into a triangle mesh: when useDelaunay is true (the default), Delaunay triangulation is used, which tries to keep each triangle from being "slender", thereby producing a more uniform mesh. Triangulation is a common preprocessing step in scenarios such as rendering fills, meshing, and finite element preprocessing.

Click triangulate() for detailed property and method descriptions.

import { MxCpp, McCmColor, McDbMxRegion, McDbCircle } from "mxcad"

const mxcad = MxCpp.getCurrentMxCAD()

// Create a region based on a circle
const region = new McDbMxRegion()
region.addEntityContour(new McDbCircle(0, 0, 0, 50))
region.trueColor = new McCmColor(255, 0, 0)
mxcad.drawEntity(region)

// Perform Delaunay triangulation on the circular region to get a new region composed of triangles
const triangulated = region.triangulate(true)
triangulated.trueColor = new McCmColor(0, 128, 255)
mxcad.drawEntity(triangulated)

Boundary and area query

A region also provides a set of query and data management methods: getContourCount() gets the number of boundary contours, getContour(index) gets the boundary coordinates of the specified index, getArea() calculates the area of the region (returning { ret, val }, where ret indicates whether it succeeded and val is the area value), and getBoundingBox() gets the minimum bounding rectangle of the region. In addition, you can use isEmpty() to check whether the region data is empty, clearData() to clear the region data, and copyData() to copy data from another region.

Click getContourCount() , getContour() , getArea() , getBoundingBox() for detailed property and method descriptions.

import { MxCpp, McDbMxRegion, McGePoint3d, McGePoint3dArray } from "mxcad"

const mxcad = MxCpp.getCurrentMxCAD()

const region = new McDbMxRegion()
const points = new McGePoint3dArray()
points.append(new McGePoint3d(0, 0, 0))
points.append(new McGePoint3d(100, 0, 0))
points.append(new McGePoint3d(100, 80, 0))
points.append(new McGePoint3d(0, 80, 0))
region.addContour(points)

// The number of boundary contours
console.log("Contour count:", region.getContourCount())
// The coordinate points of the 0th boundary
console.log("Contour points:", region.getContour(0))
// Area
const area = region.getArea()
if (area.ret) console.log("Area:", area.val)
// Minimum bounding rectangle
const box = region.getBoundingBox()
if (box.ret) console.log("Bounding box:", box.minPt, box.maxPt)