topologicpy.Face module

Axial edges

Face.AxialEdges generates maximal straight visibility edges within a planar polygonal face, respecting holes and optional coplanar polygonal face/wire obstacles. Face.AxialLines is an alias of the same function. Results retain the original face plane, including tilted and vertical planes. Curved boundaries and non-planar input are rejected.

The first implementation is an approximate sampled map. It generates candidates from boundary directions and rays between interior samples and polygon corners. Reduction covers sampled witnesses by visibility from a distributed working set of candidate edges, expanding it if necessary for coverage. It uses the full candidate set to add connecting candidates, and removes redundant candidates while retaining sampled coverage and connectivity within each free-space component. Visibility coverage is not a proof of complete movement-axis coverage, nor a classical fewest-line map or a DepthmapX-compatible all-lines algorithm. Narrow features may require smaller samplingDistance. The default spacing is one sixth of the largest bounding dimension. The result is not guaranteed to be invariant under sampling changes or polygon decomposition details.

reduce=False returns the candidate edges. returnReport=True returns a dictionary containing edges, candidateCount, sampleCount, uncoveredSamples, componentCount, samplingDistance and approximate=True. Sample and candidate budgets return the available map instead of failing when a limit is exceeded. Sampling is coarsened and distributed when necessary; candidates are generated round-robin across regions and seeds, with architectural directions preceding corner rays. Near-duplicate candidates are removed by endpoint distance within tolerance, including reversed Edges and points on adjacent spatial-hash cells. maxCandidates caps the candidate set before reduction, so the returned map may contain fewer Edges. A warning identifies a partial result unless silent=True.

The report includes truncated, limitsReached, coverageComplete, connected and componentConnected. Uncovered samples are returned as 3D coordinates in the original plane. Coverage completeness refers to retained samples, not all points in the Face. With reduce=False, coverage and connectivity are not evaluated and these fields are None. Retained witness coordinates are available as samples for inspecting coverage. The requested and actual spacing are reported separately as requestedSamplingDistance and samplingDistance. evaluatedCandidateCount records how many candidates needed visibility evaluation during reduction. Increasing a budget or reducing the requested spacing can improve an approximate map; budgets bound storage, not runtime.

Each output edge has its own uuid/edge_id, the source face’s source_face_id and an axial_index. Regeneration creates new source edges and therefore new UUIDs. Use TGraph.AxialGraph(edges=edges) to analyse them, then transfer selected node dictionary values back with TGraph.TransferDictionariesToOriginators for colouring.

Offset regions

Face.ByOffset returns a Face when one region survives and a Cluster containing all Faces when the offset separates the region. A multi-region result prints a warning with the number of regions unless silent=True. Complete erosion returns None; it does not return an inverted remnant.

Uniform polygonal offsets can close narrow necks, merge holes, remove shrinking holes, or let expanding holes meet the exterior. They are resolved in the Face’s own plane, including vertical and tilted planes, with mitred joins. Single-region cases retain the existing Wire offset path when it agrees with the region result. Curved and variable offsets retain their exact Wire construction; collisions between otherwise valid curved boundaries are resolved with native face Booleans, without tessellation. Unsupported/self-intersecting curved or variable Wire offsets can still fail and return None.

With transferDictionaries=True, the source Face dictionary is transferred to every returned Face and the Cluster. The existing Wire path retains its source Edge/Vertex dictionary transfer; newly resolved boundaries do not always have one-to-one source Edge/Vertex correspondences.

result = Face.ByOffset(face, offset=0.3)
regions = Topology.Faces(result) if result is not None else []

Face.ByOffsetArea optimises the combined area of all surviving regions and uses the same return convention. Optimisation trials suppress diagnostics; the final multi-region result emits the warning.

class topologicpy.Face.Face

Bases: object

Methods

`AddInternalBoundaries`(face, wires[, ...])	Adds internal boundaries (holes) to the input Face while preserving the Face's original support surface and existing boundary geometry.
`AddInternalBoundariesCluster`(face, cluster)	Adds the input cluster of internal boundaries (closed wires) to the input face.
`Angle`(faceA, faceB[, mantissa])	Returns the angle in degrees between the two input faces.
`Area`(face[, mantissa, silent])	Returns the area of the input face.
`AxialEdges`(face[, obstacles, reduce, ...])	Generates maximal straight visibility Edges in a planar polygonal Face.
`AxialLines`(face[, obstacles, reduce, ...])	Generates maximal straight visibility Edges in a planar polygonal Face.
`BoundingRectangle`(topology[, optimize, ...])	Returns a face representing a bounding rectangle of the input topology.
`ByEdges`(edges[, tolerance, silent])	Creates a face from the input list of edges.
`ByEdgesCluster`(cluster[, tolerance, silent])	Creates a face from the input cluster of edges.
`ByMesh`([triangulateQuads, quadSplit, ...])	Creates faces from indexed mesh data.
`ByNurbsParameters`(controlPoints[, weights, ...])	Creates a Face from exact NURBS/B-spline surface parameters.
`ByOffset`(face[, offset, offsetKey, ...])	Creates an offset planar region, preserving all surviving components.
`ByOffsetArea`(face, area[, offsetKey, ...])	Creates an offset face from the input face based on the input area.
`ByParametricFunction`(function[, uRange, ...])	Creates a genuine BSpline Face fitted to `function(u, v)`.
`ByShapely`(polygon[, z, tolerance, silent])	Create a planar Face from a valid Shapely Polygon, preserving holes.
`ByShell`(shell[, origin, angTolerance, ...])	Creates a single Face by merging the Faces of the input Shell without flattening the Shell or reconstructing its geometry from Vertices or Wires.
`ByThickenedWire`(wire[, offsetA, offsetB, ...])	Creates a planar Face by thickening the input Wire.
`ByVertices`(vertices[, tolerance, silent])	Creates a face from the input list of vertices.
`ByVerticesCluster`(cluster[, tolerance, silent])	Creates a face from the input cluster of vertices.
`ByWire`(wire[, tolerance, silent])	Creates a Face from the input closed Wire.
`ByWires`(externalBoundary[, ...])	Creates a Face from one closed external Wire and optional closed internal Wires.
`ByWiresCluster`(externalBoundary[, ...])	Creates a face from the input external boundary (closed wire) and the input cluster of internal boundaries (closed wires).
`CHS`([origin, radius, thickness, sides, ...])	Creates a circular hollow section (CHS).
`CShape`([origin, width, length, a, b, c, ...])	Creates a C-shape.
`Catenoid`([origin, radius, height, sides, ...])	Creates a catenoid minimal-surface Face as a BSpline.
`Circle`([origin, radius, sides, fromAngle, ...])	Creates a circular Face.
`Compactness`(face[, mantissa, silent, method])	Returns the compactness measure of the input face.
`CompassAngle`(face[, north, mantissa, tolerance])	Returns the horizontal compass angle in degrees between the normal vector of the input face and the input vector.
`ConcaveCornerVertices`(face[, ...])	Returns the concave corner vertices of the input face.
`Conoid`([origin, width, length, height, ...])	Creates a parabolic conoid with straight rulings in the V direction.
`ConvexCornerVertices`(face[, ...])	Returns the convex corner vertices of the input face.
`CrossShape`([origin, width, length, a, b, c, ...])	Creates a Cross-shape.
`CurvatureAtParameters`(face[, u, v, ...])	Returns the local surface curvature properties of the input Face at the specified normalized U and V parameters.
`Edges`(face[, silent])	Returns the edges of the input face.
`Einstein`([origin, radius, direction, ...])	Creates an aperiodic monotile, also called an 'einstein' tile (meaning one tile in German, not the name of the famous physicist).
`Ellipse`([origin, inputMode, width, length, ...])	Creates an elliptical Face.
`ExteriorAngles`(face[, ...])	Returns the exterior angles of the input face in degrees.
`ExternalBoundary`(face[, tolerance, silent])	Returns the external boundary (closed wire) of the input face.
`FacingToward`(face[, direction, asVertex, ...])	Returns True if the input face is facing toward the input direction.
`Fillet`(face[, radius, sides, radiusKey, ...])	Fillets the corners of the input planar Face while preserving its native support surface and boundary geometry.
`Helicoid`([origin, radius, height, turns, ...])	Creates a helicoid minimal-surface Face as a BSpline.
`HyperbolicParaboloid`([origin, width, ...])	Creates an exact bilinear hyperbolic-paraboloid (hypar) Face.
`IShape`([origin, width, length, a, b, c, ...])	Creates an I-shape.
`InteriorAngles`(face[, ...])	Returns the interior angles of the input face in degrees.
`InternalBoundaries`(face)	Returns the internal boundaries (closed wires) of the input face.
`InternalVertex`(face[, tolerance, silent])	Creates a vertex guaranteed to be inside the input face.
`Invert`(face[, tolerance, silent])	Reverses the orientation of the input Face without approximating its geometry.
`IsConvex`(face[, mantissa, silent])	Returns True if the input face is convex.
`IsCoplanar`(faceA, faceB[, mantissa, tolerance])	Returns True if the two input faces are coplanar.
`IsPlanar`(face[, tolerance, silent])	Returns True if the input Face lies on a plane.
`Isovist`(face, vertex[, obstacles, ...])	Returns the face representing the isovist projection from the input viewpoint.
`LShape`([origin, width, length, a, b, ...])	Creates an L-shape.
`MedialAxis`(face[, resolution, ...])	Returns a wire representing an approximation of the medial axis of the input topology.
`Normal`(face[, outputType, mantissa, silent])	Returns the normal vector to the input face.
`NormalAtParameters`(face[, u, v, outputType, ...])	Returns the oriented unit normal vector to the input Face at the specified normalized U and V parameters.
`NormalEdge`(face[, length, tolerance, silent])	Returns an Edge representing the local surface normal of the input Face.
`NorthArrow`([origin, radius, sides, ...])	Creates a north arrow.
`Paraboloid`([origin, radius, height, sides, ...])	Creates an elliptic paraboloid Face as a tolerance-controlled BSpline.
`Planarize`(face[, origin, tolerance])	Planarizes the input face such that its center of mass is located at the input origin and its normal is pointed in the input direction.
`PlaneEquation`(face[, mantissa])	Returns the a, b, c, d coefficients of the plane equation of the input face.
`Project`(faceA, faceB[, direction, mantissa, ...])	Creates a projection of the first input Face onto the second input Face.
`RHS`([origin, width, length, thickness, ...])	Creates a rectangular hollow section (RHS).
`Rectangle`([origin, width, length, ...])	Creates a rectangle.
`RemoveCollinearEdges`(face[, angTolerance, ...])	Removes redundant consecutive linear collinear Edges from the boundaries of the input Face while preserving the Face's original support surface and all curved boundary geometry.
`Ring`([origin, radius, thickness, sides, ...])	Creates a circular ring.
`SHS`([origin, size, thickness, outerFillet, ...])	Creates a square hollow section (SHS).
`Scherk`([origin, width, length, height, ...])	Creates Scherk's first minimal surface as a BSpline Face.
`Simplify`(face[, method, epsilon, tolerance, ...])	Simplifies the linear portions of the boundaries of a planar Face while preserving curved Edges.
`Skeleton`(face[, boundary, tolerance])	Creates a straight skeleton. This method is contributed by 高熙鹏 xipeng gao <gaoxipeng1998@gmail.com>
`Square`([origin, size, direction, placement, ...])	Creates a square.
`Squircle`([origin, radius, sides, a, b, ...])	Creates a Squircle which is a hybrid between a circle and a square.
`Star`([origin, radiusA, radiusB, rays, ...])	Creates a star.
`TShape`([origin, width, length, a, b, ...])	Creates a T-shape.
`TangentAtParameters`(face[, u, v, axis, ...])	Returns one parametric tangent direction of the input Face at the specified normalized parameters.
`TangentsAtParameters`(face[, u, v, ...])	Returns the U and V parametric tangent directions of the input Face at the specified normalized parameters.
`ThirdVertex`(face[, tolerance, silent])	Returns a third vertex on the input face to enable rotation matrix creation.
`Trapezoid`([origin, widthA, widthB, offsetA, ...])	Creates a trapezoid.
`Triangulate`(face[, mode, meshSize, ...])	Triangulates the input Face and returns its triangular Faces.
`TrimByWire`(face, wire[, reverse, tolerance, ...])	Trims the input face by the input wire.
`VertexByParameters`(face[, u, v, tolerance, ...])	Creates a vertex at normalized `u` and `v` parameters of the input face.
`VertexParameters`(face, vertex[, outputType, ...])	Returns normalized face parameters at the location of the input vertex.
`Vertices`(face)	Returns the vertices of the input face.
`Wire`(face)	Returns the external boundary (closed wire) of the input face.
`Wires`(face)	Returns the wires of the input face.

