The geometry module

This module provides classes for handling geometry-related data, specifically designed to store and manipulate sensor and background geometry information.

Classes:

BaseGeometry

Base class for storing and managing sensor and background geometry data.

Geometry1

Class for storing and managing sensor and background geometry data for Geometry 1.

Geometry2

Class for storing and managing sensor and background geometry data for Geometry 2.

ModeGeo1Data

Headless mode-shape geometry data for a Geometry1 setup.

ModeGeo2Data

Headless mode-shape geometry data for a Geometry2 setup.

GeometryMixin

Mixin that gives the ability to define the geometry the instance of the setup class.

Warning

The module is designed to be used as part of the pyOMA2 package and relies on its internal data structures and algorithms.

class pyoma2.support.geometry.data.BaseGeometry(*, sens_names: list[str], sens_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] | None = None, bg_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_surf: ndarray[tuple[Any, ...], dtype[int64]] | None = None)

Bases: BaseModel

Base class for storing and managing sensor and background geometry data.

sens_names

Names of the sensors.

Type:

List[str]

sens_lines

An array representing lines between sensors, where each entry is a pair of sensor indices. Default is None.

Type:

numpy.ndarray of shape (n, 2), optional

bg_nodes

An array of background nodes in 3D space. Default is None.

Type:

numpy.ndarray of shape (m, 3), optional

bg_lines

An array of lines between background nodes, where each entry is a pair of node indices. Default is None.

Type:

numpy.ndarray of shape (p, 2), optional

bg_surf

An array of background surfaces, where each entry is a node index. Default is None.

Type:

numpy.ndarray of shape (q, 3), optional

class pyoma2.support.geometry.data.Geometry1(*, sens_names: list[str], sens_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] | None = None, bg_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_surf: ndarray[tuple[Any, ...], dtype[int64]] | None = None, sens_coord: DataFrame, sens_dir: ndarray[tuple[Any, ...], dtype[int64]])

Bases: BaseGeometry

Class for storing and managing sensor and background geometry data for Geometry 1.

This class provides a structured way to store the coordinates and directions of sensors, as well as optional background data such as nodes, lines, and surfaces.

sens_names

Names of the sensors.

Type:

List[str]

sens_coord

A DataFrame containing the coordinates of each sensor.

Type:

pandas.DataFrame

sens_dir

An array representing the direction vectors of the sensors.

Type:

numpy.ndarray of shape (n, 3)

sens_lines

An array representing lines between sensors, where each entry is a pair of sensor indices. Default is None.

Type:

numpy.ndarray of shape (n, 2), optional

bg_nodes

An array of background nodes in 3D space. Default is None.

Type:

numpy.ndarray of shape (m, 3), optional

bg_lines

An array of lines between background nodes, where each entry is a pair of node indices. Default is None.

Type:

numpy.ndarray of shape (p, 2), optional

bg_surf

An array of background surfaces, where each entry is a node index. Default is None.

Type:

numpy.ndarray of shape (q, 3), optional

class pyoma2.support.geometry.data.Geometry2(*, sens_names: list[str], sens_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] | None = None, bg_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_surf: ndarray[tuple[Any, ...], dtype[int64]] | None = None, pts_coord: DataFrame, sens_map: DataFrame, cstrn: DataFrame | None = None, sens_sign: DataFrame | None = None, sens_surf: ndarray[tuple[Any, ...], dtype[int64]] | None = None)

Bases: BaseGeometry

Class for storing and managing sensor and background geometry data for Geometry 2.

This class is designed to store sensor data and their associated point coordinates, along with optional constraints and sensor surface information. It supports mapping sensors to specific points in space, and includes optional background data for further geometric analysis.

sens_names

Names of the sensors.

Type:

List[str]

pts_coord

A DataFrame containing the coordinates of the points.

Type:

pandas.DataFrame

sens_map

A DataFrame mapping sensors to points locations.

Type:

pandas.DataFrame

cstrn

A DataFrame of constraints applied to the points or sensors. Default is None.

Type:

pandas.DataFrame, optional

sens_sign

A DataFrame indicating the sign or orientation of the sensors. Default is None.

Type:

