gcode_reader.visualize
======================

.. py:module:: gcode_reader.visualize


Functions
---------

.. autoapisummary::

   gcode_reader.visualize.plot_additive_part
   gcode_reader.visualize.plot_event_series
   gcode_reader.visualize.plot_gcode_dataframe
   gcode_reader.visualize.plot_operation


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

.. py:function:: plot_additive_part(part: gcode_reader.emulate.additive_part.AdditivePart, layer_range=None, layer_index=None, **kwargs)

   Generates and displays a 3D plot from a AdditivePart object.

   This function visualizes the depoisition toolpath defined in an AdditivePart for a provided
   range of layers, or a specified layer index.

   :param part: The AdditivePart object to be plotted.
   :type part: AdditivePart
   :param layer_range: A range of layer indices to plot.
   :type layer_range: tuple, optional
   :param layer_index: A specified layer index to plot. Takes precidence over layer_range.
   :type layer_index: int, optional
   :param \*\*kwargs: Additional keyword arguments to pass to `plotly.express.line_3d`.

   :returns: The Plotly Figure object.
   :rtype: plotly.graph_objects.Figure


.. py:function:: plot_event_series(event_series: pandas.DataFrame, color_by='e', colorscale='Viridis', **kwargs)

   Creates a 3D plot of an Event Series colored by a continuous scalar value.

   :param event_series: DataFrame containing the event series data. Must
                        include columns for 'x', 'y', 'z', 'e', 'time'.
   :type event_series: pd.DataFrame
   :param color_by: The name of the column used to color the line.
                    Defaults to "e".
   :type color_by: str, optional
   :param colorscale: The name of the Plotly colorscale to use for
                      the gradient. Defaults to "Viridis".
   :type colorscale: str, optional
   :param show: If True, the plot is displayed immediately. Else return the figure.
                Defaults to True.
   :type show: bool, optional
   :param \*\*kwargs: Additional keyword arguments to pass to `fig.update_layout`.

   :returns: The Plotly Figure object.
   :rtype: plotly.graph_objects.Figure


.. py:function:: plot_gcode_dataframe(df, x='x', y='y', z='z', tag=None, **kwargs)

   Generates and displays a 3D plot of a G-code toolpath from a DataFrame.

   :param df: DataFrame containing processed G-code. It is expected
              to have columns for coordinates and an optional 'tags' column.
   :type df: pd.DataFrame
   :param x: The name of the column containing the X-axis data. Defaults to "x".
   :type x: str, optional
   :param y: The name of the column containing the Y-axis data. Defaults to "y".
   :type y: str, optional
   :param z: The name of the column containing the Z-axis data. Defaults to "z".
   :type z: str, optional
   :param tag: A tag to filter the DataFrame. If provided, only rows
               where this tag is present in the 'tags' column will be plotted.
               Defaults to None.
   :type tag: str, optional
   :param \*\*kwargs: Additional keyword arguments to pass to `plotly.express.line_3d`.

   :returns: The Plotly Figure object.
   :rtype: plotly.graph_objects.Figure


.. py:function:: plot_operation(operation: gcode_reader.emulate.operations.Operation, command_type: type = None, **kwargs)

   "Generates and displays a 3D plot from a processed Operation object.

   This function visualizes the toolpath defined by an Operation. It can either
   plot the entire path as a single continuous line or plot only the segments
   that correspond to a specific command type (e.g., `Move`) as
   separate polylines.

   :param operation: The processed Operation object to be plotted.
   :type operation: Operation
   :param command_type: A command class used to filter the plot.
                        If provided, only toolpath segments generated by this command type
                        (or its subclasses) will be shown. Defaults to None.
   :type command_type: type, optional
   :param \*\*kwargs: Additional keyword arguments to pass to `plotly.express.line_3d`.

   :returns: The Plotly Figure object.
   :rtype: plotly.graph_objects.Figure

   :raises ValueError: If the operation has not been processed or if the number of
       commands does not match the number of process data points.