RectangleByPlaneEquation

static AddInternalBoundaries(face, wires: list, tolerance: float = 0.0001, silent: bool = False)

Adds internal boundaries (holes) to the input Face while preserving the Face’s original support surface and existing boundary geometry.

The operation is delegated to the active geometry backend. The input Face is not reconstructed from its external and internal boundary Wires.

Parameters

facetopologic_core.Face: The input Face.
wireslist: The input list of closed Wires to add as internal boundaries.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The Face with the additional internal boundaries, or None if the active backend cannot perform the operation while preserving the original support surface.

static AddInternalBoundariesCluster(face, cluster)

Adds the input cluster of internal boundaries (closed wires) to the input face. Internal boundaries are considered holes in the input face.

Parameters

facetopologic_core.Face: The input face.
clustertopologic_core.Cluster: The input cluster of internal boundaries (topologic wires).

Returns

topologic_core.Face: The created face with internal boundaries added to it.

static Angle(faceA, faceB, mantissa: int = 6) → float

Returns the angle in degrees between the two input faces.

Parameters

faceAtopologic_core.Face: The first input face.
faceBtopologic_core.Face: The second input face.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.

Returns

float: The angle in degrees between the two input faces.

static Area(face, mantissa: int = 6, silent: bool = False) → float

Returns the area of the input face.

Parameters

facetopologic_core.Face: The input face.
mantissaint , optional: The number of decimal places to round the result to. If None, the value is returned without rounding. Default is 6.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

float: The area of the input face.

static AxialEdges(face, obstacles=None, reduce: bool = True, samplingDistance: float = None, maxCandidates: int = 10000, maxSamples: int = 1000, returnReport: bool = False, tolerance: float = 0.0001, silent: bool = False)

Generates maximal straight visibility Edges in a planar polygonal Face.

This is an approximate sampled axial map, not a DepthmapX all-lines or fewest-lines implementation. Candidates use boundary directions and rays from sampled interior points toward polygon corners. reduce=True greedily covers sampled witnesses by visibility from a distributed working set of candidate edges (expanding it if needed), bridges their intersection graph, then removes redundant edges while retaining sampled coverage and connectivity within each free-space component.

obstacles is a list of coplanar polygonal Faces or closed Wires. Face holes are always excluded. Curved boundaries and non-planar input are rejected. samplingDistance defaults to one sixth of the largest bounding dimension. Positive maxSamples/maxCandidates limits bound the working set. Sampling is coarsened when needed, and candidate generation stops at its budget, returning the available map with a warning instead of discarding it. Returns a list of Edges in the original plane. returnReport=True returns edges, candidateCount, sampleCount, uncoveredSamples, componentCount, samplingDistance and approximate=True. The report also includes truncated, limitsReached, coverageComplete, connected, componentConnected and evaluatedCandidateCount. Coverage refers to retained samples; coarsened or capped sampling does not establish full spatial coverage. Boundary tangent contact is permitted; obstacle interiors are never crossed. Output edges have edge_id/uuid, source_face_id and axial_index dictionaries.

static AxialLines(face, obstacles=None, reduce: bool = True, samplingDistance: float = None, maxCandidates: int = 10000, maxSamples: int = 1000, returnReport: bool = False, tolerance: float = 0.0001, silent: bool = False)

Generates maximal straight visibility Edges in a planar polygonal Face.

This is an approximate sampled axial map, not a DepthmapX all-lines or fewest-lines implementation. Candidates use boundary directions and rays from sampled interior points toward polygon corners. reduce=True greedily covers sampled witnesses by visibility from a distributed working set of candidate edges (expanding it if needed), bridges their intersection graph, then removes redundant edges while retaining sampled coverage and connectivity within each free-space component.

obstacles is a list of coplanar polygonal Faces or closed Wires. Face holes are always excluded. Curved boundaries and non-planar input are rejected. samplingDistance defaults to one sixth of the largest bounding dimension. Positive maxSamples/maxCandidates limits bound the working set. Sampling is coarsened when needed, and candidate generation stops at its budget, returning the available map with a warning instead of discarding it. Returns a list of Edges in the original plane. returnReport=True returns edges, candidateCount, sampleCount, uncoveredSamples, componentCount, samplingDistance and approximate=True. The report also includes truncated, limitsReached, coverageComplete, connected, componentConnected and evaluatedCandidateCount. Coverage refers to retained samples; coarsened or capped sampling does not establish full spatial coverage. Boundary tangent contact is permitted; obstacle interiors are never crossed. Output edges have edge_id/uuid, source_face_id and axial_index dictionaries.

static BoundingRectangle(topology, optimize: int = 0, tolerance: float = 0.0001, silent: bool = False)

Returns a face representing a bounding rectangle of the input topology. The returned face contains a dictionary with key “zrot” that represents rotations around the Z axis. If applied the resulting face will become axis-aligned.

Parameters

topologytopologic_core.Topology: The input topology.
optimizeint , optional: If set to an integer from 1 (low optimization) to 10 (high optimization), the method will attempt to optimize the bounding rectangle so that it reduces its surface area. Default is 0 which will result in an axis-aligned bounding rectangle. Default is 0.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The bounding rectangle of the input topology.

static ByEdges(edges: list, tolerance: float = 0.0001, silent: bool = False)

Creates a face from the input list of edges.

Parameters

edgeslist: The input list of edges.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

facetopologic_core.Face: The created face.

static ByEdgesCluster(cluster, tolerance: float = 0.0001, silent: bool = False)

Creates a face from the input cluster of edges.

Parameters