pandas.DataFrame, optional

sens_lines

An array representing lines between sensors, where each entry is a pair of sensor indices. Default is None.

Type:

numpy.ndarray of shape (n, 2), optional

sens_surf

An array representing surfaces between sensors, where each entry is a node index. Default is None.

Type:

numpy.ndarray of shape (p, ?), optional

bg_nodes

An array of background nodes in 3D space. Default is None.

Type:

numpy.ndarray of shape (m, 3), optional

bg_lines

An array of lines between background nodes, where each entry is a pair of node indices. Default is None.

Type:

numpy.ndarray of shape (p, 2), optional

bg_surf

An array of background surfaces, where each entry is a node index. Default is None.

Type:

numpy.ndarray of shape (q, 3), optional

class pyoma2.support.geometry.data.ModeGeo1Data(*, sens_names: list[str], sens_coord: ndarray[tuple[Any, ...], dtype[float64]], sens_dir: ndarray[tuple[Any, ...], dtype[int64]], phi: ndarray[tuple[Any, ...], dtype[float64]], mode_displ: ndarray[tuple[Any, ...], dtype[float64]], deformed_coord: ndarray[tuple[Any, ...], dtype[float64]], fn: float, mode_nr: int, scaleF: float, sens_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] | None = None, bg_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_surf: ndarray[tuple[Any, ...], dtype[int64]] | None = None)

Bases: BaseModel

Headless mode-shape geometry data for a Geometry1 setup.

Carries the complete set of arrays a geo1 mode-shape renderer needs: sensor coordinates and directions, the per-sensor real modal displacement, the deformed coordinates, plus the connectivity and background elements echoed from the geometry. Built by pyoma2.support.geometry.mode_data.build_mode_geo1_data() and returned by pyoma2.support.geometry.mixin.GeometryMixin.get_mode_geo1_data().

sens_names

Names of the sensors; row order matches every (Nch, ...) array.

Type:

list of str

sens_coord

Undeformed sensor coordinates (x, y, z).

Type:

numpy.ndarray of shape (Nch, 3)

sens_dir

Per-sensor measurement direction.

Type:

numpy.ndarray of shape (Nch, 3)

phi

Real part of the mode shape for mode_nr (unscaled).

Type:

numpy.ndarray of shape (Nch,)

mode_displ

Per-sensor modal displacement, sens_dir * phi (unscaled — this is the raw quiver vector; scaleF is applied only in deformed_coord).

Type:

numpy.ndarray of shape (Nch, 3)

deformed_coord

Deformed sensor coordinates, sens_coord + mode_displ * scaleF.

Type:

numpy.ndarray of shape (Nch, 3)

fn

Natural frequency of mode_nr (Hz).

Type:

float

mode_nr

Mode number (1-based).

Type:

int

scaleF

Displacement scale factor applied in deformed_coord.

Type:

float

sens_lines

Sensor-index pairs forming connection lines (0-indexed). Default None.

Type:

numpy.ndarray of shape (n, 2), optional

bg_nodes

Background node coordinates. Default None.

Type:

numpy.ndarray of shape (m, 3), optional

bg_lines

Background node-index pairs. Default None.

Type:

numpy.ndarray of shape (p, 2), optional

bg_surf

Background surface node-index triplets. Default None.

Type:

numpy.ndarray of shape (q, 3), optional

class pyoma2.support.geometry.data.ModeGeo2Data(*, sens_names: list[str], pts_coord: ndarray[tuple[Any, ...], dtype[float64]], sens_map: DataFrame, sens_sign: DataFrame, phi: ndarray[tuple[Any, ...], dtype[float64]], df_phi_map: DataFrame, mode_displ: ndarray[tuple[Any, ...], dtype[float64]], deformed_coord: ndarray[tuple[Any, ...], dtype[float64]], displ_magnitude: ndarray[tuple[Any, ...], dtype[float64]], fn: float, mode_nr: int, scaleF: float, cstrn: DataFrame | None = None, sens_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, sens_surf: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] | None = None, bg_lines: ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_surf: ndarray[tuple[Any, ...], dtype[int64]] | None = None)

Bases: BaseModel

