bluemira.geometry.overlap_checking
==================================

.. py:module:: bluemira.geometry.overlap_checking

.. autoapi-nested-parse::

   Contains functions to efficiently check for overlaps between solids.



Functions
---------

.. autoapisummary::

   bluemira.geometry.overlap_checking.two_set_mutually_exclusive
   bluemira.geometry.overlap_checking.check_two_sets_bb_non_interference
   bluemira.geometry.overlap_checking.get_overlaps_asymmetric
   bluemira.geometry.overlap_checking.is_mutually_exclusive
   bluemira.geometry.overlap_checking.check_bb_non_interference
   bluemira.geometry.overlap_checking.get_overlaps_arr
   bluemira.geometry.overlap_checking.scale_points_from_centroid
   bluemira.geometry.overlap_checking.find_approx_overlapping_pairs


Module Contents
---------------

.. py:function:: two_set_mutually_exclusive(min_a: numpy.ndarray[float], max_a: numpy.ndarray[float], min_b: numpy.ndarray[float], max_b: numpy.ndarray[float]) -> numpy.ndarray

   Given TWO lists of bounds, (e.g. x-bounds, i.e. x-min and x-max for each cell),
   find whether each cell is mutually exclusive (i.e. does NOT overlap) with other
   cells. This forms a 2D exclusivity matrix.

   :param min_a: lower bound for each cell in set A, a 1D array.
   :param max_a: upper bound for each cell in set A, a 1D array.
   :param min_b: lower bound for each cell in set B, a 1D array.
   :param max_b: upper bound for each cell in set B, a 1D array.

   :returns: A 2D exclusivity matrix showing True where they're NOT overlapping, False if
             overlapping. The main-diagonal of this matrix can be ignored.

   .. note:: Must have the property that all(min_a<=max_a) and all(min_b<=max_b).


.. py:function:: check_two_sets_bb_non_interference(set_a_3d_tensor: numpy.ndarray, set_b_3d_tensor: numpy.ndarray) -> numpy.ndarray

   Check which bounding box do not interfere/overlap with which other bounding box.

   :param set_a_3d_tensor: An array of 2D arrays (each with shape = (3,2)), each row of the 2D array is
                           the x, y, z bounds (min, max) for that set A cell.
   :param set_b_3d_tensor: An array of 2D arrays (each with shape = (3,2)), each row of the 2D array is
                           the x, y, z bounds (min, max) for that set B cell.

   :returns: A matrix of booleans showing whether the bounding boxes overlap.
   :rtype: exclusivity_matrix


.. py:function:: get_overlaps_asymmetric(exclusivity_matrix) -> numpy.ndarray

   Get the indices of the bounding boxes that are overlapping. The overlap matrix is the
   element-wise negation of the exclusivity matrix. This function returns the 2-D
   indices of non-zero elements.

   :param exclusivity_matrix: The matrix denoting whether each bounding box overlap with other bounding boxes,
                              generated by :func:`~check_two_sets_bb_non_interference`.

   :returns: 2D array of integers, each row is a pair of indices of i<j
   :rtype: indices


.. py:function:: is_mutually_exclusive(min_: numpy.ndarray[float], max_: numpy.ndarray[float]) -> numpy.ndarray

   Given a list of bounds, (e.g. x-bounds, showing .xmin() and .xmax() for each cell),
   find whether each cell is mutually exclusive (i.e. does NOT overlap) with other
   cells. This forms a 2D exclusivity matrix.

   :param min_: lower bound for each cell, a 1D array.
   :param max_: upper bound for each cell, a 1D array.

   :returns: A 2D exclusivity matrix showing True where they're NOT overlapping, False if
             overlapping. The main-diagonal of this matrix can be ignored.

   .. note:: Must have the property that all(min_<=max_)==True.


.. py:function:: check_bb_non_interference(tensor_3d: numpy.ndarray) -> numpy.ndarray

   Check which bounding box do not interfere/overlap with which other bounding box.

   :param tensor_3d: An array of 2D arrays (each with shape = (3,2)), each row of the 2D array is
                     the x, y, z bounds (min, max) for that cell.

   :returns: A matrix of booleans showing whether the bounding boxes overlap.
   :rtype: exclusivity_matrix


.. py:function:: get_overlaps_arr(exclusivity_matrix) -> numpy.ndarray

   Get the indices of the bounding boxes that are overlapping. The overlap matrix is the
   element-wise negation of the exclusivity matrix. This function returns the 2-D
   indices of non-zero elements on the upper-right triangle of this matrix.

   :param exclusivity_matrix: The matrix denoting whether each bounding box overlap with other bounding boxes,
                              generated by :func:`~check_bb_non_interference`.

   :returns: 2D array of integers, each row is a pair of indices of i<j
   :rtype: indices


.. py:function:: scale_points_from_centroid(points, scale_factor)

   Scale a set of points from their centroid by a given scale factor.

   :param points: An array of shape (n, 3) representing the x, y, z coordinates of the points.
   :type points: np.ndarray
   :param scale_factor: The scale factor by which to scale the points.
   :type scale_factor: float

   :returns: **scaled_points** -- An array of shape (n, 3) representing the scaled x, y, z
             coordinates of the points.
   :rtype: np.ndarray


.. py:function:: find_approx_overlapping_pairs(solids: collections.abc.Iterable[bluemira.geometry.solid.BluemiraSolid], *, use_cgal: bool = True)

   Finds the pairs of solids that are approximately overlapping.

   This function uses bounding boxes to quickly eliminate non-overlapping pairs,
   and then refines the results using a numpy (or CGAL, if installed) based apporach
   to refind the number of overlapping pairs taking into the geometry,
   in a confirmal manner.

   :param solids: An iterable of BluemiraSolid objects to check for overlaps between.
   :param use_cgal: If True, use CGAL to check for overlaps. Otherwise, use numpy.
                    If CGAL is not available, this will default to numpy (even if True).

   :rtype: A list of tuples of indices of overlapping pairs.