upxo.viz.gsviz module

upxo.viz.gsviz.see_map(lfi, fids=None, cmap='viridis', figsize=(8, 6), dpi=100, vmin=None, vmax=None, title='Map View', xlabel='X-axis', ylabel='Y-axis', cmlabel='Value', preset='minimal', ax=None, show=True, cbar_ticks=None, mbar=False, mbar_length=10, mbar_loc='bot_left', mbar_units='μm', **imshow_kwargs)[source]

Visualize 2D map data with flexible styling options.

Parameters:

  • mapdata (array_like) – 2D data array to visualize

  • cmap (str, optional) – Colormap name. Default is ‘viridis’.

  • figsize (tuple, optional) – Figure size (width, height). Default is (8, 6).

  • dpi (int, optional) – Figure resolution. Default is 100.

  • vmin (float, optional) – Color scale limits

  • vmax (float, optional) – Color scale limits

  • title (str, optional) – Plot title. Default is ‘Map View’.

  • xlabel (str, optional) – Axis labels. Default is ‘X-axis’, ‘Y-axis’.

  • ylabel (str, optional) – Axis labels. Default is ‘X-axis’, ‘Y-axis’.

  • cmlabel (str, optional) – Colorbar label. Default is ‘Value’.

  • preset (str, optional) – Use predefined style preset (‘publication’, ‘presentation’, ‘quick’, ‘minimal’). Overrides figsize, dpi, cmap if specified. Individual parameters override preset.

  • ax (matplotlib.axes.Axes, optional) – Existing axis to plot on. If None, creates new figure.

  • show (bool, optional) – Whether to call plt.show(). Default is True. Set False for further customization.

  • **kwargs (dict) – Additional arguments passed to imshow (e.g., interpolation, alpha, extent)

Returns:

  • ax (matplotlib.axes.Axes) – The axis object for further customization

  • Usage

  • —–

  • from upxo.viz.gsviz import see_map

Examples

>>> # Quick visualization
>>> see_map(data)

>>> # Publication-ready figure
>>> see_map(data, preset='publication', title='Grain Structure')

>>> # Custom styling with preset base
>>> ax = see_map(data, preset='presentation', cmap='coolwarm', show=False)
>>> ax.set_aspect('equal')
>>> plt.show()
upxo.viz.gsviz.see_bsegs_gid(lfi, pcid, dim=2, bsegGeomType='pix', figsize=(5, 5), dpi=75)[source]

Orchastrator function to visualize boundary segments.

Parameters:

  • lfi (ndarray) – Local feature ID array. here, this should be the lfi of segments and not the usual lfi/lgi of MCGS2D/MCGS3D.

  • dim (int) – Dimensionality

  • pcid (int) – Parent cell ID. This could be the grain ID you are interested in.

  • bsegGeomType (str) – Boundary segment geometry type. Options include: ‘pix’ (for 2D), ‘vox’ (for 3D) and ‘geom’ (for 2D and 3D: MCGS or VTGS). Currently only ‘pix’ (pixel) is supported.

  • figsize (tuple, optional) – Figure size. Default is (5, 5).

  • dpi (int, optional) – Figure resolution. Default is 75.

Returns:

  • None

  • Functions orchastrated

  • ———————-

  • see_bsegs_gid_pix(lfi, pcid)

Examples

see_bsegs_gid(localSegIDMasked_lfi, pcid, dim=2, bsegGeomType=’pix’)

upxo.viz.gsviz.see_bsegs_gid_pix(lfi, pcid, figsize=(8, 6), dpi=100, vmin=None, vmax=None, title='Map View', xlabel='X-axis', ylabel='Y-axis', cmlabel='Value', preset='minimal', ax=None, show=True, cbar_ticks=None, **imshow_kwargs)[source]

Visualize boundary segments for a given parent cell ID in 2D pixel data.

Parameters:

  • lfi (ndarray) – Local feature ID array. here, this should be the lfi of segments and not the usual lfi/lgi of MCGS2D/MCGS3D.

  • pcid (int) – Parent cell ID. This could be the grain ID you are interested in.

  • figsize (tuple, optional) – Figure size. Default is (5, 5).

  • dpi (int, optional) – Figure resolution. Default is 75.

Return type:

None

Examples

>>> # Visualize boundary segments for parent cell ID of largest grain
>>> pcid = np.argmax(pxt.gs[3].prop.npixels.to_numpy())+1
>>> see_bsegs_gid_pix(localSegIDMasked_lfi, pcid, figsize=(5,5), dpi=75)
upxo.viz.gsviz.plot_multipolygon_geometric(gs_geometric, fig=None, ax=None, cmap='tab20', edgecolor='black', alpha=0.7, lw=1, figsize=(10, 10), dpi=100, points=None, point_color='red', point_size=20, point_marker='o', point_alpha=0.8, point_label='Points')[source]

