visu_pyvista

visualize_with_pyvista(cochain, fig=None, scaling_factor=1, data_range=None, display=True, layout_parameters={})

Generates a pyvista Plotter to visualize a Cochain.

Parameters:

Name	Type	Description	Default
cochain	Cochain	The cochain to visualize.	required
fig	Optional[Plotter]	Optional (default is None). An existing pv.Plotter to which the Cochain is added.	None
scaling_factor	float	Optional (default is 1). A multiplier to apply to all values of the Cochain prior to its visualization. Mostly useful for vector-valued cochains.	1
data_range	Optional[Tuple]	Optional, default is None. A Tuple (val_min, val_max) to clip the data we want to visualize.	None
display	bool	Optional (default is False). If True, the pv.Plotter object containing the data is displayed.	True
layout_parameters	dict	Optional (default is {}). Contains values for rendering parameters, c.f. See Also section. * keys: parameter names, should be in: ['background_color','window_size', 'title'] * values: parameters values.	{}

Returns:

Type	Description
`pv.Plotter` containing the desired `Cochain`.

Notes

• The argument display is used if one wants to add multiple objects to the same visualization. In this case the display argument should be set to False for all calls except the last one.
• In the current version vector-valued dual cochains are represented on the primal complex with vectors at the circumcenters of top-simplices. Maybe it could be interesting to enable the visualization on the dual cell complex?
• When a vector-valued Cochain is provided, the surface is colored as well, but apparently, this color corresponds to the first component of the vector field, v_x. TODO:This should be changed

See Also

• _set_layout() function in the same module for details on the layout parameters.

Source code in src/dxtr/visu/visu_pyvista.py

@require_pyvista
@typecheck(Cochain)
def visualize_with_pyvista(cochain:Cochain, fig:Optional[pv.Plotter]=None,
                           scaling_factor:float=1, 
                           data_range: Optional[Tuple]=None, display:bool=True, 
                           layout_parameters:dict={}) -> Optional[pv.Plotter]:
    """Generates a pyvista Plotter to visualize a `Cochain`.

    Parameters
    ----------
    cochain
        The cochain to visualize.
    fig
        Optional (default is None). An existing `pv.Plotter` to which
        the `Cochain` is added.
    scaling_factor
        Optional (default is 1). A multiplier to apply to all values of the 
        `Cochain` prior to its visualization. Mostly useful for vector-valued
        cochains.
    data_range
        Optional, default is None. A Tuple (val_min, val_max) to clip the 
        data we want to visualize.
    display
        Optional (default is False). If True, the `pv.Plotter` object 
        containing the data is displayed.
    layout_parameters
        Optional (default is {}). Contains values for rendering parameters, 
        c.f. See Also section.
        * keys: parameter names, should be in:
          ['background_color','window_size', 'title']
        * values: parameters values.

    Returns
    -------
        `pv.Plotter` containing the desired `Cochain`.

    Notes
    -----
      * The argument `display` is used if one wants to add multiple objects to 
        the same visualization. In this case the `display` argument should be 
        set to `False` for all calls except the last one.
      * In the current version vector-valued dual cochains are represented on 
        the primal complex with vectors at the circumcenters of top-simplices.
        Maybe it could be interesting to enable the visualization on the dual 
        cell complex?
      * When a vector-valued `Cochain` is provided, the surface is colored as 
        well, but apparently, this color corresponds to the first component of 
        the vector field, v_x. TODO:This should be changed

    See Also
    --------
      * `_set_layout()` function in the same module for details on the
         layout parameters.
    """

    if (data_range is not None) & (not cochain.isvectorvalued):
        clipped_values = np.clip(cochain.values, data_range[0], data_range[-1])
        cochain = Cochain(cochain.complex, cochain.dim, clipped_values,
                          dual=cochain.isdual)

    data = '_'.join(cochain.name.split(' '))
    # data = cochain.name

    if fig is None: fig = pv.Plotter(border=False)

    if not _isvalid_for_visualization(cochain, fig): return None

    mesh = UGrid.generate_from(cochain, scaling_factor=scaling_factor, 
                               for_visualization=True)

    if (cochain.dim == 1) & (not cochain.isvectorvalued):
        fig.add_mesh(mesh, style='surface', color='w')

        # body = pv.Cylinder(resolution=100, height=.1, radius=.005)
        head = pv.Cone(resolution=100, center=(0,0,0), height=.05, radius=.02)

        # arrow_bodies = mesh.glyph(scale=data, orient=data, geom=body)
        arrow_heads = mesh.glyph(scale=data, orient=data, geom=head)

        # fig.add_mesh(arrow_bodies, show_scalar_bar=False)
        fig.add_mesh(arrow_heads, show_scalar_bar=False)

    elif cochain.isvectorvalued:
        fig.add_mesh(mesh, style='surface', color='w')
        arrows = mesh.glyph(scale=data, orient=data)
        fig.add_mesh(arrows, show_scalar_bar=False,
                     cmap=layout_parameters.get('colormap', 'viridis'))

    else:
        cplx_name = cochain.complex.name
        fig.add_mesh(mesh, show_scalar_bar=False, 
                    cmap=layout_parameters.get('colormap', 'viridis'))

        if layout_parameters.get('show_colorbar', False):
            fig.add_scalar_bar(f'{data[:1]} on {cplx_name[:1]}',
                               title_font_size=1, fmt='%.1f',)

    fig = _set_layout(fig, layout_parameters)

    if display: fig.show()

    return fig