topologicpy.Topology module

class topologicpy.Topology.MergingProcess(message_queue, sources, sinks, so_dicts)

Bases: Process

Receive message from other processes and merging the result

Attributes

authkey

daemon

Return whether process is a daemon

exitcode

Return exit code of process or None if it has yet to stop

ident

Return identifier (PID) of process or None if it has yet to start

name

pid

Return identifier (PID) of process or None if it has yet to start

sentinel

Return a file descriptor (Unix) or handle (Windows) suitable for waiting for process termination.

Methods

close()	Close the Process object.
is_alive()	Return whether process is alive
join([timeout])	Wait until child process terminates
kill()	Terminate process; sends SIGKILL signal or uses TerminateProcess()
run()	Method to be run in sub-process; can be overridden in sub-class
start()	Start child process
terminate()	Terminate process; sends SIGTERM signal or uses TerminateProcess()

wait_message

wait_message()

class topologicpy.Topology.QueueItem(ID, sinkKeys, sinkValues)

Bases: tuple

Attributes

ID

Alias for field number 0

sinkKeys

Alias for field number 1

sinkValues

Alias for field number 2

Methods

count(value, /)	Return number of occurrences of value.
index(value[, start, stop])	Return first index of value.

ID

Alias for field number 0

sinkKeys

Alias for field number 1

sinkValues

Alias for field number 2

class topologicpy.Topology.SinkItem(ID, sink_str)

Bases: tuple

Attributes

ID

Alias for field number 0

sink_str

Alias for field number 1

Methods

count(value, /)	Return number of occurrences of value.
index(value[, start, stop])	Return first index of value.

ID

Alias for field number 0

sink_str

Alias for field number 1

class topologicpy.Topology.Topology

Bases: object

Methods

AddApertures(topology, apertures[, ...])	Adds the input list of apertures to the input topology or to its subtopologies based on the input subTopologyType.
AddContent(topology, contents[, ...])	Adds the input list of contents to the input topology or to its subtpologies based on the input subTopologyType.
AddDictionary(topology, dictionary)	Adds the input dictionary to the input topology.
AdjacentTopologies(topology, hostTopology[, ...])	Returns the topologies, as specified by the input topology type, adjacent to the input topology within the input host topology.
Analyze(topology)	Returns an analysis string that describes the input topology.
ApertureTopologies(topology[, subTopologyType])	Returns the aperture topologies of the input topology.
Apertures(topology[, subTopologyType, silent])	Returns the apertures of the input topology.
BREPString(topology[, version])	Returns the BRep string of the input topology.
BinByDictionaryKey(topologies, key[, ...])	Bins a list of Topologic topologies into groups based on identical key/value pairs found in each topology's Dictionary.
BoundingBox(topology[, optimize, axes, ...])	Returns a cell representing a bounding box of the input topology.
ByBIMFile(file[, guidKey, colorKey, ...])	Imports topologies from the input BIM (dotbimpy.file.File) file object.
ByBIMPath(path[, guidKey, colorKey, ...])	Imports topologies from the input BIM file.
ByBIMString(string[, guidKey, colorKey, ...])	Imports topologies from the input BIM file.
ByBREPFile(file[, ontology, silent])	Imports a topology from a BREP file.
ByBREPPath(path[, ontology, silent])	Imports a topology from a BREP file path.
ByBREPString(string[, ontology, silent])	Creates a topology from the input brep string
ByDXFFile(file[, sides, tolerance, silent])	Imports a list of topologies from a DXF file.
ByDXFPath(path[, sides, tolerance, silent])	Imports a list of topologies from a DXF file path.
ByGeometry([vertices, edges, faces, ...])	Create a topology by the input lists of vertices, edges, and faces.
ByIFCFile(file[, includeTypes, ...])	Import an IFC file into a list of TopologicPy topologies using the Bonsai triangulation pipeline.
ByIFCPath(path[, includeTypes, ...])	Imports the topologies from an IFC file path.
ByJSONDictionary(jsonDictionary[, ontology, ...])	Imports the topology from a JSON dictionary.
ByJSONFile(file[, ontology, tolerance, silent])	Imports the topology from a JSON file.
ByJSONPath(path[, ontology, tolerance, silent])	Imports the topology from a JSON file.
ByJSONString(string[, ontology, tolerance, ...])	Imports the topology from a JSON string.
ByMeshData(dictionary[, ...])	Create a cluster by the input python dictionary of vertices, edges, faces, and cells.
ByOBJFile(objFile[, mtlFile, defaultColor, ...])	Imports a topology from an OBJ file and an associated materials file.
ByOBJPath(objPath[, defaultColor, ...])	Imports a topology from an OBJ file path and an associated materials file.
ByOBJString(objString[, mtlString, ...])	Imports a TopologicPy hierarchy from OBJ and optional MTL strings.
ByOCCTShape(occtShape)	Creates a topology from the input OCCT shape.
ByPDFFile(file[, wires, faces, ...])	Import PDF file and convert its entities to topologies.
ByPDFPath(path[, wires, faces, ...])	Import PDF file and convert its entities to topologies.
ByXYZFile(file[, frameIdKey, vertexIdKey])	Imports the topology from an XYZ file path.
ByXYZPath(path[, frameIdKey, vertexIdKey])	Imports the topology from an XYZ file path.
CanonicalMatrix([n, normalize, mantissa, silent])	Returns the canonical matrix of the input topology.
CellComplexes(topology[, silent])	Returns the cellcomplexes of the input topology.
Cells(topology[, silent])	Returns the cells of the input topology.
CenterOfMass(topology)	Returns the center of mass of the input topology.
Centroid(topology[, silent])	Returns the true geometric centroid of the input topology.
Cleanup([topology])	Cleans up all resources in which are managed by topologic library.
ClusterByKeys(topologies, *keys[, silent])	Clusters the input list of topologies based on the input key or keys.
ClusterFaces(topology[, angTolerance, tolerance])	Clusters the faces of the input topology by their direction.
Clusters(topology[, silent])	Returns the clusters of the input topology.
Contains(topologyA, topologyB[, mantissa, ...])	Returns True if topologyA contains topologyB.
Contents(topology)	Returns the contents of the input topology
Contexts(topology)	Returns the list of contexts of the input topology
ConvexHull(topology[, mantissa, tolerance, ...])	Computes the convex hull of the input topology.
Copy(topology[, deep])	Returns a copy of the input topology
CoveredBy(topologyA, topologyB[, mantissa, ...])	Returns True if topologyA is covered by topologyB, with topologyA's surface lying entirely on topologyB's surface.
Decompose(topology[, tiltAngle, tolerance, ...])	Decomposes the input topology into its logical components.
Degree(topology, hostTopology)	Returns the number of immediate super topologies that use the input topology
Diameter(topology[, mantissa, tolerance, silent])	Computes the diameter of the convex hull of the given topology.
Dictionary(topology[, silent])	Returns the dictionary of the input topology
Difference(topologyA, topologyB[, tranDict, ...])	Subtracts topologyB from topologyA.
Dimensionality(topology[, silent])	Returns the dimensionality of the input topology
Divide(topologyA, topologyB[, ...])	Divides the input topology by the input tool and places the results in the contents of the input topology.
Edges(topology[, silent])	Returns the edges of the input topology.
Explode(topology[, origin, scale, ...])	Explodes the input topology.
ExportToBIM(topologies, path[, overwrite, ...])	Exports the input topology to a BIM file.
ExportToBREP(topology, path[, overwrite, ...])	Exports the input topology to a BREP file.
ExportToDXF(path[, overwrite, mantissa])	Exports the input topology to a DXF file.
ExportToJSON(topologies, path[, overwrite])	Exports the input list of topologies to a JSON file.
ExportToOBJ(*topologies, path[, nameKey, ...])	Exports the input topology to a Wavefront OBJ file.
ExternalBoundary(topology[, silent])	Returns the external boundary of the input topology.
Faces(topology[, silent])	Returns the faces of the input topology.
Filter(topologies[, topologyType, ...])	Filters the input list of topologies based on the input parameters.
Fix(topology[, topologyType, tolerance])	Attempts to fix the input topology to matched the desired output type.
Flatten(topology[, origin, direction, ...])	Flattens the input topology such that the input origin is located at the world origin and the input topology is rotated such that the input vector is pointed in the Up direction (see Vector.Up()).
Geometry(topology[, transferDictionaries, ...])	Returns the geometry (mesh data format) of the input topology as a dictionary of vertices, edges, and faces.
HighestType(topology)	Returns the highest topology type found in the input topology.
Impose(topologyA, topologyB[, tranDict, ...])	Imposes topologyB on topologyA.
Imprint(topologyA, topologyB[, tranDict, ...])	Imprints topologyB on topologyA.
Inherit(targets, sources[, keys, exclusive, ...])	Transfers dictionary information from topologiesB to topologiesA based on co-location of internal vertices.
InternalVertex(topology[, timeout, ...])	Returns a vertex guaranteed to be inside the input topology.
Intersect(topologyA, topologyB[, tranDict, ...])	Finds the intersection between the input operand topologies.
IsInstance(topology, type)	Returns True if the input topology is an instance of the class specified by the input type string.
IsPlanar(topology[, mantissa, tolerance])	Returns True if all the vertices of the input topology are co-planar.
IsSame(topologyA, topologyB[, silent])	Returns True if the input topologies are the same topology.
IsSimilar(topologyA, topologyB[, ...])	Calculates if the input topologies are similar.
IsVertexCongruent(topologyA, topologyB[, ...])	Returns True if the input topologies are vertex congruent (have same number of vertices and all vertices are congruent within a tolerance).
JSONString(topologies[, mantissa])	Exports the input list of topologies to a JSON string
LargestFaces(topology[, ...])	Returns the list of the largest faces found in the input topology.
LongestEdges(topology[, ...])	Returns the list of the longest edges found in the input topology.
Merge(topologyA, topologyB[, tranDict, ...])	Merges the input operand topologies.
MergeAll(*topologies[, tolerance, silent])	Merge all the input topologies.
Mesh(topology[, minSize, maxSize, ...])	Use gmsh to create a variable-resolution mesh of a Topologic topology and return mesh data as:
MeshData(topology[, mode, ...])	Creates a mesh data python dictionary from the input topology.
MeshToTopologies(vertices[, faces, tets, ...])	Converts mesh data in the form of:
Move(topology[, x, y, z])	Moves the input topology.
NonPlanarFaces(topology[, tolerance])	Returns any nonplanar faces in the input topology
OBJString(*topologies[, nameKey, colorKey, ...])	Exports the input topology to Wavefront OBJ and MTL strings.
OCCTShape(topology)	Returns the occt shape of the input topology.
OntologyClass(topology[, defaultValue])	Returns the ontology class assigned to the input topology.
OpenEdges(topology)	Returns the edges that border only one face.
OpenFaces(topology)	Returns the faces that border no cells.
OpenVertices(topology)	Returns the vertices that border only one edge.
Orient(topology[, origin, dirA, dirB, tolerance])	Orients the input topology such that the input such that the input dirA vector is parallel to the input dirB vector.
Place(topology[, originA, originB, mantissa])	Places the input topology at the specified location.
PrincipalAxes(topology[, n, mantissa, silent])	Returns the prinicipal axes (vectors) of the input topology.
RemoveCollinearEdges(topology[, ...])	Removes the collinear edges of the input topology
RemoveContent(topology, contents)	Removes the input content list from the input topology
RemoveCoplanarFaces(topology[, epsilon, ...])	Removes coplanar faces in the input topology
RemoveEdges(topology[, edges, tolerance])	Removes the input list of faces from the input topology
RemoveFaces(topology[, faces, tolerance])	Removes the input list of faces from the input topology
RemoveFacesBySelectors(topology[, ...])	Removes faces that contain the input list of selectors (vertices) from the input topology
RemoveVertices(topology[, vertices, tolerance])	Removes the input list of vertices from the input topology
ReplaceVertices(topology[, verticesA, ...])	Replaces the vertices in the first input list with the vertices in the second input list and rebuilds the input topology.
Rotate(topology[, origin, axis, angle, ...])	Rotates the input topology
RotateByEulerAngles(topology[, origin, ...])	Rotates the input topology using Euler angles (roll, pitch, yaw).
RotateByQuaternion(topology[, origin, ...])	Rotates the input topology using Quaternion rotations.
Scale(topology[, origin, x, y, z, ...])	Scales the input topology
SelectSubTopology(topology, selector[, ...])	Returns the subtopology within the input topology based on the input selector and the subTopologyType.
SelfMerge(topology[, transferDictionaries, ...])	Self merges the input topology to return the most logical topology type given the input data.
SetDictionary(topology, dictionary[, silent])	Sets the input topology's dictionary to the input dictionary
SetOntology(topology[, ontologyClass, ...])	Annotates the input topology with TopologicPy ontology metadata.
SharedEdges(topologyA, topologyB)	Returns the shared edges between the two input topologies
SharedFaces(topologyA, topologyB)	Returns the shared faces between the two input topologies
SharedTopologies(topologyA, topologyB)	Returns the shared topologies between the two input topologies
SharedVertices(topologyA, topologyB)	Returns the shared vertices between the two input topologies
SharedWires(topologyA, topologyB)	Returns the shared wires between the two input topologies
Shells(topology[, silent])	Returns the shells of the input topology.
ShortestDistance(topologyA, topologyB[, ...])	Returns the shortest Euclidean distance between two topologies.
ShortestEdge(topologyA, topologyB[, ...])	Returns the shortest connecting Edge between two topologies.
ShortestEdges(topology[, ...])	Returns the list of the shortest edges found in the input topology.
Show(*topologies[, nameKey, opacityKey, ...])	Shows the input topology on screen.
Slice(topologyA, topologyB[, tranDict, ...])	Slices topologyA using topologyB.
SmallestFaces(topology[, ...])	Returns the list of the smallest faces found in the input topology.
SortBySelectors(topologies, selectors[, ...])	Sorts the input list of topologies according to the input list of selectors.
SpatialRelationship(topologyA, topologyB[, ...])	Returns the spatial relationship string between the two input topologies according to OGC / ISO 19107 / DE-9IM / RCC-8
Spin(topology[, origin, triangulate, ...])	Spins the input topology around an axis to create a new topology.See https://en.wikipedia.org/wiki/Solid_of_revolution.
SubCombinations(topology[, subTopologyType, ...])	Creates connected sub-combination topologies of the input topology.
SubTopologies(topology[, subTopologyType, ...])	Returns the subtopologies of the input topology as specified by the subTopologyType input string.
SuperTopologies(topology, hostTopology[, ...])	Returns the supertopologies connected to the input topology.
SymDif(topologyA, topologyB[, tranDict, ...])	Returns the symmetric difference (XOR) of the input operand topologies.
SymmetricDifference(topologyA, topologyB[, ...])	Returns the symmetric difference (XOR) of the input operand topologies.
Taper(topology[, origin, ratioRange, ...])	Tapers the input topology.
TransferDictionaries(sources, sinks[, ...])	Transfers the dictionaries from the list of sources to the list of sinks.
TransferDictionariesBySelectors(topology, ...)	Transfers the dictionaries of the list of selectors to the subtopologies of the input topology based on the input parameters.
Transform(topology, matrix[, angTolerance, ...])	Transforms the input topology by the input 4x4 affine transformation matrix.
Transform_old(topology, matrix[, ...])	Transforms the input topology by the input 4X4 transformation matrix.
Translate(topology[, x, y, z, ...])	Translates (moves) the input topology.
TranslateByDirectionDistance(topology[, ...])	Translates (moves) the input topology along the input direction by the specified distance.
Triangulate(topology[, ...])	Triangulates the input topology.
Twist(topology[, origin, angleRange, ...])	Twists the input topology.
Type(topology)	Returns the type of the input topology.
TypeAsString(topology[, silent])	Returns the type of the input topology as a string.
TypeID([name])	Returns the type id of the input name string.
UUID(topology[, namespace, uuidKey, ...])	Returns the UUID of the input topology.
Unflatten(topology[, origin, direction, ...])	Unflattens the input topology such that the world origin is translated to the input origin and the input topology is rotated such that the Up direction (see Vector.Up()) is aligned with the input vector.
Union(topologyA, topologyB[, tranDict, ...])	Unions the input operand topologies.
Vertices(topology[, silent])	Returns the vertices of the input topology.
VerticesCentroid(topology[, mantissa, silent])	Returns the centroid of the vertices of the input topology.
View3D(*topologies[, uuid, nameKey, ...])	Sends the input topologies to 3dviewer.net.
Wires(topology[, silent])	Returns the wires of the input topology.
XOR(topologyA, topologyB[, tranDict, ...])	Returns the symmetric difference (XOR) of the input operand topologies.