Plot a Shapely MultiPolygon object using matplotlib with unique colors per polygon.

Parameters:

  • gs_geometric (shapely.geometry.MultiPolygon) – The MultiPolygon object to plot

  • cmap (str or matplotlib.colors.Colormap, optional) – Colormap for polygon colors. Default ‘tab20’

  • edgecolor (str, optional) – Edge color for polygons. Default ‘black’

  • alpha (float, optional) – Transparency level (0-1). Default 0.7

  • lw (float, optional) – Line width for edges. Default 1

  • figsize (tuple, optional) – Figure size if creating new figure. Default (10, 10)

  • dpi (int, optional) – DPI for figure. Default 100

  • points (ndarray or None, optional) – N×2 array of coordinate points to plot on top of polygons. Format: [[x1, y1], [x2, y2], …]. Default None (no points plotted)

  • point_color (str, optional) – Color for plotted points. Default ‘red’

  • point_size (float, optional) – Size of plotted points. Default 20

  • point_marker (str, optional) – Marker style for points. Default ‘o’ (circle)

  • point_alpha (float, optional) – Transparency for points (0-1). Default 0.8

  • point_label (str, optional) – Label for points in legend. Default ‘Points’

Returns:

  • fig (matplotlib.figure.Figure) – Figure object

  • ax (matplotlib.axes.Axes) – Axes object

  • Usage

  • —–

  • from upxo.viz.gsviz import plot_multipolygon_geometric

  • Function signature

  • ——————

  • plot_multipolygon_geometric(gs_geometric, fig=None, ax=None, cmap=’tab20’, edgecolor=’black’, – alpha=0.7, lw=1, figsize=(10, 10), dpi=100, points=None, point_color=’red’, point_size=20, point_marker=’o’, point_alpha=0.8, point_label=’Points’)

upxo.viz.gsviz.make_pvgrid(lfi, scalar_name='lfi', origin=(0, 0, 0), spacing=(1, 1, 1))[source]

Build and return pvgrid.

upxo.viz.gsviz.plot_pvgrid(pvgrid, scalar_name='lfi', show_edges=False, alpha=1.0, title='', cmap='nipy_spectral', _xname_='', _yname_='', _zname_='')[source]
gsviz.plot_pvgrid(gsviz.make_pvgrid(lfi, scalar_name=’lfi’),

scalar_name, show_edges=False, alpha=1.0, title=’’, cmap=’nipy_spectral’, _xname_=’’, _yname_=’’, _zname_=’’)

Usage

from upxo.viz import gsviz

upxo.viz.gsviz.grain_viewer(lfi)[source]

Create an interactive 3D visualization with a slider to explore individual grains.

Parameters:

lfi (np.ndarray) – 3D labeled image array where each voxel contains a grain ID.

Returns:

  • None

  • Usage

  • —–

  • from upxo.viz import gsviz

  • Use as (gsviz.grain_viewer(lfi))

upxo.viz.gsviz.view_selected_grain_boundary_voxels(lfi, grain_ids, viewInternalOnly=True, spacing=(1.0, 1.0, 1.0), origin=(0.0, 0.0, 0.0), cmap='tab20', opacity=1.0, point_size=6.0, show_as_cubes=True, show=True)[source]

Visualize boundary voxels of selected grain IDs in 3D. :param lfi: 3D grain ID array. :type lfi: ndarray[int] :param grain_ids: Grain IDs to visualize. Should be a list, set, or array of integers corresponding to

grain IDs in the LFI.

Parameters:

  • viewInternalOnly (bool, optional) – If True, only visualize internal grain boundaries. If False, include outer RVE boundaries. Default is True.

  • spacing (tuple of float, optional) – Voxel spacing in (x, y, z) directions. Default is (1.0, 1.0, 1.0).

  • origin (tuple of float, optional) – Origin coordinates for the grid. Default is (0.0, 0.0, 0.0).

  • cmap (str, optional) – Colormap for visualizing different grain IDs. Default is “tab20”.

  • opacity (float, optional) – Opacity for the visualized voxels (0.0 to 1.0). Default is 1.0 (fully opaque).

  • point_size (float, optional) – Size of the points representing boundary voxels. Default is 6.0.

  • show_as_cubes (bool, optional) – If True, visualize boundary voxels as cubes. If False, visualize as points. Default is True.

  • show (bool, optional) – Whether to display the plot immediately. Default is True. Set to False for further customization before showing.

