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 list of 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 the free cells of the input cluster that are not part of a higher topology.

FreeEdges(cluster[, tolerance, silent])

Returns the free edges of the input cluster that are not part of a higher topology.

FreeFaces(cluster[, tolerance, silent])

Returns the free faces of the input cluster that are not part of a higher topology.

FreeShells(cluster[, tolerance, silent])

Returns the free shells of the input cluster that are not part of a higher topology.

FreeTopologies(cluster[, tolerance])

Returns the free topologies of the input cluster that are not part of a higher topology.

FreeVertices(cluster[, tolerance, silent])

Returns the free vertices of the input cluster that are not part of a higher topology.

FreeWires(cluster[, tolerance, silent])

Returns the free wires of the input cluster that are not part of a higher topology.

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])

Creates a cluster that contains cellComplexes where it can create them plus any additional free cells.

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

Creates a mystic rose.

Shells(cluster[, silent])

Returns the shells of the input cluster.

Simplify(cluster)

Simplifies the input cluster if possible.

Topologies(cluster[, tolerance, silent])

Returns the topologies of the input 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=False)

Creates a topologic Cluster from the input list of topologies. The input can be individual topologies each as an input argument or a list of topologies stored in one input argument.

Parameters
*topologiestopologic_core.Topology

One or more instances of topologic_core.Topology to be processed.

transferDictionariesbool , optional

If set to True, the dictionaries from the input topologies are merged and transferred to the cluster. Otherwise they are not. Default is False.

silentbool , optional

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

Returns
topologic_core.Cluster

The created topologic Cluster.

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 the free cells of the input cluster that are not part of a higher topology.

Parameters
clustertopologic_core.Cluster

The input cluster.

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 free cells.

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

Returns the free edges of the input cluster that are not part of a higher topology.

Parameters
clustertopologic_core.Cluster

The input cluster.

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 free edges.

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

Returns the free faces of the input cluster that are not part of a higher topology.

Parameters
clustertopologic_core.Cluster

The input cluster.

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 free faces.

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

Returns the free shells of the input cluster that are not part of a higher topology.

Parameters
clustertopologic_core.Cluster

The input cluster.

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 free shells.

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

Returns the free topologies of the input cluster that are not part of a higher topology.

Parameters
clustertopologic_core.Cluster

The input cluster.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns
list

The list of free topologies.

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

Returns the free vertices of the input cluster that are not part of a higher topology.

Parameters
clustertopologic_core.Cluster

The input cluster.

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 free vertices.

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

Returns the free wires of the input cluster that are not part of a higher topology.

Parameters
clustertopologic_core.Cluster

The input cluster.

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 free wires.

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=0.0001)

Creates a cluster that contains cellComplexes where it can create them plus any additional free cells.

Parameters
cellslist

The input list of cells.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns
topologic_core.Cluster

The created cluster with merged cells as possible.

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)

Simplifies the input cluster if possible. For example, if the cluster contains only one cell, that cell is returned.

Parameters
clustertopologic_core.Cluster

The input cluster.

Returns
topologic_core.Topology or list

The simplification of the cluster.

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

Returns the topologies of the input cluster.

Parameters
clustertopologic_core.Cluster

The input cluster.

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

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.