topologicpy 0.8.0__py3-none-any.whl → 0.8.3__py3-none-any.whl

topologicpy/Matrix.py

@@ -49,70 +49,47 @@ class Matrix:
 
     @staticmethod
     def ByRotation(angleX=0, angleY=0, angleZ=0, order="xyz"):
-        """
-        Creates a 4x4 rotation matrix.
-
-        Parameters
-        ----------
-        angleX : float , optional
-            The desired rotation angle in degrees around the X axis. The default is 0.
-        angleY : float , optional
-            The desired rotation angle in degrees around the Y axis. The default is 0.
-        angleZ : float , optional
-            The desired rotation angle in degrees around the Z axis. The default is 0.
-        order : string , optional
-            The order by which the roatations will be applied. The possible values are any permutation of "xyz". This input is case insensitive. The default is "xyz".
-
-        Returns
-        -------
-        list
-            The created 4X4 rotation matrix.
-
-        """
         def rotateXMatrix(radians):
-            """ Return matrix for rotating about the x-axis by 'radians' radians """
             c = math.cos(radians)
             s = math.sin(radians)
             return [[1, 0, 0, 0],
-                    [0, c,-s, 0],
+                    [0, c, -s, 0],
                     [0, s, c, 0],
                     [0, 0, 0, 1]]
 
         def rotateYMatrix(radians):
-            """ Return matrix for rotating about the y-axis by 'radians' radians """
-            
             c = math.cos(radians)
             s = math.sin(radians)
-            return [[ c, 0, s, 0],
-                    [ 0, 1, 0, 0],
+            return [[c, 0, s, 0],
+                    [0, 1, 0, 0],
                     [-s, 0, c, 0],
-                    [ 0, 0, 0, 1]]
+                    [0, 0, 0, 1]]
 
         def rotateZMatrix(radians):
-            """ Return matrix for rotating about the z-axis by 'radians' radians """
-            
             c = math.cos(radians)
             s = math.sin(radians)