SetSnapshot
Snapshots

static AddApertures(topology, apertures, exclusive=False, subTopologyType=None, tolerance=0.001)

Adds the input list of apertures to the input topology or to its subtopologies based on the input subTopologyType.

Parameters

topologytopologic_core.Topology

The input topology.

apertureslist

The input list of apertures.

exclusivebool , optional

If set to True, one (sub)topology will accept only one aperture. Otherwise, one (sub)topology can accept multiple apertures. Default is False.

subTopologyTypestring , optional

The subtopology type to which to add the apertures. This can be “cell”, “face”, “edge”, or “vertex”. It is case insensitive. If set to None, the apertures will be added to the input topology. Default is None.

tolerancefloat , optional

The desired tolerance. Default is 0.001. This is larger than the usual 0.0001 as it seems to work better.

Returns

topologic_core.Topology

The input topology with the apertures added to it.

static AddContent(topology, contents, subTopologyType=None, tolerance=0.0001)

Adds the input list of contents to the input topology or to its subtpologies based on the input subTopologyType.

Parameters

topologytopologic_core.Topology

The input topology.

contentslist or topologic_core.Topology

The input list of contents (of type topologic_core.Topology). A single topology is also accepted as input.

subTopologyTypestring , optional

The subtopology type to which to add the contents. This can be “cellcomplex”, “cell”, “shell”, “face”, “wire”, “edge”, or “vertex”. It is case insensitive. If set to None, the contents will be added to the input topology. Default is None.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

topologic_core.Topology

The input topology with the contents added to it.

static AddDictionary(topology, dictionary)

Adds the input dictionary to the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

dictionarytopologic_core.Dictionary

The input dictionary.

Returns

topologic_core.Topology

The input topology with the input dictionary added to it.

static AdjacentTopologies(topology, hostTopology, topologyType=None)

Returns the topologies, as specified by the input topology type, adjacent to the input topology within the input host topology.

Parameters

topologytopologic_core.Topology or topologic_core.graph

The input topology.

hostTopologytopologic_core.Topology

The host topology in which to search.

topologyTypestr

The type of topology for which to search. This can be one of “vertex”, “edge”, “wire”, “face”, “shell”, “cell”, “cellcomplex”. It is case-insensitive. If it is set to None, the type will be set to the same type as the input topology. Default is None.

Returns

adjacentTopologieslist

The list of adjacent topologies.

static Analyze(topology)

Returns an analysis string that describes the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

Returns

str

The analysis string.

static ApertureTopologies(topology, subTopologyType=None)

Returns the aperture topologies of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

subTopologyTypestring , optional

The subtopology type from which to retrieve the apertures. This can be “cell”, “face”, “edge”, or “vertex” or “all”. It is case insensitive. If set to “all”, then all apertures will be returned. If set to None, the apertures will be retrieved only from the input topology. Default is None.

Returns

list

The list of aperture topologies found in the input topology.

static Apertures(topology, subTopologyType=None, silent: bool = False)

Returns the apertures of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

subTopologyTypestring , optional

The subtopology type from which to retrieve the apertures. This can be “cell”, “face”, “edge”, or “vertex” or “all”. It is case insensitive. If set to “all”, then all apertures will be returned. If set to None, the apertures will be retrieved only from the input topology. Default is None.

silentbool , optional

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

Returns

list

The list of apertures belonging to the input topology.

static BREPString(topology, version=3)

Returns the BRep string of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

versionint , optional

The desired BRep version number. Default is 3.

Returns

str

The BREP string.

static BinByDictionaryKey(topologies: Iterable[Any], key: str, missing_label: str = '__MISSING__', return_counts: bool = False) → Tuple[Dict[Any, List[Any]], Dict[Any, int]]

Bins a list of Topologic topologies into groups based on identical key/value pairs found in each topology’s Dictionary. Topologies that do not have the key are binned together under missing_label.

Parameters

topologiesIterable[topologic_core.Topology]

The input topologies to bin.

keystr

The dictionary key to group by.

missing_labelstr , optional

Identifier used for the group of topologies that lack key. Default is “__MISSING__”.

return_countsbool , optional

If True, returns a second dictionary of group -> count. Default is False.

Returns

groupsdict

A mapping from group identifier to list of topologies. - For present keys, the identifier is the original value if it is hashable (str/int/float/bool) or a stable, hashable structural surrogate for complex types (lists/dicts) that preserves equality semantics. - For missing keys, the identifier is missing_label.

countsdict

A mapping from group identifier to group size. Returned only if return_counts=True; otherwise an empty dict.

Notes

• This function avoids unnecessary method lookups and branches for speed.

• Values that are lists/dicts are converted to stable, hashable surrogates so that

“identical” (by structure/content) values end up in the same bin. - If you need the original (potentially unhashable) values back for complex keys, you can inspect any representative item’s dictionary value in that group.

Examples

>>> groups, counts = BinByDictionaryKey(topologies, key="material", return_counts=True)
>>> metal_group = groups.get("steel", [])
>>> missing = groups.get("__MISSING__", [])