clustertopologic_core.Cluster: The input cluster of edges.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

facetopologic_core.Face: The created face.

ByMesh(triangulateQuads: bool = False, quadSplit: str = 'shortest', tolerance: float = 0.0001, silent: bool = False) → list

Creates faces from indexed mesh data.

The mesh is expected to use the canonical TopologicPy mesh schema:

{
“vertices”: [[x, y, z], …], “faces”: [[i, j, k], [i, j, k, l], …]

}

The transitional aliases verts, tris, and quads are also accepted. Triangular elements always create triangular faces. Quad elements create four-sided faces unless triangulateQuads is True, in which case each quad is split into two triangles.

Parameters

meshdict: The input indexed mesh data.
triangulateQuadsbool , optional: If True, quad elements are split into triangles. Default is False.
quadSplitstr , optional: Controls the diagonal used when triangulating quads. Supported values are “shortest”, “02”, and “13”. “02” connects local quad vertices 0 and 2; “13” connects 1 and 3. Default is “shortest”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

list: The created list of triangular and/or quadrilateral faces, or None if the mesh data is invalid or any requested face cannot be created.

static ByNurbsParameters(controlPoints, weights=None, uKnots=None, vKnots=None, isRational: bool = False, isUPeriodic: bool = False, isVPeriodic: bool = False, uDegree: int = 3, vDegree: int = 3, tolerance: float = 0.0001, silent: bool = False)

Creates a Face from exact NURBS/B-spline surface parameters.

The control points are supplied as a rectangular two-dimensional grid:

controlPoints[u][v]

where the first index varies in the U direction and the second index varies in the V direction.

The returned topology is a single Face whose underlying geometry is a genuine B-spline/NURBS surface. It is not a triangulated or polygonal approximation.

Parameters

controlPointslist: A rectangular two-dimensional list of control vertices arranged as controlPoints[u][v].
weightslist , optional: A rectangular two-dimensional list of positive weights having the same dimensions as controlPoints. If None, all weights are set to 1.0. Default is None.
uKnotslist , optional: The expanded nondecreasing knot vector in the U direction. Repeated knots are repeated in the list. If None, an appropriate uniform knot vector is generated. Default is None.
vKnotslist , optional: The expanded nondecreasing knot vector in the V direction. Repeated knots are repeated in the list. If None, an appropriate uniform knot vector is generated. Default is None.
isRationalbool , optional: If True, the supplied weights are used to construct a rational NURBS surface. If False, all weights are treated as 1.0. Default is False.
isUPeriodicbool , optional: If True, the surface is periodic in the U direction. Default is False.
isVPeriodicbool , optional: If True, the surface is periodic in the V direction. Default is False.
uDegreeint , optional: The B-spline degree in the U direction. Default is 3.
vDegreeint , optional: The B-spline degree in the V direction. Default is 3.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created NURBS/B-spline Face, or None if construction fails.

static ByOffset(face, offset: float = 1.0, offsetKey: str = 'offset', stepOffsetA: float = 0, stepOffsetB: float = 0, stepOffsetKeyA: str = 'stepOffsetA', stepOffsetKeyB: str = 'stepOffsetB', reverse: bool = False, smooth: bool = True, transferDictionaries: bool = False, epsilon: float = 0.01, tolerance: float = 0.0001, silent: bool = False, numWorkers: int = None)

Creates an offset planar region, preserving all surviving components.

Returns a Face for one region, a Cluster of Faces for several regions, or None if no positive-area region survives or the operation fails. Multiple regions print a warning unless silent=True. Uniform polygonal offsets handle neck collapse, merging holes, and holes reaching the exterior. Valid curved boundary collisions use native face Booleans; curves are never silently tessellated.

The external boundary and all internal boundary Wires are first normalized to the same traversal direction. The external boundary is then passed to Wire.ByOffset using the input offset as its default offset distance.

Each internal boundary is passed to Wire.ByOffset using -offset as its default offset distance. Thus, for a positive default offset, the external boundary moves inward while holes move outward. Explicit per-Edge values stored under offsetKey always take precedence over these defaults.

Every returned Face is validated independently. Holes can merge, disappear, or become exterior boundaries as the offset changes topology. transferDictionaries applies the source Face dictionary to every region and to the returned Cluster. The ordinary Wire path retains its existing Edge/Vertex dictionary transfer behaviour.

Parameters

facetopologic_core.Face: The input Face. The Face must be planar.
offsetfloat , optional: The default signed offset distance. For the external boundary, positive values move toward the interior of a counter-clockwise boundary. For internal boundaries, the default value is automatically negated so that positive Face offsets enlarge holes. Explicit Edge dictionary values stored under offsetKey override the default. Default is 1.0.
offsetKeystr , optional: Edge dictionary key used by Wire.ByOffset to override the default offset independently for each Edge. Default is “offset”.
stepOffsetAfloat , optional: Default backward trim distance used by Wire.ByOffset when resolving a variable-offset step. Default is 0.
stepOffsetBfloat , optional: Default forward trim distance used by Wire.ByOffset when resolving a variable-offset step. Default is 0.
stepOffsetKeyAstr , optional: Vertex dictionary key overriding stepOffsetA. Default is “stepOffsetA”.
stepOffsetKeyBstr , optional: Vertex dictionary key overriding stepOffsetB. Default is “stepOffsetB”.
reversebool , optional: If True, reverses all effective offset directions. Default is False.
smoothbool , optional: Passed directly to Wire.ByOffset. If True, curved offsets approaching a cusp/fold singularity use the shape-preserving smooth offset strategy. Default is True.
transferDictionariesbool , optional: If True, dictionaries are transferred by Wire.ByOffset and the input Face dictionary is assigned to every returned region and the Cluster, if present. New region boundaries do not necessarily have one-to-one source Edge/Vertex correspondences. Default is False.
epsilonfloat , optional: Cleanup tolerance passed to Wire.ByOffset. Default is 0.01.
tolerancefloat , optional: Geometric tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.
numWorkersint , optional: Worker count passed to Wire.ByOffset. Default is None.

Returns

topologic_core.Face or topologic_core.Cluster or None: One offset Face, a Cluster containing all surviving Faces, or None. Use Topology.Faces(result) to obtain regions from either return type.

static ByOffsetArea(face, area, offsetKey='offset', minOffsetKey='minOffset', maxOffsetKey='maxOffset', defaultMinOffset=0, defaultMaxOffset=1, maxIterations=1, tolerance=0.0001, silent=False, numWorkers=None)

Creates an offset face from the input face based on the input area.

Parameters

facetopologic_core.Face: The input face.
areafloat: The desired area of the created face.
offsetKeystr , optional: The edge dictionary key under which to store the offset value. Default is “offset”.
minOffsetKeystr , optional: The edge dictionary key under which to find the desired minimum edge offset value. If a value cannot be found, the defaultMinOffset input parameter value is used instead. Default is “minOffset”.
maxOffsetKeystr , optional: The edge dictionary key under which to find the desired maximum edge offset value. If a value cannot be found, the defaultMaxOffset input parameter value is used instead. Default is “maxOffset”.
defaultMinOffsetfloat , optional: The desired minimum edge offset distance. Default is 0.
defaultMaxOffsetfloat , optional: The desired maximum edge offset distance. Default is 1.
maxIterations: int , optional: The desired maximum number of iterations to attempt to converge on a solution. Default is 1.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.
numWorkersint , optional: Number of workers run in parallel to process. If you set it to 1, no parallel processing will take place. The default is None which causes the algorithm to use twice the number of cpu cores in the host computer.

Returns

topologic_core.Face or topologic_core.Cluster: The created region(s). Multiple regions use their combined area and return a Cluster, following Face.ByOffset.

static ByParametricFunction(function, uRange: list = [0.0, 1.0], vRange: list = [0.0, 1.0], uSamples: int = 16, vSamples: int = 16, uDegree: int = 3, vDegree: int = 3, tolerance: float = 0.0001, silent: bool = False)

Creates a genuine BSpline Face fitted to function(u, v).

The function must return [x, y, z], (x, y, z), or a TopologicPy Vertex. Sampling is used only to fit the BSpline support; the returned topology is not a mesh or a collection of planar Faces.

static ByShapely(polygon, z: float = 0.0, tolerance: float = 0.0001, silent: bool = False)

Create a planar Face from a valid Shapely Polygon, preserving holes.

Parameters

polygonshapely.geometry.Polygon: A non-empty, valid Polygon with positive area. MultiPolygon and other geometry types are rejected because this method returns one Face. Convert MultiPolygon members separately. Invalid polygons are not automatically repaired.
zfloat, optional: Elevation of the output XY plane. Default is 0.0. Only the input X and Y coordinates are used; any Shapely Z values are ignored.
tolerancefloat, optional: Positive, finite construction tolerance. Default is 0.0001. Features smaller than the backend tolerance may fail conversion.
silentbool, optional: Suppress error messages. Default is False.

Returns

topologic_core.Face or None: A Face with the exterior and every interior ring, or None if input validation or construction fails. Coordinates are not rounded. Ring closure coordinates are removed before building closed Wires.

static ByShell(shell, origin=None, angTolerance: float = 0.1, tolerance: float = 0.0001, silent: bool = False)

