vectorose.triangle_sphere
=========================

.. py:module:: vectorose.triangle_sphere

.. autoapi-nested-parse::

   Triangle-based Sphere Plotting.

   This module provides the functions necessary to produce a triangle mesh of
   a sphere, with face colours corresponding to the point count in each face.



Classes
-------

.. autoapisummary::

   vectorose.triangle_sphere.TriangleSphere


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

.. py:class:: TriangleSphere(number_of_subdivisions: int = 3, number_of_shells: int = 1, magnitude_range: Optional[Tuple[float, float]] = None)

   Bases: :py:obj:`vectorose.sphere_base.SphereBase`


   Representation of a sphere constructed using equal-area triangles.

   Compute and visualise histograms using a sphere composed of equal-area
   triangles.


   .. py:attribute:: _sphere
      :type:  trimesh.primitives.Sphere

      Sphere mesh used to compute and visualise the histogram.


   .. py:attribute:: _faces
      :type:  pandas.DataFrame

      Data frame containing information about the mesh faces.


   .. py:property:: orientation_cols
      :type: List[str]


      Name of the histogram columns to use for orientation.


   .. py:method:: _initial_vector_component_preparation(vectors: pandas.DataFrame) -> pandas.DataFrame

      Prepare the vector components for histogram construction.

      Override this method to include specific operations that should be
      performed on the vectors in order to construct the histogram in the
      specific implementation.

      .. warning::

         This function should **not** perform any tasks related to the
         vector spatial locations, if those are included in the data. Those
         are handled separately by :meth:`._initial_vector_data_preparation`
         which calls this function.



   .. py:method:: _compute_orientation_binning(vectors: pandas.DataFrame) -> pandas.Series

      Bin the provided vectors based on orientation.

      :param vectors: The vectors to place in orientation bins.

      :returns: :class:`pandas.Series` or :class:`pandas.DataFrame` -- The orientation bin(s) corresponding to each vector. The number
                of columns will depend on the specific sphere representation
                used.



   .. py:method:: to_dataframe() -> pandas.DataFrame

      Get the data frame representation of the sphere.

      .. rubric:: Notes

      The produced table contains one row for each face in the
      triangulated sphere. The column headers are ``x1``, ``y1``, ``z1``,
      ``x2``, ``y2``, ``z2``, ``x3``, ``y3``, ``z3``, reflecting the
      Cartesian coordinates of each vertex forming the face.



   .. py:method:: _construct_orientation_index() -> pandas.RangeIndex

      Get the orientation index for the current triangulated sphere.

      Produce the orientation index for the current triangulated sphere,
      containing all face indices for a given shell.

      :returns: :class:`pandas.RangeIndex` -- Index containing all valid ``face`` indices.



   .. py:method:: create_mesh() -> pyvista.PolyData

      Return the mesh representation of the current sphere.



   .. py:method:: convert_vectors_to_cartesian_array(labelled_vectors: pandas.DataFrame, create_unit_vectors: bool = False, include_spatial_coordinates: bool = False) -> numpy.ndarray

      Convert a set of labelled vectors into Cartesian coordinates.

      Each concrete implementation of a sphere may internally represent
      the vectors differently. This abstract method converts from that
      implementation-specific formatting to Cartesian coordinates.

      :param labelled_vectors: The set of labelled ``n`` labelled vectors in ``d`` dimensions,
                               in the same format as produced by
                               :meth:`SphereBase.assign_histogram_bins`.
      :param create_unit_vectors: Indicate where the returned vectors should be unit vectors.
                                  Depending on the implementation, this may either remove an
                                  extraneous normalisation step later, or add an extra
                                  normalisation step now.
      :param include_spatial_coordinates: Indicate whether to include spatial coordinates in the new
                                          array. This option may only be called if the vectors have
                                          spatial coordinates.

      :returns: :class:`numpy.ndarray` -- Array of shape ``(n, d)`` containing the vector components in
                Cartesian coordinates.

      .. warning::

         The option `include_spatial_coordinates` is only valid if the
         `labelled_vectors` include spatial coordinates.



   .. py:method:: get_cell_indices(bins: pandas.DataFrame) -> pandas.Series

      Get cell indices for specific bins.

      Get the mesh cell index for specified orientation bins.

      :param bins: DataFrame containing the implementation-specific orientation
                   bin information for the desired cells

      :returns: :class:`Series` -- Indices of the mesh cells corresponding to the desired
                orientation bin.

      .. seealso::

         :obj:`.SphereBase.assign_histogram_bins`
             assign specific orientations and magnitudes to histogram bins.