pencil.visu.pv_plotter_utils
============================

.. py:module:: pencil.visu.pv_plotter_utils

.. autoapi-nested-parse::

   Requirements
   ------------
   See ``pv_plotter.py`` docstring!



Functions
---------

.. autoapisummary::

   pencil.visu.pv_plotter_utils.plotPreview
   pencil.visu.pv_plotter_utils.randomSampleMeshPoints
   pencil.visu.pv_plotter_utils.randomSampleMesh
   pencil.visu.pv_plotter_utils.getCameraParamsRounded
   pencil.visu.pv_plotter_utils.gridFromCylCoords
   pencil.visu.pv_plotter_utils.cellBounds
   pencil.visu.pv_plotter_utils.create_sbar_args


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

.. py:function:: plotPreview(plotter) -> None

   Routine for interactive plot preview window showing the camera parameters.
   :param plotter: Instance of pv.Plotter
   :type plotter: pv.Plotter
   :param window_size: Windows size [width, height], by default None
   :type window_size: list, optional

   .. rubric:: Notes

   Last updated: 18.6.2021


.. py:function:: randomSampleMeshPoints(n, mesh, set_seed_1=False, constant_seed=False, get_arrays=False, seed=None)

   Returns randomly (uniformly) sampled points from the given mesh,
   i.e. a subset of mesh.points

   :param n: Number of points to choose from the mesh
   :type n: int
   :param mesh: Pyvista mesh
   :param set_seed_1: If set_seed_1 set to True, sets seed used by the random generator to 1,
                      i.e. each time.time this is called with the same mesh, function would return
                      the same points. For debugging purposes. By default False
   :type set_seed_1: bool, optional
   :param get_arrays: If True, also samples all the point arrays that the given mesh contains,
                      and adds them to the returned pyvista.PolyData
   :type get_arrays: bool, optional

   :returns: Set of n randomly sampled points from the given mesh.
   :rtype: pyvista.PolyData


.. py:function:: randomSampleMesh(n, mesh)

   PROBLEM: random samples individual cells which consists of 9 points. Hence ends up being
   individual cells all around the plot each having 9 streamlines


.. py:function:: getCameraParamsRounded(plotter: pyvista.Plotter, precision=3) -> tuple

   Returns camera parameters rounded to given precision.
   :param plotter: Instance of pv.Plotter
   :type plotter: pv.Plotter
   :param precision: Precision to round to, by default 3
   :type precision: int, optional

   :returns: (camera_centre, focal_point, view_up)
   :rtype: tuple

   .. rubric:: Notes

   Last updated: 18.6.2021


.. py:function:: gridFromCylCoords(r, theta, z) -> pyvista.StructuredGrid

   "
   Create PyVista StructuredGrid out of cylinder coordinates.
   :param r: Radial distances
   :type r: numpy.ndarray
   :param theta: Polar angles (in radians)
   :type theta: numpy.ndarray
   :param z: Z-coordinates (heights)
   :type z: numpy.ndarray

   :returns: Mesh given the coordinates
   :rtype: pyvista.StructuredGrid

   .. rubric:: Notes

   Last updated: 18.6.2021


.. py:function:: cellBounds(points, bound_position=0.5) -> numpy.ndarray

   Calculate coordinate cell boundaries.
   :param points: One-dimensional array of uniformly spaced values of shape (M,)
   :type points: numpy.array
   :param bound_position: The desired position of the bounds relative to the position
                          of the points.
   :type bound_position: bool, optional

   :returns: **bounds** -- Array of shape (M+1,)
   :rtype: numpy.array

   .. rubric:: Examples

   >>> a = np.arange(-1, 2.5, 0.5)
   >>> a
   array([-1. , -0.5,  0. ,  0.5,  1. ,  1.5,  2. ])
   >>> cell_bounds(a)
   array([-1.25, -0.75, -0.25,  0.25,  0.75,  1.25,  1.75,  2.25])


.. py:function:: create_sbar_args(settings, title, posx, posy)

   Small convenience function to remove duplicate code. Combines all scalarbar
   arguments into one dictionary. Note that PlotSettings __post_init__ creates
   _sbar_args but it is still missing parameters that depend on whether one is
   showing field (stream | vectors) or scalars.