pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/visualsimplotter.py

@@ -0,0 +1,180 @@
+#===============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+#===============================================================================
+# import vtk #NOTE: has to be here to fix latex bug in pyvista/vtk
+# See: https://github.com/pyvista/pyvista/discussions/2928
+#NOTE: causes output to console to be suppressed unfortunately
+import pyvista as pv
+
+import pyvale.mooseherder as mh
+
+from pyvale.sensorsim.sensorspoint import SensorsPoint
+from pyvale.sensorsim.fieldconverter import simdata_to_pyvista
+from pyvale.sensorsim.visualopts import (VisOptsSimSensors,VisOptsImageSave)
+from pyvale.sensorsim.visualtools import (create_pv_plotter,
+                                     get_colour_lims,
+                                     save_image)
+
+
+#TODO: Docstrings
+
+def add_sim_field(pv_plot: pv.Plotter,
+                  sensor_array: SensorsPoint,
+                  component: str,
+                  time_step: int,
+                  vis_opts: VisOptsSimSensors,
+                  ) -> tuple[pv.Plotter,pv.UnstructuredGrid]:
+
+    sim_vis = sensor_array.field.get_visualiser()
+    sim_data = sensor_array.field.get_sim_data()
+    sim_vis[component] = sim_data.node_vars[component][:,time_step]
+    comp_ind = sensor_array.field.get_component_index(component)
+
+    scalar_bar_args = {"title":sensor_array.descriptor.create_label(comp_ind),
+                        "vertical":vis_opts.colour_bar_vertical,
+                        "title_font_size":vis_opts.colour_bar_font_size,
+                        "label_font_size":vis_opts.colour_bar_font_size}
+
+    pv_plot.add_mesh(sim_vis,
+                     scalars=component,
+                     label="sim-data",
+                     show_edges=vis_opts.show_edges,
+                     show_scalar_bar=vis_opts.colour_bar_show,
+                     scalar_bar_args=scalar_bar_args,
+                     lighting=False,
+                     clim=vis_opts.colour_bar_lims)
+
+    if vis_opts.time_label_show:
+        pv_plot.add_text(f"Time: {sim_data.time[time_step]} " + \
+                            f"{sensor_array.descriptor.time_units}",
+                            position=vis_opts.time_label_position,
+                            font_size=vis_opts.time_label_font_size,
+                            name='time-label')
+
+    return (pv_plot,sim_vis)
+
+
+def add_sensor_points_nom(pv_plot: pv.Plotter,
+                          sensor_array: SensorsPoint,
+                          vis_opts: VisOptsSimSensors,
+                          ) -> pv.Plotter:
+
+    vis_sens_nominal = pv.PolyData(sensor_array.sensor_data.positions)
+    vis_sens_nominal["labels"] = sensor_array.descriptor.create_sensor_tags(
+    sensor_array.get_measurement_shape()[0])
+
+    # Add points to show sensor locations
+    pv_plot.add_point_labels(vis_sens_nominal,"labels",
+                            font_size=vis_opts.sens_label_font_size,
+                            shape_color=vis_opts.sens_label_colour,
+                            point_color=vis_opts.sens_colour_nom,
+                            render_points_as_spheres=True,
+                            point_size=vis_opts.sens_point_size,
+                            always_visible=True)
+
+    return pv_plot
+
+
+def add_sensor_points_pert(pv_plot: pv.Plotter,
+                           sensor_array: SensorsPoint,
+                           vis_opts: VisOptsSimSensors,
+                           ) -> pv.Plotter:
+
+    sens_data_perturbed = sensor_array.get_sensor_data_perturbed()
+
+    if sens_data_perturbed is not None and vis_opts.show_perturbed_pos:
+        vis_sens_perturbed = pv.PolyData(sens_data_perturbed.positions)
+        vis_sens_perturbed["labels"] = ["",]*sensor_array.get_measurement_shape()[0]
+
+        pv_plot.add_point_labels(vis_sens_perturbed,"labels",
+                                font_size=vis_opts.sens_label_font_size,
+                                shape_color=vis_opts.sens_label_colour,
+                                point_color=vis_opts.sens_colour_pert,
+                                render_points_as_spheres=True,
+                                point_size=vis_opts.sens_point_size,
+                                always_visible=True)
+
+    return pv_plot
+
+
+def plot_sim_mesh(sim_data: mh.SimData,
+                  vis_opts: VisOptsSimSensors | None = None,
+                  ) -> pv.Plotter:
+
+    if vis_opts is None:
+        vis_opts = VisOptsSimSensors()
+
+    pv_simdata = simdata_to_pyvista(sim_data,
+                                         None,
+                                         sim_data.num_spat_dims)
+
+    pv_plot = create_pv_plotter(vis_opts)
+
+    pv_plot.add_mesh(pv_simdata,
+                     label='sim-data',
+                     show_edges=True,
+                     show_scalar_bar=False)
+
+    return pv_plot
+
+
+def plot_sim_data(sim_data: mh.SimData,
+                  component: str,
+                  time_step: int = -1,
+                  vis_opts: VisOptsSimSensors | None = None
+                  ) -> pv.Plotter:
+
+    if vis_opts is None:
+        vis_opts = VisOptsSimSensors()
+
+    pv_simdata = simdata_to_pyvista(sim_data,
+                                        (component,),
+                                         sim_data.num_spat_dims)
+
+    pv_plot = create_pv_plotter(vis_opts)
+
+    pv_plot.add_mesh(pv_simdata,
+                     scalars=pv_simdata[component][:,time_step],
+                     label="sim-data",
+                     show_edges=True,
+                     show_scalar_bar=True,
+                     scalar_bar_args={"title":component},)
+
+
+    return pv_plot
+
+
+def plot_point_sensors_on_sim(sensor_array: SensorsPoint,
+                              component: str,
+                              time_step: int = -1,
+                              vis_opts: VisOptsSimSensors | None = None,
+                              image_save_opts: VisOptsImageSave | None = None,
+                              ) -> pv.Plotter:
+
+    if vis_opts is None:
+        vis_opts = VisOptsSimSensors()
+
+    sim_data = sensor_array.field.get_sim_data()
+    vis_opts.colour_bar_lims = get_colour_lims(
+        sim_data.node_vars[component][:,time_step],
+        vis_opts.colour_bar_lims)
+
+    pv_plot = create_pv_plotter(vis_opts)
+
+    pv_plot = add_sensor_points_pert(pv_plot,sensor_array,vis_opts)
+    pv_plot = add_sensor_points_nom(pv_plot,sensor_array,vis_opts)
+    (pv_plot,_) = add_sim_field(pv_plot,
+                                sensor_array,
+                                component,
+                                time_step,
+                                vis_opts)
+
+    pv_plot.camera_position = vis_opts.camera_position
+
+    if image_save_opts is not None:
+        save_image(pv_plot,image_save_opts)
+
+    return pv_plot
+

