boinor.plotting.orbit.backends.plotly
=====================================

.. py:module:: boinor.plotting.orbit.backends.plotly

.. autoapi-nested-parse::

   A module implementing orbit plotter backends based on Plotly.



Classes
-------

.. autoapisummary::

   boinor.plotting.orbit.backends.plotly.BasePlotly
   boinor.plotting.orbit.backends.plotly.Plotly2D
   boinor.plotting.orbit.backends.plotly.Plotly3D


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

.. py:class:: BasePlotly(figure, layout)

   Bases: :py:obj:`boinor.plotting.orbit.backends._base.OrbitPlotterBackend`


   An orbit plotter backend class based on Plotly.


   .. py:property:: figure

      The plotly figure use to render the scene.

      :returns: The plotly ``Figure`` representing the scene.
      :rtype: ~plotly.graph_objects.Figure


   .. py:property:: layout

      The plotly layout of the figure.

      :returns: The plotly ``Layout`` object linked to the figure.
      :rtype: ~plotly.graph_objects.Layout


   .. py:method:: draw_marker(position, *, color, label, marker_symbol, size)
      :abstractmethod:


      Draw desired marker into the scene.

      :param position: A list containing the x, y and z coordinates of the point.
      :type position: list[float, float, float]
      :param color: A string representing the hexadecimal color for the point.
      :type color: str
      :param label: The name to be used in the legend for the marker.
      :type label: str
      :param marker_symbol: The marker symbol to be used when drawing the point.
      :type marker_symbol: str
      :param size: The size of the marker.
      :type size: float



   .. py:method:: draw_sphere(position, *, color, label, radius)
      :abstractmethod:


      Draw an sphere into the scene.

      :param position: A list containing the x, y and z coordinates of the sphere location.
      :type position: list[float, float, float]
      :param color: A string representing the hexadecimal color for the sphere.
      :type color: str
      :param label: The name to be used in the legend for the marker.
      :type label: str
      :param radius: The radius of the sphere.
      :type radius: float



   .. py:method:: draw_coordinates(coordinates, *, colors, dashed, label)
      :abstractmethod:


      Draw desired coordinates into the scene.

      :param coordinates: A set of lists containing the x, y and z coordinates.
      :type coordinates: list[list[float, float, float]]
      :param colors: A list of string representing the hexadecimal color for the coordinates.
      :type colors: list[str]
      :param dashed: Whether to use a dashed or solid line style for the coordiantes.
      :type dashed: bool
      :param label: The name to be used to identify the coordinates in the legend of the
                    figure.
      :type label: str



   .. py:method:: draw_axes_labels_with_length_scale_units(length_scale_units)
      :abstractmethod:


      Draw the desired label into the specified axis.

      :param lenght_scale_units: Desired units of lenght used for representing distances.
      :type lenght_scale_units: ~astropy.units.Unit



   .. py:method:: update_layout(layout)

      Update the layout of the figure scene.

      :param layout: The new plotly ``Layout`` to be used in the figure.
      :type layout: ~plotly.graph_objects.Layout



   .. py:method:: undraw_attractor()

      Removes the attractor from the scene.



   .. py:method:: draw_position(position, *, color, label, size)

      Draw the position of a body in the scene.

      :param position: A list containing the x, y and z coordinates of the point.
      :type position: list[float, float, float]
      :param color: A string representing the hexadecimal color for the marker.
      :type color: str
      :param label: The name shown in the figure legend to identify the position.
      :type label: str
      :param size: The size of the marker.
      :type size: float

      :returns: An object representing the trace of the coordinates in the scene.
      :rtype: [~plotly.graph_objects.Surface, ~plotly.graph_objects.Trace]



   .. py:method:: draw_impulse(position, *, color, label, size)

      Draw an impulse into the scene.

      :param position: A list containing the x and y coordinates of the impulse location.
      :type position: list[float, float]
      :param color: A string representing the hexadecimal color for the impulse marker.
      :type color: str
      :param label: The name shown in the figure legend to identify the impulse.
      :type label: str
      :param size: The size of the marker for the impulse.
      :type size: float

      :returns: An object representing the trace of the impulse in the scene.
      :rtype: object



   .. py:method:: update_legend()

      Update the legend of the scene.



   .. py:method:: resize_limits()

      Resize the limits of the scene.



   .. py:method:: show()

      Display the scene.



   .. py:method:: generate_labels(label, has_coordinates, has_position)

      Generate the labels for coordinates and position.

      :param label: A string representing the label.
      :type label: str
      :param has_coordinates: Whether the object has coordinates to plot or not.
      :type has_coordinates: boolean
      :param has_position: Whether the object has a position to plot or not.
      :type has_position: boolean

      :returns: A tuple containing the coordinates and position labels.
      :rtype: tuple



   .. py:property:: scene

      Return the scene object.


   .. py:property:: name

      Return the name of the backend.

      :returns: Name of the backend.
      :rtype: str


   .. py:property:: is_2D

      Assert if backend is 2D.

      :returns: ``True`` if it is a 2D backend, ``False`` if it is not.
      :rtype: bool


   .. py:property:: is_3D

      Assert if backend is 3D.

      :returns: ``True`` if it is a 3D backend, ``False`` if it is not.
      :rtype: bool