Returns:

  • pl (pyvista.Plotter) –

    The PyVista plotter object containing the visualization. Can be used for further

    customization or saving the plot.

  • pdata (pyvista.PolyData) – The PolyData object containing the boundary voxel points and their associated grain IDs. Can be used for further analysis or custom visualization.

  • Usage

  • —–

  • from upxo.viz import gsviz

  • Example usage

  • >>> # Visualize boundary voxels for grain IDs 1, 2, and 3

  • >>> gsviz.view_selected_grain_boundary_voxels(lfi, grain_ids=[1, 2, 3], viewInternalOnly=True, spacing=(1.0, 1.0, 1.0),

  • … origin=(0.0, 0.0, 0.0), cmap=”tab20”, opacity=0.9, point_size=6.0, show_as_cubes=True, show=True)

upxo.viz.gsviz.viz_clip_plane(lfi, normal='x', origin=[5.0, 5.0, 5.0], scalarName='lfi', cmap='viridis', invert=True, crinkle=True, normal_rotation=True, add_outline=False, throw=False, pvp=None)[source]

Visualize grain structure along a clip plane.

Parameters:

  • normal (str or dth.dt.ITERABLE(float), optional) – Normal specification of clipping plane. Default value is ‘x’.

  • origin (dth.dt.ITERABLE(float), optional) – Specification of origin, that is clip plane centre coordinate.

  • scalarName (str, optional) – self.pvgrid cell_data scalar specification. Default value is ‘lfi’.

  • cmap (str, optional) –

    Colour map specification. Default value is ‘viridis’. Recommended values:

    • viridis

    • nipy_spectral

  • invert (bool, optional) – Invert clip sense if True, dont if False. Default value is True.

  • crinkle (bool, optional) – Crinkle view voxels if True, section view if False. Default value is True.

  • normal_rotation (bool, optional) – Rotation specification of normal. Default value is True. NOTE: To be implemented completely.

  • add_outline (bool, optional) – Add an outline around the grain structure. Default value is False.

  • throw (bool, optional) – Throw the pvp if True, dont if False. Default value is False.

  • pvp (pv.Plotter, optional) – PyVista plotter object to plot over. If no pvp has been provided, new pvp shall be created. Default value is None.

  • Usage

  • -----

  • gsviz (from upxo.viz import)

  • as (Use) –

    cmap=’viridis’, invert=True, crinkle=True,

    normal_rotation=True, add_outline=False, throw=False, pvp=None)

upxo.viz.gsviz.viz_mesh_slice(lfi, normal='x', origin=[5.0, 5.0, 5.0], scalarName='lgi', cmap='viridis', normal_rotation=True, add_outline=False, throw=False, pvp=None)[source]

Visualize grain structure along a slice plane.

Parameters:

  • lfi (object) – The grain structure object to visualize.

  • normal (str or dth.dt.ITERABLE(float), optional) – Normal specification of clipping plane. Default value is ‘x’.

  • origin (dth.dt.ITERABLE(float), optional) – Specification of origin, that is clip plane centre coordinate.

  • scalarName (str, optional) – self.pvgrid cell_data scalar specification. Default value is ‘lgi’.

  • cmap (str, optional) –

    Colour map specification. Default value is ‘viridis’. Recommended values:

    • viridis

    • nipy_spectral

  • add_outline (bool, optional) – Add an outline around the grain structure. Default value is False.

  • throw (bool, optional) – Throw the pvp if True, dont if False. Default value is False.

  • pvp (bool, optional) – PyVista plotter object to plot over. If no pvp has been provided, new pvp shall be created. Default value is None.

  • Usage

  • -----

  • gsviz (from upxo.viz import)

  • gsviz.viz_mesh_slice(lfi – cmap=’viridis’, normal_rotation=True, add_outline=False, throw=False, pvp=None)

  • normal='x' – cmap=’viridis’, normal_rotation=True, add_outline=False, throw=False, pvp=None)

  • origin=[5.0 – cmap=’viridis’, normal_rotation=True, add_outline=False, throw=False, pvp=None)

  • 5.0 – cmap=’viridis’, normal_rotation=True, add_outline=False, throw=False, pvp=None)

  • 5.0] – cmap=’viridis’, normal_rotation=True, add_outline=False, throw=False, pvp=None)

  • scalar='lgi' – cmap=’viridis’, normal_rotation=True, add_outline=False, throw=False, pvp=None)