Creates a single Face by merging the Faces of the input Shell without flattening the Shell or reconstructing its geometry from Vertices or Wires.

The input Faces must belong to one geometrically compatible supporting surface. Adjacent same-domain Faces are unified natively whenever the active backend supports that operation. Analytical, B-Spline, and NURBS curves and surfaces are retained.

If the Shell is folded, non-coplanar, or otherwise cannot be represented as one trimmed Face on a common supporting surface, the method returns None rather than creating a planar approximation.

Parameters

shelltopologic_core.Shell: The input Shell.
origintopologic_core.Vertex , optional: Retained for backward compatibility. It is not used because this method does not flatten or planarize the input Shell.
angTolerancefloat , optional: The angular tolerance in degrees. Retained for API compatibility. Default is 0.1.
tolerancefloat , optional: The desired geometric tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The unified Face, or None if the Shell cannot be represented as one Face without replacing its native geometry.

static ByThickenedWire(wire, offsetA: float = 1.0, offsetB: float = 0.0, tolerance: float = 0.0001, silent: bool = False)

Creates a planar Face by thickening the input Wire.

Two offset Wires are created on opposite sides of the input Wire. Their existing Edge geometry is preserved exactly. For an open Wire, only two new straight cap Edges are created between corresponding endpoints. Curved, circular, B-Spline, and NURBS offset Edges are never reconstructed from their Vertices.

For a closed Wire, the larger offset loop is used as the external boundary and the smaller offset loop as the internal boundary.

Parameters

wiretopologic_core.Wire: The input manifold planar Wire.
offsetAfloat , optional: The desired offset distance on one side of the Wire. For a closed Wire this is intended to represent the exterior offset. Default is 1.0.
offsetBfloat , optional: The desired offset distance on the opposite side of the Wire. For a closed Wire this is intended to represent the interior offset. Default is 0.0.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The thickened Face, or None if the operation fails.

static ByVertices(vertices: list, tolerance: float = 0.0001, silent: bool = False)

Creates a face from the input list of vertices.

Parameters

verticeslist: The input list of vertices.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created face.

static ByVerticesCluster(cluster, tolerance: float = 0.0001, silent: bool = False)

Creates a face from the input cluster of vertices.

Parameters

clustertopologic_core.Cluster: The input cluster of vertices.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created face.

static ByWire(wire, tolerance: float = 0.0001, silent: bool = False)

Creates a Face from the input closed Wire.

Curved Edges are preserved exactly whenever the active backend supports them. The method never converts a curved Wire to its topological vertices as a fallback. If exact Face construction fails for a curved Wire, None is returned rather than silently chordalising the boundary.

For polygonal Wires only, one conservative SelfMerge cleanup attempt is retained for compatibility with legacy input containing redundant or poorly joined straight Edges.

Parameters

wiretopologic_core.Wire: The input Wire.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created Face, or None if a valid Face cannot be constructed.

static ByWires(externalBoundary, internalBoundaries: list = [], tolerance: float = 0.0001, silent: bool = False)

Creates a Face from one closed external Wire and optional closed internal Wires.

Exact curved Edges are preserved by passing the original Wires directly to the active backend. Invalid or non-contained internal Wires are ignored.

Parameters

externalBoundarytopologic_core.Wire: The external closed boundary Wire.
internalBoundarieslist , optional: Internal closed boundary Wires representing holes. Default is an empty list.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created Face, or None on failure.

static ByWiresCluster(externalBoundary, internalBoundariesCluster=None, tolerance: float = 0.0001, silent: bool = False)

Creates a face from the input external boundary (closed wire) and the input cluster of internal boundaries (closed wires).

Parameters

externalBoundary topologic_core.Wire: The input external boundary (closed wire).
internalBoundariesClustertopologic_core.Cluster: The input cluster of internal boundaries (closed wires). Default is None.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created face.

static CHS(origin=None, radius: float = 0.5, thickness: float = 0.25, sides: int = 16, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False)

Creates a circular hollow section (CHS).

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the CHS. Default is None which results in the CHS being placed at (0, 0, 0).
radiusfloat , optional: The outer radius of the CHS. Default is 0.5.
thicknessfloat , optional: The thickness of the CHS. Default is 0.25.
directionlist , optional: The vector representing the up direction of the CHS. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the CHS. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created face.

static CShape(origin=None, width=1, length=1, a=0.25, b=0.25, c=0.25, flipHorizontal=False, flipVertical=False, direction=[0, 0, 1], placement='center', tolerance=0.0001, silent=False)

Creates a C-shape.

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the C-shape. Default is None which results in the C-shape being placed at (0, 0, 0).
widthfloat , optional: The overall width of the C-shape. Default is 1.0.
lengthfloat , optional: The overall length of the C-shape. Default is 1.0.
afloat , optional: The hortizontal thickness of the vertical arm of the C-shape. Default is 0.25.
bfloat , optional: The vertical thickness of the bottom horizontal arm of the C-shape. Default is 0.25.
cfloat , optional: The vertical thickness of the top horizontal arm of the C-shape. Default is 0.25.
directionlist , optional: The vector representing the up direction of the C-shape. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the C-shape. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created C-shape.

static Catenoid(origin=None, radius: float = 0.5, height: float = 1.0, sides: int = 64, rings: int = 24, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False): Creates a catenoid minimal-surface Face as a BSpline.

static Circle(origin=None, radius: float = 0.5, sides: int = 16, fromAngle: float = 0.0, toAngle: float = 360.0, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, polyline: bool = True, silent: bool = False)

Creates a circular Face.

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the circle. Default is None.
radiusfloat , optional: The radius of the circle. Default is 0.5.
sidesint , optional: In polyline mode, the number of straight sides. In exact curved mode, the number of exact circular-arc Edge subtopologies. Default is 16.
fromAnglefloat , optional: The angle in degrees from which to start creating the arc. Default is 0.
toAnglefloat , optional: The angle in degrees at which to end creating the arc. Default is 360.
directionlist , optional: The vector representing the Face normal. Default is [0, 0, 1].
placementstr , optional: The placement mode. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
polylinebool , optional: Explicitly selects straight-segment or exact curved construction. Default is False.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created circular Face.

static Compactness(face, mantissa: int = 6, silent: bool = False, method: str = 'depthmap') → float

Returns the compactness measure of the input face. See https://en.wikipedia.org/wiki/Compactness_measure_of_a_shape

Parameters

facetopologic_core.Face: The input face.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.
methodstr , optional: Case-insensitive calculation method. ‘topologicpy’ uses sqrt(4*pi*area)/perimeter. ‘depthmap’ uses 4*pi*area/perimeter**2, the square of the first measure. Both use the external-boundary perimeter and net face area. Default is “depthmap”.

Returns

float: The compactness measure of the input face.

static CompassAngle(face, north: list = None, mantissa: int = 6, tolerance: float = 0.0001) → float

Returns the horizontal compass angle in degrees between the normal vector of the input face and the input vector. The angle is measured in counter-clockwise fashion. Only the first two elements of the vectors are considered.

Parameters

facetopologic_core.Face: The input face.
northlist , optional: The second vector representing the north direction. Default is the positive YAxis ([0,1,0]).
mantissaint, optional: The length of the desired mantissa. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

float: The horizontal compass angle in degrees between the direction of the face and the second input vector.

static ConcaveCornerVertices(face, includeInternalBoundaries: bool = False, angTolerance: float = 0.01, mantissa: int = 6, silent: bool = False, tolerance: float = 0.0001) → list

Returns the concave corner vertices of the input face.

A vertex is considered concave if the actual face-material angle at that vertex is greater than 180 degrees, within the specified tolerance. Collinear vertices with angles close to 180 degrees are not returned.

For internal boundaries, the returned classification is based on the material angle around the hole, not the interior angle of the hole loop itself. Thus, a rectangular hole contributes concave corners.

Parameters

facetopologic_core.Face: The input face.
includeInternalBoundariesbool , optional: If set to True, internal boundary vertices are also checked using their face-material angles. Default is False.
angTolerancefloat , optional: The angular tolerance in degrees. Default is 0.01.
mantissaint , optional: The number of decimal places to round computed angles to. Default is 6.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.
tolerancefloat , optional: The geometric tolerance used for ordering boundary vertices. Default is 0.0001.

Returns

list: The list of concave corner vertices.

static Conoid(origin=None, width: float = 1.0, length: float = 1.0, height: float = 1.0, uSamples: int = 24, vSamples: int = 16, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False): Creates a parabolic conoid with straight rulings in the V direction.

static ConvexCornerVertices(face, includeInternalBoundaries: bool = False, angTolerance: float = 0.01, mantissa: int = 6, silent: bool = False, tolerance: float = 0.0001) → list

Returns the convex corner vertices of the input face.

A vertex is considered convex if the actual face-material angle at that vertex is less than 180 degrees, within the specified tolerance. Collinear vertices with angles close to 180 degrees are not returned.

For internal boundaries, the returned classification is based on the material angle around the hole, not the interior angle of the hole loop itself. Thus, a rectangular hole contributes concave corners, not convex corners.

Parameters

