topologicpy.Cluster module

class topologicpy.Cluster.Cluster

Bases: object

Methods

ByFormula(formula[, xRange, yRange, ...])

Creates a cluster of vertices by evaluating the input formula for a range of x values and, optionally, a range of y values.

ByFunction(topologies, function[, mantissa, ...])

Clusters the list of input topologies based on an input evaluation function.

ByTopologies(*topologies[, ...])

Creates a topologic Cluster from the input topologies.

CellComplexes(cluster[, silent])

Returns the cellComplexes of the input cluster.

Cells(cluster[, silent])

Returns the cells of the input cluster.

DBSCAN(topologies[, selectors, keys, ...])

Clusters the input vertices based on the Density-Based Spatial Clustering of Applications with Noise (DBSCAN) method.

Edges(cluster[, silent])

Returns the edges of the input cluster.

ExternalBoundary(cluster[, silent])

Returns the external boundary of the input cluster.

Faces(cluster[, silent])

Returns the faces of the input cluster.

FreeCells(cluster[, tolerance, silent])

Returns direct Cell constituents of the input Cluster.

FreeEdges(cluster[, tolerance, silent])

Returns direct Edge constituents of the input Cluster.

FreeFaces(cluster[, tolerance, silent])

Returns direct Face constituents of the input Cluster.

FreeShells(cluster[, tolerance, silent])

Returns direct Shell constituents of the input Cluster.

FreeTopologies(cluster[, tolerance, silent])

Returns direct constituent Topologies of the Cluster.

FreeVertices(cluster[, tolerance, silent])

Returns direct Vertex constituents of the input Cluster.

FreeWires(cluster[, tolerance, silent])

Returns direct Wire constituents of the input Cluster.

HighestType(cluster)

Returns the type of the highest dimension subtopology found in the input cluster.

KMeans(topologies[, selectors, keys, k, ...])

Clusters the input topologies using K-Means-like clustering.

MergeCells(cells[, tolerance, silent])

Groups face-adjacent Cells into connected CellComplex components.

MysticRose([wire, origin, radius, sides, ...])

Creates a mystic rose.

Shells(cluster[, silent])

Returns the shells of the input cluster.

Simplify(cluster[, tolerance, silent])

Simplifies a Cluster only when it has exactly one direct constituent.

Topologies(cluster[, tolerance, silent])

Returns the direct, top-level constituent Topologies of a Cluster.

Tripod([size, radius, sides, faceColorKey, ...])

Creates a color-coded Axes tripod for X, Y, and Z axes.

Vertices(cluster[, silent])

Returns the vertices of the input cluster.

Wires(cluster[, silent])

Returns the wires of the input cluster.
static ByFormula(formula, xRange=None, yRange=None, xString='X', yString='Y')

Creates a cluster of vertices by evaluating the input formula for a range of x values and, optionally, a range of y values.

Parameters
formulastr

A string representing the formula to be evaluated. For 2D formulas (i.e. Z = 0), use either ‘X’ (uppercase) or ‘Y’ (uppercase) for the independent variable. For 3D formulas, use ‘X’ and ‘Y’ (uppercase) for the independent variables. The Z value will be evaluated. For 3D formulas, both xRange and yRange MUST be specified. You can use standard math functions like ‘sin’, ‘cos’, ‘tan’, ‘sqrt’, etc. For example, ‘X**2 + 2*X - sqrt(X)’ or ‘cos(abs(X)+abs(Y))’

xRangetuple , optional

A tuple (start, end, step) representing the range of X values for which the formula should be evaluated. For example, to evaluate Y for X values from -5 to 5 with a step of 0.1, you should specify xRange=(-5, 5, 0.1). If the xRange is set to None or not specified: . The method assumes that the formula uses the yString (e.g. ‘Y’ as in ‘Y**2 + 2*Y - sqrt(Y)’) . The method will attempt to evaluate X based on the specified yRange. . xRange and yRange CANNOT be None or unspecified at the same time. One or the other must be specified.