-            return [[c,-s, 0, 0],
+            return [[c, -s, 0, 0],
                     [s, c, 0, 0],
                     [0, 0, 1, 0],
                     [0, 0, 0, 1]]
-        
+
         xMat = rotateXMatrix(math.radians(angleX))
         yMat = rotateYMatrix(math.radians(angleY))
         zMat = rotateZMatrix(math.radians(angleZ))
+
         if order.lower() == "xyz":
-            return Matrix.Multiply(Matrix.Multiply(zMat,yMat),xMat)
+            return Matrix.Multiply(Matrix.Multiply(zMat, yMat), xMat)
         if order.lower() == "xzy":
-            return Matrix.Multiply(Matrix.Multiply(yMat,zMat),xMat)
+            return Matrix.Multiply(Matrix.Multiply(yMat, zMat), xMat)
         if order.lower() == "yxz":
-            return Matrix.Multiply(Matrix.Multiply(zMat,xMat),yMat)
-        if order.lower == "yzx":
-            return Matrix.Multiply(Matrix.Multiply(xMat,zMat),yMat)
+            return Matrix.Multiply(Matrix.Multiply(zMat, xMat), yMat)
+        if order.lower() == "yzx":
+            return Matrix.Multiply(Matrix.Multiply(xMat, zMat), yMat)
         if order.lower() == "zxy":
-            return Matrix.Multiply(Matrix.Multiply(yMat,xMat),zMat)
+            return Matrix.Multiply(Matrix.Multiply(yMat, xMat), zMat)
         if order.lower() == "zyx":
-            return Matrix.Multiply(Matrix.Multiply(xMat,yMat),zMat)
+            return Matrix.Multiply(Matrix.Multiply(xMat, yMat), zMat)
+
     
     @staticmethod
     def ByScaling(scaleX=1.0, scaleY=1.0, scaleZ=1.0):
@@ -159,10 +136,10 @@ class Matrix:
             The created 4X4 translation matrix.
 
         """
-        return [[1,0,0,0],
-                [0,1,0,0],
-                [0,0,1,0],
-                [translateX,translateY,translateZ,1]]
+        return [[1,0,0,translateX],
+                [0,1,0,translateY],
+                [0,0,1,translateZ],
+                [0,0,0,1]]
     
     @staticmethod
     def EigenvaluesAndVectors(matrix, mantissa: int = 6, silent: bool = False):
@@ -228,49 +205,84 @@ class Matrix:
         return e_values, e_vectors
     
     @staticmethod
-    def Multiply(matA, matB):
+    def Invert(matA, silent: bool = False):
         """
-        Multiplies the two input matrices. When transforming an object, the first input matrix is applied first
-        then the second input matrix.
-        
+        Inverts the input matrix.
+
         Parameters
         ----------
-        matA : list
-            The first input matrix.
-        matB : list
-            The second input matrix.
+        matA : list of list of float
+            The input matrix.
+        silent : bool , optional
+            If set to True, no error and warning messages are printed. Otherwise, they are. The default is False.
 
         Returns
         -------
-        list
-            The matrix resulting from the multiplication of the two input matrices.
+        list of list of float
+            The resulting matrix after it has been inverted.
 
         """
+        import numpy as np
+
         if not isinstance(matA, list):
+            if not silent:
+                print("Matrix.Invert - Error: The input matA parameter is not a valid 4X4 matrix. Returning None.")
             return None
-        if not isinstance(matB, list):
-            return None
-        nr = len(matA)
-        nc = len(matA[0])
-        matC = []
-        for i in range(nr):
-            tempRow = []
-            for j in range(nc):
-                tempRow.append(0)
-            matC.append(tempRow)
-        if not isinstance(matA, list):
+        np_matrix = np.array(matA)
+        if np_matrix.shape != (4, 4):
+            if not silent:
+                print("Matrix.Invert - Error: The input matA parameter is not a valid 4X4 matrix. Returning None.")
             return None
-        if not isinstance(matB, list):
+        
+        # Check if the matrix is invertible
+        if np.isclose(np.linalg.det(np_matrix), 0):
+            if not silent:
+                print("Matrix.Invert - Error: The input matA parameter is not invertible. Returning None.")
             return None
-        # iterate through rows of X
-        for i in range(len(matA)):
-            # iterate through columns of Y
-            tempRow = []
-            for j in range(len(matB[0])):
-                # iterate through rows of Y
-                for k in range(len(matB)):
-                    matC[i][j] += matA[i][k] * matB[k][j]
-        return matC
+        
+        # Invert the matrix
+        inverted_matrix = np.linalg.inv(np_matrix)
+        return inverted_matrix.tolist()
+    
+    @staticmethod
+    def Multiply(matA, matB):
+        """
+        Multiplies two matrices (matA and matB). The first matrix (matA) is applied first in the transformation,
+        followed by the second matrix (matB).
+
+        Parameters
+        ----------
+        matA : list of list of float
+            The first input matrix.
+        matB : list of list of float
+            The second input matrix.
+
+        Returns
+        -------
+        list of list of float
+            The resulting matrix after multiplication.
+
+        """
+        # Input validation
+        if not (isinstance(matA, list) and all(isinstance(row, list) for row in matA) and
+                isinstance(matB, list) and all(isinstance(row, list) for row in matB)):
+            raise ValueError("Both inputs must be 2D lists representing matrices.")
+        
+        # Check matrix dimension compatibility
+        if len(matA[0]) != len(matB):
+            raise ValueError("Number of columns in matA must equal the number of rows in matB.")
+
+        # Dimensions of the resulting matrix
+        rows_A, cols_A = len(matA), len(matA[0])
+        rows_B, cols_B = len(matB), len(matB[0])
+        result = [[0.0] * cols_B for _ in range(rows_A)]
+
+        # Matrix multiplication
+        for i in range(rows_A):
+            for j in range(cols_B):
+                result[i][j] = sum(matA[i][k] * matB[k][j] for k in range(cols_A))
+
+        return result
 
     @staticmethod
     def Subtract(matA, matB):

topologicpy/Topology.py

@@ -4126,6 +4126,116 @@ class Topology():
             return None
         return Topology.ByXYZFile(file, frameIdKey=frameIdKey, vertexIdKey=frameIdKey)
     
+    def CanonicalMatrix(topology, 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
+        ----------
+        topology : topologic_core.Topology
+            The input topology.
+        n : int , optional
+            The number of segments to use to increase the number of points on each face. The default is 10.
+        normalize : bool , optional
+            If set to True, the longest edge in the input topology is scaled to become of length 1. The default is False.
+        mantissa : int , optional
+            The desired length of the mantissa. The default is 6.
+        silent : bool , optional
+            If set to True, no error and warning messages are printed. Otherwise, they are. The default is False.
+        
+        Returns
+        -------
+        list
+            The 4X4 canonical matrix.
+
+        """
+        from topologicpy.Vertex import Vertex
+        from topologicpy.Edge import Edge
+        from topologicpy.CellComplex import CellComplex
+        from topologicpy.Topology import Topology
+        from topologicpy.Grid import Grid
+        from topologicpy.Matrix import Matrix
+        import numpy as np
+
+        def generate_floats(n):
+            if n < 2:
+                return [0.0] if n == 1 else []
+            return [i / (n - 1) for i in range(n)]
+
+        if not Topology.IsInstance(topology, "topology"):
+            if not silent:
+                print("Topology.CanonicalMatrix - Error: The input topology parameter is not a valid topology. Returning None.")
+            return None
+        
+        faces = Topology.Faces(topology)
+        if len(faces) == 0:
+            if not silent:
+                print("Topology.CanonicalMatrix - Error: The input topology parameter does not contain any faces. Returning None.")
+            return None
+        
+        # Step 1: Derive a copy topology to work with.
+        if Topology.IsInstance(topology, "CellComplex"):
+            top = CellComplex.ExternalBoundary(topology)
+        else:
+            top = Topology.Copy(topology)
+        
+        # Step 2: Create a Translation Matrix to translate to origin
+        centroid = Topology.Centroid(top)
+        translation_matrix = Matrix.ByTranslation(-Vertex.X(centroid, mantissa=mantissa), -Vertex.Y(centroid, mantissa=mantissa), -Vertex.Z(centroid, mantissa=mantissa))
+        translated_top = Topology.Translate(top, -Vertex.X(centroid, mantissa=mantissa), -Vertex.Y(centroid, mantissa=mantissa), -Vertex.Z(centroid, mantissa=mantissa))
+
+        # Step 3: Create a Scaling matrix to normalize size (e.g., largest edge length to 1)
+        if normalize == False:
+            scale_factor = 1.0
+        else:
+            edges = Topology.Edges(translated_top)
+            max_edge_length = max([Edge.Length(edge, mantissa=mantissa) for edge in edges])
+            scale_factor = 1.0 / max_edge_length if max_edge_length != 0 else 1.0
+        scaling_matrix = Matrix.ByScaling(scaleX=scale_factor, scaleY=scale_factor, scaleZ=scale_factor)
+        scaled_top = Topology.Scale(translated_top, origin=Vertex.Origin(), x=scale_factor, y=scale_factor, z=scale_factor)
+
+        # Step 4: Increase the number of vertices by adding a grid of points on each face.
+        faces = Topology.Faces(scaled_top)
+        vertices = Topology.Vertices(scaled_top)
+        r = generate_floats(n)
+        for face in faces:
+            vertices += Topology.Vertices(Grid.VerticesByParameters(face=face, uRange=r, vRange=r, clip=True))
+        points = np.array([[Vertex.X(v, mantissa=mantissa), Vertex.Y(v, mantissa=mantissa), Vertex.Z(v, mantissa=mantissa)] for v in vertices])
+
+        # Step 5: Align orientation using PCA
+        # Compute PCA
+        mean = points.mean(axis=0)
+        centered_points = points - mean
+        covariance_matrix = np.cov(centered_points.T)
+        eigenvalues, eigenvectors = np.linalg.eigh(covariance_matrix)
+
+        # Step 6: Sort eigenvectors by eigenvalues (largest first)
+        sorted_indices = np.argsort(-eigenvalues)
+        eigenvectors = eigenvectors[:, sorted_indices]
+
+        # Step 7: Enforce consistent orientation by flipping eigenvectors
+        for i in range(3):  # Ensure each eigenvector points in a positive direction
+            if np.dot(eigenvectors[:, i], [1, 0, 0]) < 0:
+                eigenvectors[:, i] *= -1
+        
+        # Step 8: Create the rotation matrix
+        rotation_matrix = np.eye(4)
+        rotation_matrix[:3, :3] = eigenvectors.T  # Use transpose to align points to axes
+        
+        # Step 9: Rotate the object to align it 
+        transformation_matrix = Matrix.Multiply(scaling_matrix, translation_matrix)
+        transformation_matrix = Matrix.Multiply(rotation_matrix.tolist(), transformation_matrix)
+
+        # Step 10: Return the resulting matrix
+        return transformation_matrix
+
     @staticmethod
     def CenterOfMass(topology):
         """
@@ -6492,6 +6602,87 @@ class Topology():
             return None
         return topologic.Topology.IsSame(topologyA, topologyB)
     
+    def IsVertexMatched(topologyA, topologyB, mantissa: int = 6, tolerance=0.0001, silent : bool = False):
+        """
+        Returns True if the input topologies are vertex matched (have same number of vertices and all vertices are coincedent within a tolerance). Returns False otherwise.
+
+        Parameters
+        ----------
+        topologyA : topologic_core.Topology
+            The first input topology.
+        topologyB : topologic_core.Topology
+            The second input topology.
+        mantissa : int , optional
+            The desired length of the mantissa. The default is 6
+        tolerance : float , optional
+            The desired tolerance. The default is 0.0001.
+        silent : bool , optional
+            If set to True, no error and warning messages are printed. Otherwise, they are. The default is False.
+
+        Returns
+        -------
+        bool
+            True of the input topologies are vertex matched. False otherwise.
+
+        """
+        from topologicpy.Vertex import Vertex
+
+        def coordinates_match(list1, list2, tolerance):
+            """
+            Checks if all coordinates in list1 have a corresponding coordinate in list2
+            within a specified tolerance, with each match being unique.
+
+            Parameters
+            ----------
+            list1 : list of list of float
+                The first list of coordinates, where each coordinate is [x, y, z].
+            list2 : list of list of float
+                The second list of coordinates, where each coordinate is [x, y, z].
+            tolerance : float
+                The maximum distance within which two coordinates are considered matching.
+
+            Returns
+            -------
+            bool
+                True if all coordinates in list1 have a corresponding coordinate in list2
+                within the tolerance. False otherwise.
+            """
+            def distance(coord1, coord2):
+                """Calculate the Euclidean distance between two coordinates."""
+                return np.linalg.norm(np.array(coord1) - np.array(coord2))
+
+            # Copy list2 to keep track of unvisited coordinates
+            unmatched = list2.copy()
+
+            for coord1 in list1:
+                match_found = False
+                for i, coord2 in enumerate(unmatched):
+                    if distance(coord1, coord2) <= tolerance:
+                        # Mark the coordinate as visited by removing it
+                        unmatched.pop(i)
+                        match_found = True
+                        break
+                if not match_found:
+                    return False
+            return True
+
+        if not Topology.IsInstance(topologyA, "topology"):
+            if not silent:
+                print("Topology.IsVertexMatched - Error: The input topologyA parameter is not a valid topology. Returning None.")
+            return None
+        if not Topology.IsInstance(topologyB, "topology"):
+            if not silent:
+                print("Topology.IsVertexMatched - Error: The input topologyB parameter is not a valid topology. Returning None.")
+            return None
+        
+        vertices_a = Topology.Vertices(topologyA)
+        vertices_b = Topology.Vertices(topologyB)
+        if not len(vertices_a) == len(vertices_b):
+            return False
+        coords_a = [Vertex.Coordinates(v, mantissa=mantissa) for v in vertices_a]
+        coords_b = [Vertex.Coordinates(v, mantissa=mantissa) for v in vertices_b]
+        return coordinates_match(coords_a, coords_b, tolerance=tolerance)
+
     @staticmethod
     def MergeAll(topologies, tolerance=0.0001):
         """
@@ -6752,7 +6943,7 @@ class Topology():
         originB : topologic_core.Vertex , optional
             The new location at which to place the topology. If set to None, the world origin (0, 0, 0) is used. The default is None.
         mantissa : int , optional
-            The desired length of the mantissa. The default is 6
+            The desired length of the mantissa. The default is 6.
 
         Returns
         -------
@@ -6779,6 +6970,90 @@ class Topology():
             newTopology = None
         return newTopology
 
+    @staticmethod
+    def 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
+        ----------
+        topology : topologic_core.Topology
+            The input topology.
+        n : int , optional
+            The number of segments to use to increase the number of points on each face. The default is 10.
+        mantissa : int , optional
+            The desired length of the mantissa. The default is 6.
+        silent : bool , optional
+            If set to True, no error and warning messages are printed. Otherwise, they are. The default is False.
+        
+        Returns
+        -------
+        list
+            The list of x, y, and z vectors representing the principal axes of the topology.
+
+        """
+        from topologicpy.Vertex import Vertex
+        from topologicpy.CellComplex import CellComplex
+        from topologicpy.Topology import Topology
+        from topologicpy.Grid import Grid
+        from topologicpy.Vector import Vector
+        import numpy as np
+
+        def generate_floats(n):
+            if n < 2:
+                return [0.0] if n == 1 else []
+            return [i / (n - 1) for i in range(n)]
+
+        
+        if not Topology.IsInstance(topology, "topology"):
+            if not silent:
+                print("Topology.CanonicalMatrix - Error: The input topology parameter is not a valid topology. Returning None.")
+            return None
+        
+        faces = Topology.Faces(topology)
+        if len(faces) == 0:
+            if not silent:
+                print("Topology.CanonicalMatrix - Error: The input topology parameter does not contain any faces. Returning None.")
+            return None
+        
+        # Step 1: Derive a copy topology to work with.
+        if Topology.IsInstance(topology, "CellComplex"):
+            top = CellComplex.ExternalBoundary(topology)
+        else:
+            top = Topology.Copy(topology)
+        
+        # Step 2: Increase the number of vertices by adding a grid of points on each face.
+        faces = Topology.Faces(top)
+        vertices = Topology.Vertices(top)
+        r = generate_floats(n)
+        for face in faces:
+            vertices += Topology.Vertices(Grid.VerticesByParameters(face=face, uRange=r, vRange=r, clip=True))
+        points = np.array([[Vertex.X(v, mantissa=mantissa), Vertex.Y(v, mantissa=mantissa), Vertex.Z(v, mantissa=mantissa)] for v in vertices])
+
+        # Step 3: Align orientation using PCA
+        # Compute PCA
+        mean = points.mean(axis=0)
+        centered_points = points - mean
+        covariance_matrix = np.cov(centered_points.T)
+        eigenvalues, eigenvectors = np.linalg.eigh(covariance_matrix)
+
+        # Sort eigenvectors by eigenvalues (largest first)
+        sorted_indices = np.argsort(-eigenvalues)
+        eigenvectors = eigenvectors[:, sorted_indices]
+
+        # Enforce consistent orientation by flipping eigenvectors
+        for i in range(3):  # Ensure each eigenvector points in a positive direction
+            if np.dot(eigenvectors[:, i], [1, 0, 0]) < 0:
+                eigenvectors[:, i] *= -1
+        
+        # Retrieve and return the principal axes
+        x_axis = Vector.ByCoordinates(*eigenvectors[:, 0])
+        y_axis = Vector.ByCoordinates(*eigenvectors[:, 1])
+        z_axis = Vector.ByCoordinates(*eigenvectors[:, 2])
+        return x_axis, y_axis, z_axis
+
     @staticmethod
     def RemoveCollinearEdges(topology, angTolerance: float = 0.1, tolerance: float = 0.0001, silent: bool = False):
         """
@@ -9229,9 +9504,9 @@ class Topology():
         kRotation31 = matrix[2][0]
         kRotation32 = matrix[2][1]
         kRotation33 = matrix[2][2]
-        kTranslationX = matrix[3][0]
-        kTranslationY = matrix[3][1]
-        kTranslationZ = matrix[3][2]
+        kTranslationX = matrix[0][3]
+        kTranslationY = matrix[1][3]
+        kTranslationZ = matrix[2][3]
 
         return_topology = topologic.TopologyUtility.Transform(topology, kTranslationX, kTranslationY, kTranslationZ, kRotation11, kRotation12, kRotation13, kRotation21, kRotation22, kRotation23, kRotation31, kRotation32, kRotation33)