facetopologic_core.Face: The input face.
includeInternalBoundariesbool , optional: If set to True, internal boundary vertices are also checked using their face-material angles. Default is False.
angTolerancefloat , optional: The angular tolerance in degrees. Default is 0.01.
mantissaint , optional: The number of decimal places to round computed angles to. Default is 6.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.
tolerancefloat , optional: The geometric tolerance used for ordering boundary vertices. Default is 0.0001.

Returns

list: The list of convex corner vertices.

static CrossShape(origin=None, width=1, length=1, a=0.25, b=0.25, c=None, d=None, flipHorizontal=False, flipVertical=False, direction=[0, 0, 1], placement='center', tolerance=0.0001, silent=False)

Creates a Cross-shape.

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the T-shape. Default is None which results in the Cross-shape being placed at (0, 0, 0).
widthfloat , optional: The overall width of the Cross-shape. Default is 1.0.
lengthfloat , optional: The overall length of the Cross-shape. Default is 1.0.
afloat , optional: The hortizontal thickness of the vertical arm of the Cross-shape. Default is 0.25.
bfloat , optional: The vertical thickness of the horizontal arm of the Cross-shape. Default is 0.25.
cfloat , optional: The distance of the vertical symmetry axis measured from the left side of the Cross-shape. Default is None which results in the Cross-shape being symmetrical on the Y-axis.
dfloat , optional: The distance of the horizontal symmetry axis measured from the bottom side of the Cross-shape. Default is None which results in the Cross-shape being symmetrical on the X-axis.
directionlist , optional: The vector representing the up direction of the Cross-shape. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the Cross-shape. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created Cross-shape.

static CurvatureAtParameters(face, u: float = 0.5, v: float = 0.5, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False) → dict

Returns the local surface curvature properties of the input Face at the specified normalized U and V parameters.

Principal curvatures are signed relative to the oriented normal of the Face. Reversing the Face therefore reverses the signs of the principal and mean curvatures while leaving Gaussian curvature unchanged.

Parameters

facetopologic_core.Face: The input face.
ufloat , optional: The normalized U parameter. Default is 0.5.
vfloat , optional: The normalized V parameter. Default is 0.5.
mantissaint , optional: The number of decimal places to round numerical results to. If None, no rounding is applied. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

dict

A dictionary containing:

maximum: maximum principal curvature.
minimum: minimum principal curvature.
mean: mean curvature.
gaussian: Gaussian curvature.
maximumDirection: maximum principal-curvature direction.
minimumDirection: minimum principal-curvature direction.
isUmbilic: True when the two principal curvatures coincide.

static Edges(face, silent: bool = False) → list

Returns the edges of the input face.

Parameters

facetopologic_core.Face: The input face.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The list of edges.

static Einstein(origin=None, radius: float = 0.5, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001)

Creates an aperiodic monotile, also called an ‘einstein’ tile (meaning one tile in German, not the name of the famous physicist). See https://arxiv.org/abs/2303.10798

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the tile. Default is None which results in the tiles first vertex being placed at (0, 0, 0).
radiusfloat , optional: The radius of the hexagon determining the size of the tile. Default is 0.5.
directionlist , optional: The vector representing the up direction of the ellipse. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the hexagon determining the location of the tile. This can be “center”, or “lowerleft”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

topologic_core.Face: The created Einstein tile.

static Ellipse(origin=None, inputMode: int = 1, width: float = 2.0, length: float = 1.0, focalLength: float = 0.866025, eccentricity: float = 0.866025, majorAxisLength: float = 1.0, minorAxisLength: float = 0.5, sides: int = 32, fromAngle: float = 0.0, toAngle: float = 360.0, close: bool = True, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False, polyline: bool = False)

Creates an elliptical Face.

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the ellipse. Default is None.
inputModeint , optional: Ellipse definition mode. Default is 1.
widthfloat , optional: Overall width when inputMode is 1. Default is 2.0.
lengthfloat , optional: Overall length when inputMode is 1. Default is 1.0.
focalLengthfloat , optional: Focal length used by input modes 2 and 3. Default is 0.866025.
eccentricityfloat , optional: Eccentricity used by input mode 2. Default is 0.866025.
majorAxisLengthfloat , optional: Major-axis length used by input mode 4. Default is 1.0.
minorAxisLengthfloat , optional: Minor-axis length used by input modes 3 and 4. Default is 0.5.
sidesint , optional: Number of exact curve Edge subtopologies, or straight sides when polyline is True. Default is 32.
fromAnglefloat , optional: Start angle in degrees. Default is 0.
toAnglefloat , optional: End angle in degrees. Default is 360.
closebool , optional: If True, a partial ellipse is closed. Default is True.
directionlist , optional: The vector representing the Face normal. Default is [0, 0, 1].
placementstr , optional: The placement mode. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.
polylinebool , optional: If False, preserves the exact rational-NURBS ellipse. If True, creates the historical straight-segment approximation. Default is False.

Returns

topologic_core.Face: The created elliptical Face.

static ExteriorAngles(face, includeInternalBoundaries=False, mantissa: int = 6) → list

Returns the exterior angles of the input face in degrees. The face must be planar.

Parameters

facetopologic_core.Face: The input face.
includeInternalBoundariesbool , optional: If set to True and if the face has internal boundaries (holes), the returned list will be a nested list where the first list is the list of exterior angles of the external boundary and the second list will contain lists of the exterior angles of each of the internal boundaries (holes). For example: [[270,270,270,270], [[270,270,270,270],[300,300,300]]]. If not, the returned list will be a simple list of interior angles of the external boundary. For example: [270,270,270,270]. Please note that that the interior angles of the internal boundaries are considered to be those interior to the original face. Thus, they are exterior to the internal boundary.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.
Returns
——-
list: The list of exterior angles.

static ExternalBoundary(face, tolerance: float = 0.0001, silent=False)

Returns the external boundary (closed wire) of the input face.

Parameters

facetopologic_core.Face: The input face.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Wire: The external boundary of the input face.

static FacingToward(face, direction: list = [0, 0, -1], asVertex: bool = False, mantissa: int = 6, tolerance: float = 0.0001) → bool

Returns True if the input face is facing toward the input direction.

Parameters

facetopologic_core.Face: The input face.
directionlist , optional: The input direction. Default is [0,0,-1].
asVertexbool , optional: If set to True, the direction is treated as an actual vertex in 3D space. Default is False.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

bool: True if the face is facing toward the direction. False otherwise.

static Fillet(face, radius: float = 0, sides: int = 16, radiusKey: str = None, tolerance: float = 0.0001, silent: bool = False)

Fillets the corners of the input planar Face while preserving its native support surface and boundary geometry.

The operation is delegated to the active geometry backend. Existing boundary Edges and internal boundaries are not reconstructed from Vertices.

Backends may provide an exact native planar-face fillet operation. Straight and circular boundary Edges are supported exactly. Unsupported curve configurations fail cleanly rather than being approximated.

Parameters

facetopologic_core.Face: The input planar Face.
radiusfloat , optional: The default fillet radius. Default is 0.
sidesint , optional: Retained for backward API compatibility. Native fillets are exact circular arcs and are not segmented. Default is 16.
radiusKeystr , optional: If specified, each Vertex dictionary is queried for this key. A valid non-negative numerical value overrides the default radius at that Vertex. Default is None.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The filleted Face, or None if the operation fails.

static Helicoid(origin=None, radius: float = 0.5, height: float = 1.0, turns: float = 1.0, radialSamples: int = 16, angularSamples: int = 64, direction: list = [0, 0, 1], placement: str = 'bottom', tolerance: float = 0.0001, silent: bool = False): Creates a helicoid minimal-surface Face as a BSpline.

static HyperbolicParaboloid(origin=None, width: float = 1.0, length: float = 1.0, height: float = 1.0, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False): Creates an exact bilinear hyperbolic-paraboloid (hypar) Face.

static IShape(origin=None, width=1, length=1, a=0.25, b=0.25, c=0.25, flipHorizontal=False, flipVertical=False, direction=[0, 0, 1], placement='center', tolerance=0.0001, silent=False)

Creates an I-shape.

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the I-shape. Default is None which results in the I-shape being placed at (0, 0, 0).
widthfloat , optional: The overall width of the I-shape. Default is 1.0.
lengthfloat , optional: The overall length of the I-shape. Default is 1.0.
afloat , optional: The hortizontal thickness of the central vertical arm of the I-shape. Default is 0.25.
bfloat , optional: The vertical thickness of the bottom horizontal arm of the I-shape. Default is 0.25.
cfloat , optional: The vertical thickness of the top horizontal arm of the I-shape. Default is 0.25.
flipHorizontalbool , optional: if set to True, the shape is flipped horizontally. Default is False.
flipVerticalbool , optional: if set to True, the shape is flipped vertically. Default is False.
directionlist , optional: The vector representing the up direction of the I-shape. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the I-shape. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created I-shape.

static InteriorAngles(face, includeInternalBoundaries: bool = False, mantissa: int = 6) → list

Returns the interior angles of the input face in degrees. The face must be planar.

Parameters