static BoundingBox(topology, optimize: int = 0, axes: str = 'xyz', mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns a cell representing a bounding box of the input topology. The returned cell contains a dictionary with keys “xrot”, “yrot”, and “zrot” that represents rotations around the X, Y, and Z axes. If applied in the order of Z, Y, X, the resulting box 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 box so that it reduces its surface area. Default is 0 which will result in an axis-aligned bounding box. Default is 0.

axesstr , optional

Sets what axes are to be used for rotating the bounding box. This can be any permutation or substring of “xyz”. It is not case sensitive. Default is “xyz”.

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.Cell or topologic_core.Face

The bounding box of the input topology.

static ByBIMFile(file, guidKey: str = 'guid', colorKey: str = 'color', typeKey: str = 'type', defaultColor: list = [255, 255, 255, 1], defaultType: str = 'Structure', authorKey='author', dateKey='date', mantissa: int = 6, angTolerance: float = 0.001, tolerance: float = 0.0001)

Imports topologies from the input BIM (dotbimpy.file.File) file object. See https://dotbim.net/

Parameters

filedotbimpy.file.File

The input dotbim file.

guidKeystr , optional

The key to use to store the the guid of the topology. Default is “guid”.

colorKeystr , optional

The key to use to find the the color of the topology. Default is “color”. If no color is found, the defaultColor parameter is used.

typeKeystr , optional

The key to use to find the the type of the topology. Default is “type”. If no type is found, the defaultType parameter is used.

defaultColorlist , optional

The default color to use for the topology. Default is [255,255,255,1] which is opaque white.

defaultTypestr , optional

The default type to use for the topology. Default is “Structure”.

authorKeystr , optional

The key to use to store the author of the topology. Default is “author”.

dateKeystr , optional

The key to use to store the creation date of the topology. This should be in the formate “DD.MM.YYYY”. If no date is found the date of import is used.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

angTolerancefloat , optional

The angle tolerance in degrees under which no rotation is carried out. Default is 0.001 degrees.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

list

The list of imported topologies

static ByBIMPath(path, guidKey: str = 'guid', colorKey: str = 'color', typeKey: str = 'type', defaultColor: list = [255, 255, 255, 1], defaultType: str = 'Structure', authorKey='author', dateKey='date', mantissa: int = 6, angTolerance: float = 0.001, tolerance: float = 0.0001)

Imports topologies from the input BIM file. See https://dotbim.net/

Parameters

path :str

The path to the .bim file.

guidKeystr , optional

The key to use to store the the guid of the topology. Default is “guid”.

colorKeystr , optional

The key to use to find the the color of the topology. Default is “color”. If no color is found, the defaultColor parameter is used.

typeKeystr , optional

The key to use to find the the type of the topology. Default is “type”. If no type is found, the defaultType parameter is used.

defaultColorlist , optional

The default color to use for the topology. Default is [255,255,255,1] which is opaque white.

defaultTypestr , optional

The default type to use for the topology. Default is “Structure”.

authorKeystr , optional

The key to use to store the author of the topology. Default is “author”.

dateKeystr , optional

The key to use to store the creation date of the topology. This should be in the formate “DD.MM.YYYY”. If no date is found the date of import is used.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

angTolerancefloat , optional

The angle tolerance in degrees under which no rotation is carried out. Default is 0.001 degrees.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

list

The list of imported topologies

static ByBIMString(string, guidKey: str = 'guid', colorKey: str = 'color', typeKey: str = 'type', defaultColor: list = [255, 255, 255, 1], defaultType: str = 'Structure', authorKey: str = 'author', dateKey: str = 'date', mantissa: int = 6, angTolerance: float = 0.001, tolerance: float = 0.0001)

Imports topologies from the input BIM file. See https://dotbim.net/

Parameters

string :str

The input dotbim str (in JSON format).

guidKeystr , optional

The key to use to store the the guid of the topology. Default is “guid”.

colorKeystr , optional

The key to use to find the the color of the topology. Default is “color”. If no color is found, the defaultColor parameter is used.

typeKeystr , optional

The key to use to find the the type of the topology. Default is “type”. If no type is found, the defaultType parameter is used.

defaultColorlist , optional

The default color to use for the topology. Default is [255,255,255,1] which is opaque white.

defaultTypestr , optional

The default type to use for the topology. Default is “Structure”.

authorKeystr , optional

The key to use to store the author of the topology. Default is “author”.

dateKeystr , optional

The key to use to store the creation date of the topology. This should be in the formate “DD.MM.YYYY”. If no date is found the date of import is used.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

angTolerancefloat , optional

The angle tolerance in degrees under which no rotation is carried out. Default is 0.001 degrees.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

list

The list of imported topologies

static ByBREPFile(file, ontology: bool = False, silent: bool = False)

Imports a topology from a BREP file.

Parameters

filefile object

The BREP file.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

silentbool , optional

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

Returns

topologic_core.Topology

The imported topology.

static ByBREPPath(path, ontology: bool = False, silent: bool = False)

Imports a topology from a BREP file path.

Parameters

pathstr

The path to the BREP file.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

silentbool , optional

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

Returns

topologic_core.Topology

The imported topology.

static ByBREPString(string, ontology: bool = False, silent: bool = False)

Creates a topology from the input brep string

Parameters

stringstr

The input brep string.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

silentbool , optional

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

Returns

topologic_core.Topology

The created topology.

static ByDXFFile(file, sides: int = 16, tolerance: float = 0.0001, silent: bool = False)

Imports a list of topologies from a DXF file. This is an experimental method with limited capabilities.

Parameters

filea DXF file object

The DXF file object.

sidesint , optional

The desired number of sides of splines. Default is 16.

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 imported topologies.

static ByDXFPath(path, sides: int = 16, tolerance: float = 0.0001, silent: bool = False)

Imports a list of topologies from a DXF file path. This is an experimental method with limited capabilities.

Parameters

pathstr

The path to the DXF file.

sidesint , optional

The desired number of sides of splines. Default is 16.

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 imported topologies.

static ByGeometry(vertices=[], edges=[], faces=[], topologyType: str = None, tolerance: float = 0.0001, ontology: bool = False, silent: bool = False)

Create a topology by the input lists of vertices, edges, and faces.

Parameters

verticeslist

The input list of vertices in the form of [x, y, z].

edgeslist , optional

The input list of edges in the form of [i, j] where i and j are vertex indices.

faceslist , optional

The input list of faces in the form of [i, j, k, l, …] where the items in the list are vertex indices. The face is assumed to be closed, so the last vertex is connected to the first vertex automatically.

topologyTypestr , optional

The desired highest topology type. The options are: “Vertex”, “Edge”, “Wire”, “Face”, “Shell”, “Cell”, “CellComplex”. It is case insensitive. If any of these options are selected, the returned topology will only contain this type either as a single topology or as a Cluster of these types of topologies. If set to None, a Cluster will be returned of vertices, edges, and/or faces. Default is None.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

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

topologytopologic_core.Topology

The created topology.

static ByIFCFile(file, includeTypes: list = [], excludeTypes: list = [], dictionaryMode: str = 'basic', clean: bool = False, epsilon: float = 0.01, angTolerance: float = 0.1, tolerance: float = 0.0001, silent: bool = False) → list[Any]

Import an IFC file into a list of TopologicPy topologies using the Bonsai triangulation pipeline. See IFC.TopologiesByFile.

Parameters

fileifcopenshell.file

The input IFC file object.

includeTypeslist , optional

IFC object types to include. Case-insensitive. Default is [].

excludeTypeslist , optional

IFC object types to exclude. Case-insensitive. Default is [].

dictionaryModestr , optional

Options are “none”, “basic”, or “psets”. Default is “basic”.

cleanbool , optional

If set to True, coplanar faces and collinear edges are removed. Default is False.

epsilonfloat , optional

The desired epsilon (another form of tolerance) for finding if two faces are coplanar. Default is 0.01.

angTolerancefloat , optional

The desired angular tolerance for removing collinear edges. Default is 0.1.

tolerancefloat , optional

TopologicPy tolerance. Default is 0.0001.

silentbool , optional

If True, warnings and progress messages are suppressed. Default is False.

Returns

list

The created TopologicPy topologies.

static ByIFCPath(path: str, includeTypes: list = [], excludeTypes: list = [], dictionaryMode: str = 'basic', clean: bool = False, epsilon: float = 0.0001, angTolerance: float = 0.1, tolerance: float = 0.0001, silent: bool = False) → list[Any]

Imports the topologies from an IFC file path. See IFC.TopologiesByPath

Parameters

pathstr

The path to the IFC file.

includeTypeslist , optional

The list of IFC object types to include. It is case insensitive. If set to an empty list, all types are included. Default is [].

excludeTypeslist , optional

The list of IFC object types to exclude. It is case insensitive. If set to an empty list, no types are excluded. Default is [].

dictionaryModestr , optional

Options are “none”, “basic”, or “psets”. Default is “basic”.

cleanbool , optional

If set to True, coplanar faces and collinear edges are removed. Default is False.

epsilonfloat , optional

The desired epsilon (another form of tolerance) for finding if two faces are coplanar. Default is 0.01.

angTolerancefloat , optional

The desired angular tolerance 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

list

The created list of topologies.

static ByJSONDictionary(jsonDictionary: dict, ontology: bool = False, tolerance: float = 0.0001, silent: bool = False)

Imports the topology from a JSON dictionary.

Parameters

jsonDictionarydict

The input JSON dictionary.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

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 imported topologies. The list can contain 0, 1, or many topologies, but this method always returns a list.

static ByJSONFile(file, ontology: bool = False, tolerance: float = 0.0001, silent: bool = False)

Imports the topology from a JSON file.

Parameters

filefile object

The input JSON file.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

silentbool , optional

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

Returns

list

The list of imported topologies (Warning: the list could contain 0, 1, or many topologies, but this method will always return a list)

static ByJSONPath(path, ontology: bool = False, tolerance: float = 0.0001, silent: bool = False)

Imports the topology from a JSON file.

Parameters

pathstr

The file path to the json file.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

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 imported topologies.

static ByJSONString(string: str, ontology: bool = False, tolerance: float = 0.0001, silent: bool = False)

Imports the topology from a JSON string.

Parameters

stringstr

The input JSON string.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

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 imported topologies (Warning: the list could contain 0, 1, or many topologies, but this method will always return a list)

static ByMeshData(dictionary, transferDictionaries: bool = False, ontology: bool = False, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Create a cluster by the input python dictionary of vertices, edges, faces, and cells.

Parameters

dictionarydict

The input python dictionary of vertices, edges, faces, and cells in the form of: { ‘mode’: int, The expected mode of input face data:

0: The faces list is indexed into the vertices list. 1: The faces list is indexesd into the edges list.

‘vertices’: list, (list of coordinates) ‘edges’: list, (list of indices into the list of vertices) ‘faces’: list, (list of indices into the list of edges) ‘cells’: list, (list of indices into the list of faces) ‘vertex_dict’: list of dicts, ‘edge_dicts’: list of dicts, ‘face_dicts’, list of dicts, ‘cell_dicts’, list of dicts }

transferDictionariesbool , optional

If set to True, the python dictionaries will be transferred to the coorespoding topologies. Default is False.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

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

The created cluster of vertices, edges, faces, and cells.

static ByOBJFile(objFile, mtlFile=None, defaultColor: list = [255, 255, 255], defaultOpacity: float = 1.0, transposeAxes: bool = True, removeCoplanarFaces: bool = False, selfMerge: bool = True, mantissa: int = 6, tolerance: float = 0.0001)

Imports a topology from an OBJ file and an associated materials file. This method is basic and does not support textures and vertex normals.

Parameters

objFilefile object

The OBJ file.

mtlFilefile object , optional

The MTL file. Default is None.

defaultColorlist , optional

The default color to use if none is specified in the file. Default is [255, 255, 255] (white).

defaultOpacityfloat , optional

The default opacity to use if none is specified in the file. Default is 1.0 (fully opaque).

transposeAxesbool , optional

If set to True the Z and Y axes are transposed. Otherwise, they are not. Default is True.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are merged. Default is True.

selfMergebool , optional

If set to True, the faces of the imported topologies will each be self-merged to create higher-dimensional objects. Otherwise, they remain a cluster of faces. 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

list

The imported topologies.

static ByOBJPath(objPath, defaultColor: list = [255, 255, 255], defaultOpacity: float = 1.0, transposeAxes: bool = True, removeCoplanarFaces: bool = False, selfMerge: bool = False, mantissa: int = 6, tolerance: float = 0.0001)

Imports a topology from an OBJ file path and an associated materials file. This method is basic and does not support textures and vertex normals.

Parameters

objPathstr

The path to the OBJ file.

defaultColorlist , optional

The default color to use if none is specified in the file. Default is [255, 255, 255] (white).

defaultOpacityfloat , optional

The default opacity to use if none is specified in the file. Default is 1.0 (fully opaque).

transposeAxesbool , optional

If set to True the Z and Y axes are transposed. Otherwise, they are not. Default is True.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are merged. Default is True.

selfMergebool , optional

If set to True, the faces of the imported topologies will each be self-merged to create higher-dimensional objects. Otherwise, they remain a cluster of faces. 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

list

The imported topologies.

static ByOBJString(objString: str, mtlString: str = None, defaultColor=None, defaultOpacity: float = 1.0, transposeAxes: bool = True, removeCoplanarFaces: bool = False, selfMerge: bool = False, mantissa: int = 6, tolerance: float = 0.0001)

Imports a TopologicPy hierarchy from OBJ and optional MTL strings.

Supported OBJ primitives - v : vertices - l : polylines (edges-only / wire-only models) - f : faces (tri/quad/ngon; may be self-merged) - p : points

Grouping - g / o : groups/objects become separate returned topologies (one per group/object)

Materials - usemtl + MTL Kd/d/Tr are used to set:

color : [R,G,B] in 0..255 opacity : 0..1

Parameters

objStringstr

The OBJ file contents as a string.

mtlStringstr , optional

The MTL file contents as a string.

defaultColorlist , optional

The default color to use if none is specified in the file. Default is [255, 255, 255].

defaultOpacityfloat , optional

The default opacity to use if none is specified in the file. Default is 1.0.

transposeAxesbool , optional

If set to True, converts OBJ coordinates from (x, y, z) to (x, -z, y). Default is True.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are merged. Default is False.

selfMergebool , optional

If set to True, imported face clusters are self-merged. Default is False.

mantissaint , optional

The number of decimal places to round coordinates to. Default is 6.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

list

One TopologicPy topology per OBJ group/object: - If a group has faces: returns a Cluster of faces, or a self-merged topology. - Else if a group has polylines/edges: returns a Cluster of Wires/Edges. - Else if a group has only points: returns a Cluster of Vertices. - If mixed: returns a Cluster containing the appropriate mix.

static ByOCCTShape(occtShape)

Creates a topology from the input OCCT shape. See https://dev.opencascade.org/doc/overview/html/occt_user_guides__modeling_data.html.

Parameters

occtShapetopologic_core.TopoDS_Shape

The inoput OCCT Shape.

Returns

topologic_core.Topology

The created topology.

static ByPDFFile(file, wires=False, faces=False, includeTypes=[], excludeTypes=[], edgeColorKey='edge_color', edgeWidthKey='edge_width', faceColorKey='face_color', faceOpacityKey='face_opacity', tolerance=0.0001, silent=False)

Import PDF file and convert its entities to topologies.

Parameters

filefile

The input PDF file

wiresbool , optional

If set to True, wires will be constructed when possible. Default is True.

facesbool , optional

If set to True, faces will be constructed when possible. Default is True.

includeTypeslist , optional

A list of PDF object types to include in the returned result. Default is [] which means all PDF objects will be included. The possible strings to include in this list are: [“line”, “curve”, “rectangle”, “quadrilateral”]

excludeTypeslist , optional

A list of PDF object types to exclude from the returned result. Default is [] which mean no PDF object type will be excluded. The possible strings to include in this list are: [“line”, “curve”, “rectangle”, “quadrilateral”]

edgeColorKeystr , optional

The dictionary key under which to store the edge color. Default is None.

edgeWidthKeystr , optional

The dictionary key under which to store the edge width. Default is None.

faceColorKeystr , optional

The dictionary key under which to store the face color. Default is None.

faceOpacityKeystr , optional

The dictionary key under which to store the face opacity. 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

list

A list of Topologic entities (edges, wires, faces, clusters) with attached dictionaries.

static ByPDFPath(path, wires=False, faces=False, includeTypes=[], excludeTypes=[], edgeColorKey='edge_color', edgeWidthKey='edge_width', faceColorKey='face_color', faceOpacityKey='face_opacity', tolerance=0.0001, silent=False)

Import PDF file and convert its entities to topologies.

Parameters

pathpath

The input path to the PDF file

wiresbool , optional

If set to True, wires will be constructed when possible. Default is True.

facesbool , optional

If set to True, faces will be constructed when possible. Default is True.

includeTypeslist , optional

A list of PDF object types to include in the returned result. Default is [] which means all PDF objects will be included. The possible strings to include in this list are: [“line”, “curve”, “rectangle”, “quadrilateral”]

excludeTypeslist , optional

A list of PDF object types to exclude from the returned result. Default is [] which mean no PDF object type will be excluded. The possible strings to include in this list are: [“line”, “curve”, “rectangle”, “quadrilateral”]

edgeColorKeystr , optional

The dictionary key under which to store the edge color. Default is None.

edgeWidthKeystr , optional

The dictionary key under which to store the edge width. Default is None.

faceColorKeystr , optional

The dictionary key under which to store the face color. Default is None.

faceOpacityKeystr , optional

The dictionary key under which to store the face opacity. 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

list

A list of Topologic entities (edges, wires, faces, clusters) with attached dictionaries.

static ByXYZFile(file, frameIdKey='id', vertexIdKey='id')

Imports the topology from an XYZ file path. This is a very experimental method. While variants of the format exist, topologicpy reads XYZ files that conform to the following: An XYZ file can be made out of one or more frames. Each frame will be stored in a sepatate topologic cluster. First line: total number of vertices in the frame. This must be an integer. No other words or characters are allowed on this line. Second line: frame label. This is free text and will be stored in the dictionary of each frame (topologic_core.Cluster) All other lines: vertex_label, x, y, and z coordinates, separated by spaces, tabs, or commas. The vertex label must be one word with no spaces. It is stored in the dictionary of each vertex.

Example: 3 Frame 1 A 5.67 -3.45 2.61 B 3.91 -1.91 4 A 3.2 1.2 -12.3 4 Frame 2 B 5.47 -3.45 2.61 B 3.91 -1.93 3.1 A 3.2 1.2 -22.4 A 3.2 1.2 -12.3 3 Frame 3 A 5.67 -3.45 2.61 B 3.91 -1.91 4 C 3.2 1.2 -12.3

Parameters

filefile object

The input XYZ file.

frameIdKeystr , optional

The desired id key to use to store the ID of each frame in its dictionary. Default is “id”.

vertexIdKeystr , optional

The desired id key to use to store the ID of each point in its dictionary. Default is “id”.

Returns

list

The list of frames (topologic_core.Cluster).

static ByXYZPath(path, frameIdKey='id', vertexIdKey='id')

Imports the topology from an XYZ file path. This is a very experimental method. While variants of the format exist, topologicpy reads XYZ files that conform to the following: An XYZ file can be made out of one or more frames. Each frame will be stored in a sepatate topologic cluster. First line: total number of vertices in the frame. This must be an integer. No other words or characters are allowed on this line. Second line: frame label. This is free text and will be stored in the dictionary of each frame (topologic_core.Cluster) All other lines: vertex_label, x, y, and z coordinates, separated by spaces, tabs, or commas. The vertex label must be one word with no spaces. It is stored in the dictionary of each vertex.

Example: 3 Frame 1 A 5.67 -3.45 2.61 B 3.91 -1.91 4 A 3.2 1.2 -12.3 4 Frame 2 B 5.47 -3.45 2.61 B 3.91 -1.93 3.1 A 3.2 1.2 -22.4 A 3.2 1.2 -12.3 3 Frame 3 A 5.67 -3.45 2.61 B 3.91 -1.91 4 C 3.2 1.2 -12.3

Parameters

pathstr

The input XYZ file path.

frameIdKeystr , optional

The desired id key to use to store the ID of each frame in its dictionary. Default is “id”.

vertexIdKeystr , optional

The desired id key to use to store the ID of each point in its dictionary. Default is “id”.

Returns

list

The list of frames (topologic_core.Cluster).

CanonicalMatrix(n: int = 10, normalize: bool = False, mantissa: int = 6, silent: bool = False)

Returns the canonical matrix of the input topology. The canonical matrix refers to a transformation matrix that maps an object’s coordinate system to a canonical coordinate frame, where: . The origin of the object aligns with the world origin . The principal axes of the object align with the world axes This transformation is computed using Principal Component Analysis (PCA), leveraging the eigenvectors of the covariance matrix of the object’s vertices and thus can give erroneous results. The transformation matrix may not yield an object oriented as expected.

Parameters

topologytopologic_core.Topology

The input topology.

nint , optional

The number of segments to use to increase the number of points on each face. Default is 10.

normalizebool , optional

If set to True, the longest edge in the input topology is scaled to become of length 1. Default is False.

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.

Returns

list

The 4X4 canonical matrix.

static CellComplexes(topology, silent: bool = False)

Returns the cellcomplexes of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

list

The list of cellcomplexes.

static Cells(topology, silent: bool = False)

Returns the cells of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

list

The list of cells.

static CenterOfMass(topology)

Returns the center of mass of the input topology. See https://en.wikipedia.org/wiki/Center_of_mass.

Parameters

topologytopologic_core.Topology

The input topology.

Returns

topologic_core.Vertex

The center of mass of the input topology.

static Centroid(topology, silent: bool = False)

Returns the true geometric centroid of the input topology. This is an alias for Topology.CenterOfMass().

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

topologic_core.Vertex or None

The centroid of the input topology.

static Cleanup(topology=None)

Cleans up all resources in which are managed by topologic library. Use this to manage your application’s memory consumption. USE WITH CARE. This methods deletes dictionaries, contents, and contexts

Parameters

topologytopologic_core.Topology , optional

If specified the resources used by the input topology will be deleted. If not, ALL resources will be deleted.

Returns

topologic_core.Topology

The input topology, but with its resources deleted or None.

static ClusterByKeys(topologies, *keys, silent=False)

Clusters the input list of topologies based on the input key or keys.

Parameters

topologieslist

The input list of topologies.

keysstr or list or comma-separated str input parameters

The key or keys in the topology’s dictionary to use for clustering.

silentbool , optional

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

Returns

list

A nested list of topologies where each element is a list of topologies with the same key values.

static ClusterFaces(topology, angTolerance=2, tolerance=0.0001)

Clusters the faces of the input topology by their direction.

Parameters

topologytopologic_core.Topology

The input topology.

angTolerancefloat , optional

The desired angular tolerance. Default is 0.1.

tolerancefloat, optional

The desired tolerance. Default is 0.0001.

Returns

list

The list of clusters of faces where faces in the same cluster have the same direction.

static Clusters(topology, silent: bool = False)

Returns the clusters of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

list

The list of clusters.

static Contains(topologyA, topologyB, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns True if topologyA contains topologyB. Contains is the inverse of “within,” where geometry A contains geometry B. The interior and boundary of B are completely contained within the interior of A.

Parameters

topologyAtopologic_core.Topology

The first input topology

topologyBtopologic_core. Topology

The second input topology.

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

bool

True if topologyA contains topologyB. False otherwise.

static Contents(topology)

Returns the contents of the input topology

Parameters

topologytopologic_core.Topology

The input topology.

Returns

list

The list of contents of the input topology.

static Contexts(topology)

Returns the list of contexts of the input topology

Parameters

topologytopologic_core.Topology

The input topology.

Returns

list

The list of contexts of the input topology.

static ConvexHull(topology, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Computes the convex hull of the input topology. Returns a Face in 2D (even embedded in 3D), or a Cell/Shell in 3D.

Parameters

topologytopologic_core.Topology

The input Topology.

mantissaint, optional

Precision of the coordinates. Default is 6.

tolerancefloat, optional

Tolerance value for geometric operations. Default is 0.0001.

silentbool, optional

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

Returns

topologic_core.Topology

The convex hull of the topology as a Face (2D) or Cell/Shell (3D).

static Copy(topology, deep=False)

Returns a copy of the input topology

Parameters

topologytopologic_core.Topology

The input topology.

deepbool , optional

If set to True, a deep copy will be performed (this is slow). Othwerwise, it will not. Default is False

Returns

topologic_core.Topology

A copy of the input topology.

static CoveredBy(topologyA, topologyB, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns True if topologyA is covered by topologyB, with topologyA’s surface lying entirely on topologyB’s surface.

Parameters

topologyAtopologic_core.Topology

The first input topology

topologyBtopologic_core. Topology

The second input topology.

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

bool

True if topologyA is covered by topologyB. False otherwise.

static Decompose(topology, tiltAngle: float = 10.0, tolerance: float = 0.0001, silent: bool = False) → dict

Decomposes the input topology into its logical components. This method assume: 1. The input topology is either a cell, a CellComplex, or a Cluster containing at least one or more faces. 2. That the positive Z direction is UP [0,0,1].

Parameters

topologytopologic_core.Topology

the input topology (cell, cellComplex, or Cluster with at least faces).

tiltAnglefloat , optional

The threshold tilt angle in degrees to determine if a face is vertical, horizontal, or tilted. The tilt angle is measured from the nearest cardinal direction. Default is 10.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

ontologybool , optional

If True, the returned topology is annotated with TopologicPy ontology metadata. Default is False.

silentbool , optional

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

Returns

dictionary

A dictionary with the following keys and values: 1. “cells”: list of cells 2. “externalVerticalFaces”: list of external vertical faces 3. “internalVerticalFaces”: list of internal vertical faces 4. “topHorizontalFaces”: list of top horizontal faces 5. “bottomHorizontalFaces”: list of bottom horizontal faces 6. “internalHorizontalFaces”: list of internal horizontal faces 7. “externalInclinedFaces”: list of external inclined faces 8. “internalInclinedFaces”: list of internal inclined faces 9. “externalVerticalApertures”: list of apertures that belong to external vertical faces 10. “internalVerticalApertures”: list of apertures that belong to internal vertical faces 11. “topHorizontalApertures”: list of apertures that belong to top horizontal faces 12. “bottomHorizontalApertures”: list of apertures that belong to bottom horizontal faces 13. “internalHorizontalApertures”: list of aperttures that belong to internal horizontal faces 14. “externalInclinedApertures”: list of apertures that belong to external inclined faces 15. “internalInclinedApertures”: list of apertures that belong to internal inclined faces 16. “freeVerticalFaces” : list of free vertical faces 17. “freeHorizontalFaces” : list of free horizontal faces 18. “freeInclinedFaces” : list of free inclined faces, 19. “freeVerticalApertures” : list of apertures that belong to free vertical faces, 20. “freeHorizontalApertures” : list of apertures that belong to free horiztontal faces 21. “freeInclinedApertures” : list of apertures that belong to free inclined faces

static Degree(topology, hostTopology)

Returns the number of immediate super topologies that use the input topology

Parameters

topologytopologic_core.Topology

The input topology.

hostTopologytopologic_core.Topology

The input host topology to which the input topology belongs

Returns

int

The degree of the topology (the number of immediate super topologies that use the input topology).

static Diameter(topology, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Computes the diameter of the convex hull of the given topology. The diameter is the maximum distance between any two vertices on the convex hull.

Parameters

topologytopologic_core.Topology

The input topology

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

float

The diameter of the convex hull of the topology.

static Dictionary(topology, silent: bool = False)

Returns the dictionary of the input topology

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

topologic_core.Dictionary

The dictionary of the input topology.

static Difference(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Subtracts topologyB from topologyA. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static Dimensionality(topology, silent: bool = False)

Returns the dimensionality of the input topology

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

int

The dimensionality of the input topology.

static Divide(topologyA, topologyB, transferDictionary=False, addNestingDepth=False, silent: bool = False)

Divides the input topology by the input tool and places the results in the contents of the input topology.

Parameters

topologyAtopologic_core.Topology

The input topology to be divided.

topologyBtopologic_core.Topology

the tool used to divide the input topology.

transferDictionarybool , optional

If set to True the dictionary of the input topology is transferred to the divided topologies.

addNestingDepthbool , optional

If set to True the nesting depth of the division is added to the dictionaries of the divided topologies.

silentbool , optional

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

Returns

topologic_core.Topology

The input topology with the divided topologies added to it as contents.

static Edges(topology, silent: bool = False)

Returns the edges of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

list

The list of edges.

static Explode(topology, origin=None, scale: float = 1.25, typeFilter: str = None, axes: str = 'xyz', transferDictionaries: bool = False, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Explodes the input topology. See https://en.wikipedia.org/wiki/Exploded-view_drawing.

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The origin of the explosion. If set to None, the centroid of the input topology will be used. Default is None.

scalefloat , optional

The scale factor of the explosion. Default is 1.25.

typeFilterstr , optional

The type of the subtopologies to explode. This can be any of “vertex”, “edge”, “face”, or “cell”. If set to None, a subtopology one level below the type of the input topology will be used. Default is None.

axesstr , optional

Sets what axes are to be used for exploding the topology. This can be any permutation or substring of “xyz”. It is not case sensitive. Default is “xyz”.

transferDictionariesbool , optional

If set to True, the dictionaries of the original subTopologies are transferred to the exploded topologies. Otherwise, they are not. 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.

silentbool , optional

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

Returns

topologic_core.Cluster

The exploded topology.

static ExportToBIM(topologies, path: str, overwrite: bool = False, version: str = '1.0.0', guidKey: str = 'guid', colorKey: str = 'color', typeKey: str = 'type', defaultColor: list = [255, 255, 255, 1], defaultType: str = 'Structure', author: str = 'topologicpy', date: str = None, mantissa: int = 6, tolerance: float = 0.0001)

Exports the input topology to a BIM file. See https://dotbim.net/

Parameters

topologieslist or topologic_core.Topology

The input list of topologies or a single topology. The .bim format is restricted to triangulated meshes. No wires, edges, or vertices are supported.

pathstr

The input file path.

overwritebool , optional

If set to True the ouptut file will overwrite any pre-existing file. Otherwise, it won’t. Default is False.

versionstr , optional

The desired version number for the BIM file. Default is “1.0.0”.

guidKeystr , optional

The key to use to find the the guid of the topology. It is case insensitive. Default is “guid”. If no guid is found, one is generated automatically.

colorKeystr , optional

The key to use to find the the color of the topology. It is case insensitive. Default is “color”. If no color is found, the defaultColor parameter is used.

typeKeystr , optional

The key to use to find the the type of the topology. It is case insensitive. Default is “type”. If no type is found, the defaultType parameter is used.

defaultColorlist , optional

The default color to use for the topology. Default is [255,255,255,1] which is opaque white.

defaultTypestr , optional

The default type to use for the topology. Default is “Structure”.

authorstr , optional

The author of the topology. Default is “topologicpy”.

datestr , optional

The creation date of the topology. This should be in the formate “DD.MM.YYYY”. Default is None which uses the date of export.

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 export operation is successful. False otherwise.

static ExportToBREP(topology, path, overwrite=False, version=3)

Exports the input topology to a BREP file. See https://dev.opencascade.org/doc/occt-6.7.0/overview/html/occt_brep_format.html.

Parameters

topologytopologic_core.Topology

The input topology.

pathstr

The input file path.

overwritebool , optional

If set to True the ouptut file will overwrite any pre-existing file. Otherwise, it won’t. Default is False.

versionint , optional

The desired version number for the BREP file. Default is 3.

Returns

bool

True if the export operation is successful. False otherwise.

ExportToDXF(path: str, overwrite: bool = False, mantissa: int = 6)

Exports the input topology to a DXF file. See https://en.wikipedia.org/wiki/AutoCAD_DXF. THe DXF version is ‘R2010’ This is experimental and only geometry is exported.

Parameters

topologieslist or topologic_core.Topology

The input list of topologies. This can also be a single topologic_core.Topology.

pathstr

The input file path.

overwritebool , optional

If set to True the ouptut file will overwrite any pre-existing file. Otherwise, it won’t. Default is False.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

Returns

bool

True if the export operation is successful. False otherwise.

static ExportToJSON(topologies, path, overwrite=False)

Exports the input list of topologies to a JSON file.

Parameters

topologieslist

The input list of topologies.

pathstr

The path to the JSON file.

overwritebool , optional

If set to True the ouptut file will overwrite any pre-existing file. Otherwise, it won’t. Default is False.

Returns

bool

The status of exporting the JSON file. If True, the operation was successful. Otherwise, it was unsuccesful.

static ExportToOBJ(*topologies, path, nameKey='name', colorKey='color', opacityKey='opacity', defaultColor=[256, 256, 256], defaultOpacity=0.5, transposeAxes: bool = True, triangulate: bool = False, mode: int = 0, meshSize: float = None, overwrite: bool = False, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Exports the input topology to a Wavefront OBJ file. This is very experimental and outputs a simple solid topology.

Parameters

topologieslist or comma separated topologies

The input list of topologies.

pathstr

The input file path.

nameKeystr , optional

The topology dictionary key under which to find the name of the topology. Default is “name”.

colorKeystr, optional

The topology dictionary key under which to find the color of the topology. Default is “color”.

opacityKeystr , optional

The topology dictionary key under which to find the opacity of the topology. Default is “opacity”.

defaultColorlist , optional

The default color to use if no color is stored in the topology dictionary. Default is [255,255, 255] (white).

defaultOpacityfloat , optional

The default opacity to use of no opacity is stored in the topology dictionary. This must be between 0 and 1. Default is 1 (fully opaque).

transposeAxesbool , optional

If set to True the Z and Y coordinates are transposed so that Y points “up”

triangulatebool , optional

If set to True, all faces of the input geometry are triangulated. Otherwise, only faces with holes are triangulated. Default is False.

modeint , optional

The desired mode of meshing algorithm (for triangulation). Several options are available: 0: Classic 1: MeshAdapt 3: Initial Mesh Only 5: Delaunay 6: Frontal-Delaunay 7: BAMG 8: Fontal-Delaunay for Quads 9: Packing of Parallelograms All options other than 0 (Classic) use the gmsh library. See https://gmsh.info/doc/texinfo/gmsh.html#Mesh-options WARNING: The options that use gmsh can be very time consuming and can create very heavy geometry.

meshSizefloat , optional

The desired size of the mesh when using the “mesh” option. If set to None, it will be calculated automatically and set to 10% of the overall size of the face.

overwritebool , optional

If set to True the ouptut file will overwrite any pre-existing file. Otherwise, it won’t. 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.

silentbool , optional

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

Returns

bool

True if the export operation is successful. False otherwise.

static ExternalBoundary(topology, silent: bool = False)

Returns the external boundary of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

topologic_core.Topology

The external boundary of the input topology.

static Faces(topology, silent: bool = False)

Returns the faces of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

list

The list of faces.

static Filter(topologies, topologyType='any', searchType='any', key=None, value=None)

Filters the input list of topologies based on the input parameters.

Parameters

topologieslist

The input list of topologies.

topologyTypestr , optional

The type of topology to filter by. This can be one of “any”, “vertex”, “edge”, “wire”, “face”, “shell”, “cell”, “cellcomplex”, or “cluster”. It is case insensitive. Default is “any”.

searchTypestr , optional

The type of search query to conduct in the topology’s dictionary. This can be one of “any”, “equal to”, “contains”, “starts with”, “ends with”, “not equal to”, or “does not contain”. It is case insensitive. Wildcard matching using shell-style patterns is supported in all search types through the use of “*” and “?”. Default is “any”.

keystr , optional

The dictionary key to search within. Default is None which means it will filter by topology type only.

valueany , optional

The value to search for at the specified key. Default is None which means it will filter by topology type only.

Returns

dict

A dictionary with the following keys: - “filtered”: the filtered topologies. - “other”: the other topologies that did not meet the filter criteria.

static Fix(topology, topologyType: str = 'CellComplex', tolerance: float = 0.0001)

Attempts to fix the input topology to matched the desired output type.

Parameters

topologytopologic_core.Topology

The input topology

topologyTypestr , optional

The desired output topology type. This must be one of “vertex”, “edge”, “wire”, “face”, “shell”, “cell”, “cellcomplex”, “cluster”. It is case insensitive. Default is “CellComplex”

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

topologic_core.Topology

The output topology in the desired type.

static Flatten(topology, origin=None, direction: list = [0, 0, 1], transferDictionaries=True, mantissa: int = 6, silent: bool = False)

Flattens the input topology such that the input origin is located at the world origin and the input topology is rotated such that the input vector is pointed in the Up direction (see Vector.Up()).

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The input origin. If set to None, The object’s centroid will be used to place the world origin. Default is None.

directionlist , optional

The input direction vector. The input topology will be rotated such that this vector is pointed in the positive Z axis.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

transferDictionariesbool , optional

If set to True, the dictionaries are transfered from the original object to the translated object. Default is True.

silentbool , optional

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

Returns

topologic_core.Topology

The flattened topology.

static Geometry(topology, transferDictionaries: bool = False, triangulate: bool = False, mode: int = 0, meshSize: float = None, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns the geometry (mesh data format) of the input topology as a dictionary of vertices, edges, and faces.

Parameters

topologytopologic_core.Topology

The input topology.

transferDictionariesbool , optional

If set to True, vertex, edge, and face dictionaries will be included in the output. Otherwise, they are not. Default is False.

triangulatebool , optional

If set to True, all faces of the input geometry are triangulated. Otherwise, only faces with holes are triangulated. Default is False.

mode : int , optional

The desired mode of meshing algorithm (for triangulation). Several options are available: 0: Classic 1: MeshAdapt 3: Initial Mesh Only 5: Delaunay 6: Frontal-Delaunay 7: BAMG 8: Fontal-Delaunay for Quads 9: Packing of Parallelograms All options other than 0 (Classic) use the gmsh library. See https://gmsh.info/doc/texinfo/gmsh.html#Mesh-options WARNING: The options that use gmsh can be very time consuming and can create very heavy geometry.

meshSizefloat , optional

The desired size of the mesh when using the “mesh” option. If set to None, it will be calculated automatically and set to 10% of the overall size of the face. 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

dict

A dictionary containing the vertices, edges, and faces data. The keys found in the dictionary are “vertices”, “edges”, and “faces”.

static HighestType(topology)

Returns the highest topology type found in the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

Returns

int

The highest type found in the input topology.

static Impose(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Imposes topologyB on topologyA. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static Imprint(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Imprints topologyB on topologyA. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static Inherit(targets, sources, keys: list = None, exclusive: bool = True, tolerance: float = 0.0001, silent: bool = False)

Transfers dictionary information from topologiesB to topologiesA based on co-location of internal vertices.

Parameters

targetslist of topologic_core.Topology

The list of target topologies that will inherit the dictionaries.

sourceslist of topologic_core. Topology

The list of source topologies from which to inherit dictionary information.

exclusivebool , optional

If set to True, a target will inherit information only from the first eligible source. Default is True.

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 target topologies with the dictionary information inherited from the list of source topologies.

static InternalVertex(topology, timeout: int = 30, tolerance: float = 0.0001, silent: bool = False)

Returns a vertex guaranteed to be inside the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

timeoutint , optional

The amount of seconds to wait before timing out. Default is 30 seconds.

tolerancefloat , ptional

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

A vertex guaranteed to be inside the input topology.

static Intersect(topologyA, topologyB, tranDict=False, tolerance=0.0001, silent: bool = False)

Finds the intersection between the input operand topologies. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static IsInstance(topology, type: str)

Returns True if the input topology is an instance of the class specified by the input type string.

static IsPlanar(topology, mantissa: int = 6, tolerance: float = 0.0001)

Returns True if all the vertices of the input topology are co-planar. Returns False otherwise.

Parameters

topologytopologic_core.Topology

The input topology.

mantissaint , optional

The desired length of the mantissa. Default is 6

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

bool

True if all the vertices of the input topology are co-planar. False otherwise.

static IsSame(topologyA, topologyB, silent: bool = False)

Returns True if the input topologies are the same topology. Returns False otherwise.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

silentbool , optional

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

Returns

bool

True of the input topologies are the same topology. False otherwise.

static IsSimilar(topologyA, topologyB, removeCoplanarFaces: bool = False, mantissa: int = 6, epsilon: float = 0.1, tolerance: float = 0.0001, silent: bool = False)

Calculates if the input topologies are similar. See https://en.wikipedia.org/wiki/Similarity_(geometry).

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are removed. Otherwise they are not. Default is False.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

epsilonfloat , optional

The desired epsilon (another form of percentage tolerance) for finding if two objects are similar. Should be in the range 0 to 1. Default is 0.1 (10%).

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

[bool, list]

True if the input topologies are similar, False otherwise and the matrix needed to tranform topologyA to match topologyB. If the topologies are not similar, the transformation matrix is None.

static IsVertexCongruent(topologyA, topologyB, mantissa: int = 6, epsilon: float = 0.1, tolerance: float = 0.0001, silent: bool = False)

Returns True if the input topologies are vertex congruent (have same number of vertices and all vertices are congruent within a tolerance). Returns False otherwise.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

epsilonfloat , optional

The desired accepted tolerance for the number of matched number of vertices. For example, an epsilon of 0.1 indicates that the algorithm will return True even if 10% of the vertices do not match. 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

bool

True of the input topologies are vertex congruent. False otherwise.

static JSONString(topologies, mantissa: int = 6)

Exports the input list of topologies to a JSON string

Parameters

topologieslist or topologic_core.Topology

The input list of topologies or a single topology.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

Returns

bool

The status of exporting the JSON file. If True, the operation was successful. Otherwise, it was unsuccesful.

static LargestFaces(topology, removeCoplanarFaces: bool = False, epsilon: float = 0.001, tolerance: float = 0.0001, silent: bool = False)

Returns the list of the largest faces found in the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are removed to find the true largest faces. Otherwise they are not. Default is False.

epsilonfloat , optional

The desired epsilon (another form of tolerance) for finding if two faces are coplanar. Default is 0.01.

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 the largest faces found in the input topology.

static LongestEdges(topology, removeCoplanarFaces: bool = False, epsilon: float = 0.001, tolerance: float = 0.0001, silent: bool = False)

Returns the list of the longest edges found in the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are removed to find the true longest straight edges. Otherwise they are not. Default is False.

epsilonfloat , optional

The desired epsilon (another form of tolerance) for finding if two faces are coplanar. Default is 0.01.

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 of the longest edges found in the input topology.

static Merge(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Merges the input operand topologies. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static MergeAll(*topologies, tolerance: float = 0.0001, silent: bool = False)

Merge all the input topologies.

Parameters

*topologieslist

The list of input topologies.

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

The resulting merged Topology

static Mesh(topology, minSize: float = 0.1, maxSize: float = 1.0, algorithm2D: int = 1, algorithm3D: int = 1, refineEdges: bool = True, refineFaces: bool = True, optimize: bool = True, meshDim: int = None, mantissa: int = 6, silent: bool = False)

Use gmsh to create a variable-resolution mesh of a Topologic topology and return mesh data as:

vertices: List[(x, y, z)] faces : List[(i0, i1, i2)] # unique triangular faces, 0-based tets : List[(i0, i1, i2, i3)] # tetrahedra (3D only; [] for 2D, 0-based)

• If the topology has cells (Cell / CellComplex), does a 3D mesh (tets)

and derives unique triangle faces from tetrahedra. * Otherwise (Face / Shell / etc.), does a 2D surface mesh and returns triangular surface elements as faces; tets = [].

Parameters

topologytopologic_core.Topology

Input topology (Face, Shell, Cell, CellComplex, etc.).

minSizefloat, optional

Target smallest element size near boundaries.

maxSizefloat, optional

Target largest element size away from boundaries.

algorithm2Dint , optional

The desired mode of 2D meshing algorithm. Several options are available: 1: MeshAdapt, 2: Automatic, 3: Initial mesh only, 4: Delaunay, 5: Frontal-Delaunay , 6: BAMG, 7: Frontal-Delaunay for Quads, 8: Packing of Parallelograms, 9: Quasi-structured Quad Default is 1. WARNING: The options that use gmsh can be very time consuming and can create very heavy geometry.

algorithm3Dint , optional

The desired mode of 3D meshing algorithm. Several options are available: 1: Delaunay 2: Initial mesh only 3: Frontal 4: MMG3D 5: R-tree 6: HXT Default is 1 WARNING: The options that use gmsh can be very time consuming and can create very heavy geometry.

refineEdgesbool, optional

If True, refine near model edges (gmsh 1D entities).

refineFacesbool, optional

If True, refine near model faces (gmsh 2D entities).

optimizebool, optional

If True, run gmsh mesh optimizer.

meshDimint or None, optional

If 3, force 3D mesh. If 2, force 2D surface mesh. If None, auto: 3 if Topology.Cells(topology) non-empty, else 2.

mantissaint , optional

The desired size of the mantissa. Default is 6.

silentbool, optional

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

Returns

dict

“verts”: List[(x, y, z)] “tris”: List[(i0, i1, i2)] # triangles “tets”: List[(i0, i1, i2, i3)] # tetrahedra (3D) or [] (2D)

static MeshData(topology, mode: int = 1, transferDictionaries: bool = False, mantissa: int = 6, silent: bool = False)

Creates a mesh data python dictionary from the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

modeint , optional

The desired mode of conversion: 0: The faces list indexes into the vertices list. 1: The faces list indexes into the edges list. The default is 1.

transferDictionariesbool , optional

If set to True, the python dictionaries will be transferred to the coorespoding topologies. 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.

silentbool , optional

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

Returns

dict

The created mesh data python dictionary of vertices, edges, faces, and cells in the form of: { ‘mode’ : int (the mode of the face data) ‘vertices’: list, (list of coordinates) ‘edges’: list, (list of indices into the list of vertices) ‘faces’: list, (list of indices into the list of edges or list of vertices based on mode) ‘cells’: list, (list of indices into the list of faces) ‘vertex_dict’: list of dicts, ‘edge_dicts’: list of dicts, ‘face_dicts’, list of dicts, ‘cell_dicts’, list of dicts }

static MeshToTopologies(vertices: list, faces: list = [], tets: list = [], tolerance: float = 0.0001, silent: bool = False)

Converts mesh data in the form of:

vertices: List[(x, y, z)] faces : List[(i0, i1, i2)] # unique triangular faces, 0-based tets : List[(i0, i1, i2, i3)] # tetrahedra (3D only; [] for 2D, 0-based)

into a list of topologic vertices, faces, and cells. This method is designed to work in conjunction with the Topology.Mesh method.

Parameters

verticeslist

The list of vertices coordinates in the form: List[(x, y, z)].

faceslist , optional

The list of unique triangular faces in the form: List[(i0, i1, i2)]

tetslist , optional

The list of tetrahedral cells in the form: List[i0, i1, ,i2, i3, i4]

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

silentbool, optional

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

Returns

dict

“vertices”: List[topologic_core.Vertex] “faces” : List[topologic_core.Face] # triangles “cells” : List[topologicy_core.Cell] # tetrahedra (3D) or [] (2D)

static Move(topology, x=0, y=0, z=0)

Moves the input topology.

Parameters

topologytopologic_core.topology

The input topology.

xfloat , optional

The x distance value. Default is 0.

yfloat , optional

The y distance value. Default is 0.

zfloat , optional

The z distance value. Default is 0.

Returns

topologic_core.Topology

The moved topology.

static NonPlanarFaces(topology, tolerance=0.0001)

Returns any nonplanar faces in the input topology

Parameters

topologytopologic_core.Topology

The input topology.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

list

The list of nonplanar faces.

static OBJString(*topologies, nameKey='name', colorKey='color', opacityKey='opacity', defaultColor=[255, 255, 255], defaultOpacity=0.5, transposeAxes: bool = True, triangulate: bool = False, mode: int = 0, meshSize: float = None, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Exports the input topology to Wavefront OBJ and MTL strings.

Parameters

topologieslist or comma separated topologies

The input topology or list of topologies.

nameKeystr , optional

The topology dictionary key under which to find the name of the topology. Default is “name”.

colorKeystr, optional

The topology dictionary key under which to find the color of the topology. Default is “color”.

opacityKeystr , optional

The topology dictionary key under which to find the opacity of the topology. Default is “opacity”.

defaultColorlist , optional

The default color to use if no color is stored in the topology dictionary. Default is [255, 255, 255].

defaultOpacityfloat , optional

The default opacity to use if no opacity is stored in the topology dictionary. Default is 0.5.

transposeAxesbool , optional

If set to True, the Z and Y coordinates are transposed so that Y points up. Default is True.

triangulatebool , optional

If set to True, all faces of the input geometry are triangulated. Otherwise, only faces with holes are triangulated. Default is False.

modeint , optional

The desired mode of meshing algorithm (for triangulation). Several options are available: 0: Classic 1: MeshAdapt 3: Initial Mesh Only 5: Delaunay 6: Frontal-Delaunay 7: BAMG 8: Fontal-Delaunay for Quads 9: Packing of Parallelograms All options other than 0 (Classic) use the gmsh library. See https://gmsh.info/doc/texinfo/gmsh.html#Mesh-options WARNING: The options that use gmsh can be very time consuming and can create very heavy geometry.

meshSizefloat , optional

The desired size of the mesh when using the “mesh” option. If set to None, it will be calculated automatically and set to 10% of the overall size of the face.

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

tuple

Returns the OBJ and MTL strings as a tuple.

static OCCTShape(topology)

Returns the occt shape of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

Returns

topologic_core.TopoDS_Shape

The OCCT Shape.

static OntologyClass(topology, defaultValue=None)

Returns the ontology class assigned to the input topology.

static OpenEdges(topology)

Returns the edges that border only one face.

Parameters

topologytopologic_core.Topology

The input topology.

Returns

list

The list of open edges.

static OpenFaces(topology)

Returns the faces that border no cells.

Parameters

topologytopologic_core.Topology

The input topology.

Returns

list

The list of open edges.

static OpenVertices(topology)

Returns the vertices that border only one edge.

Parameters

topologytopologic_core.Topology

The input topology.

Returns

list

The list of open edges.

static Orient(topology, origin=None, dirA=[0, 0, 1], dirB=[0, 0, 1], tolerance=0.0001)

Orients the input topology such that the input such that the input dirA vector is parallel to the input dirB vector.

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The input origin. If set to None, The object’s centroid will be used to locate the input topology. Default is None.

dirAlist , optional

The first input direction vector. The input topology will be rotated such that this vector is parallel to the input dirB vector. Default is [0, 0, 1].

dirBlist , optional

The target direction vector. The input topology will be rotated such that the input dirA vector is parallel to this vector. Default is [0, 0, 1].

tolerancefloat , optional

The desired tolerance. Default is 0.0001

Returns

topologic_core.Topology

The flattened topology.

static Place(topology, originA=None, originB=None, mantissa: int = 6)

Places the input topology at the specified location.

Parameters

topologytopologic_core.Topology

The input topology.

originAtopologic_core.Vertex , optional

The old location to use as the origin of the movement. If set to None, the centroid of the input topology is used. Default is None.

originBtopologic_core.Vertex , optional

The new location at which to place the topology. If set to None, the world origin (0, 0, 0) is used. Default is None.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

Returns

topologic_core.Topology

The placed topology.

static PrincipalAxes(topology, n: int = 10, mantissa: int = 6, silent: bool = False)

Returns the prinicipal axes (vectors) of the input topology. Please note that this is not a perfect algorithm and it can get confused based on the geometry of the input. Also, please note that there is no guarantee that three returned vectors match your expectation for an x,y,z axis order.

Parameters

topologytopologic_core.Topology

The input topology.

nint , optional

The number of segments to use to increase the number of points on each face. Default is 10.

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.

Returns

list

The list of x, y, and z vectors representing the principal axes of the topology.

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

Removes the collinear edges of the input topology

Parameters

topologytopologic_core.Topology

The input topology.

angTolerancefloat , optional

The desired angular tolerance. 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.Topology

The input topology with the collinear edges removed.

static RemoveContent(topology, contents)

Removes the input content list from the input topology

Parameters

topologytopologic_core.Topology

The input topology.

contentListlist

The input list of contents.

Returns

topologic_core.Topology

The input topology with the input list of contents removed.

static RemoveCoplanarFaces(topology, epsilon=0.01, tolerance=0.0001, silent: bool = False)

Removes coplanar faces in the input topology

Parameters

topologytopologic_core.Topology

The input topology.

epsilonfloat , optional

The desired epsilon (another form of tolerance) for finding if two faces are coplanar. Default is 0.01.

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

The input topology with coplanar faces merged into one face.

static RemoveEdges(topology, edges=[], tolerance=0.0001)

Removes the input list of faces from the input topology

Parameters

topologytopologic_core.Topology

The input topology.

edgeslist

The input list of edges.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

topologic_core.Topology

The input topology with the input list of edges removed.

static RemoveFaces(topology, faces=[], tolerance=0.0001)

Removes the input list of faces from the input topology

Parameters

topologytopologic_core.Topology

The input topology.

faceslist

The input list of faces.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

topologic_core.Topology

The input topology with the input list of faces removed.

static RemoveFacesBySelectors(topology, selectors=[], tolerance=0.0001)

Removes faces that contain the input list of selectors (vertices) from the input topology

Parameters

topologytopologic_core.Topology

The input topology.

selectorslist

The input list of selectors (vertices).

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

topologic_core.Topology

The input topology with the identified faces removed.

static RemoveVertices(topology, vertices=[], tolerance=0.0001)

Removes the input list of vertices from the input topology

Parameters

topologytopologic_core.Topology

The input topology.

verticeslist

The input list of vertices.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

topologic_core.Topology

The input topology with the input list of vertices removed.

static ReplaceVertices(topology, verticesA: list = [], verticesB: list = [], mantissa: int = 6, tolerance: float = 0.0001)

Replaces the vertices in the first input list with the vertices in the second input list and rebuilds the input topology. The two lists must be of the same length.

Parameters

topologytopologic_core.Topology

The input topology.

verticesAlist

The first input list of vertices.

verticesBlist

The second input list of vertices.

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

topologic_core.Topology

The new topology.

static Rotate(topology, origin=None, axis: list = [0, 0, 1], angle: float = 0, angTolerance: float = 0.001, transferDictionaries: bool = True, tolerance: float = 0.0001, silent: bool = False)

Rotates the input topology

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The origin (center) of the rotation. If set to None, the world origin (0, 0, 0) is used. Default is None.

axislist , optional

The vector representing the axis of rotation. Default is [0, 0, 1] which equates to the Z axis.

anglefloat , optional

The angle of rotation in degrees. Default is 0.

angTolerancefloat , optional

The angle tolerance in degrees under which no rotation is carried out. Default is 0.001 degrees.

transferDictionariesbool , optional

If set to True, the dictionaries are transfered from the original object to the rotated object. Default is True.

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

The rotated topology.

static RotateByEulerAngles(topology, origin=None, roll: float = 0, pitch: float = 0, yaw: float = 0, transferDictionaries: bool = True, angTolerance: float = 0.001, tolerance: float = 0.0001, silent: bool = False)

Rotates the input topology using Euler angles (roll, pitch, yaw). See https://en.wikipedia.org/wiki/Aircraft_principal_axes

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The origin (center) of the rotation. If set to None, the world origin (0, 0, 0) is used. Default is None.

rollfloat , optional

The rotation angle in degrees around the X-axis. Default is 0.

pitch = float , optional

The rotation angle in degrees around the Y-axis. Default is 0.

yaw = float , optional

The rotation angle in degrees around the Z-axis. Default is 0.

transferDictionariesbool , optional

If set to True, the dictionaries are transfered from the original object to the rotated object. Default is True.

angTolerancefloat , optional

The angle tolerance in degrees under which no rotation is carried out. Default is 0.001 degrees.

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

The rotated topology.

static RotateByQuaternion(topology, origin=None, quaternion: list = [0, 0, 0, 1], transferDictionaries: bool = False, angTolerance: float = 0.001, tolerance: float = 0.0001, silent: bool = False)

Rotates the input topology using Quaternion rotations. See https://en.wikipedia.org/wiki/Quaternion

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The origin (center) of the rotation. If set to None, the world origin (0, 0, 0) is used. Default is None.

quaternionlist or numpy array of size 4

The input Quaternion list. It should be in the form [x, y, z, w].

transferDictionariesbool , optional

If set to True, the dictionaries are transfered from the original object to the rotated object. Default is True.

angTolerancefloat , optional

The angle tolerance in degrees under which no rotation is carried out. Default is 0.001 degrees.

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

The rotated topology.

static Scale(topology, origin=None, x=1, y=1, z=1, transferDictionaries: bool = True, silent: bool = False)

Scales the input topology

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The origin (center) of the scaling. If set to None, the world origin (0, 0, 0) is used. Default is None.

xfloat , optional

The ‘x’ component of the scaling factor. Default is 1.

yfloat , optional

The ‘y’ component of the scaling factor. Default is 1.

zfloat , optional

The ‘z’ component of the scaling factor. Default is 1..

Returns

topologic_core.Topology

The scaled topology.

static SelectSubTopology(topology, selector, subTopologyType='vertex')

Returns the subtopology within the input topology based on the input selector and the subTopologyType.

Parameters

topologytopologic_core.Topology

The input topology.

selectortopologic_core.Vertex

A vertex located on the desired subtopology.

subTopologyTypestr , optional.

The desired subtopology type. This can be of “vertex”, “edge”, “wire”, “face”, “shell”, “cell”, or “cellcomplex”. It is case insensitive. Default is “vertex”.

Returns

topologic_core.Topology

The selected subtopology.

static SelfMerge(topology, transferDictionaries: bool = False, ontology: bool = False, tolerance: float = 0.0001, silent: bool = False)

Self merges the input topology to return the most logical topology type given the input data.

This version uses a fast progressive singleton test before falling back to the expensive core SelfMerge operation.

Parameters

topologytopologic_core.Topology

The input topology.

transferDictionariesbool , optional

If set to True, the dictionary of the input Cluster is transferred to the returned singleton candidate when applicable. Default is False.

ontologybool , optional

If set to True, ontology metadata and semantic class annotations are added to the created/imported topology or graph. Default is True.

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

The self-merged topology.

static SetDictionary(topology, dictionary, silent=False)

Sets the input topology’s dictionary to the input dictionary

Parameters

topologytopologic_core.Topology

The input topology.

dictionarytopologic_core.Dictionary

The input dictionary.

silentbool , optional

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

Returns

topologic_core.Topology

The input topology with the input dictionary set in it.

static SetOntology(topology, ontologyClass: str = None, category: str = None, label: str = None, source: str = None, derivedFrom: str = None, generatedBy: str = None, annotateSubtopologies: bool = False, silent: bool = False)

Annotates the input topology with TopologicPy ontology metadata.

Parameters

topologytopologic_core.Topology

The input topology.

ontologyClassstr , optional

The ontology class, for example “top:Face”, “top:Cell”, or “top:Space”. If set to None, the class is inferred from the Topologic type. Default is None.

categorystr , optional

The semantic category. Default is None.

labelstr , optional

A human-readable label. Default is None.

sourcestr , optional

A source file, URI, or process identifier. Default is None.

derivedFromstr , optional

The source entity from which this topology was derived. Default is None.

generatedBystr , optional

The method or process that generated the topology. Default is None.

annotateSubtopologiesbool , optional

If True, vertices, edges, wires, faces, shells, cells, and cell complexes contained by the topology are also annotated. Default is False.

silentbool , optional

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

Returns

topologic_core.Topology

The annotated topology.

static SetSnapshot(topology, snapshot=None, timestamp=None, key='timestamp', silent=False)

static SharedEdges(topologyA, topologyB)

Returns the shared edges between the two input topologies

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

Returns

list

The list of shared edges.

static SharedFaces(topologyA, topologyB)

Returns the shared faces between the two input topologies

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

Returns

list

The list of shared faces.

static SharedTopologies(topologyA, topologyB)

Returns the shared topologies between the two input topologies

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

Returns

dict

A dictionary with the list of vertices, edges, wires, and faces. The keys are “vertices”, “edges”, “wires”, and “faces”.

static SharedVertices(topologyA, topologyB)

Returns the shared vertices between the two input topologies

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

Returns

list

The list of shared vertices.

static SharedWires(topologyA, topologyB)

Returns the shared wires between the two input topologies

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

Returns

list

The list of shared wires.

static Shells(topology, silent: bool = False)

Returns the shells of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

list

The list of shells.

static ShortestDistance(topologyA, topologyB, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns the shortest Euclidean distance between two topologies.

This is a thin wrapper around Topology.ShortestEdge. It computes the shortest connecting Edge between the two input topologies and returns its length.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

mantissaint , optional

Number of decimal places to which the distance is rounded. Default is 6.

tolerancefloat , optional

Numerical tolerance used when computing the shortest edge. Default is 1e-6.

silentbool , optional

If True, the method will not print warnings. Default is False.

Returns

float or None

The shortest distance between topologyA and topologyB, rounded to the specified mantissa. Returns None if the distance cannot be computed.

static ShortestEdge(topologyA, topologyB, tolerance: float = 0.0001, silent: bool = False)

Returns the shortest connecting Edge between two topologies.

This method deterministically finds the pair of closest points between topologyA and topologyB by examining their sub-topologies (vertices, edges, and faces). It then returns a new Edge whose endpoints lie at these two closest points.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tolerancefloat , optional

Numerical tolerance for detecting near-zero distances and degeneracies. Default is 1e-6.

silentbool , optional

If True, the method will not print warnings. Default is False.

Returns

topologic_core.Edge or None

A new Edge whose start and end vertices represent the closest points on topologyA and topologyB, respectively. Returns None if a valid distance cannot be computed.

Notes

• Sub-topologies are collected using:

  • Topology.Vertices(topology)

  • Topology.Edges(topology)

  • Topology.Faces(topology)

• The returned Edge is not required to belong to either original

  topology; it is a geometric representation of the shortest segment.

• If the shortest distance is (numerically) zero, the start and end

  vertices of the returned Edge will coincide (or be extremely close).

static ShortestEdges(topology, removeCoplanarFaces: bool = False, epsilon: float = 0.001, tolerance: float = 0.0001, silent: bool = False)

Returns the list of the shortest edges found in the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are removed to find the true shortest straight edges. Otherwise they are not. Default is False.

epsilonfloat , optional

The desired epsilon (another form of tolerance) for finding if two faces are coplanar. Default is 0.01.

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 the shortest edges found in the input topology.

static Show(*topologies, nameKey='name', opacityKey='opacity', showVertices=True, vertexSize=None, vertexSizeKey=None, vertexColor='black', vertexColorKey=None, vertexBorderWidth=0, vertexBorderColor='black', vertexBorderWidthKey=None, vertexBorderColorKey=None, vertexLabelKey=None, showVertexLabel=False, vertexLabelFontSize=5, vertexGroupKey=None, vertexGroups=[], vertexMinGroup=None, vertexMaxGroup=None, showVertexLegend=False, vertexLegendLabel='Vertices', directed=False, arrowSize=0.1, arrowSizeKey=None, showEdges=True, edgeWidth=None, edgeWidthKey=None, edgeColor=None, edgeColorKey=None, edgeDash=False, edgeDashKey=None, edgeLabelKey=None, showEdgeLabel=False, edgeGroupKey=None, edgeGroups=[], edgeMinGroup=None, edgeMaxGroup=None, showEdgeLegend=False, edgeLegendLabel='Edges', showFaces=True, faceOpacity=0.5, faceOpacityKey=None, faceColor='#FAFAFA', faceColorKey=None, faceLabelKey=None, faceGroupKey=None, faceGroups=[], faceMinGroup=None, faceMaxGroup=None, showFaceLegend=False, faceLegendLabel='Faces', intensityKey=None, intensities=[], material='default', materialKey=None, flatShading=True, ambient=None, ambientKey=None, diffuse=None, diffuseKey=None, specular=None, specularKey=None, roughness=None, roughnessKey=None, width=950, height=500, xAxis=False, yAxis=False, zAxis=False, axisSize=1, backgroundColor='rgba(0,0,0,0)', marginLeft=0, marginRight=0, marginTop=20, marginBottom=0, camera=[-1.25, -1.25, 1.25], center=[0, 0, 0], up=[0, 0, 1], projection='perspective', renderer='notebook', showScale=False, cbValues=[], cbTicks=5, cbX=-0.15, cbWidth=15, cbOutlineWidth=0, cbTitle='', cbSubTitle='', cbUnits='', colorScale='Viridis', sagitta=0, absolute=False, sides=8, angle=0, showFigure=True, mantissa=6, tolerance=0.0001, silent=False)

Shows the input topology on screen.

Parameters

topologiestopologic_core.Topology or list

The input topology. This must contain faces and or edges. If the input is a list, a cluster is first created

opacityKeystr , optional

The key under which to find the opacity of the topology. Default is “opacity”.

showVerticesbool , optional

If set to True the vertices will be drawn. Otherwise, they will not be drawn. Default is True.

vertexSizefloat , optional

The desired size of the vertices. Default is 1.1.

vertexSizeKeystr , optional

The key under which to find the size of the vertex. Default is None.

vertexColorstr , optional

The desired color of the output vertices. This can be any plotly color string and may be specified as: - A hex string (e.g. ‘#ff0000’) - An rgb/rgba string (e.g. ‘rgb(255,0,0)’) - An hsl/hsla string (e.g. ‘hsl(0,100%,50%)’) - An hsv/hsva string (e.g. ‘hsv(0,100%,100%)’) - A named CSS color. The default is “black”.

vertexColorKeystr , optional

The key under which to find the color of the vertex. Default is None.

vertexBorderWidthfloat , optional

The desired width of the borders of the output vertices. Default is 0.

vertexBorderColorstr , optional

The desired color of the borders of the output vertices. This can be any plotly color string and may be specified as: - A hex string (e.g. ‘#ff0000’) - An rgb/rgba string (e.g. ‘rgb(255,0,0)’) - An hsl/hsla string (e.g. ‘hsl(0,100%,50%)’) - An hsv/hsva string (e.g. ‘hsv(0,100%,100%)’) - A named CSS color. The default is “black”.

vertexLabelKeystr , optional

The dictionary key to use to display the vertex label. Default is None.

showVertexLabelsbool , optional

If set to True, the vertex labels are shown permenantely on screen. Otherwise, they are not. Default is False.

vertexLabelFontSizeint , optional

The font size of the vertex labels. Default is 5.

vertexGroupKeystr , optional

The dictionary key to use to display the vertex group. Default is None.

vertexGroupslist , optional

The list of vertex groups against which to index the color of the vertex. Default is [].

vertexMinGroupint or float , optional

For numeric vertexGroups, vertexMinGroup is the desired minimum value for the scaling of colors. This should match the type of value associated with the vertexGroupKey. If set to None, it is set to the minimum value in vertexGroups. Default is None.

vertexMaxGroupint or float , optional

For numeric vertexGroups, vertexMaxGroup is the desired maximum value for the scaling of colors. This should match the type of value associated with the vertexGroupKey. If set to None, it is set to the maximum value in vertexGroups. Default is None.

showVertexLegendbool, optional

If set to True, the legend for the vertices of this topology is shown. Otherwise, it isn’t. Default is False.

vertexLegendLabelstr , optional

The legend label string used to identify vertices. Default is “Topology Vertices”.

directedbool , optional

If set to True, arrowheads are drawn to show direction. Default is False.

arrowSizeint, optional

The desired size of arrowheads for directed graphs. Default is 0.1.

arrowSizeKey: str , optional

The edge dictionary key under which to find the arrowhead size. Default is None.

showEdgesbool , optional

If set to True the edges will be drawn. Otherwise, they will not be drawn. Default is True.

edgeWidthfloat , optional

The desired thickness of the output edges. Default is 1.

edgeColorstr , optional

The desired color of the output edges. This can be any plotly color string and may be specified as: - A hex string (e.g. ‘#ff0000’) - An rgb/rgba string (e.g. ‘rgb(255,0,0)’) - An hsl/hsla string (e.g. ‘hsl(0,100%,50%)’) - An hsv/hsva string (e.g. ‘hsv(0,100%,100%)’) - A named CSS color. The default is “black”.

edgeColorKeystr , optional

The key under which to find the color of the edge. Default is None.

edgeDashbool , optional

If set to True, the edges are drawn as dashed lines. Default is False.

edgeDashKeystr , optional

The key under which to find the boolean flag to draw edges as dashed lines. Default is None.

edgeWidthKeystr , optional

The key under which to find the width of the edge. Default is None.

edgeLabelKeystr , optional

The dictionary key to use to display the edge label. Default is None.

showEdgeLabelsbool , optional

If set to True, the edge labels are shown permenantely on screen. Otherwise, they are not. Default is False.

edgeGroupKeystr , optional

The dictionary key to use to display the edge group. Default is None.

edgeGroupslist , optional

The list of edge groups against which to index the color of the edge. Default is [].

edgeMinGroupint or float , optional

For numeric edgeGroups, edgeMinGroup is the desired minimum value for the scaling of colors. This should match the type of value associated with the edgeGroupKey. If set to None, it is set to the minimum value in edgeGroups. Default is None.

edgeMaxGroupint or float , optional

For numeric edgeGroups, edgeMaxGroup is the desired maximum value for the scaling of colors. This should match the type of value associated with the edgeGroupKey. If set to None, it is set to the maximum value in edgeGroups. Default is None.

showEdgeLegendbool, optional

If set to True, the legend for the edges of this topology is shown. Otherwise, it isn’t. Default is False.

edgeLegendLabelstr , optional

The legend label string used to identify edges. Default is “Topology Edges”.

showFacesbool , optional

If set to True the faces will be drawn. Otherwise, they will not be drawn. Default is True.

faceOpacityfloat , optional

The desired opacity of the output faces (0=transparent, 1=opaque). Default is 0.5.

faceOpacityKeystr , optional

The key under which to find the opacity of the face. Default is None.

faceColorstr , optional

The desired color of the output faces. This can be any plotly color string and may be specified as: - A hex string (e.g. ‘#ff0000’) - An rgb/rgba string (e.g. ‘rgb(255,0,0)’) - An hsl/hsla string (e.g. ‘hsl(0,100%,50%)’) - An hsv/hsva string (e.g. ‘hsv(0,100%,100%)’) - A named CSS color. The default is “#FAFAFA”.

faceColorKeystr , optional

The key under which to find the color of the face. Default is None.

faceLabelKeystr , optional

The dictionary key to use to display the face label. Default is None.

faceGroupKeystr , optional

The dictionary key to use to display the face group. Default is None.

faceGroupslist , optional

The list of face groups against which to index the color of the face. This can bhave numeric or string values. This should match the type of value associated with the faceGroupKey. Default is [].

faceMinGroupint or float , optional

For numeric faceGroups, minGroup is the desired minimum value for the scaling of colors. This should match the type of value associated with the faceGroupKey. If set to None, it is set to the minimum value in faceGroups. Default is None.

faceMaxGroupint or float , optional

For numeric faceGroups, maxGroup is the desired maximum value for the scaling of colors. This should match the type of value associated with the faceGroupKey. If set to None, it is set to the maximum value in faceGroups. Default is None.

showFaceLegendbool, optional

If set to True, the legend for the faces of this topology is shown. Otherwise, it isn’t. Default is False.

faceLegendLabelstr , optional

The legend label string used to idenitfy edges. Default is “Topology Faces”.

widthint , optional

The width in pixels of the figure. The default value is 950.

heightint , optional

The height in pixels of the figure. The default value is 950.

xAxisbool , optional

If set to True the x axis is drawn. Otherwise it is not drawn. Default is False.

yAxisbool , optional

If set to True the y axis is drawn. Otherwise it is not drawn. Default is False.

zAxisbool , optional

If set to True the z axis is drawn. Otherwise it is not drawn. Default is False.

backgroundColorstr , optional

The desired color of the background. This can be any plotly color string and may be specified as: - A hex string (e.g. ‘#ff0000’) - An rgb/rgba string (e.g. ‘rgb(255,0,0)’) - An hsl/hsla string (e.g. ‘hsl(0,100%,50%)’) - An hsv/hsva string (e.g. ‘hsv(0,100%,100%)’) - A named CSS color. The default is “rgba(0,0,0,0)”.

marginLeftint , optional

The size in pixels of the left margin. The default value is 0.

marginRightint , optional

The size in pixels of the right margin. The default value is 0.

marginTopint , optional

The size in pixels of the top margin. The default value is 20.

marginBottomint , optional

The size in pixels of the bottom margin. The default value is 0.

cameralist , optional

The desired location of the camera). Default is [-1.25, -1.25, 1.25].

centerlist , optional

The desired center (camera target). Default is [0, 0, 0].

uplist , optional

The desired up vector. Default is [0, 0, 1].

projectionstr , optional

The desired type of projection. The options are “orthographic” or “perspective”. It is case insensitive. Default is “perspective”

rendererstr , optional

The desired renderer. See Plotly.Renderers(). If set to None, the code will attempt to discover the most suitable renderer. Default is None.

intensityKeystr , optional

If not None, the dictionary of each vertex is searched for the value associated with the intensity key. This value is then used to color-code the vertex based on the colorScale. Default is None.

intensitieslist , optional

The list of intensities against which to index the intensity of the vertex. Default is [].

materialstr , optional

The type of object material. Case in-sensitive. Supported pre-built materials are: Preset Ambient Diffuse Specular Roughness Description ————————————————————– chalk 1.0 0.4 0.0 1.0 Very soft shading, low contrast concrete 0.85 0.75 0.05 0.9 Highly matte, micro-rough surface, minimal specular reflection eggshell 0.65 0.85 0.25 0.45 Slight sheen, soft highlights without gloss glossy 0.5 0.9 0.6 0.1 Highly polished appearance matte 0.9 0.7 0.0 1.0 Flat, non-reflective surfaces metallic 0.3 0.8 0.9 0.2 Strong, sharp reflections plastic 0.6 0.9 0.2 0.4 Soft highlights, good shape readability Default is a matte material that uses facenormalepsilon=0.

materialKeystr , optional

The dictionary key under which the material string is stored. Default is None.

flatShadingbool , optional

If set to True, the model is rendered with flat shading with no clear light source. Default is True.

ambientfloat , optional

Controls the strength of ambient light applied uniformly to the surface. Higher values reduce shading contrast by increasing overall brightness. Typical range is [0, 1]. This over-rides the material pre-sets. Default is 0.6.

ambientKeystr , optional

The dictionary key under which the ambient value (float) is stored. Default is None.

diffusefloat , optional

Controls the strength of diffuse (Lambertian) lighting based on the angle between the light direction and the surface normal. Higher values enhance shape perception through shading. Typical range is [0, 1]. This over-rides the material pre-sets. Default is None.

diffuseKeystr , optional

The dictionary key under which the diffuse value (float) is stored. Default is None.

specularfloat , optional

Controls the intensity of specular (mirror-like) highlights on the surface. Higher values produce sharper and brighter highlights, giving a glossy appearance. Typical range is [0, 1]. This over-rides the material pre-sets. Default is None.

specularKeystr , optional

The dictionary key under which the specular value (float) is stored. Default is None.

roughnessfloat , optional

Controls the spread of specular highlights on the surface. Lower values result in sharp, concentrated highlights (smooth surfaces), while higher values produce broader, softer highlights (rough surfaces). Typical range is [0, 1]. This over-rides the material pre-sets. Default is None.

roughnessKeystr , optional

The dictionary key under which the roughness value (float) is stored. Default is None.

showScalebool , optional

If set to True, the colorbar is shown. Default is False.

cbValueslist , optional

The input list of values to use for the colorbar. Default is [].

cbTicksint , optional

The number of ticks to use on the colorbar. Default is 5.

cbXfloat , optional

The x location of the colorbar. Default is -0.15.

cbWidthint , optional

The width in pixels of the colorbar. Default is 15

cbOutlineWidthint , optional

The width in pixels of the outline of the colorbar. Default is 0.

cbTitlestr , optional

The title of the colorbar. Default is “”.

cbSubTitlestr , optional

The subtitle of the colorbar. Default is “”.

cbUnits: str , optional

The units used in the colorbar. Default is “”

colorScalestr , optional

The desired type of plotly color scales to use (e.g. “viridis”, “plasma”). Default is “viridis”. For a full list of names, see https://plotly.com/python/builtin-colorscales/.

showFigurebool , optional

If set to True, the figure will be shown and a None is returned. If not, the figure will be returned, but not shown. Default is True.

mantissaint , optional

The desired length of the mantissa for the values listed on the colorbar. 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

Plotly figure

The created plotly figure.

static Slice(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Slices topologyA using topologyB. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static SmallestFaces(topology, removeCoplanarFaces: bool = False, epsilon: float = 0.001, tolerance: float = 0.0001, silent: bool = False)

Returns the list of the smallest faces found in the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are removed to find the true smallest faces. Otherwise they are not. Default is False.

epsilonfloat , optional

The desired epsilon (another form of tolerance) for finding if two faces are coplanar. Default is 0.01.

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 the smallest faces found in the input topology.

static Snapshots(topology, key='timestamp', start=None, end=None, silent=False)

static SortBySelectors(topologies, selectors, exclusive=False, tolerance=0.0001)

Sorts the input list of topologies according to the input list of selectors.

Parameters

topologieslist

The input list of topologies.

selectorslist

The input list of selectors (vertices).

exclusivebool , optional

If set to True only one selector can be used to select on topology. Default is False.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

dict

A dictionary containing the list of sorted and unsorted topologies. The keys are “sorted” and “unsorted”.

static SpatialRelationship(topologyA, topologyB, include: list = ['contains', 'coveredBy', 'covers', 'crosses', 'disjoint', 'equals', 'overlaps', 'touches', 'within', 'proximity'], proximityValues=[1, 5, 10], proximityLabels=['near', 'intermediate', 'far'], mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns the spatial relationship string between the two input topologies according to OGC / ISO 19107 / DE-9IM / RCC-8

Parameters

topologyAtopologic_core.Topology

The first input topology

topologyBtopologic_core. Topology

The second input topology.

includelist , optional

The type(s) of spatial relationships to search for. Default is [“contains”, “coveredBy”, “covers”, “crosses”, “disjoint”, “equals”, “overlaps”, “touches”,”within”]. - Contains: The inverse of “within,” where geometry A contains geometry B. The interior and boundary of B are completely contained within the interior of A. - CoveredBy: The inverse of “covers.” Geometry A is covered by geometry B, with A’s surface lying entirely on B’s surface. - Covers: Geometry B lies entirely on the surface of geometry A. This is a weaker version of Contains() as it allows for B to touch A’s boundary. - Crosses: The geometries have some interior points in common, but not all of the interior of one is contained in the interior of the other. This often describes a line crossing a polygon or another line. - Disjoint: The boundary and interior of the two geometries do not intersect at all. - Equals: The two geometries are exactly the same, representing the same set of points. - Intersects: The geometries have at least one point in common. Intersects is the most general relationship, and if any other relationship (except disjoint) is true, then Intersects() is also true. - Overlaps: The intersection of the two geometries results in a new, distinct geometry of the same dimension. For example, two overlapping polygons produce a new polygon. - Touches: The geometries share at least one point on their boundaries but their interiors do not intersect. - Within: The interior and boundary of geometry A are completely contained within the interior of geometry B. - Proximity: Classifies the shortest distance between the objects according to proximityValues and proximityLabels.

proximityValues: list , optional

The list of maximum distance values that specify the desired proximityLabel. This list must be sorted in ascending order and have the same number of elements as the proximityLabels list. Objects that are further than the largest specified distance are not classified and not included. An object is considered to fall within the range if it is less than or equal to the value in this list. If you wish ALL objects to be classified specifiy the last number in this list to be larger than the largest distance that can exist between any two objects in the list. Default is [1, 5, 10]

proximityLabels: list , optional

The list of range labels (e.g. “near”, “intermediate”, “far”) that correspond to the proximityValues list. The list must have the same number of elements as the proximityValues list. Default is [“near”, “intermediate”, “far”]

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

str

The found spatial relationship. One of [“contains”, “disjoint”, “equals”, “overlaps”, “touches”, “within”, “covers”, “coveredBy”] or “unknown”

static Spin(topology, origin=None, triangulate: bool = True, direction: list = [0, 0, 1], angle: float = 360, sides: int = 16, tolerance: float = 0.0001, silent: bool = False)

Spins the input topology around an axis to create a new topology.See https://en.wikipedia.org/wiki/Solid_of_revolution.

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex

The origin (center) of the spin.

triangulatebool , optional

If set to True, the result will be triangulated. Default is True.

directionlist , optional

The vector representing the direction of the spin axis. Default is [0, 0, 1].

anglefloat , optional

The angle in degrees for the spin. Default is 360.

sidesint , optional

The desired number of sides. Default is 16.

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

The spun topology.

static SubCombinations(topology, subTopologyType=None, minSize: int = 2, maxSize: int = None, maxCombinations: int = 100, timeLimit: int = 10, removeCoplanarFaces: bool = False, removeCollinearEdges: bool = False, tolerance: float = 0.001, silent: bool = False)

Creates connected sub-combination topologies of the input topology. Warning: This is prone to combinatorial explosion.

Parameters

topologytopologic_core.Topology

The input topology. This cannot be vertex or edge.

subTopologyTypestr , optional except when topology is a Cluster

The type of subTopology to include in the combinations. If the input is a Cluster, you must specify the subTopologyType. The options are (case insensitive):

• “CellComplex”

• “Shell”

• “Wire”

If set to None, it will be set according to the input topology type as follows:

• “Cluster” -> User-defined

• “CellComplex” -> “CellComplexes”

• “Cell” -> “Shells”

• “Shell” -> “Shells”

• “Face” -> “Wires”

• “Wire” -> “Wires”

• “Edge” -> None

• “Vertex” -> None

• “Graph” -> “Graphs”

minSizeint , optional

The minimum number of subtopologies to include in a combination. This number cannot be less than 2. Default is 2.

maxSizeint , optional

The maximum number of faces to include in a combinations. This number cannot be less than the number of subtopologies minus 1. Default is None which means the maximum will be set to the number of subtopologies minus 1.

maxCombinationsint , optional

The maximum number of combinations to create. Default is 100.

timeLimitint , optional

The time limit in seconds. Default is 10 seconds. Note that this time limit only applies to creating the combination indices and not the actual Shells.

removeCoplanarFacesbool , optional

If set to True, coplanar faces are removed. Otherwise they are not. Default is False.

removeCollinearEdgesbool , optional

If set to True, collinear edges are removed. Otherwise they are not. 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

list

The list of created sub-combinations.

static SubTopologies(topology, subTopologyType='vertex', silent: bool = False)

Returns the subtopologies of the input topology as specified by the subTopologyType input string.

Parameters

topologytopologic_core.Topology

The input topology.

subTopologyTypestr , optional

The requested subtopology type. This can be one of “vertex”, “edge”, “wire”, “face”, “shell”, “cell”, “cellcomplex”, “cluster”. It is case insensitive. Default is “vertex”.

silentbool , optional

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

Returns

——-

list

The list of subtopologies.

static SuperTopologies(topology, hostTopology, topologyType: str = None) → list

Returns the supertopologies connected to the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

hostTopologytopologic_core.Topology

The host to topology in which to search for their supertopologies.

topologyTypestr , optional

The topology type to search for. This can be any of “edge”, “wire”, “face”, “shell”, “cell”, “cellcomplex”, “cluster”. It is case insensitive. If set to None, the immediate supertopology type is searched for. Default is None.

Returns

list

The list of supertopologies connected to the input topology.

static SymDif(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Returns the symmetric difference (XOR) of the input operand topologies. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static SymmetricDifference(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Returns the symmetric difference (XOR) of the input operand topologies. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static Taper(topology, origin=None, ratioRange: list = [0, 1], triangulate: bool = False, mantissa: int = 6, tolerance: float = 0.0001)

Tapers the input topology. This method tapers the input geometry along its Z-axis based on the ratio range input.

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The desired origin for tapering. If not specified, the centroid of the input topology is used. The tapering will use the X, Y coordinates of the specified origin, but will use the Z of the point being tapered. Default is None.

ratioRangelist , optional

The desired ratio range. This will specify a linear range from bottom to top for tapering the vertices. 0 means no tapering, and 1 means maximum (inward) tapering. Negative numbers mean that tapering will be outwards.

triangulatebool , optional

If set to true, the input topology is triangulated before tapering. Otherwise, it will not be traingulated. Default is False.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

tolerancefloat , optional

The desired tolerance. Vertices will not be moved if the calculated distance is at or less than this tolerance.

Returns

topologic_core.Topology

The tapered topology.

static TransferDictionaries(sources, sinks, tolerance=0.0001, numWorkers=None)

Transfers the dictionaries from the list of sources to the list of sinks.

Parameters

sourceslist

The list of topologies from which to transfer the dictionaries.

sinkslist

The list of topologies to which to transfer the dictionaries.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

numWorkersint, optional

Number of workers run in parallel to process. Default is None which sets the number to twice the number of CPU cores.

Returns

dict

Returns a dictionary with the lists of sources and sinks. The keys are “sinks” and “sources”.

static TransferDictionariesBySelectors(topology, selectors, tranVertices=False, tranEdges=False, tranFaces=False, tranCells=False, tolerance=0.0001, numWorkers=None)

Transfers the dictionaries of the list of selectors to the subtopologies of the input topology based on the input parameters.

Parameters

topologytopologic_core.Topology

The input topology.

selectorslist

The list of input selectors from which to transfer the dictionaries.

tranVerticesbool , optional

If True transfer dictionaries to the vertices of the input topology.

tranEdgesbool , optional

If True transfer dictionaries to the edges of the input topology.

tranFacesbool , optional

If True transfer dictionaries to the faces of the input topology.

tranCellsbool , optional

If True transfer dictionaries to the cells of the input topology.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

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

——-

Topology

The input topology with the dictionaries transferred to its subtopologies.

static Transform(topology, matrix: list, angTolerance: float = 0.001, transferDictionaries: bool = True, tolerance: float = 0.0001, silent: bool = False)

Transforms the input topology by the input 4x4 affine transformation matrix.

Parameters

topologytopologic_core.Topology

The input topology.

matrixlist

The input 4x4 transformation matrix (row-major). Translation is assumed to be in the last column: [ [,,*,tx],

[,,*,ty], [,,*,tz], [0,0,0, 1] ].

angTolerancefloat , optional

Angle tolerance in degrees under which no rotation is carried out. Default is 0.001.

transferDictionariesbool , optional

If True, dictionaries are transferred from the original object to the transformed object (best-effort; relies on consistent sub-topology ordering). Default is True.

tolerancefloat , optional

Desired tolerance. Default is 0.0001.

silentbool , optional

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

Returns

topologic_core.Topology

The transformed topology.

Notes

• This method prioritizes correctness and speed:

  1) If topologic_core.TopologyUtility.Transform is available, it is used (fastest + most general, supports shear). 2) Otherwise, it decomposes the matrix into (scale, rotation, translation) and applies Topology.Scale -> Topology.Rotate -> Topology.Translate. This path assumes the 3x3 linear block is (rotation * axis-aligned scale) with negligible shear.

static Transform_old(topology, matrix: list, angTolerance: float = 0.001, transferDictionaries: bool = True, tolerance: float = 0.0001, silent: bool = False)

Transforms the input topology by the input 4X4 transformation matrix.

Parameters

topologytopologic_core.Topology

The input topology.

matrixlist

The input 4x4 transformation matrix.

angTolerancefloat , optional

The angle tolerance in degrees under which no rotation is carried out. Default is 0.001 degrees.

transferDictionariesbool , optional

If set to True, the dictionaries are transfered from the original object to the transformed object. Default is True.

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

The transformed topology.

static Translate(topology, x=0, y=0, z=0, transferDictionaries: bool = True, silent: bool = False)

Translates (moves) the input topology.

Parameters

topologytopologic_core.topology

The input topology.

xfloat , optional

The x translation value. Default is 0.

yfloat , optional

The y translation value. Default is 0.

zfloat , optional

The z translation value. Default is 0.

transferDictionariesbool , optional

If set to True, the dictionaries are transfered from the original object to the translated object. Default is True.

silentbool , optional

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

Returns

topologic_core.Topology

The translated topology.

static TranslateByDirectionDistance(topology, direction: list = [0, 0, 0], distance: float = 0, transferDictionaries: bool = True, silent: bool = False)

Translates (moves) the input topology along the input direction by the specified distance.

Parameters

topologytopologic_core.topology

The input topology.

directionlist , optional

The direction vector in which the topology should be moved. Default is [0, 0, 0]

distancefloat , optional

The distance by which the toplogy should be moved. Default is 0.

transferDictionariesbool , optional

If set to True, the dictionaries are transfered from the original object to the translated object. Default is True.

silentbool , optional

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

Returns

topologic_core.Topology

The translated topology.

static Triangulate(topology, transferDictionaries: bool = False, mode: int = 0, meshSize: float = None, tolerance: float = 0.0001, silent: bool = False)

Triangulates the input topology.

Parameters

topologytopologic_core.Topology

The input topologgy.

transferDictionariesbool , optional

If set to True, the dictionaries of the faces in the input topology will be transferred to the created triangular faces. Default is False.

modeint , optional

The desired mode of meshing algorithm. Several options are available: 0: Classic 1: MeshAdapt 3: Initial Mesh Only 5: Delaunay 6: Frontal-Delaunay 7: BAMG 8: Fontal-Delaunay for Quads 9: Packing of Parallelograms All options other than 0 (Classic) use the gmsh library. See https://gmsh.info/doc/texinfo/gmsh.html#Mesh-options WARNING: The options that use gmsh can be very time consuming and can create very heavy geometry.

meshSizefloat , optional

The desired size of the mesh when using the “mesh” option. If set to None, it will be calculated automatically and set to 10% of the overall size of the 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.Topology

The triangulated topology.

static Twist(topology, origin=None, angleRange: list = [45, 90], triangulate: bool = False, mantissa: int = 6)

Twists the input topology. This method twists the input geometry along its Z-axis based on the degree range input.

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The desired origin for tapering. If not specified, the centroid of the input topology is used. The tapering will use the X, Y coordinates of the specified origin, but will use the Z of the point being tapered. Default is None.

angleRangelist , optional

The desired angle range in degrees. This will specify a linear range from bottom to top for twisting the vertices. positive numbers mean a clockwise rotation.

triangulatebool , optional

If set to true, the input topology is triangulated before tapering. Otherwise, it will not be traingulated. Default is False.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

Returns

topologic_core.Topology

The twisted topology.

static Type(topology)

Returns the type of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

Returns

int

The type of the input topology.

static TypeAsString(topology, silent: bool = False)

Returns the type of the input topology as a string.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

str

The type of the topology as a string.

static TypeID(name: str = None) → int

Returns the type id of the input name string.

Parameters

namestr , optional

The input class name string. This could be one of:

“vertex”, “edge”, “wire”, “face”, “shell”, “cell”, “cellcomplex”, “cluster”, “aperture”, “context”, “dictionary”, “graph”, “topology”

It is case insensitive. Default is None.

Returns

int

The type id of the input topologyType string.

static UUID(topology, namespace: str = 'topologicpy', uuidKey: str = 'uuid', deterministic: bool = False, silent: bool = False)

Returns the UUID of the input topology.

If deterministic is False, this method returns an existing UUID stored in the topology dictionary. If no UUID exists, a new UUID v4 is created, stored in the topology dictionary, and returned. This is the fast path.

If deterministic is True, this method computes a UUID v5 from the topology’s geometry and dictionaries. This is slower because it traverses the full topology.

Parameters

topologytopologic_core.Topology or topologicpy.Graph

The input topology or graph.

namespacestr , optional

The namespace string to use when deterministic is True. Default is “topologicpy”.

uuidKeystr , optional

The dictionary key under which the UUID is stored. Default is “uuid”.

deterministicbool , optional

If set to True, compute a deterministic content-derived UUID. If set to False, return or create a persistent stored UUID. Default is False.

silentbool , optional

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

Returns

str

The UUID string of the input topology.

static Unflatten(topology, origin=None, direction=[0, 0, 1], transferDictionaries: bool = True, silent: bool = False)

Unflattens the input topology such that the world origin is translated to the input origin and the input topology is rotated such that the Up direction (see Vector.Up()) is aligned with the input vector.

Parameters

topologytopologic_core.Topology

The input topology.

origintopologic_core.Vertex , optional

The input origin. If set to None, The object’s centroid will be used to translate the world origin. Default is None.

vectorlist , optional

The input direction vector. The input topology will be rotated such that this vector is pointed in the positive Z axis.

transferDictionariesbool , optional

If set to True, the dictionaries are transfered from the original object to the translated object. Default is True.

silentbool , optional

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

Returns

topologic_core.Topology

The flattened topology.

static Union(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Unions the input operand topologies. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

static Vertices(topology, silent: bool = True)

Returns the vertices of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

list

The list of vertices.

static VerticesCentroid(topology, mantissa: int = 6, silent: bool = False)

Returns the centroid of the vertices of the input topology.

This method computes the arithmetic mean of the coordinates of all vertices found in the input topology. It does not compute the geometric centroid by length, area, or volume.

Parameters

topologytopologic_core.Topology

The input topology.

mantissaint , optional

The number of decimal places to round the output coordinates to. Default is 6.

silentbool , optional

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

Returns

topologic_core.Vertex or None

The centroid of the vertices of the input topology.

static View3D(*topologies, uuid=None, nameKey='name', colorKey='color', opacityKey='opacity', defaultColor=[256, 256, 256], defaultOpacity=0.5, transposeAxes: bool = True, mode: int = 0, meshSize: float = None, overwrite: bool = False, mantissa: int = 6, tolerance: float = 0.0001)

Sends the input topologies to 3dviewer.net. The topologies must be 3D meshes.

Parameters

topologieslist or comma separated topologies

The input list of topologies.

uuidUUID , optional

The UUID v5 to use to identify these topologies. Default is a UUID based on the topologies themselves.

nameKeystr , optional

The topology dictionary key under which to find the name of the topology. Default is “name”.

colorKeystr, optional

The topology dictionary key under which to find the color of the topology. Default is “color”.

opacityKeystr , optional

The topology dictionary key under which to find the opacity of the topology. Default is “opacity”.

defaultColorlist , optional

The default color to use if no color is stored in the topology dictionary. Default is [255,255, 255] (white).

defaultOpacityfloat , optional

The default opacity to use of no opacity is stored in the topology dictionary. This must be between 0 and 1. Default is 1 (fully opaque).

transposeAxesbool , optional

If set to True the Z and Y coordinates are transposed so that Y points “up”

modeint , optional

The desired mode of meshing algorithm (for triangulation). Several options are available: 0: Classic 1: MeshAdapt 3: Initial Mesh Only 5: Delaunay 6: Frontal-Delaunay 7: BAMG 8: Fontal-Delaunay for Quads 9: Packing of Parallelograms All options other than 0 (Classic) use the gmsh library. See https://gmsh.info/doc/texinfo/gmsh.html#Mesh-options WARNING: The options that use gmsh can be very time consuming and can create very heavy geometry.

meshSizefloat , optional

The desired size of the mesh when using the “mesh” option. If set to None, it will be calculated automatically and set to 10% of the overall size of the face.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

overwritebool , optional

If set to True the ouptut file will overwrite any pre-existing file. Otherwise, it won’t. Default is False.

Returns

bool

True if the export operation is successful. False otherwise.

static Wires(topology, silent: bool = False)

Returns the wires of the input topology.

Parameters

topologytopologic_core.Topology

The input topology.

silentbool , optional

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

Returns

list

The list of wires.

static XOR(topologyA, topologyB, tranDict: bool = False, tolerance: float = 0.0001, silent: bool = False)

Returns the symmetric difference (XOR) of the input operand topologies. See https://en.wikipedia.org/wiki/Boolean_operation.

Parameters

topologyAtopologic_core.Topology

The first input topology.

topologyBtopologic_core.Topology

The second input topology.

tranDictbool , optional

If set to True the dictionaries of the operands are merged and transferred to the result. 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.Topology

the resultant topology.

class topologicpy.Topology.WorkerProcess(message_queue, sources, sinks, so_dicts, tolerance=0.0001)

Bases: Process

Transfers the dictionaries from a subset of sources to the list of sinks.

Attributes

authkey

daemon

Return whether process is a daemon

exitcode

Return exit code of process or None if it has yet to stop

ident

Return identifier (PID) of process or None if it has yet to start

name

pid

Return identifier (PID) of process or None if it has yet to start

sentinel

Return a file descriptor (Unix) or handle (Windows) suitable for waiting for process termination.

Methods

close()	Close the Process object.
is_alive()	Return whether process is alive
join([timeout])	Wait until child process terminates
kill()	Terminate process; sends SIGKILL signal or uses TerminateProcess()
run()	Method to be run in sub-process; can be overridden in sub-class
start()	Start child process
terminate()	Terminate process; sends SIGTERM signal or uses TerminateProcess()

run()

Method to be run in sub-process; can be overridden in sub-class

class topologicpy.Topology.WorkerProcessPool(num_workers, message_queue, sources, sinks, so_dicts, tolerance=0.0001)

Bases: object

Create and manage a list of Worker processes. Each worker process transfers the dictionaries from a subset of sources to the list of sinks.

Methods

join
startProcesses
stopProcesses

join()

startProcesses()

stopProcesses()