Headless mode-shape geometry data for a Geometry2 setup.

Carries the complete set of arrays the geo2 mode-shape renderers assemble: point coordinates, the sensor mapping and signs, the mapped modal values, the per-point modal displacement, the deformed coordinates, the displacement magnitude, plus connectivity and background elements. Built by pyoma2.support.geometry.mode_data.build_mode_geo2_data() and returned by pyoma2.support.geometry.mixin.GeometryMixin.get_mode_geo2_data().

sens_names

Names of the sensors.

Type:

list of str

pts_coord

Undeformed point coordinates (x, y, z).

Type:

numpy.ndarray of shape (P, 3)

sens_map

Per point/axis: a sensor name, a constraint name, or 0.

Type:

pandas.DataFrame of shape (P, 3)

sens_sign

Per point/axis sign (+1 / -1 / 0).

Type:

pandas.DataFrame of shape (P, 3)

phi

Real part of the mode shape for mode_nr, pre-scaled by scaleF.

Type:

numpy.ndarray of shape (Nch,)

df_phi_map

phi mapped onto each point/axis via gen.dfphi_map_func.

Type:

pandas.DataFrame of shape (P, 3)

mode_displ

Per-point modal displacement, df_phi_map * sens_sign (scaled).

Type:

numpy.ndarray of shape (P, 3)

deformed_coord

Deformed point coordinates, pts_coord + mode_displ.

Type:

numpy.ndarray of shape (P, 3)

displ_magnitude

Per-point displacement magnitude, norm(mode_displ, axis=1).

Type:

numpy.ndarray of shape (P,)

fn

Natural frequency of mode_nr (Hz).

Type:

float

mode_nr

Mode number (1-based).

Type:

int

scaleF

Displacement scale factor pre-multiplied into phi / mode_displ.

Type:

float

cstrn

Constraint matrix (index = constraint names, columns = sensor names). Default None.

Type:

pandas.DataFrame, optional

sens_lines

Point-index pairs forming connection lines (0-indexed). Default None.

Type:

numpy.ndarray of shape (n, 2), optional

sens_surf

Point-index triplets forming surface faces (0-indexed). Default None.

Type:

numpy.ndarray of shape (p, 3), optional

bg_nodes

Background node coordinates. Default None.

Type:

numpy.ndarray of shape (m, 3), optional

bg_lines

Background node-index pairs. Default None.

Type:

numpy.ndarray of shape (p, 2), optional

bg_surf

Background surface node-index triplets. Default None.

Type:

numpy.ndarray of shape (q, 3), optional

class pyoma2.support.geometry.mixin.GeometryMixin

Bases: object

Mixin that gives the ability to define the geometry the instance of the setup class.

This mixin provides methods to define the geometry setups for the instance, including sensor names, coordinates, directions, and optional elements like lines, surfaces, and background nodes. It also includes methods to plot the geometry setups using Matplotlib and PyVista for 2D and 3D visualization, respectively.

anim_mode_geo2(algo_res: BaseResult, *, mode_nr: int = 1, scaleF: float = 1.0, show_lines: bool = True, show_surf: bool = True, def_sett: dict | None = None, save_gif: bool = False, pl: pv.Plotter | None = None) → pv.Plotter | str

Creates an animation of the mode shape for the second geometry setup (geo2).

This wraps PvGeoPlotter.animate_mode, letting you animate a single mode (with optional GIF export) on geo2.

Parameters:

• algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

• mode_nr (int, optional) – Mode number to animate (1-based). Default is 1.

• scaleF (float, optional) – Scale factor for oscillation amplitude. Default is 1.0.

• show_lines (bool, optional) – Whether to render connection lines during the animation. Default is True.

• show_surf (bool, optional) – Whether to render surface faces during the animation. Default is True.

• def_sett (dict or None, optional) – Plot settings for animation frames; falls back to defaults if None.

• save_gif (bool, optional) – If True, save the animation as a GIF and return its filepath. Default is False.

• pl (pv.Plotter or None, optional) – Existing Plotter to use; if None, one is created. Default is None.

Returns:

The Plotter instance for live animation, or filepath string if GIF was saved.

Return type:

pv.Plotter or str

