uvisbox.Modules.CurveBoxplot.curve_boxplot
==========================================

.. py:module:: uvisbox.Modules.CurveBoxplot.curve_boxplot




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

.. py:function:: curve_boxplot(curves, boxplot_style=None, ax=None, workers=12)

   Create a curve band depth plot with multiple percentile bands.

   This function follows a 3-stage pipeline: statistics → mesh → visualization.
   It computes curve band depths, generates triangular meshes for percentile bands,
   and creates a visualization with median and outlier curves.

   For 2D curves, uses matplotlib. For 3D curves, uses PyVista if available,
   otherwise falls back to matplotlib.

   :param curves: 3D array of shape (n_curves, n_steps, n_dims) containing curve data.
                  Input data is not modified (computation happens on a copy).
   :type curves: numpy.ndarray
   :param boxplot_style: Configuration for the boxplot visualization including percentiles, colors,
                         and median/outlier styling. If None, uses default configuration.
   :type boxplot_style: BoxplotStyleConfig, optional
   :param ax: Axes or plotter to plot on. Can be either:
              - matplotlib.axes.Axes for 2D or 3D matplotlib rendering
              - pyvista.Plotter for 3D PyVista rendering
              If None, creates appropriate visualization object automatically.
   :type ax: matplotlib.axes.Axes or pyvista.Plotter, optional
   :param workers: Number of worker processes for parallel computation of band depths. Default is 12.
                   Set to 1 or None to use sequential processing (useful for debugging).
   :type workers: int, optional

   :returns: **ax** -- The visualization object (matplotlib axes for 2D, PyVista plotter for 3D if available).
   :rtype: matplotlib.axes.Axes or pyvista.Plotter

   .. rubric:: Notes

   - The function does not modify the input curves array
   - Bands are plotted from largest to smallest percentile for proper layering
   - The median curve is the curve with the highest depth value
   - Outliers are curves beyond the largest percentile
   - Curve depths are always computed internally
   - For 3D curves, PyVista provides better interactivity than matplotlib

   .. rubric:: Examples

   >>> # Basic usage with defaults
   >>> ax = curve_boxplot(curves)

   >>> # Custom styling
   >>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
   >>> style = BoxplotStyleConfig(
   ...     percentiles=[10, 50, 90],
   ...     percentile_colors=['lightblue', 'blue', 'darkblue'],
   ...     show_median=True,
   ...     median_color='red',
   ...     show_outliers=True
   ... )
   >>> ax = curve_boxplot(curves, boxplot_style=style)

   >>> # 3D curves with PyVista
   >>> import pyvista as pv
   >>> plotter = pv.Plotter()
   >>> curve_boxplot(curves_3d, ax=plotter)
   >>> plotter.show()

   >>> # Hide median and outliers
   >>> style = BoxplotStyleConfig(show_median=False, show_outliers=False)
   >>> ax = curve_boxplot(curves, boxplot_style=style)