Postprocess with PVBridge
=========================

Purpose
-------

``PVBridge`` is the bridge between pyFEBiOpt's FEBio-aware data structures and
PyVista. Its goal is postprocessing and figure generation: use it after reading an
``.xplt`` file to build plot-ready meshes, attach simulation fields, and render
figures from FEBio results.

The bridge keeps responsibilities separate:

- ``xplt`` reads FEBio's binary result format and exposes arrays.
- ``PVBridge`` converts mesh regions/surfaces to PyVista datasets.
- PyVista handles plotting, screenshots, filters, clipping, and warping.

Build PyVista datasets
----------------------

.. code-block:: python

   from pyfebiopt.visualization import PVBridge
   from pyfebiopt.xplt import xplt

   xp = xplt("run.xplt")
   xp.readAllStates()

   bridge = PVBridge(xp.mesh)
   grid = bridge.domain_grid("sample")
   surface = bridge.surface_mesh("grip")

``domain_grid(name)``
   Builds a PyVista ``UnstructuredGrid`` for a named FEBio domain.

``surface_mesh(name)``
   Builds a PyVista ``PolyData`` for a named FEBio surface.

Attach results
--------------

Attach a nodal displacement field:

.. code-block:: python

   disp_view = xp.results["displacement"]
   disp = disp_view.time(-1).comp(":")
   bridge.add_node_result_array(grid, view=disp_view, data=disp, name="U")

Attach an element field:

.. code-block:: python

   stress_view = xp.results["stress"].domain("sample")
   sigma_xx = stress_view.time(-1).comp("xx")
   bridge.add_elem_item_array(
       grid,
       view=stress_view,
       domain="sample",
       data=sigma_xx,
       name="sigma_xx",
   )

For FEBio variables stored at element nodes, reduce each element-node block to one
cell value before plotting:

.. code-block:: python

   strain_view = xp.results["strain"].domain("sample")
   strain = strain_view.time(-1).enodes(":").comp("xx")
   bridge.add_elem_mult_reduced_array(
       grid,
       view=strain_view,
       domain="sample",
       data=strain,
       reducer="mean",
       name="mean_strain_xx",
   )

Generate figures
----------------

.. code-block:: python

   grid.plot(scalars="sigma_xx", show_edges=True)

Use PVBridge when the goal is visual postprocessing: checking result locations,
making publication figures, or comparing optimized simulations in a consistent
PyVista plotting workflow.

Read more in the API
--------------------

For full class and method details, see the generated
:doc:`visualization API reference <../api/pyfebiopt/visualization/index>` and
:doc:`PVBridge reference <../api/pyfebiopt/visualization/plotter/index>`.