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.

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)[source]

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]])[source]

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)[source]

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.mixin.GeometryMixin[source]

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[source]

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: ndarray[tuple[Any, ...], dtype[int64]], sens_lines: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_lines: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_surf: ndarray[tuple[Any, ...], dtype[float64]] = None) → None[source]

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[source]

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: ndarray[tuple[Any, ...], dtype[int64]] = None, sens_surf: ndarray[tuple[Any, ...], dtype[int64]] = None, bg_nodes: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_lines: ndarray[tuple[Any, ...], dtype[float64]] = None, bg_surf: ndarray[tuple[Any, ...], dtype[float64]] = None) → None[source]

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[source]

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.

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[Figure, Axes][source]

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[source]

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[Figure, Axes][source]

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[Figure, Axes][source]

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[source]

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: int | None, scaleF: int = 1, view: Literal['3D', 'xy', 'xz', 'yz'] = '3D', color: str = 'cmap', *args, **kwargs) → Tuple[Figure, Axes][source]

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).