Raises:

ValueError – If geo2 is not defined or if algo_res.Fn is None.

def_geo1(sens_names: List[str] | List[List[str]] | DataFrame | ndarray[tuple[Any, ...], dtype[str_]], sens_coord: DataFrame, sens_dir: DataFrame | ndarray[tuple[Any, ...], dtype[int64]] = None, sens_lines: DataFrame | ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_nodes: DataFrame | ndarray[tuple[Any, ...], dtype[float64]] | None = None, bg_lines: DataFrame | ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_surf: DataFrame | ndarray[tuple[Any, ...], dtype[float64]] | None = None) → None

Defines the first geometry setup (geo1) for the instance.

This method sets up the geometry involving sensors’ names, coordinates, directions, and optional elements like sensor lines, background nodes, lines, and surfaces.

Parameters:

• sens_names (Union[numpy.ndarray of string, List of string]) – An array or list containing the names of the sensors.

• sens_coord (pandas.DataFrame) – A DataFrame containing the coordinates of the sensors.

• sens_dir (numpy.ndarray of int64) – An array defining the directions of the sensors.

• sens_lines (numpy.ndarray of int64, optional) – An array defining lines connecting sensors. Default is None.

• bg_nodes (numpy.ndarray of float64, optional) – An array defining background nodes. Default is None.

• bg_lines (numpy.ndarray of int64, optional) – An array defining background lines. Default is None.

• bg_surf (numpy.ndarray of float64, optional) – An array defining background surfaces. Default is None.

def_geo1_by_file(path: str, **read_excel_file_kwargs) → None

Defines the first geometry (geo1) from an Excel file.

This method reads an Excel file to extract sensor information, including sensor names, coordinates, and other optional geometry elements such as lines and background nodes. The information is used to set up the geometry for the instance.

Parameters:

• path (str) – The file path to the Excel file containing the geometry data.

• read_excel_file_kwargs (dict, optional) – Additional keyword arguments to pass to the read_excel_file function.

Raises:

ValueError – If the input data is invalid or missing required fields.

def_geo2(sens_names: List[str] | List[List[str]] | DataFrame | ndarray[tuple[Any, ...], dtype[str_]], pts_coord: DataFrame, sens_map: DataFrame, cstr: DataFrame = None, sens_sign: DataFrame = None, sens_lines: DataFrame | ndarray[tuple[Any, ...], dtype[int64]] | None = None, sens_surf: DataFrame | ndarray[tuple[Any, ...], dtype[int64]] | None = None, bg_nodes: DataFrame | ndarray[tuple[Any, ...], dtype[float64]] | None = None, bg_lines: DataFrame | ndarray[tuple[Any, ...], dtype[float64]] | None = None, bg_surf: DataFrame | ndarray[tuple[Any, ...], dtype[float64]] | None = None) → None

Defines the second geometry setup (geo2) for the instance.

This method sets up an alternative geometry configuration, including sensors’ names, points’ coordinates, mapping, sign data, and optional elements like constraints, sensor lines, background nodes, lines, and surfaces.

Parameters:

• sens_names (Union[list of str, list of list of str, pandas.DataFrame, numpy.ndarray of str]) – Sensors’ names. It can be a list of strings, a list of lists of strings, a DataFrame, or a NumPy array.

• pts_coord (pandas.DataFrame) – A DataFrame containing the coordinates of the points.

• sens_map (pandas.DataFrame) – A DataFrame containing the mapping data for sensors.

• cstrn (pandas.DataFrame, optional) – A DataFrame containing constraints. Default is None.

• sens_sign (pandas.DataFrame, optional) – A DataFrame containing sign data for the sensors. Default is None.

• sens_lines (numpy.ndarray of int64, optional) – An array defining lines connecting sensors. Default is None.

• bg_nodes (numpy.ndarray of float64, optional) – An array defining background nodes. Default is None.

• bg_lines (numpy.ndarray of float64, optional) – An array defining background lines. Default is None.

• bg_surf (numpy.ndarray of float64, optional) – An array defining background surfaces. Default is None.

Notes

This method adapts indices for 0-indexed lines in bg_lines, sens_lines, and bg_surf.

