:py:mod:`multirotor.visualize`
==============================

.. py:module:: multirotor.visualize


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

Classes
~~~~~~~

.. autoapisummary::

   multirotor.visualize.VehicleDrawing



Functions
~~~~~~~~~

.. autoapisummary::

   multirotor.visualize.plot_datalog
   multirotor.visualize.get_wind_quiver
   multirotor.visualize.make_drawing
   multirotor.visualize.update_drawing
   multirotor.visualize.make_fig
   multirotor.visualize.is_terminal



.. py:function:: plot_datalog(log: multirotor.helpers.DataLog, figsize=(21, 10.5), plots=('pos', 'vel', 'ctrl', 'traj'), nrows=2, ncols=None) -> Dict[str, matplotlib.pyplot.Axes]

   Plot recorded values from a Multirotor's flight. Including:

   1. Position and orientation,
   2. Motor speeds,
   3. Velocity in world frame,
   4. Control allocation,
   5. Allocation errors,
   6. 2D x-y position plot

   Parameters
   ----------
   log : DataLog
       The datalog, where `datalog.done_logging()` has been called.
   figsize : tuple, optional
       The x/y dimensions of the figure, by default (21,10.5)

   Returns
   -------
   Dict : Dict[str, plt.Axes]
       A dictionary of plot names mapping to Axes


.. py:function:: get_wind_quiver(heading: str, ax: matplotlib.pyplot.Axes, n=5, dim=2)

   Create arrays of x,y,z coordinates for a quiver plot of wind.

   Parameters
   ----------
   heading : str
       The heading of the wind, e.g. '5@45' for 5N wind from 45 degrees.
   ax : plt.Axes
       The axes on which to plot the quiver.
   n : int, optional
       Size of arrays, by default 5
   dim : int, optional
       Dimension of quiver (2 or 3), by default 2

   Returns
   -------
   Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]
       x,y,[z],dx,dy,[dz] coordinates for quiver plot.


.. py:class:: VehicleDrawing(vehicle: multirotor.simulation.Multirotor, axis: mpl_toolkits.mplot3d.Axes3D = None, trace: bool = False, body_axes: bool = False, make_fig_kwargs: dict = dict(xlim=(-10, 10), ylim=(-10, 10), zlim=(-10, 10)))


   A 3D representation of the vehicle.

   .. py:method:: update() -> float

      Draw vehicle position and orientation on the figure.

      Returns
      -------
      float
          The time (seconds) taken to finish this operation.


   .. py:method:: reset()

      Clear vehicle's trajectory, and place vehicle at its current position.
              


   .. py:method:: _init_func() -> Tuple[mpl_toolkits.mplot3d.art3d.Line3D]

      Add vehicle and trajectory lines to plot by initializing the Artist objects
      in `self.axis`.

      Returns
      -------
      Tuple[Line3d]



.. py:function:: make_drawing(params: multirotor.vehicle.VehicleParams, body_axes: bool = False, make_2d: bool = False, scale_arms=1.0) -> Tuple[List[Union[matplotlib.lines.Line2D, mpl_toolkits.mplot3d.art3d.Line3D]], numpy.ndarray, Union[matplotlib.lines.Line2D, mpl_toolkits.mplot3d.art3d.Line3D], List[Union[matplotlib.lines.Line2D, mpl_toolkits.mplot3d.art3d.Line3D]], numpy.ndarray]

   Create Atrist objects for vehicle arms, trajectory, body-frame axes. These will
   then be added to the Figure.

   Parameters
   ----------
   params : VehicleParams
       The description of the vehicle.
   body_axes : bool, optional
       Whether to draw body-frame x/y/z axes, by default False
   make_2d : bool, optional
       Whether to return 2D lines (if using these for some 2D plot), by default False
   scale_arms : _type_, optional
       Factor by which to scale arm lengths. Useful when a small vehicle must be made
       visible in a plot with large bounds, by default 1.

   Returns
   -------
   Tuple
       - List of lines for vehicle propeller arms,
       - Array of (2*propellers) x [2|3] containing end-points of arm lines in [2|3] dimensions
       - The line object of the vehicle trajectory
       - List of lines for body-frame axes
       - Array of (2*3) x 3 containing end-points of body-frame axis lines in [2|3] dimensions.


.. py:function:: update_drawing(drawing: VehicleDrawing, position: numpy.ndarray, orientation: numpy.ndarray) -> Tuple[List[Union[matplotlib.lines.Line2D, mpl_toolkits.mplot3d.art3d.Line3D]], Union[matplotlib.lines.Line2D, mpl_toolkits.mplot3d.art3d.Line3D], List[Union[matplotlib.lines.Line2D, mpl_toolkits.mplot3d.art3d.Line3D]]]

   Update the Artist objects for the vehicle arms, trajectory, body-frame axes given
   position and orientation.

   Parameters
   ----------
   drawing : VehicleDrawing
       The drawing to update.
   position : np.ndarray
       The 3D position of the vehicle,
   orientation : np.ndarray
       The orientation (radians) of the vehicle

   Returns
   -------
   Tuple
       - List of lines for vehicle propeller arms,
       - The line object of the vehicle trajectory
       - List of lines for body-frame axes


.. py:function:: make_fig(xlim: Tuple[float, float], ylim: Tuple[float, float], zlim: Tuple[float, float], **fig_kwargs) -> Tuple[matplotlib.pyplot.Figure, mpl_toolkits.mplot3d.Axes3D]

   Convenience function for creating a 3D axis.

   Parameters
   ----------
   xlim/ylim/zlim : Tuple[float, float]
       Min/max coordinates in plot

   Returns
   -------
   Tuple[plt.Figure, Axes3D]
       The figure and Axes3D instance


.. py:function:: is_terminal() -> bool

   Check whether code is running in a text console or jupyter notebook.

   Returns
   -------
   bool
       True if running in terminal.