yRangetuple , optional

A tuple (start, end, step) representing the range of Y values for which the formula should be evaluated. For example, to evaluate X for Y values from -5 to 5 with a step of 0.1, you should specify yRange=(-5,5,0.1). If the yRange is set to None or not specified: . The method assumes that the formula uses the xString (e.g. ‘X’ as in ‘X**2 + 2*X - sqrt(X)’) . The method will attempt to evaluate Y based on the specified xRange. . xRange and yRange CANNOT be None or unspecified at the same time. One or the other must be specified.

xStringstr , optional

The string used to represent the X independent variable. Default is ‘X’ (uppercase).

yStringstr , optional

The string used to represent the Y independent variable. Default is ‘Y’ (uppercase).

Returns
topologic_core.Cluster

The created cluster of vertices.

static ByFunction(topologies: list, function: Callable, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Clusters the list of input topologies based on an input evaluation function.

The input function may return:

  • numeric values (int, float) -> clustered using tolerance-based matching

  • booleans -> clustered by exact value

  • strings -> clustered by exact value

  • None -> clustered by exact value

  • other values -> clustered by exact value where possible

Parameters
topologieslist

The list of input topologies to be clustered.

functioncallable

The callable evaluation function that determines the category of each topology. The function must take three inputs only in the following order: 1. A single topology 2. A “mantissa” (named input) 3. A “tolerance” (named input)

e.g. compute_value(topology, mantissa=6, tolerance=0.0001)

mantissaint , optional

The desired length of the mantissa. 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 list of clusters. Each item in the list is a list of topologies that return the same or equivalent value from the evaluation function.

static ByTopologies(*topologies, transferDictionaries: bool = False, silent: bool = False)

Creates a topologic Cluster from the input topologies.

The input can be individual topologies supplied as separate arguments or a list of topologies supplied as one argument.

If a single topology is supplied directly, that topology is returned unchanged. If a list is supplied, a Cluster is created even when the list contains only one valid topology.

Parameters
*topologiestopologic_core.Topology

One or more topologies, or a list of topologies, to be processed.

transferDictionariesbool , optional

If set to True, the dictionaries from the input topologies are merged and transferred to the resulting Cluster. Default is False.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
topologic_core.Topology

The created Cluster, or the original topology if a single topology was supplied directly. Returns None if no valid topologies are found.

static CellComplexes(cluster, silent: bool = False) → list

Returns the cellComplexes of the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
list

The list of cellComplexes.

static Cells(cluster, silent: bool = False) → list

Returns the cells of the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
list

The list of cells.

static DBSCAN(topologies, selectors=None, keys=['x', 'y', 'z'], epsilon: float = 0.5, minSamples: int = 2)

Clusters the input vertices based on the Density-Based Spatial Clustering of Applications with Noise (DBSCAN) method. See https://en.wikipedia.org/wiki/DBSCAN

Parameters
topologieslist

The input list of topologies to be clustered.

selectorslist , optional

If the list of topologies are not vertices then please provide a corresponding list of selectors (vertices) that represent the topologies for clustering. For example, these can be the centroids of the topologies. If set to None, the list of topologies is expected to be a list of vertices. Default is None.

keyslist, optional

The keys in the embedded dictionaries in the topologies. If specified, the values at these keys will be added to the dimensions to be clustered. The values must be numeric. If you wish the x, y, z location to be included, make sure the keys list includes “X”, “Y”, and/or “Z” (case insensitive). Default is [“x”, “y”, “z”]

epsilonfloat , optional

The maximum radius around a data point within which other points are considered to be part of the same sense region (cluster). Default is 0.5.

minSamplesint , optional

The minimum number of points required to form a dense region (cluster). Default is 2.

Returns
list, list

The list of clusters and the list of vertices considered to be noise if any (otherwise returns None).

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

Returns the edges of the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
list

The list of edges.

static ExternalBoundary(cluster, silent: bool = False)

Returns the external boundary of the input cluster.

Parameters
clustertopologic_core.Clusterx

The input cluster.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
topologic_core.Cluster

The external boundary of the input cluster.

static Faces(cluster, silent: bool = False) → list

Returns the faces of the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
list

The list of faces.

static FreeCells(cluster, tolerance: float = 0.0001, silent: bool = False) → list

Returns direct Cell constituents of the input Cluster.

static FreeEdges(cluster, tolerance: float = 0.0001, silent: bool = False) → list

Returns direct Edge constituents of the input Cluster.

static FreeFaces(cluster, tolerance: float = 0.0001, silent: bool = False) → list

Returns direct Face constituents of the input Cluster.

static FreeShells(cluster, tolerance: float = 0.0001, silent: bool = False) → list

Returns direct Shell constituents of the input Cluster.

static FreeTopologies(cluster, tolerance: float = 0.0001, silent: bool = False) → list

Returns direct constituent Topologies of the Cluster.

No geometric Boolean subtraction is used.

static FreeVertices(cluster, tolerance: float = 0.0001, silent: bool = False) → list

Returns direct Vertex constituents of the input Cluster.

static FreeWires(cluster, tolerance: float = 0.0001, silent: bool = False) → list

Returns direct Wire constituents of the input Cluster.

static HighestType(cluster) → int

Returns the type of the highest dimension subtopology found in the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

Returns
int

The type of the highest dimension subtopology found in the input cluster.

static KMeans(topologies, selectors=None, keys=['x', 'y', 'z'], k=4, maxIterations=100, centroidKey='k_centroid', distanceMeasure: str = 'euclidean', init: str = 'kmeans++', nInit: int = 10, tol: float = 1e-06, standardize: bool = False, normalize: bool = False, randomSeed: int = None, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Clusters the input topologies using K-Means-like clustering.

Best-practice upgrades vs the legacy implementation: - k-means++ initialization (default) for faster, stabler convergence. - Multiple restarts (nInit) and selects best (lowest inertia / objective). - Vectorized numpy core for speed. - More distance measures:

  • euclidean / sqeuclidean : classic k-means (centroid = mean)

  • manhattan : k-medians update (centroid = coordinate-wise median)

  • chebyshev : centroid = coordinate-wise midrange (0.5*(min+max)) (robust-ish heuristic)

  • cosine : spherical k-means (normalize; centroid = normalized mean)

  • mahalanobis : mean in whitened space (uses global covariance)

  • Robust empty-cluster handling (reseed with farthest point).

Notes - Classic k-means objective is squared Euclidean; for other metrics this function uses the appropriate/standard centroid update where available (k-medians, spherical k-means), or a reasonable heuristic (chebyshev). - Feature extraction:

  • If keys include “x”,”y”,”z” (case-insensitive), these are taken from the selector vertex (or topology vertex).

  • Any other key is read from the topology dictionary and must be numeric.

  • Missing/None values are replaced by 0.0 (warns unless silent).

Parameters
topologieslist

The input list of topologies.

selectorslist , optional

If topologies are not vertices, provide selector vertices (e.g., centroids) of equal length. If None, topologies must be vertices.

keyslist, optional

Keys to build the feature vector. Include “x”,”y”,”z” (any case) for coordinates.

kint , optional

Number of clusters.

maxIterationsint , optional

Maximum iterations.

centroidKeystr , optional

Dictionary key under which to store the cluster centroid feature vector.

distanceMeasurestr , optional

See list above.

initstr , optional

“kmeans++” or “random”.

nInitint , optional

Number of random restarts; best result returned.

tolfloat , optional

Convergence tolerance on centroid movement.

standardizebool , optional

Z-score features before clustering (recommended when mixing units).

normalizebool , optional

L2-normalize feature rows (recommended for cosine / spherical k-means).

randomSeedint , optional

RNG seed.

mantissaint , optional

The desired length of the mantissa. Default is 6.

tolerancefloat , optional

Tolerance (kept for API consistency).

silentbool , optional

Suppress warnings/errors.

Returns
list

The created list of clusters (topologic_core.Cluster), each with centroidKey stored in its dictionary.

static MergeCells(cells, tolerance: float = 0.0001, silent: bool = False)

Groups face-adjacent Cells into connected CellComplex components.

Connectivity is transitive and is found with a complete breadth-first traversal. Shared-Face identity is tried first; Topology.Merge is used only as a compatibility fallback for independently constructed but coincident Cells.

static MysticRose(wire=None, origin=None, radius: float = 0.5, sides: int = 16, perimeter: bool = True, direction: list = [0, 0, 1], placement: str = 'center', tolerance: float = 0.0001, silent: bool = False)

Creates a mystic rose.

Parameters
wiretopologic_core.Wire , optional

The input Wire. if set to None, a circle with the input parameters is created. Otherwise, the input parameters are ignored.

origintopologic_core.Vertex , optional

The location of the origin of the circle. Default is None which results in the circle being placed at (0, 0, 0).

radiusfloat , optional

The radius of the mystic rose. Default is 1.

sidesint , optional

The number of sides of the mystic rose. Default is 16.

perimeterbool , optional

If True, the perimeter edges are included in the output. Default is True.

directionlist , optional

The vector representing the up direction of the mystic rose. Default is [0, 0, 1].

placementstr , optional

The description of the placement of the origin of the mystic rose. This can be “center”, or “lowerleft”. 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.Cluster

The created mystic rose (cluster of edges).

static Shells(cluster, silent: bool = False) → list

Returns the shells of the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
list

The list of shells.

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

Simplifies a Cluster only when it has exactly one direct constituent.

This method deliberately does not infer redundancy from vertex counts or geometric coincidence. A multi-member Cluster is returned unchanged.

Parameters
clustertopologic_core.Cluster

The input Cluster.

tolerancefloat, optional

Reserved for backend-neutral hierarchy queries. Default is 0.0001.

silentbool, optional

If True, error and warning messages are suppressed. Default is False.

Returns
topologic_core.Topology or None

The sole constituent when there is exactly one; otherwise the input Cluster.

static Topologies(cluster, tolerance: float = 0.0001, silent: bool = False) → list

Returns the direct, top-level constituent Topologies of a Cluster.

The method compares the backend’s direct query with a hierarchy-only reconstruction and keeps the more complete valid result. This avoids Boolean reconstruction and protects heterogeneous Clusters containing intersecting but independent members.

static Tripod(size: float = 1.0, radius: float = 0.03, sides: int = 4, faceColorKey='faceColor', xColor='red', yColor='green', zColor='blue', matrix=None)

Creates a color-coded Axes tripod for X, Y, and Z axes. X-Axis is red, Y-Axis is “green”, and Z-Axis= “blue”

Parameters
sizefloat , optional

The desired size of the tripod. Default is 1.0.

radiusfloat , optional

The desired radiues of the tripod. Default is 0.03

sidesint , optional

The desired number of sides of the tripod. Default is 4.

faceColorKeystr , optional

The dictionary key under which to store the colors of the axes.

xColorstr , optional

The color to use for the X axis. Default is “red”.

yColorstr , optional

The color to use for the Y axis. Default is “green”.

zColorstr , optional

The color to use for the Z axis. Default is “blue”.

matrixlist , optional

The desired 4X4 transformation matrix to use for transforming the tripod. Default is None which means the tripod will be placed at the origin and will be axis-aligned.

Returns
topologic_core.Cluster

The created tripod

static Vertices(cluster, silent: bool = False) → list

Returns the vertices of the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
list

The list of vertices.

static Wires(cluster, silent: bool = False) → list

Returns the wires of the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns
list

The list of wires.