:paramcmap=’viridis’, normal_rotation=True, add_outline=False,

throw=False, pvp=None)

upxo.viz.gsviz.viz_mesh_slice_ortho(lfi, scalarName='lfi', cmap='viridis', style='surface', add_outline=False, throw=False, pvp=None)[source]

Viz. grain str. along three fundamental mutually orthogonal planes.

Parameters:

  • lfi (object) – The grain structure object to visualize.

  • scalarName (str, optional) – self.pvgrid cell_data scalar specification. Default value is ‘lgi’.

  • cmap (str, optional) –

    Colour map specification. Default value is ‘viridis’. Recommended values:

    • viridis

    • nipy_spectral

  • add_outline (bool, optional) – Add an outline around the grain structure. Default value is False.

  • throw (bool, optional) – Throw the pvp if True, dont if False. Default value is False.

  • pvp (bool, optional) – PyVista plotter object to plot over. If no pvp has been provided, new pvp shall be created. Default value is None.

  • Usage

  • -----

  • gsviz (from upxo.viz import)

  • gsviz.viz_mesh_slice_ortho(lfi – style=’surface’, add_outline=False, throw=False, pvp=None)

  • scalarName='lfi' – style=’surface’, add_outline=False, throw=False, pvp=None)

  • cmap='viridis' – style=’surface’, add_outline=False, throw=False, pvp=None)

:paramstyle=’surface’, add_outline=False,

throw=False, pvp=None)

upxo.viz.gsviz.vox2geom_plots(plotType, **kwargs)[source]

Vox2geom plots.

upxo.viz.gsviz.view_grains(lfi=None, **kwargs)[source]

View grains.

upxo.viz.gsviz.view_boundary_voxels(lfi=None, **kwargs)[source]

View boundary voxels.

upxo.viz.gsviz.see_clip_plane(lfi=None, **kwargs)[source]

See clip plane.

upxo.viz.gsviz.see_mesh_slice(lfi=None, **kwargs)[source]

See mesh slice.

upxo.viz.gsviz.see_mesh_slice_ortho(lfi=None, **kwargs)[source]

See mesh slice ortho.

upxo.viz.gsviz.plot_manifold_geom(cells_dict_list, figsize=(12, 6), dpi=100, inlude_legend=True)[source]

Helper to handle MultiPolygon and GeometryCollection iteration for plotting.

Parameters:

  • cells_dict_list (list of dict) – List of dictionaries, each mapping grain IDs to Shapely geometries (which may be Polygons, MultiPolygons, or GeometryCollections).

  • figsize (tuple, optional) – Figure size (width, height). Default is (12, 6).

Returns:

  • fig (matplotlib.figure.Figure) – Figure object

  • axes (ndarray of matplotlib.axes.Axes) – Array of axes objects

  • Usage

  • —–

  • from upxo.viz import gsviz

  • Use as (gsviz.plot_manifold_geom([cells_dict_1, cells_dict_2], figsize=(12, 6)))

upxo.viz.gsviz.see_2dPoints(points, figsize=(6, 6), dpi=100, title='2D Points', xlabel='X-axis', ylabel='Y-axis', point_color='black', point_size=20, point_marker='.', point_alpha=0.8, label='Points', plot_legend=True)[source]

Visualize a set of 2D points using matplotlib.

Parameters:

  • points (ndarray) – N×2 array of coordinate points to visualize. Format: [[x1, y1], [x2, y2], …].

  • figsize (tuple, optional) – Figure size (width, height). Default is (6, 6).

  • dpi (int, optional) – Figure resolution. Default is 100.

  • title (str, optional) – Plot title. Default is ‘2D Points’.

  • xlabel (str, optional) – X-axis label. Default is ‘X-axis’.

  • ylabel (str, optional) – Y-axis label. Default is ‘Y-axis’.

  • point_color (str or list of str, optional) – Color for the points. Can be a single color or a list of colors for each point. Default is ‘black’.

  • point_size (float or list of float, optional) – Size of the points. Can be a single size or a list of sizes for each point. Default is 20.

  • point_marker (str, optional) – Marker style for the points (e.g., ‘.’ for dots). Default is ‘.’.

  • point_alpha (float or list of float, optional) – Transparency level for the points (0-1). Can be a single value or a list for each point. Default is 0.8.

Returns:

  • fig (matplotlib.figure.Figure) – The figure object containing the plot.

  • ax (matplotlib.axes.Axes) – The axes object containing the plot.

  • Usage

  • —–

  • from upxo.viz import gsviz

  • Use as (gsviz.see_2dPoints(points_array))