def_geo2_by_file(path: str, **read_excel_file_kwargs) → None

Defines the second geometry (geo2) from an Excel file.

This method reads an Excel file to extract information related to the geometry configuration, including sensor names, points’ coordinates, mapping, and optional background nodes and surfaces. The information is used to set up the second geometry for the instance.

Parameters:

• path (str) – The file path to the Excel file containing the geometry data.

• read_excel_file_kwargs (dict, optional) – Additional keyword arguments to pass to the read_excel_file function.

Raises:

ValueError – If the input data is invalid or missing required fields.

get_mode_geo1_data(algo_res: BaseResult, mode_nr: int, scaleF: float = 1.0) → ModeGeo1Data

Assembles headless mode-shape data for the first geometry setup (geo1).

Returns the deformed mode-shape geometry as a plain data model — sensor coordinates and directions, the per-sensor modal displacement, the deformed coordinates and the connectivity/background elements — without creating a plot. Suitable for headless renderers and servers.

Parameters:

• algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

• mode_nr (int) – The mode number to extract (1-based).

• scaleF (float, optional) – Scaling factor applied to the modal displacement. Default is 1.0.

Returns:

The assembled headless mode-shape data for geo1.

Return type:

ModeGeo1Data

Raises:

ValueError – If geo1 is not defined or if the algorithm results are missing.

get_mode_geo2_data(algo_res: BaseResult, mode_nr: int, scaleF: float = 1.0) → ModeGeo2Data

Assembles headless mode-shape data for the second geometry setup (geo2).

Returns the deformed mode-shape geometry as a plain data model — point coordinates, the sensor mapping, the per-point modal displacement, the deformed coordinates, the displacement magnitude and the connectivity/background elements — without creating a plot. Suitable for headless renderers and servers.

Parameters:

• algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

• mode_nr (int) – The mode number to extract (1-based).

• scaleF (float, optional) – Scaling factor applied to the modal displacement. Default is 1.0.

Returns:

The assembled headless mode-shape data for geo2.

Return type:

ModeGeo2Data

Raises:

ValueError – If geo2 is not defined or if the algorithm results are missing.