facetopologic_core.Face: The input face.
includeInternalBoundariesbool , optional: If set to True and if the face has internal boundaries (holes), the returned list will be a nested list where the first list is the list of interior angles of the external boundary and the second list will contain lists of the interior angles of each of the internal boundaries (holes). For example: [[90,90,90,90], [[90,90,90,90],[60,60,60]]]. If not, the returned list will be a simple list of interior angles of the external boundary. For example: [90,90,90,90]. Please note that that the interior angles of the internal boundaries are considered to be those interior to the original face. Thus, they are exterior to the internal boundary.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.
Returns
——-
list: The list of interior angles.

static InternalBoundaries(face) → list

Returns the internal boundaries (closed wires) of the input face.

Parameters

facetopologic_core.Face: The input face.

Returns

list: The list of internal boundaries (closed wires).

static InternalVertex(face, tolerance: float = 0.0001, silent: bool = False)

Creates a vertex guaranteed to be inside the input face.

Parameters

facetopologic_core.Face: The input face.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Vertex: The created vertex.

static Invert(face, tolerance: float = 0.0001, silent: bool = False)

Reverses the orientation of the input Face without approximating its geometry.

Exact curved boundaries and NURBS surfaces are preserved. The preferred path reverses the backend-native Face directly. If native reversal is unavailable, a planar fallback reverses the existing boundary Wires rather than rebuilding them from vertices.

Parameters

facetopologic_core.Face: The input Face.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The orientation-reversed Face, or None on failure.

static IsConvex(face, mantissa: int = 6, silent: bool = False) → bool

Returns True if the input face is convex. Returns False otherwise.

Parameters

facetopologic_core.Face: The input face.
mantissaint , optional: The length of the desired mantissa. Default is 6.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

bool: True if the input face is convex. False otherwise.

static IsCoplanar(faceA, faceB, mantissa: int = 6, tolerance: float = 0.0001) → bool

Returns True if the two input faces are coplanar. Returns False otherwise.

Parameters

faceAtopologic_core.Face: The first input face.
faceBtopologic_core.Face: The second input face
mantissaint , optional: The length of the desired mantissa. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

bool: True if the two input faces are coplanar. False otherwise.

static IsPlanar(face, tolerance: float = 0.0001, silent: bool = False) → bool

Returns True if the input Face lies on a plane. Returns False otherwise.

The active backend is queried first for an exact/native planarity test. If one is not available, the underlying surface is sampled in normalized UV space and tested against the tangent plane at its parametric centre.

This method tests the actual supporting surface rather than merely testing whether the boundary vertices happen to be coplanar.

Parameters

facetopologic_core.Face: The input face.
tolerancefloat , optional: The desired geometric tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

bool: True if the Face is planar. False if it is non-planar. None if planarity cannot be determined.

static Isovist(face, vertex, obstacles: list = [], direction: list = [0, 1, 0], fov: float = 360, transferDictionaries: bool = False, metrics: bool = False, triangles: bool = False, method: str = 'depthmap', mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False, radius: float = None, radiusSides: int = 64, holes: list = None, boundaryTypeKey: str = 'isovistType', defaultBoundaryType: str = 'obstacle')

Returns the face representing the isovist projection from the input viewpoint.

This implementation uses a fast 2D visibility algorithm: 1. The input face and exclusion wires are flattened to the XY plane. 2. Viewpoints in holes or obstacles are rejected. Only obstacles are

subtracted from the visibility domain; holes remain transparent.

Critical-angle rays are cast from the viewpoint to all polygon vertices.
The nearest boundary intersection along each ray is used to construct the visible polygon.
The resulting Shapely polygon is converted back to a TopologicPy Face.
Metrics and dictionary transfer are preserved.

This method assumes all visibility computation is carried out in 2D. The input topology may be non-horizontal because it is flattened before computation and unflattened before return.

Parameters

facetopologic_core.Face: The face representing the boundary of the isovist.
vertextopologic_core.Vertex: The vertex representing the viewpoint.
obstacleslist , optional: Additional closed Wires representing opaque obstacles. Their interiors and boundaries reject viewpoints and block sightlines. Wire dictionary labels are ignored for these additional inputs. Default is [].
directionlist, optional: The vector representing the direction of view in the XY plane. Default is [0,1,0].
fovfloat , optional: The horizontal field of view angle in degrees. Acceptable range is 1 to 360. Default is 360.
transferDictionariesbool , optional: If True, dictionaries of encountered physical edges are transferred to matching isovist edges.
metricsbool , optional: If True, isovist metrics are calculated and stored in the dictionary of the returned face. occlusivity is occluded boundary length divided by perimeter; occluded_length stores the absolute length in model units. Physical wall coverage is matched within tolerance, including adjacent wall segments. Edge dictionaries contain occlusive and occluded_length.
trianglesbool , optional: If True, radial triangles from the viewpoint to isovist edges are stored as contents.
methodstr , optional: Case-insensitive calculation method for face compactness. ‘topologicpy’ uses sqrt(4*pi*area)/perimeter. ‘depthmap’ uses 4*pi*area/perimeter**2, the square of the first measure. Both use the external-boundary perimeter and net face area. Default is “depthmap”.
mantissaint , optional: Number of decimal places to round results to. Default is 6.
tolerancefloat , optional: Desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.
radiusfloat, optional: Maximum sight distance in model units, measured in the face plane. None preserves unlimited visibility. A finite value must exceed tolerance. The working free space is clipped before ray casting, so distant boundaries cannot increase the visibility-ray count.
radiusSidesint, optional: Number of sides in the inscribed regular polygon approximating the circular radius limit. Default 64; must be an integer >= 8 when radius is supplied. Maximum radial deficit is radius*(1-cos(pi/radiusSides)). Radius edges are tagged range_limited and excluded from occluded_length/occlusivity and closed_perimeter. Metrics additionally store radius and range_limited_length.
holeslist, optional: Additional closed Wires representing transparent, non-walkable holes. Viewpoints in or on them are rejected, but their boundaries and interiors do not clip the isovist polygon or block sightlines. Default is None. Inputs and their dictionaries are not modified.
boundaryTypeKeystr, optional: Dictionary key on each internal boundary Wire of face. A value of “hole” makes that boundary transparent; “obstacle” makes it opaque. Values are case-insensitive. Missing/None values use defaultBoundaryType; unrecognised values return None with an error unless silent is True. Default key is “isovistType”. Labels are read before flattening, so non-horizontal faces are supported.
defaultBoundaryTypestr, optional: Treatment of unlabelled internal boundaries: “hole” or “obstacle” (case-insensitive). Default is “obstacle” for backward compatibility. The resulting isovist measures visible area, including transparent holes; it is not a walkable-area or navigation polygon. Transparent hole edges are excluded from physical-edge dictionary transfer and occlusivity/closed-perimeter classification.

Returns

topologic_core.Face: The face representing the isovist projection from the input viewpoint.

static LShape(origin=None, width=1, length=1, a=0.25, b=0.25, flipHorizontal=False, flipVertical=False, direction=[0, 0, 1], placement='center', tolerance=0.0001, silent=False)

Creates an L-shape.

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the L-shape. Default is None which results in the L-shape being placed at (0, 0, 0).
widthfloat , optional: The overall width of the L-shape. Default is 1.0.
lengthfloat , optional: The overall length of the L-shape. Default is 1.0.
afloat , optional: The hortizontal thickness of the vertical arm of the L-shape. Default is 0.25.
bfloat , optional: The vertical thickness of the horizontal arm of the L-shape. Default is 0.25.
directionlist , optional: The vector representing the up direction of the L-shape. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the L-shape. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created L-shape.

static MedialAxis(face, resolution: int = 0, externalVertices: bool = False, internalVertices: bool = False, toLeavesOnly: bool = False, angTolerance: float = 0.1, tolerance: float = 0.0001, silent: bool = False)

Returns a wire representing an approximation of the medial axis of the input topology. See https://en.wikipedia.org/wiki/Medial_axis.

Parameters

facetopologic_core.Face: The input face.
resolutionint , optional: The desired resolution of the solution (range is 0: standard resolution to 10: high resolution). This determines the density of the sampling along each edge. Default is 0.
externalVerticesbool , optional: If set to True, the external vertices of the face will be connected to the nearest vertex on the medial axis. Default is False.
internalVerticesbool , optional: If set to True, the internal vertices of the face will be connected to the nearest vertex on the medial axis. Default is False.
toLeavesOnlybool , optional: If set to True, the vertices of the face will be connected to the nearest vertex on the medial axis only if this vertex is a leaf (end point). Otherwise, it will connect to any nearest vertex. Default is False.
angTolerancefloat , optional: The desired angular tolerance in degrees for removing collinear edges. Default is 0.1.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Wire: The medial axis of the input face.

static Normal(face, outputType='xyz', mantissa: int = 6, silent: bool = False)

Returns the normal vector to the input face. A normal vector of a face is a vector perpendicular to it.

Parameters

facetopologic_core.Face: The input face.
outputTypestring , optional: The string defining the desired output. This can be any subset or permutation of “xyz”. It is case insensitive. Default is “xyz”.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.

Returns

list: The normal vector to the input face.