pyvale/sensorsim/visualsimsensors.py

@@ -0,0 +1,343 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+This module contains functions for visualising virtual sensors on a simulation
+mesh with simulated fields using pyvista.
+"""
+import numpy as np
+import vtk #NOTE: has to be here to fix latex bug in pyvista/vtk
+# See: https://github.com/pyvista/pyvista/discussions/2928
+#NOTE: causes output to console to be suppressed unfortunately
+#NOTE: May 2025, the console suppression output is fixed but the vtk import is
+#still required to make latex work.
+import pyvista as pv
+
+import pyvale.mooseherder as mh
+
+from pyvale.sensorsim.sensorspoint import SensorsPoint
+from pyvale.sensorsim.fieldconverter import (simdata_to_pyvista_vis,
+                                   simdata_to_pyvista_interp)
+from pyvale.sensorsim.sensordescriptor import SensorDescriptor
+from pyvale.sensorsim.visualopts import (VisOptsSimSensors,VisOptsImageSave)
+from pyvale.sensorsim.visualtools import (create_pv_plotter,
+                                     get_colour_lims,
+                                     save_pv_image)
+
+
+# TODO: this needs to be updated to allow the user to plot at sensor times not
+# just simulation times. This will require interpolation of the underlying
+# simulation fields.
+def add_sim_field(pv_plot: pv.Plotter,
+                  sensor_array: SensorsPoint,
+                  component: str,
+                  time_step: int,
+                  vis_opts: VisOptsSimSensors,
+                  ) -> tuple[pv.Plotter,pv.UnstructuredGrid]:
+    """Adds a simulation field to a pyvista plot object which is visualised on
+    the mesh using a colormap.
+
+    Parameters
+    ----------
+    pv_plot : pv.Plotter
+        Handle to the pyvista plot object to add the simulation field to.
+    sensor_array : SensorArrayPoint
+        Sensor array associated with the field to be plotted.
+    component : str
+        String key for the field component to be shown.
+    time_step : int
+        Time step to plot based on the time steps in the underlying simulation
+        data object.
+    vis_opts : VisOptsSimSensors
+        Dataclass containing options for controlling the appearance of the
+        virtual sensors.
+
+    Returns
+    -------
+    tuple[pv.Plotter,pv.UnstructuredGrid]
+        Tuple containing a handle to the pyvista plotter which has had the field
+        visualisation added and the pyvistas unstructured grid that was used to
+        plot the field.
+    """
+    sim_vis = sensor_array._field.get_visualiser()
+    sim_data = sensor_array._field.get_sim_data()
+    sim_vis[component] = sim_data.node_vars[component][:,time_step]
+    comp_ind = sensor_array._field.get_component_index(component)
+
+    scalar_bar_args = {"title":sensor_array._descriptor.create_label(comp_ind),
+                        "vertical":vis_opts.colour_bar_vertical,
+                        "title_font_size":vis_opts.colour_bar_font_size,
+                        "label_font_size":vis_opts.colour_bar_font_size}
+
+    pv_plot.add_mesh(sim_vis,
+                     scalars=component,
+                     label="sim-data",
+                     show_edges=vis_opts.show_edges,
+                     show_scalar_bar=vis_opts.colour_bar_show,
+                     scalar_bar_args=scalar_bar_args,
+                     lighting=False,
+                     clim=vis_opts.colour_bar_lims)
+
+    if vis_opts.time_label_pos is not None:
+        pv_plot.add_text(f"Time: {sim_data.time[time_step]} " + \
+                            f"{sensor_array._descriptor.time_units}",
+                            position=vis_opts.time_label_pos,
+                            font_size=vis_opts.time_label_font_size,
+                            name='time-label')
+
+    return (pv_plot,sim_vis)
+
+
+# TODO: this should be able to take a list of ISensorArray and plot all of them
+# on the same mesh.
+def add_sensor_points_nom(pv_plot: pv.Plotter,
+                          sensor_positions: np.ndarray,
+                          descriptor: SensorDescriptor,
+                          vis_opts: VisOptsSimSensors,
+                          ) -> pv.Plotter:
+    """Adds points and tagged labels showing the virtual sensor locations on
+    the simulation mesh in the given pyvista plot object.
+
+    Parameters
+    ----------
+    pv_plot : pv.Plotter
+        Pyvista plotter used to display the virtual sensor locations.
+    sensor_positions : np.ndarray
+        Array of sensor positions with shape=(num_sensors,coord[X,Y,Z]).
+    vis_opts : VisOptsSimSensors
+        Dataclass containing options for controlling the appearance of the
+        virtual sensors.
+
+    Returns
+    -------
+    pv.Plotter
+        Pyvista plotter which has had the virtual sensor locations added.
+    """
+    num_sensors = sensor_positions.shape[0]
+    vis_sens_nominal = pv.PolyData(sensor_positions)
+    vis_sens_nominal["labels"] = descriptor.create_sensor_tags(num_sensors)
+
+    # Add points to show sensor locations
+    pv_plot.add_point_labels(vis_sens_nominal,"labels",
+                            font_size=vis_opts.sens_label_font_size,
+                            shape_color=vis_opts.sens_label_colour,
+                            point_color=vis_opts.sens_colour_nom,
+                            render_points_as_spheres=True,
+                            point_size=vis_opts.sens_point_size,
+                            always_visible=True)
+
+    return pv_plot
+
+
+def add_sensor_points_pert(pv_plot: pv.Plotter,
+                           sensor_positions: np.ndarray,
+                           vis_opts: VisOptsSimSensors,
+                           ) -> pv.Plotter:
+    """Adds points showing the perturbed virtual sensor locations on
+    the simulation mesh in the given pyvista plot object. Note that this will
+    only work if field errors are added perturbing the sensor locations.
+
+    Parameters
+    ----------
+    pv_plot : pv.Plotter
+        Pyvista plotter used to display the virtual sensor locations.
+    sensor_positions : np.ndarray | None
+        Array of sensor positions with shape=(num_sensors,coord[X,Y,Z]).
+    vis_opts : VisOptsSimSensors
+        Dataclass containing options for controlling the appearance of the
+        virtual sensors.
+
+    Returns
+    -------
+    pv.Plotter
+        Pyvista plotter which has had the virtual sensor locations added.
+    """
+        
+    if vis_opts.show_perturbed_pos:
+        vis_sens_perturbed = pv.PolyData(sensor_positions)
+        vis_sens_perturbed["labels"] = ["",]*sensor_positions.shape[0]
+
+        pv_plot.add_point_labels(vis_sens_perturbed,"labels",
+                                font_size=vis_opts.sens_label_font_size,
+                                shape_color=vis_opts.sens_label_colour,
+                                point_color=vis_opts.sens_colour_pert,
+                                render_points_as_spheres=True,
+                                point_size=vis_opts.sens_point_size,
+                                always_visible=True)
+
+    return pv_plot
+
+
+def plot_sim_mesh(sim_data: mh.SimData,
+                  elem_dims: int,
+                  vis_opts: VisOptsSimSensors | None = None,
+                  ) -> pv.Plotter:
+    """Plots the simulation mesh without any fields. Useful for visualising
+    mesh geometry.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        Sim data object containing the mesh to plot.
+    elem_dims : int
+        Number of dimensions for the elements to be plotted.
+    vis_opts : VisOptsSimSensors | None, optional
+        Dataclass containing options for controlling the appearance of the
+        virtual sensors, by default None. If None then a default options
+        dataclass is created.
+
+    Returns
+    -------
+    pv.Plotter
+        Handle to the pyvista plotter that is showing the mesh.
+    """
+    if vis_opts is None:
+        vis_opts = VisOptsSimSensors()
+
+    (_,sim_vis) = simdata_to_pyvista_vis(sim_data=sim_data,
+                                         elem_dims=elem_dims)
+
+    pv_plot = create_pv_plotter(vis_opts)
+    pv_plot.add_mesh(sim_vis,
+                     label="sim-data",
+                     show_edges=vis_opts.show_edges,
+                     lighting=False)
+    return pv_plot
+
+
+def plot_sim_data(sim_data: mh.SimData,
+                  component: str,
+                  elem_dims: int,
+                  time_step: int = -1,
+                  vis_opts: VisOptsSimSensors | None = None
+                  ) -> pv.Plotter:
+    """Plots the simulation mesh showing the specified phyiscal field at the
+    time step specified.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        simulation data object containing the mesh and field data to show.
+    component : str
+        String key for accessing the nodal field to visualise in the sim data
+        object.
+    elem_dims : int
+        Number of dimensions for the elements to be plotted.
+    time_step : int, optional
+        Simulation time step number to plot, by default -1 (the last time step).
+    vis_opts : VisOptsSimSensors | None, optional
+        Dataclass containing options for controlling the appearance of the
+        virtual sensors, by default None. If None then a default options
+        dataclass is created.
+
+    Returns
+    -------
+    pv.Plotter
+        Handle to the pyvista plotter showing the simulation mesh and field.
+    """
+    if vis_opts is None:
+        vis_opts = VisOptsSimSensors()
+
+    (_,sim_vis) = simdata_to_pyvista_interp(sim_data,
+                                            (component,),
+                                            elem_dims)
+
+    sim_vis[component] = sim_data.node_vars[component][:,time_step]
+
+    pv_plot = create_pv_plotter(vis_opts)
+    pv_plot.add_mesh(sim_vis,
+                     scalars=component,
+                     label="sim-data",
+                     show_edges=vis_opts.show_edges,
+                     show_scalar_bar=vis_opts.colour_bar_show,
+                     lighting=False,
+                     clim=vis_opts.colour_bar_lims)
+
+    return pv_plot
+
+
+def plot_point_sensors_on_sim(sensor_array: SensorsPoint,
+                              comp_key: str,
+                              time_step: int = -1,
+                              perturbed_sens_pos: np.ndarray | None = None,
+                              vis_opts: VisOptsSimSensors | None = None,
+                              image_save_opts: VisOptsImageSave | None = None,
+                              ) -> pv.Plotter:
+    """Creates a visualisation of the virtual sensor locations on the simulation
+    mesh showing the underlying field the sensors are sampling at the specified
+    time step.
+
+    Parameters
+    ----------
+    sensor_array : SensorArrayPoint
+        Sensor array containing the sensors to plot and the field to display.
+    comp_key : str
+        String key for accessing the nodal field to visualise in the sim data
+        object.
+    time_step : int, optional
+        Simulation time step number to plot, by default -1 (the last time step).
+    perturbed_sens_pos: np.ndarray, optional
+        Array of perturbed sensor position to plot with shape=(num_sensors,coord
+        [X,Y,Z]), by default None. If None then perturbed sensor positions are
+        taken from the sensor array itself, if available. 
+    vis_opts : VisOptsSimSensors | None, optional
+        Dataclass containing options for controlling the appearance of the
+        virtual sensors, by default None. If None then a default options
+        dataclass is created.
+    image_save_opts : VisOptsImageSave | None, optional
+        Dataclass containing options for saving image of the virtual sensor
+        visualisation, by default None. If None an image is not saved.
+
+    Returns
+    -------
+    pv.Plotter
+        Handle to the pyvista plotter showing the sensor locations.
+    """
+    if vis_opts is None:
+        vis_opts = VisOptsSimSensors()
+
+    sim_data = sensor_array.get_field().get_sim_data()
+    vis_opts.colour_bar_lims = get_colour_lims(
+        sim_data.node_vars[comp_key][:,time_step],
+        vis_opts.colour_bar_lims)
+
+    pv_plot = create_pv_plotter(vis_opts)
+
+    if perturbed_sens_pos is not None:
+        sensor_pos_pert = perturbed_sens_pos
+    else:
+        # Can be None if there no field errors perturbing the sensor position
+        sensor_pos_pert = (
+            sensor_array
+            .get_error_integrator()
+            .get_sens_data_accumulated()
+            .positions
+        )
+
+    if sensor_pos_pert is not None:
+        pv_plot = add_sensor_points_pert(pv_plot,sensor_pos_pert,vis_opts)
+
+    
+    sensor_pos_nom = sensor_array._sensor_data.positions   
+    descriptor = sensor_array.get_descriptor()
+    pv_plot = add_sensor_points_nom(pv_plot,
+                                    sensor_pos_nom,
+                                    descriptor,
+                                    vis_opts)
+
+    (pv_plot,_) = add_sim_field(pv_plot,
+                                sensor_array,
+                                comp_key,
+                                time_step,
+                                vis_opts)
+
+    pv_plot.camera_position = vis_opts.camera_position
+
+    if image_save_opts is not None:
+        save_pv_image(pv_plot,image_save_opts)
+
+    return pv_plot
+

pyvale/sensorsim/visualtools.py

@@ -0,0 +1,136 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+This module contains utility functions used for creating pyvale visualisations.
+"""
+
+from pathlib import Path
+import numpy as np
+import vtk #NOTE: has to be here to fix latex bug in pyvista/vtk
+# See: https://github.com/pyvista/pyvista/discussions/2928
+# NOTE: causes output to console to be suppressed unfortunately
+# NOTE: May2025 still needs include but does not suppress console output
+import pyvista as pv
+from pyvale.sensorsim.visualopts import (VisOptsSimSensors,
+                                    VisOptsImageSave,
+                                    EImageType,
+                                    VisOptsAnimation,
+                                    EAnimationType)
+
+def create_pv_plotter(vis_opts: VisOptsSimSensors) -> pv.Plotter:
+    """Creates a pyvista plotter based on the input options.
+
+    Parameters
+    ----------
+    vis_opts : VisOptsSimSensors
+        Dataclass containing the visualisation options for creating the plotter.
+
+    Returns
+    -------
+    pv.Plotter
+        Blank pyvista plotter object with the given settings.
+    """
+    pv_plot = pv.Plotter(window_size=vis_opts.window_size_px)
+    pv_plot.set_background(vis_opts.background_colour)
+    pv.global_theme.font.color = vis_opts.font_colour
+    pv_plot.add_axes_at_origin(labels_off=True)
+    return pv_plot
+
+
+def get_colour_lims(component_data: np.ndarray,
+                    colour_bar_lims: tuple[float,float] | None
+                    ) -> tuple[float,float]:
+    """Gets the colourbar limits based on the input component data array.
+
+    Parameters
+    ----------
+    component_data : np.ndarray
+        Array of data for the field component of interest. Can be any shape as
+        the array is flattened for the limit calculations
+    colour_bar_lims : tuple[float,float] | None
+        Forces the colourbar limits to be the values give in the tuple. If None
+        then the colorbar limits are calculated based on the input data array.
+
+    Returns
+    -------
+    tuple[float,float]
+        Colourbar limits in the form: (min,max).
+    """
+    if colour_bar_lims is None:
+        min_comp = np.min(component_data.flatten())
+        max_comp = np.max(component_data.flatten())
+        colour_bar_lims = (min_comp,max_comp)
+
+    assert colour_bar_lims[1] > colour_bar_lims[0], ("Colourbar minimum must be"
+    + " smaller than the colourbar maximum.")
+
+    return colour_bar_lims
+
+
+def save_pv_image(pv_plot: pv.Plotter,
+               image_save_opts: VisOptsImageSave) -> None:
+    """Saves an image of a pyvista visualisation to disk based on the input
+    options.
+
+    Parameters
+    ----------
+    pv_plot : pv.Plotter
+        Pyvista plotter object to save the image from.
+    image_save_opts : VisOptsImageSave
+        Dataclass containing the options to save the image.
+    """
+
+    if image_save_opts.path is None:
+        image_save_opts.path = Path.cwd() / "pyvale-image"
+
+    if image_save_opts.image_type == EImageType.PNG:
+        image_save_opts.path = image_save_opts.path.with_suffix(".png")
+        pv_plot.screenshot(image_save_opts.path,
+                           image_save_opts.transparent_background)
+
+    elif image_save_opts.image_type == EImageType.SVG:
+        image_save_opts.path = image_save_opts.path.with_suffix(".svg")
+        pv_plot.save_graphic(image_save_opts.path)
+
+
+def set_animation_writer(pv_plot: pv.Plotter,
+                         anim_opts: VisOptsAnimation) -> pv.Plotter:
+    """Sets the animation writer and output path for a virtual sensor simulation
+    visualisation.
+
+    Parameters
+    ----------
+    pv_plot : pv.Plotter
+        Pyvistas plot object which will be used to create the animation.
+    anim_opts : VisOptsAnimation
+        Dataclass containing the options for creating the animation.
+
+    Returns
+    -------
+    pv.Plotter
+        Pyvista plotter with the given animation writer opened.
+    """
+    if anim_opts.save_animation is None:
+          return pv_plot
+
+    if anim_opts.save_path is None:
+        anim_opts.save_path = Path.cwd() / "pyvale-animation"
+
+    if anim_opts.save_animation == EAnimationType.GIF:
+        anim_opts.save_path = anim_opts.save_path.with_suffix(".gif")
+        pv_plot.open_gif(anim_opts.save_path,
+                         loop=0,
+                         fps=anim_opts.frames_per_second)
+
+    elif anim_opts.save_animation == EAnimationType.MP4:
+        anim_opts.save_path = anim_opts.save_path.with_suffix(".mp4")
+        pv_plot.open_movie(anim_opts.save_path,
+                           anim_opts.frames_per_second)
+
+    return pv_plot
+
+