plot_geo1(scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'red', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray', col_txt: str = 'red') → Tuple[plt.Figure, plt.Axes]

Plots the first geometry setup (geo1) using Matplotlib.

This method creates a 2D or 3D plot of the first geometry, including sensors, lines, background nodes, and surfaces, using customizable color schemes for each element.

Parameters:

• scaleF (int, optional) – Scaling factor for the plot. Default is 1.

• view ({'3D', 'xy', 'xz', 'yz'}, optional) – The view angle of the plot. Default is ‘3D’.

• col_sns (str, optional) – Color of the sensors. Default is ‘red’.

• col_sns_lines (str, optional) – Color of the lines connecting sensors. Default is ‘red’.

• col_BG_nodes (str, optional) – Color of the background nodes. Default is ‘gray’.

• col_BG_lines (str, optional) – Color of the background lines. Default is ‘gray’.

• col_BG_surf (str, optional) – Color of the background surfaces. Default is ‘gray’.

• col_txt (str, optional) – Color of the text labels for sensors. Default is ‘red’.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

tuple

Raises:

ValueError – If geo1 is not defined.

plot_geo2(*, scaleF: float = 1.0, col_sens: str = 'red', show_points: bool = True, show_lines: bool = True, show_surf: bool = True, points_sett: dict | None = None, lines_sett: dict | None = None, surf_sett: dict | None = None, background: bool = True, notebook: bool = False) → pv.Plotter

Plots the second geometry setup (geo2) using PyVista for 3D visualization.

This method creates a 3D interactive plot of the second geometry setup with options to visualize sensor points, connecting lines, and surfaces. It provides various customization options for coloring and rendering.

Parameters:

• scaleF (float, optional) – Scaling factor for sensor arrow length. Default is 1.0.

• col_sens (str, optional) – Color of the sensors. Default is ‘red’.

• show_points (bool, optional) – Whether to plot sensor points. Default is True.

• show_lines (bool, optional) – Whether to plot lines connecting sensors. Default is True.

• show_surf (bool, optional) – Whether to plot surfaces connecting sensors. Default is True.

• points_sett (dict or None, optional) – Settings for the points’ appearance; falls back to defaults if None.

• lines_sett (dict or None, optional) – Settings for the lines’ appearance; falls back to defaults if None.

• surf_sett (dict or None, optional) – Settings for the surfaces’ appearance; falls back to defaults if None.

• background (bool, optional) – Whether to use a background Qt plotter if creating new. Default is True.

• notebook (bool, optional) – Whether to render the plot in a Jupyter notebook environment. Default is False.

Returns:

A PyVista Plotter object with the geometry visualization.

Return type:

pyvista.Plotter

Raises:

ValueError – If geo2 is not defined.

plot_geo2_mpl(scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz', 'x', 'y', 'z'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'black', col_sns_surf: str = 'lightcoral', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray', col_txt: str = 'red') → Tuple[plt.Figure, plt.Axes]

Plots the second geometry setup (geo2) using Matplotlib.

This method creates a 2D or 3D plot of the second geometry, including sensors, lines, surfaces, background nodes, and surfaces, with customizable colors.

Parameters:

• scaleF (int, optional) – Scaling factor for the plot. Default is 1.

• view ({'3D', 'xy', 'xz', 'yz', 'x', 'y', 'z'}, optional) – The view angle of the plot. Default is ‘3D’.

• col_sns (str, optional) – Color of the sensors. Default is ‘red’.

• col_sns_lines (str, optional) – Color of the lines connecting sensors. Default is ‘black’.

• col_sns_surf (str, optional) – Color of the surfaces connecting sensors. Default is ‘lightcoral’.

• col_BG_nodes (str, optional) – Color of the background nodes. Default is ‘gray’.

• col_BG_lines (str, optional) – Color of the background lines. Default is ‘gray’.

• col_BG_surf (str, optional) – Color of the background surfaces. Default is ‘gray’.

• col_txt (str, optional) – Color of the text labels for sensors. Default is ‘red’.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

tuple

Raises:

ValueError – If geo2 is not defined.

plot_mode_geo1(algo_res: BaseResult, mode_nr: int, scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', col_sns: str = 'red', col_sns_lines: str = 'red', col_BG_nodes: str = 'gray', col_BG_lines: str = 'gray', col_BG_surf: str = 'gray') → Tuple[plt.Figure, plt.Axes]

Plots the mode shapes for the first geometry setup (geo1) using Matplotlib.

This method visualizes the mode shapes corresponding to the specified mode number, with customizable colors and scaling for different geometrical elements such as sensors, lines, and background surfaces.

Parameters:

• algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

• mode_nr (int) – The mode number to be plotted.

• scaleF (int, optional) – Scaling factor to adjust the size of the mode shapes. Default is 1.

• view ({'3D', 'xy', 'xz', 'yz'}, optional) – The viewing plane or angle for the plot. Default is ‘3D’.

• col_sns (str, optional) – Color of the sensors in the plot. Default is ‘red’.

• col_sns_lines (str, optional) – Color of the lines connecting the sensors. Default is ‘red’.

• col_BG_nodes (str, optional) – Color of the background nodes in the plot. Default is ‘gray’.

• col_BG_lines (str, optional) – Color of the background lines in the plot. Default is ‘gray’.

• col_BG_surf (str, optional) – Color of the background surfaces in the plot. Default is ‘gray’.

Returns:

A tuple containing the Matplotlib figure and axes objects for further customization or saving.

Return type:

tuple

Raises:

ValueError – If geo1 is not defined or if the algorithm results are missing.

plot_mode_geo2(algo_res: BaseResult, *, mode_nr: int = 1, scaleF: float = 1.0, show_lines: bool = True, show_surf: bool = True, def_sett: dict | None = None, undef_sett: dict | None = None, background: bool = True, notebook: bool = False) → pv.Plotter

Plots the mode shapes for the second geometry setup (geo2) using PyVista.

This method creates an interactive 3D plot of a single mode shape (with undeformed geometry underneath) for the second geometry setup. You can toggle connection lines and surface faces, and supply custom plot settings.

Parameters:

• algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

• mode_nr (int, optional) – Mode number to visualize (1-based). Default is 1.

• scaleF (float, optional) – Scale factor for deformation amplitude. Default is 1.0.

• show_lines (bool, optional) – Whether to render connection lines on the mode shape. Default is True.

• show_surf (bool, optional) – Whether to render surface faces on the mode shape. Default is True.

• def_sett (dict or None, optional) – Plot settings for the deformed shape; falls back to defaults if None.

• undef_sett (dict or None, optional) – Plot settings for the undeformed shape; falls back to defaults if None.

• background (bool, optional) – Whether to use a background Qt plotter if creating new. Default is True.

• notebook (bool, optional) – Whether to render the plot in a Jupyter notebook environment. Default is False.

Returns:

A PyVista Plotter object with the mode‐shape visualization.

Return type:

pv.Plotter

Raises:

ValueError – If geo2 is not defined or if algo_res.Fn is None.

plot_mode_geo2_mpl(algo_res: BaseResult, mode_nr: Optional[int], scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', color: str = 'cmap', *args, **kwargs) → Tuple[plt.Figure, plt.Axes]

Plots the mode shapes for the second geometry setup (geo2) using Matplotlib.

This method visualizes the mode shapes for geo2, with customizable scaling, color, and viewing options. The plot can be configured for different modes and color maps.

Parameters:

• algo_res (BaseResult) – The result object containing modal parameters and mode shape data.

• mode_nr (int, optional) – The mode number to be plotted. If None, the default mode is plotted.

• scaleF (int, optional) – Scaling factor to adjust the size of the mode shapes. Default is 1.

• view ({'3D', 'xy', 'xz', 'yz'}, optional) – The viewing plane or angle for the plot. Default is ‘3D’.

• color (str, optional) – Color scheme or colormap to be used for the mode shapes. Default is ‘cmap’.

Returns:

A tuple containing the Matplotlib figure and axes objects for further customization or saving.

Return type:

tuple

Raises:

ValueError – If geo2 is not defined or if the algorithm results are missing (e.g., Fn is None).

Headless builders that assemble mode-shape geometry data.

These functions map a modal result onto a geometry model and return the ModeGeo1Data / ModeGeo2Data Pydantic models. They are headless — numpy / pandas / pydantic and gen.dfphi_map_func only — so they run in a core (GUI-free) install.

pyoma2.support.geometry.mode_data.build_mode_geo1_data(geo1: Geometry1, res: BaseResult, mode_nr: int, scaleF: float = 1.0) → ModeGeo1Data

Assemble ModeGeo1Data for one mode of a Geometry1 setup.

Parameters:

• geo1 (Geometry1) – The geometry-1 model (sensor coordinates, directions, connectivity).

• res (BaseResult) – Modal result; res.Phi is (Nch, Nmodes) and res.Fn is (Nmodes,).

• mode_nr (int) – Mode number to extract (1-based).

• scaleF (float, default 1.0) – Displacement scale factor applied when computing deformed_coord.

Returns:

The assembled headless mode-shape data for geo1.

Return type:

ModeGeo1Data

Raises:

ValueError – If mode_nr is outside the range 1..res.Phi.shape[1].

pyoma2.support.geometry.mode_data.build_mode_geo2_data(geo2: Geometry2, res: BaseResult, mode_nr: int, scaleF: float = 1.0) → ModeGeo2Data

Assemble ModeGeo2Data for one mode of a Geometry2 setup.

Parameters:

• geo2 (Geometry2) – The geometry-2 model (point coordinates, sensor mapping, signs, constraints, connectivity).

• res (BaseResult) – Modal result; res.Phi is (Nch, Nmodes) and res.Fn is (Nmodes,).

• mode_nr (int) – Mode number to extract (1-based).

• scaleF (float, default 1.0) – Displacement scale factor; pre-multiplied into phi (matching the geo2 plotters), so deformed_coord = pts_coord + mode_displ.

Returns:

The assembled headless mode-shape data for geo2.

Return type:

ModeGeo2Data

Raises:

ValueError – If mode_nr is outside the range 1..res.Phi.shape[1].