.. py:class:: Plotly2D(figure=None, use_dark_theme=False, width=None, height=None)

   Bases: :py:obj:`BasePlotly`


   An orbit plotter backend class based on Plotly.


   .. py:method:: draw_marker(position, *, color, label, marker_symbol, size)

      Draw a marker into the scene.

      :param position: A list containing the x and y coordinates of the point.
      :type position: list[float, float]
      :param color: A string representing the hexadecimal color for the point.
      :type color: str
      :param label: The name shown in the legend of the figure to identify the marker.
      :type label: str
      :param marker_symbol: The marker symbol to be used when drawing the point.
      :type marker_symbol: str
      :param size: Desired size for the marker.
      :type size: float

      :returns: An object representing the trace of the marker in the scene.
      :rtype: object



   .. py:method:: draw_sphere(position, *, color, label, radius)

      Draw an sphere into the scene.

      :param position: A list containing the x and y coordinates of the sphere location.
      :type position: list[float, float]
      :param color: A string representing the hexadecimal color for the sphere.
      :type color: str
      :param label: Unuseful for this routine. See the ``Notes`` section.
      :type label: str
      :param radius: The radius of the sphere.
      :type radius: float

      .. rubric:: Notes

      Plotting a sphere in a two-dimensional figure in plotly requires a shape
      instead of a trace. Shapes do not accept a label, as the legend does not
      support labels for shapes.

      :returns: A dictionary representing the shape of the sphere.
      :rtype: dict



   .. py:method:: draw_coordinates(coordinates, *, colors, dashed, label)

      Draw desired coordinates into the scene.

      :param position: A set of lists containing the x and y coordinates of the sphere location.
      :type position: list[list[float, float, float]]
      :param colors: A list of string representing the hexadecimal color for the coordinates.
      :type colors: list[str]
      :param dashed: Whether to use a dashed or solid line style for the coordiantes.
      :type dashed: bool
      :param label: The name shown in the legend for identifying the coordinates.
      :type label: str

      :returns: **trace_coordinates** -- An object representing the trace of the coordinates in the scene.
      :rtype: object



   .. py:method:: draw_axes_labels_with_length_scale_units(length_scale_units)

      Draw the desired label into the specified axis.

      :param lenght_scale_units: Desired units of lenght used for representing distances.
      :type lenght_scale_units: ~astropy.units.Unit



   .. py:property:: figure

      The plotly figure use to render the scene.

      :returns: The plotly ``Figure`` representing the scene.
      :rtype: ~plotly.graph_objects.Figure


   .. py:property:: layout

      The plotly layout of the figure.

      :returns: The plotly ``Layout`` object linked to the figure.
      :rtype: ~plotly.graph_objects.Layout


   .. py:method:: update_layout(layout)

      Update the layout of the figure scene.

      :param layout: The new plotly ``Layout`` to be used in the figure.
      :type layout: ~plotly.graph_objects.Layout



   .. py:method:: undraw_attractor()

      Removes the attractor from the scene.



   .. py:method:: draw_position(position, *, color, label, size)

      Draw the position of a body in the scene.

      :param position: A list containing the x, y and z coordinates of the point.
      :type position: list[float, float, float]
      :param color: A string representing the hexadecimal color for the marker.
      :type color: str
      :param label: The name shown in the figure legend to identify the position.
      :type label: str
      :param size: The size of the marker.
      :type size: float

      :returns: An object representing the trace of the coordinates in the scene.
      :rtype: [~plotly.graph_objects.Surface, ~plotly.graph_objects.Trace]



   .. py:method:: draw_impulse(position, *, color, label, size)

      Draw an impulse into the scene.

      :param position: A list containing the x and y coordinates of the impulse location.
      :type position: list[float, float]
      :param color: A string representing the hexadecimal color for the impulse marker.
      :type color: str
      :param label: The name shown in the figure legend to identify the impulse.
      :type label: str
      :param size: The size of the marker for the impulse.
      :type size: float

      :returns: An object representing the trace of the impulse in the scene.
      :rtype: object



   .. py:method:: update_legend()

      Update the legend of the scene.



   .. py:method:: resize_limits()

      Resize the limits of the scene.



   .. py:method:: show()

      Display the scene.



   .. py:method:: generate_labels(label, has_coordinates, has_position)

      Generate the labels for coordinates and position.

      :param label: A string representing the label.
      :type label: str
      :param has_coordinates: Whether the object has coordinates to plot or not.
      :type has_coordinates: boolean
      :param has_position: Whether the object has a position to plot or not.
      :type has_position: boolean

      :returns: A tuple containing the coordinates and position labels.
      :rtype: tuple



   .. py:property:: scene

      Return the scene object.


   .. py:property:: name

      Return the name of the backend.

      :returns: Name of the backend.
      :rtype: str


   .. py:property:: is_2D

      Assert if backend is 2D.

      :returns: ``True`` if it is a 2D backend, ``False`` if it is not.
      :rtype: bool


   .. py:property:: is_3D

      Assert if backend is 3D.

      :returns: ``True`` if it is a 3D backend, ``False`` if it is not.
      :rtype: bool