static NormalAtParameters(face, u: float = 0.5, v: float = 0.5, outputType: str = 'xyz', mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns the oriented unit normal vector to the input Face at the specified normalized U and V parameters.

This method evaluates the actual underlying surface and therefore supports planar, analytic, B-spline, and NURBS surfaces.

Parameters

facetopologic_core.Face: The input face.
ufloat , optional: The normalized U parameter in the range 0 to 1. Default is 0.5.
vfloat , optional: The normalized V parameter in the range 0 to 1. Default is 0.5.
outputTypestr , optional: Any subset or permutation of “xyz”. Default is “xyz”.
mantissaint , optional: The number of decimal places to round the result to. If None, no rounding is applied. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The requested normal-vector components.

static NormalEdge(face, length: float = 1.0, tolerance: float = 0.0001, silent: bool = False)

Returns an Edge representing the local surface normal of the input Face.

The normal is evaluated at an internal vertex of the Face. For a curved Face, the corresponding local U and V parameters are used to obtain the actual surface normal at that point.

Parameters

facetopologic_core.Face: The input face.
lengthfloat , optional: The desired length of the normal edge. Default is 1.0.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Edge: The created normal Edge, or None if it cannot be created.

static NorthArrow(origin=None, radius: float = 0.5, sides: int = 16, direction: list = [0, 0, 1], northAngle: float = 0.0, placement: str = 'center', tolerance: float = 0.0001)

Creates a north arrow.

The arrow is built in canonical local XY with a +Z normal, rotated about the local origin, translated for placement, placed once at the requested origin, and finally oriented to the requested direction.

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the north arrow. Default is None.
radiusfloat , optional: The radius of the circular body. Default is 0.5.
sidesint , optional: The number of sides of the circular body. Default is 16.
directionlist , optional: The vector representing the Face normal. Default is [0, 0, 1].
northAnglefloat , optional: Angular offset in degrees from positive Y, measured counter-clockwise. Default is 0.
placementstr , optional: One of “center”, “lowerleft”, “upperleft”, “lowerright”, or “upperright”. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

topologic_core.Face: The created north-arrow Face, or None on failure.

static Paraboloid(origin=None, radius: float = 0.5, height: float = 1.0, sides: int = 64, rings: int = 16, direction: list = [0, 0, 1], placement: str = 'bottom', tolerance: float = 0.0001, silent: bool = False): Creates an elliptic paraboloid Face as a tolerance-controlled BSpline.

static Planarize(face, origin=None, tolerance: float = 0.0001)

Planarizes the input face such that its center of mass is located at the input origin and its normal is pointed in the input direction.

Parameters

facetopologic_core.Face: The input face.
origintopologic_core.Vertex , optional: The desired vertex to use as the origin of the plane to project the face unto. If set to None, the centroidof the input face is used. Default is None.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

topologic_core.Face: The planarized face.

static PlaneEquation(face, mantissa: int = 6) → dict

Returns the a, b, c, d coefficients of the plane equation of the input face. The input face is assumed to be planar.

Parameters

facetopologic_core.Face: The input face.

Returns

dict: The dictionary containing the coefficients of the plane equation. The keys of the dictionary are: [“a”, “b”, “c”, “d”].

static Project(faceA, faceB, direction: list = None, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Creates a projection of the first input Face onto the second input Face.

The projected boundary Wires are used to trim the receiving Face itself. The result therefore retains the receiving Face’s native supporting surface, including B-spline and NURBS surfaces, instead of asking Face.ByWires to infer a new surface from the projected boundaries. Native projected curve geometry is likewise retained.

Parameters

faceAtopologic_core.Face: The face to be projected.
faceBtopologic_core.Face: The face unto which the first input face will be projected.
directionlist, optional: The vector direction of the projection. If None, the reverse vector of the receiving face normal will be used. Default is None.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The projected Face.

static RHS(origin=None, width: float = 1.0, length: float = 1.0, thickness: float = 0.25, outerFillet: float = 0.0, innerFillet: float = 0.0, sides: int = 16, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False)

Creates a rectangular hollow section (RHS).

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the RHS. Default is None.
widthfloat , optional: The width of the RHS. Default is 1.0.
lengthfloat , optional: The length of the RHS. Default is 1.0.
thicknessfloat , optional: The wall thickness. Default is 0.25.
outerFilletfloat , optional: Outer fillet factor multiplied by thickness. Default is 0.
innerFilletfloat , optional: Inner fillet factor multiplied by thickness. Default is 0.
sidesint , optional: The desired number of sides of the fillets. Default is 16.
directionlist , optional: The vector representing the Face normal. Default is [0, 0, 1].
placementstr , optional: One of “center”, “lowerleft”, “upperleft”, “lowerright”, or “upperright”. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created RHS Face, or None on failure.

static Rectangle(origin=None, width: float = 1.0, length: float = 1.0, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = True)

Creates a rectangle.

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the rectangle. Default is None which results in the rectangle being placed at (0, 0, 0).
widthfloat , optional: The width of the rectangle. Default is 1.0.
lengthfloat , optional: The length of the rectangle. Default is 1.0.
directionlist , optional: The vector representing the up direction of the rectangle. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the rectangle. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created face.

static RectangleByPlaneEquation(origin=None, width: float = 1.0, length: float = 1.0, placement: str = 'center', equation: dict = None, tolerance: float = 0.0001)

static RemoveCollinearEdges(face, angTolerance: float = 0.1, tolerance: float = 0.0001, silent: bool = False)

Removes redundant consecutive linear collinear Edges from the boundaries of the input Face while preserving the Face’s original support surface and all curved boundary geometry.

Only linear Edge chains are eligible for merging. Vertices incident to genuinely curved Edges are protected so curved, circular, B-Spline, and NURBS Edges remain unchanged.

Parameters

facetopologic_core.Face: The input Face.
angTolerancefloat , optional: Maximum angular deviation in degrees for adjacent linear Edges to be considered collinear. Default is 0.1.
tolerancefloat , optional: The desired geometric tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The simplified Face, or None if the active backend cannot perform the operation while preserving the original support surface.

static Ring(origin=None, radius: float = 0.5, thickness: float = 0.25, sides: int = 16, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False)

Creates a circular ring. This is an alias method for creating a circular hollow section (CHS).

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the ring. Default is None which results in the ring being placed at (0, 0, 0).
radiusfloat , optional: The outer radius of the ring. Default is 0.5.
thicknessfloat , optional: The thickness of the ring. Default is 0.25.
directionlist , optional: The vector representing the up direction of the ring. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the ring. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created face.

static SHS(origin=None, size: float = 1.0, thickness: float = 0.25, outerFillet: float = 0.0, innerFillet: float = 0.0, sides: int = 16, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False)

Creates a square hollow section (SHS).

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the SHS. Default is None which results in the SHS being placed at (0, 0, 0).
sizefloat , optional: The outer size of the SHS. Default is 1.0.
thicknessfloat , optional: The thickness of the SHS. Default is 0.25.
outerFilletfloat , optional: The outer fillet multiplication factor based on the thickness (e.g. 1t). Default is 0.
innerFilletfloat , optional: The inner fillet multiplication factor based on the thickness (e.g. 1.5t). Default is 0.
sidesint , optional: The desired number of sides of the fillets. Default is 16.
directionlist , optional: The vector representing the up direction of the SHS. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the SHS. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created face.

static Scherk(origin=None, width: float = 1.0, length: float = 1.0, height: float = 1.0, uSamples: int = 32, vSamples: int = 32, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False): Creates Scherk’s first minimal surface as a BSpline Face.

static Simplify(face, method: str = 'douglas-peucker', epsilon: float = 0.0001, tolerance: float = 0.0001, silent: bool = False)

Simplifies the linear portions of the boundaries of a planar Face while preserving curved Edges.

Curved Edges are retained exactly. Purely polygonal boundaries and contiguous linear portions of mixed boundaries are simplified using Wire.Simplify.

Parameters

facetopologic_core.Face: The input Face.
methodstr , optional: The simplification method. Supported values are “douglas-peucker”, “visvalingam-whyatt”, and “reumann-witkam”. Default is “douglas-peucker”.
epsilonfloat , optional: The simplification threshold. Default is 0.0001.
tolerancefloat , optional: The topology construction and coincidence tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The simplified Face.

static Skeleton(face, boundary: bool = True, tolerance: float = 0.001)

Creates a straight skeleton. This method is contributed by 高熙鹏 xipeng gao <gaoxipeng1998@gmail.com> This algorithm depends on the polyskel code which is included in the library. Polyskel code is found at: https://github.com/Botffy/polyskel

Parameters

facetopologic_core.Face: The input face.
boundarybool , optional: If set to True the original boundary is returned as part of the roof. Otherwise it is not. Default is True.
tolerancefloat , optional: The desired tolerance. Default is 0.001. (This is set to a larger number than the usual 0.0001 as it was found to work better)

Returns

topologic_core.Wire: The created straight skeleton.

static Square(origin=None, size: float = 1.0, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001)

Creates a square.

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the square. Default is None which results in the square being placed at (0, 0, 0).
sizefloat , optional: The size of the square. Default is 1.0.
directionlist , optional: The vector representing the up direction of the square. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the square. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, or “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

topologic_core.Face: The created square.

static Squircle(origin=None, radius: float = 0.5, sides: int = 121, a: float = 2.0, b: float = 2.0, direction: list = [0, 0, 1], placement: str = 'center', angTolerance: float = 0.1, tolerance: float = 0.0001, silent: bool = False)

Creates a Squircle which is a hybrid between a circle and a square. See https://en.wikipedia.org/wiki/Squircle

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the squircle. Default is None which results in the squircle being placed at (0, 0, 0).
radiusfloat , optional: The desired radius of the squircle. Default is 0.5.
sidesint , optional: The desired number of sides of the squircle. Default is 121.
afloat , optional: The “a” factor affects the x position of the points to interpolate between a circle and a square. A value of 1 will create a circle. Higher values will create a more square-like shape. Default is 2.0.
bfloat , optional: The “b” factor affects the y position of the points to interpolate between a circle and a square. A value of 1 will create a circle. Higher values will create a more square-like shape. Default is 2.0.
directionlist , optional: The vector representing the up direction of the circle. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the circle. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, or “upperright”. It is case insensitive. Default is “center”.
angTolerancefloat , optional: The desired angular tolerance. Default is 0.1.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

topologic_core.Face: The created squircle.

static Star(origin=None, radiusA: float = 0.5, radiusB: float = 0.2, rays: int = 8, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False)

Creates a star.

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the star. Default is None which results in the star being placed at (0, 0, 0).
radiusAfloat , optional: The outer radius of the star. Default is 1.0.
radiusBfloat , optional: The outer radius of the star. Default is 0.4.
raysint , optional: The number of star rays. Default is 5.
directionlist , optional: The vector representing the up direction of the star. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the star. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, or “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

topologic_core.Face: The created face.

static TShape(origin=None, width=1, length=1, a=0.25, b=0.25, flipHorizontal=False, flipVertical=False, direction=[0, 0, 1], placement='center', tolerance=0.0001, silent=False)

Creates a T-shape.

Parameters

origintopologic_core.Vertex , optional: The location of the origin of the T-shape. Default is None which results in the T-shape being placed at (0, 0, 0).
widthfloat , optional: The overall width of the T-shape. Default is 1.0.
lengthfloat , optional: The overall length of the T-shape. Default is 1.0.
afloat , optional: The hortizontal thickness of the vertical arm of the T-shape. Default is 0.25.
bfloat , optional: The vertical thickness of the horizontal arm of the T-shape. Default is 0.25.
directionlist , optional: The vector representing the up direction of the T-shape. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the T-shape. This can be “center”, “lowerleft”, “upperleft”, “lowerright”, “upperright”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created T-shape.

static TangentAtParameters(face, u: float = 0.5, v: float = 0.5, axis: str = 'u', outputType: str = 'xyz', mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False) → list

Returns one parametric tangent direction of the input Face at the specified normalized parameters.

Parameters

facetopologic_core.Face: The input face.
ufloat , optional: The normalized U parameter. Default is 0.5.
vfloat , optional: The normalized V parameter. Default is 0.5.
axisstr , optional: The requested parametric direction. Valid values are “u” and “v”. Default is “u”.
outputTypestr , optional: Any subset or permutation of “xyz”. Default is “xyz”.
mantissaint , optional: The number of decimal places to round the result to. If None, no rounding is applied. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The requested unit tangent direction.

static TangentsAtParameters(face, u: float = 0.5, v: float = 0.5, outputType: str = 'xyz', mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False) → dict

Returns the U and V parametric tangent directions of the input Face at the specified normalized parameters.

The U tangent points in the direction of increasing U and the V tangent points in the direction of increasing V. The two tangent directions are not necessarily orthogonal on a general parametric surface.

These are parametric surface directions. Reversing the topological orientation of a Face does not reverse its U or V parameter directions.

Parameters

facetopologic_core.Face: The input face.
ufloat , optional: The normalized U parameter. Default is 0.5.
vfloat , optional: The normalized V parameter. Default is 0.5.
outputTypestr , optional: Any subset or permutation of “xyz”. Default is “xyz”.
mantissaint , optional: The number of decimal places to round the result to. If None, no rounding is applied. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

dict: A dictionary with keys u and v containing the corresponding unit tangent directions.

static ThirdVertex(face, tolerance: float = 0.0001, silent: bool = False)

Returns a third vertex on the input face to enable rotation matrix creation.

Parameters

facetopologic_core.Face: The input face.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The created face.

static Trapezoid(origin=None, widthA: float = 1.0, widthB: float = 0.75, offsetA: float = 0.0, offsetB: float = 0.0, length: float = 1.0, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False)

Creates a trapezoid.

Parameters

origintopologic_core.Vertex, optional: The location of the origin of the trapezoid. Default is None which results in the trapezoid being placed at (0, 0, 0).
widthAfloat , optional: The width of the bottom edge of the trapezoid. Default is 1.0.
widthBfloat , optional: The width of the top edge of the trapezoid. Default is 0.75.
offsetAfloat , optional: The offset of the bottom edge of the trapezoid. Default is 0.0.
offsetBfloat , optional: The offset of the top edge of the trapezoid. Default is 0.0.
lengthfloat , optional: The length of the trapezoid. Default is 1.0.
directionlist , optional: The vector representing the up direction of the trapezoid. Default is [0, 0, 1].
placementstr , optional: The description of the placement of the origin of the trapezoid. This can be “center”, or “lowerleft”. It is case insensitive. Default is “center”.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.

Returns

topologic_core.Face: The created trapezoid.

static Triangulate(face, mode: int = 0, meshSize: float = None, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False) → list

Triangulates the input Face and returns its triangular Faces.

This method is a thin compatibility wrapper around Topology.Triangulate(). Face-level triangulation no longer owns a meshing implementation and never invokes gmsh. Numerical 2D/3D meshing is provided separately by Topology.Mesh().

Parameters

facetopologic_core.Face: The input Face.
modeint , optional: Deprecated compatibility parameter. It is ignored. Historical gmsh algorithm selection has moved to Topology.Mesh. Default is 0.
meshSizefloat , optional: Deprecated compatibility parameter. It is ignored. Use Topology.Mesh for numerical mesh sizing. Default is None.
mantissaint , optional: Retained for API compatibility. It is not used by this wrapper. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If True, error and warning messages are suppressed. Default is False.

Returns

list: The triangular Faces, or None if triangulation fails.

static TrimByWire(face, wire, reverse: bool = False, tolerance: float = 0.0001, silent: bool = False)

Trims the input face by the input wire.

Parameters

facetopologic_core.Face: The input face.
wiretopologic_core.Wire: The trimming wire.
reversebool , optional: If True, the complementary part of the face is returned. Default is False.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Face: The resulting trimmed face.

static VertexByParameters(face, u: float = 0.5, v: float = 0.5, tolerance: float = 0.0001, silent: bool = False)

Creates a vertex at normalized u and v parameters of the input face.

Parameters

facetopologic_core.Face: The input face.
ufloat , optional: The normalized u parameter. Default is 0.5.
vfloat , optional: The normalized v parameter. Default is 0.5.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Vertex: The created vertex.

static VertexParameters(face, vertex, outputType: str = 'uv', mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False) → list

Returns normalized face parameters at the location of the input vertex.

Parameters

facetopologic_core.Face: The input face.
vertextopologic_core.Vertex: The input vertex.
outputTypestr , optional: Any subset or permutation of “uv”. Default is “uv”.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The requested normalized parameters.

static Vertices(face) → list

Returns the vertices of the input face.

Parameters

facetopologic_core.Face: The input face.

Returns

list: The list of vertices.

static Wire(face)

Returns the external boundary (closed wire) of the input face.

Parameters

facetopologic_core.Face: The input face.

Returns

topologic_core.Wire: The external boundary of the input face.

static Wires(face) → list

Returns the wires of the input face.

Parameters

facetopologic_core.Face: The input face.

Returns

list: The list of wires.

Transparent holes in isovists

Face.Isovist distinguishes non-walkable holes from opaque obstacles. Its existing obstacles list accepts additional closed Wires; the new holes list accepts additional transparent exclusion Wires. Both reject viewpoints in or on them, but only obstacles stop sightlines. Visible area includes transparent holes and must not be used as a navigation domain.

Internal boundary Wires use the dictionary key isovistType by default, with case-insensitive values hole or obstacle. Set boundaryTypeKey to use another key. Missing labels follow defaultBoundaryType="obstacle" (the previous behaviour); choose defaultBoundaryType="hole" to see across all unlabelled internal voids. Explicit input lists determine their members’ roles regardless of labels. Opaque obstacles take precedence wherever the two types overlap.

For example:

isovist = Face.Isovist(room, viewpoint,
                      holes=[atrium], obstacles=[column],
                      boundaryTypeKey="isovistType",
                      defaultBoundaryType="hole", metrics=True)

The geometry is evaluated in the face plane, including tilted faces. Transparent hole edges do not contribute physical wall dictionaries or occlusion/closed-perimeter metrics. Existing positional arguments remain unchanged; the new parameters are appended to the signature.

To classify an existing internal boundary individually:

inner = Face.InternalBoundaries(room)[0]
Topology.SetDictionary(inner,
                      Dictionary.ByPythonDictionary({"isovistType": "hole"}))
isovist = Face.Isovist(room, viewpoint)