.. py:class:: Plotly3D(figure=None, use_dark_theme=False, width=None, height=None)

   Bases: :py:obj:`BasePlotly`


   An orbit plotter backend class based on Plotly.


   .. py:method:: draw_marker(position, *, color, marker_symbol, label, size)

      Draw a marker into the scene.

      :param position: A list containing the x and y coordinates of the point.
      :type position: list[float, float]
      :param color: A string representing the hexadecimal color for the point.
      :type color: str
      :param marker_symbol: The marker symbol to be used when drawing the point.
      :type marker_symbol: str
      :param label: The name shown in the legend of the figure to identify the marker.
      :type label: str
      :param size: Desired size for the marker.
      :type size: float

      :returns: An object representing the trace of the marker in the scene.
      :rtype: object



   .. py:method:: draw_sphere(position, *, color, label, radius)

      Draw an sphere into the scene.

      :param position: A list containing the x and y coordinates of the sphere location.
      :type position: list[float, float]
      :param color: A string representing the hexadecimal color for the sphere.
      :type color: str
      :param label: The name shown in the legend of the figure to identify the sphere.
      :type label: str
      :param radius: The radius of the sphere.
      :type radius: float

      :returns: An object representing the trace of the sphere in the scene.
      :rtype: object



   .. py:method:: draw_coordinates(coordinates, *, colors, dashed, label)

      Draw desired coordinates into the scene.

      :param position: A set of lists containing the x and y coordinates of the sphere location.
      :type position: list[list[float, float, float]]
      :param colors: A list of string representing the hexadecimal color for the coordinates.
      :type colors: list[str]
      :param dashed: Whether to use a dashed or solid line style for the coordiantes.
      :type dashed: bool
      :param label: The name shown in the legend of the figure to identify the coordinates.
      :type label: str

      :returns: **trace_coordinates** -- An object representing the trace of the coordinates in the scene.
      :rtype: object



   .. py:method:: draw_axes_labels_with_length_scale_units(length_scale_units)

      Draw the desired label into the specified axis.

      :param lenght_scale_units: Desired units of lenght used for representing distances.
      :type lenght_scale_units: ~astropy.units.Unit



   .. py:method:: set_view(elevation_angle, azimuth_angle, distance)

      Change 3D view.

      :param elevation_angle: Desired elevation angle in radians.
      :type elevation_angle: float
      :param azimuth_angle: Desired azimuth angle in radians.
      :type azimuth_angle: float
      :param distance: Desired distance of the camera.
      :type distance: float



   .. py:property:: figure

      The plotly figure use to render the scene.

      :returns: The plotly ``Figure`` representing the scene.
      :rtype: ~plotly.graph_objects.Figure


   .. py:property:: layout

      The plotly layout of the figure.

      :returns: The plotly ``Layout`` object linked to the figure.
      :rtype: ~plotly.graph_objects.Layout


   .. py:method:: update_layout(layout)

      Update the layout of the figure scene.

      :param layout: The new plotly ``Layout`` to be used in the figure.
      :type layout: ~plotly.graph_objects.Layout



   .. py:method:: undraw_attractor()

      Removes the attractor from the scene.



   .. py:method:: draw_position(position, *, color, label, size)

      Draw the position of a body in the scene.

      :param position: A list containing the x, y and z coordinates of the point.
      :type position: list[float, float, float]
      :param color: A string representing the hexadecimal color for the marker.
      :type color: str
      :param label: The name shown in the figure legend to identify the position.
      :type label: str
      :param size: The size of the marker.
      :type size: float

      :returns: An object representing the trace of the coordinates in the scene.
      :rtype: [~plotly.graph_objects.Surface, ~plotly.graph_objects.Trace]



   .. py:method:: draw_impulse(position, *, color, label, size)

      Draw an impulse into the scene.

      :param position: A list containing the x and y coordinates of the impulse location.
      :type position: list[float, float]
      :param color: A string representing the hexadecimal color for the impulse marker.
      :type color: str
      :param label: The name shown in the figure legend to identify the impulse.
      :type label: str
      :param size: The size of the marker for the impulse.
      :type size: float

      :returns: An object representing the trace of the impulse in the scene.
      :rtype: object



   .. py:method:: update_legend()

      Update the legend of the scene.



   .. py:method:: resize_limits()

      Resize the limits of the scene.



   .. py:method:: show()

      Display the scene.



   .. py:method:: generate_labels(label, has_coordinates, has_position)

      Generate the labels for coordinates and position.

      :param label: A string representing the label.
      :type label: str
      :param has_coordinates: Whether the object has coordinates to plot or not.
      :type has_coordinates: boolean
      :param has_position: Whether the object has a position to plot or not.
      :type has_position: boolean

      :returns: A tuple containing the coordinates and position labels.
      :rtype: tuple



   .. py:property:: scene

      Return the scene object.


   .. py:property:: name

      Return the name of the backend.

      :returns: Name of the backend.
      :rtype: str


   .. py:property:: is_2D

      Assert if backend is 2D.

      :returns: ``True`` if it is a 2D backend, ``False`` if it is not.
      :rtype: bool


   .. py:property:: is_3D

      Assert if backend is 3D.

      :returns: ``True`` if it is a 3D backend, ``False`` if it is not.
      :rtype: bool