Modules.SquidGlyphs package

Submodules

Modules.SquidGlyphs.squid_glyphs module

Top-level API for squid glyph visualization.

This module provides high-level functions that orchestrate the three-stage pipeline:

  1. Compute statistics (vector depths, spreads, variations)

  2. Build mesh geometry (vertices, triangles)

  3. Render visualization (matplotlib or pyvista)

For fine-grained control, use the individual stage functions directly:

  • squid_glyphs_2d_summary_statistics() / squid_glyphs_3d_summary_statistics()

  • squid_glyphs_2d_mesh() / squid_glyphs_3d_mesh()

  • visualize_squid_glyphs_2d() / visualize_squid_glyphs_3d()

Modules.SquidGlyphs.squid_glyphs.squid_glyph_2D(positions, ensemble_vectors, percentile=95, scale=0.2, ax=None, workers=None)[source]

Visualize 2D uncertainty squid glyphs.

This function orchestrates the three-stage pipeline:

  1. Convert Cartesian → Polar, compute vector depths and spreads

  2. Build glyph mesh (vertices, triangles)

  3. Render with matplotlib

Based on: T. A. J. Ouermi et al., “Glyph-Based Uncertainty Visualization and Analysis of Time-Varying Vector Fields,” IEEE UncertaintyVis 2024.

Parameters:

positionsnumpy.ndarray

Array of shape (n, 2) representing the positions of the squid glyphs.

ensemble_vectorsnumpy.ndarray

Array of shape (n, m, 2) representing the ensemble vectors for each position.

percentilefloat (0-100)

Percentile of ensemble members to include based on depth ranking. Higher values include more vectors (larger glyphs showing more variation). - percentile=50: Include top 50% deepest vectors - percentile=95: Include top 95% deepest vectors (typical, default) - percentile=100: Include ALL vectors (maximum variation)

scalefloat

The scale factor for the glyphs.

axmatplotlib axis

The axis to draw on. If None, a new figure and axis will be created.

workersint, optional

Number of parallel workers for computation. Default is None (sequential).

Returns:

axmatplotlib axis

The axis with the drawn squid glyphs.

Modules.SquidGlyphs.squid_glyphs.squid_glyph_3D(positions, ensemble_vectors, point_values=None, percentile=95, scale=0.5, show_edges=True, glyph_color='lightblue', ax=None)[source]

Visualize 3D uncertainty squid glyphs.

This function orchestrates the three-stage pipeline:

  1. Convert Cartesian → Spherical, compute vector depths, spreads, and PCA

  2. Build superelliptical glyph mesh (vertices, triangles)

  3. Render with pyvista

Based on: T. A. J. Ouermi et al., “Glyph-Based Uncertainty Visualization and Analysis of Time-Varying Vector Fields,” IEEE UncertaintyVis 2024.

Parameters:

positionsnumpy.ndarray

Array of shape (n, 3) The positions of the squid glyphs.

ensemble_vectorsnumpy.ndarray

Array of shape (n, m, 3) The ensemble vectors for each position in Cartesian coordinates.

point_valuesnumpy.ndarray, optional

Array of shape (n,) The values associated with each position for coloring.

percentilefloat (0-100)

Percentile of ensemble members to include based on depth ranking. Higher values include more vectors (larger glyphs showing more variation). - percentile=50: Include top 50% deepest vectors - percentile=95: Include top 95% deepest vectors (typical, default) - percentile=100: Include ALL vectors (maximum variation)

scalefloat, optional

The scale factor for the glyphs. Default is 0.5.

show_edgesbool, optional

Whether to show edges of the glyphs. Default is True.

glyph_colorstr, optional

The color of the glyphs. Default is ‘lightblue’.

axpyvista.Plotter, optional

The pyvista plotter to use. If None, a new plotter will be created.

Returns:

plotterpyvista.Plotter

The pyvista plotter with the drawn squid glyphs.

pointsnumpy.ndarray

The points of the squid glyphs.

polygonsnumpy.ndarray

The polygon connectivity for the glyphs.

Modules.SquidGlyphs.squid_glyphs_mesh module

Modules.SquidGlyphs.squid_glyphs_mesh.squid_glyphs_2d_mesh(positions, stats_2d, scale=0.2)[source]

Build 2D squid glyph mesh from statistics.

Creates arrow-shaped glyphs with three components: 1. Base rectangle (uncertainty in magnitude) 2. Shaft rectangle (tapered middle section) 3. Head triangle (arrow tip)

Parameters:

positionsnumpy.ndarray

Shape (n, 2) - glyph positions

stats_2ddict

From squid_glyphs_2d_summary_statistics()

scalefloat

Glyph scale factor (default: 0.2)

Returns:

mesh_2ddict
{

‘points’: (k, 2) - vertex positions, ‘polygons’: (m, 3) - triangle connectivity

}

Modules.SquidGlyphs.squid_glyphs_mesh.squid_glyphs_3d_mesh(positions, stats_3d, point_values=None, scale=0.5, resolution=10)[source]

Build 3D squid glyph mesh from statistics.

Parameters:

positionsnumpy.ndarray

Shape (n, 3) - glyph positions

stats_3ddict

From squid_glyphs_3d_summary_statistics()

point_valuesnumpy.ndarray, optional

Shape (n,) - scalar values for coloring

scalefloat

Glyph scale factor (default: 0.5)

resolutionint

Circle resolution (default: 10)

Returns:

mesh_3ddict
{

‘points’: (k, 3) - vertex positions, ‘polygons’: (m, 3) - triangle connectivity, ‘point_values’: (k,) - scalar values for coloring

}

Modules.SquidGlyphs.squid_glyphs_mesh.squid_glyphs_meshing_3D(pca_components, positions, vectors, spread_min_vectors, median_vectors, spread_max_vectors, scaler_values, glyph_types, scale, resolution, num_of_glyphs)[source]

Build superelliptical squid glyphs for 3D visualization.

Creates glyphs with these components: 1. Base disk (at position) 2. Body cylinder (from base to shoulder) 3. Shaft (tapered section) 4. Head cone (arrow tip)

Parameters:

pca_componentsnumpy.ndarray

PCA components for cross-section shape

positionsnumpy.ndarray

Glyph center positions (n, 3)

vectorsnumpy.ndarray

Ensemble vectors (unused, for compatibility)

spread_min_vectors, median_vectors, spread_max_vectorsnumpy.ndarray

Vector statistics in spherical coordinates

scaler_valuesnumpy.ndarray

Scalar values for coloring

glyph_typesnumpy.ndarray

Glyph type flags (0=none, 1=full, 2=arrow only)

scalefloat

Overall glyph scale

resolutionint

Number of vertices per circle

num_of_glyphsint

Number of full glyphs to create

Returns:

points, polygons, points_valuestuple

Mesh geometry and scalar values

Modules.SquidGlyphs.squid_glyphs_stats module

Modules.SquidGlyphs.squid_glyphs_stats.getDirectionalVariations(vectors, depths, percentile, min_vectors, median_vectors, max_vectors)[source]

Compute the directional variation of the vectors.

Parameters:

vectorsnumpy.ndarray

Array of shape (num_points, num_ensemble_members, 3) where the last dimension contains the vector components.

depthsnumpy.ndarray

Array of shape (num_points, num_ensemble_members) containing depth values for each vector.

percentilefloat

Percentile of ensemble members to include (0-100). Higher values include more vectors.

min_vectorsnumpy.ndarray

Array of shape (num_points, 3) where the last dimension contains the min vector components.

median_vectorsnumpy.ndarray

Array of shape (num_points, 3) where the last dimension contains the median vector components.

max_vectorsnumpy.ndarray

Array of shape (num_points, 3) where the last dimension contains the max vector components.

Returns:

directional_variationnumpy.ndarray

Array of shape (num_points, 3, 2) where the 3 represents the (pca first component, pca second component, pca mean) and the 2 represents the x and y components of the pca components.

Modules.SquidGlyphs.squid_glyphs_stats.squid_glyphs_2d_summary_statistics(ensemble_vectors, percentile, workers=None)[source]

Compute vector depth statistics for 2D squid glyphs.

Parameters:

ensemble_vectorsnumpy.ndarray

Shape (n, m, 2) - Cartesian ensemble vectors

percentilefloat

Percentile of ensemble members to include based on depth ranking (0-100). Higher values include more vectors (larger glyphs showing more variation). - percentile=50: Include top 50% deepest vectors - percentile=95: Include top 95% deepest vectors (typical) - percentile=100: Include ALL vectors (maximum variation)

workersint, optional

Number of parallel workers for depth computation. Default is None (sequential)

Returns:

stats_2ddict
{

‘ensemble_polar_vectors’: (n, m, 2) - polar coordinates, ‘depths’: (n, m) - vector depths, ‘median_vectors’: (n, 2) - median vectors per position, ‘magnitudes_min’: (n,) - min magnitude per position, ‘magnitudes_max’: (n,) - max magnitude per position, ‘angles_min’: (n,) - min angle per position, ‘angles_max’: (n,) - max angle per position

}

Modules.SquidGlyphs.squid_glyphs_stats.squid_glyphs_3d_summary_statistics(ensemble_vectors, percentile)[source]

Compute vector depth statistics for 3D squid glyphs.

Parameters:

ensemble_vectorsnumpy.ndarray

Shape (n, m, 3) - Cartesian ensemble vectors

percentilefloat

Percentile of ensemble members to include based on depth ranking (0-100). Higher values include more vectors (larger glyphs showing more variation). - percentile=50: Include top 50% deepest vectors - percentile=95: Include top 95% deepest vectors (typical) - percentile=100: Include ALL vectors (maximum variation)

Returns:

stats_3ddict
{

‘ensemble_spherical_vectors’: (n, m, 3) - spherical coordinates, ‘depths’: (n, m) - vector depths, ‘median_vectors’: (n, 3) - median vectors, ‘spread_min_vectors’: (n, 3) - min spread vectors, ‘spread_max_vectors’: (n, 3) - max spread vectors, ‘glyph_types’: (n,) - glyph type markers, ‘pca_components’: (n, 3, 2) - PCA components, ‘num_glyphs’: int - count of full glyphs

}

Modules.SquidGlyphs.squid_glyphs_vis module

Modules.SquidGlyphs.squid_glyphs_vis.visualize_squid_glyphs_2d(mesh_2d, ax=None)[source]

Render 2D squid glyph mesh with matplotlib.

Parameters:

mesh_2ddict

From squid_glyphs_2d_mesh()

axmatplotlib.Axes, optional

Existing axis to draw on

Returns:

axmatplotlib.Axes

The axis with drawn glyphs

Modules.SquidGlyphs.squid_glyphs_vis.visualize_squid_glyphs_3d(mesh_3d, point_values=None, show_edges=True, glyph_color='lightblue', cmap='RdBu_r', ax=None)[source]

Render 3D squid glyph mesh with pyvista.

Parameters:

mesh_3ddict

From squid_glyphs_3d_mesh()

point_valuesnumpy.ndarray, optional

Override mesh point_values for coloring

show_edgesbool

Show glyph edges (default: True)

glyph_colorstr

Solid color when no point_values (default: ‘lightblue’)

cmapstr

Colormap for scalar coloring (default: ‘RdBu_r’)

axpyvista.Plotter, optional

Existing plotter to use

Returns:

plotterpyvista.Plotter

The plotter with drawn glyphs

Module contents

Squid Glyph Uncertainty Visualization Module.

High-level API (for most users):

  • squid_glyph_2D: Visualize 2D vector field uncertainty

  • squid_glyph_3D: Visualize 3D vector field uncertainty

Low-level API (for advanced customization):
Stats Stage:

  • squid_glyphs_2d_summary_statistics: Compute 2D vector depths and spreads

  • squid_glyphs_3d_summary_statistics: Compute 3D vector depths, spreads, and PCA

Mesh Stage:

  • squid_glyphs_2d_mesh: Build 2D glyph geometry

  • squid_glyphs_3d_mesh: Build 3D glyph geometry

Visualization Stage:

  • visualize_squid_glyphs_2d: Render 2D glyphs with matplotlib

  • visualize_squid_glyphs_3d: Render 3D glyphs with pyvista

Modules.SquidGlyphs.squid_glyph_2D(positions, ensemble_vectors, percentile=95, scale=0.2, ax=None, workers=None)[source]

Visualize 2D uncertainty squid glyphs.

This function orchestrates the three-stage pipeline:

  1. Convert Cartesian → Polar, compute vector depths and spreads

  2. Build glyph mesh (vertices, triangles)

  3. Render with matplotlib

Based on: T. A. J. Ouermi et al., “Glyph-Based Uncertainty Visualization and Analysis of Time-Varying Vector Fields,” IEEE UncertaintyVis 2024.

Parameters:

positionsnumpy.ndarray

Array of shape (n, 2) representing the positions of the squid glyphs.

ensemble_vectorsnumpy.ndarray

Array of shape (n, m, 2) representing the ensemble vectors for each position.

percentilefloat (0-100)

Percentile of ensemble members to include based on depth ranking. Higher values include more vectors (larger glyphs showing more variation). - percentile=50: Include top 50% deepest vectors - percentile=95: Include top 95% deepest vectors (typical, default) - percentile=100: Include ALL vectors (maximum variation)

scalefloat

The scale factor for the glyphs.

axmatplotlib axis

The axis to draw on. If None, a new figure and axis will be created.

workersint, optional

Number of parallel workers for computation. Default is None (sequential).

Returns:

axmatplotlib axis

The axis with the drawn squid glyphs.

Modules.SquidGlyphs.squid_glyph_3D(positions, ensemble_vectors, point_values=None, percentile=95, scale=0.5, show_edges=True, glyph_color='lightblue', ax=None)[source]

Visualize 3D uncertainty squid glyphs.

This function orchestrates the three-stage pipeline:

  1. Convert Cartesian → Spherical, compute vector depths, spreads, and PCA

  2. Build superelliptical glyph mesh (vertices, triangles)

  3. Render with pyvista

Based on: T. A. J. Ouermi et al., “Glyph-Based Uncertainty Visualization and Analysis of Time-Varying Vector Fields,” IEEE UncertaintyVis 2024.

Parameters:

positionsnumpy.ndarray

Array of shape (n, 3) The positions of the squid glyphs.

ensemble_vectorsnumpy.ndarray

Array of shape (n, m, 3) The ensemble vectors for each position in Cartesian coordinates.

point_valuesnumpy.ndarray, optional

Array of shape (n,) The values associated with each position for coloring.

percentilefloat (0-100)

Percentile of ensemble members to include based on depth ranking. Higher values include more vectors (larger glyphs showing more variation). - percentile=50: Include top 50% deepest vectors - percentile=95: Include top 95% deepest vectors (typical, default) - percentile=100: Include ALL vectors (maximum variation)

scalefloat, optional

The scale factor for the glyphs. Default is 0.5.

show_edgesbool, optional

Whether to show edges of the glyphs. Default is True.

glyph_colorstr, optional

The color of the glyphs. Default is ‘lightblue’.

axpyvista.Plotter, optional

The pyvista plotter to use. If None, a new plotter will be created.

Returns:

plotterpyvista.Plotter

The pyvista plotter with the drawn squid glyphs.

pointsnumpy.ndarray

The points of the squid glyphs.

polygonsnumpy.ndarray

The polygon connectivity for the glyphs.

Modules.SquidGlyphs.squid_glyphs_2d_mesh(positions, stats_2d, scale=0.2)[source]

Build 2D squid glyph mesh from statistics.

Creates arrow-shaped glyphs with three components: 1. Base rectangle (uncertainty in magnitude) 2. Shaft rectangle (tapered middle section) 3. Head triangle (arrow tip)

Parameters:

positionsnumpy.ndarray

Shape (n, 2) - glyph positions

stats_2ddict

From squid_glyphs_2d_summary_statistics()

scalefloat

Glyph scale factor (default: 0.2)

Returns:

mesh_2ddict
{

‘points’: (k, 2) - vertex positions, ‘polygons’: (m, 3) - triangle connectivity

}

Modules.SquidGlyphs.squid_glyphs_2d_summary_statistics(ensemble_vectors, percentile, workers=None)[source]

Compute vector depth statistics for 2D squid glyphs.

Parameters:

ensemble_vectorsnumpy.ndarray

Shape (n, m, 2) - Cartesian ensemble vectors

percentilefloat

Percentile of ensemble members to include based on depth ranking (0-100). Higher values include more vectors (larger glyphs showing more variation). - percentile=50: Include top 50% deepest vectors - percentile=95: Include top 95% deepest vectors (typical) - percentile=100: Include ALL vectors (maximum variation)

workersint, optional

Number of parallel workers for depth computation. Default is None (sequential)

Returns:

stats_2ddict
{

‘ensemble_polar_vectors’: (n, m, 2) - polar coordinates, ‘depths’: (n, m) - vector depths, ‘median_vectors’: (n, 2) - median vectors per position, ‘magnitudes_min’: (n,) - min magnitude per position, ‘magnitudes_max’: (n,) - max magnitude per position, ‘angles_min’: (n,) - min angle per position, ‘angles_max’: (n,) - max angle per position

}

Modules.SquidGlyphs.squid_glyphs_3d_mesh(positions, stats_3d, point_values=None, scale=0.5, resolution=10)[source]

Build 3D squid glyph mesh from statistics.

Parameters:

positionsnumpy.ndarray

Shape (n, 3) - glyph positions

stats_3ddict

From squid_glyphs_3d_summary_statistics()

point_valuesnumpy.ndarray, optional

Shape (n,) - scalar values for coloring

scalefloat

Glyph scale factor (default: 0.5)

resolutionint

Circle resolution (default: 10)

Returns:

mesh_3ddict
{

‘points’: (k, 3) - vertex positions, ‘polygons’: (m, 3) - triangle connectivity, ‘point_values’: (k,) - scalar values for coloring

}

Modules.SquidGlyphs.squid_glyphs_3d_summary_statistics(ensemble_vectors, percentile)[source]

Compute vector depth statistics for 3D squid glyphs.

Parameters:

ensemble_vectorsnumpy.ndarray

Shape (n, m, 3) - Cartesian ensemble vectors

percentilefloat

Percentile of ensemble members to include based on depth ranking (0-100). Higher values include more vectors (larger glyphs showing more variation). - percentile=50: Include top 50% deepest vectors - percentile=95: Include top 95% deepest vectors (typical) - percentile=100: Include ALL vectors (maximum variation)

Returns:

stats_3ddict
{

‘ensemble_spherical_vectors’: (n, m, 3) - spherical coordinates, ‘depths’: (n, m) - vector depths, ‘median_vectors’: (n, 3) - median vectors, ‘spread_min_vectors’: (n, 3) - min spread vectors, ‘spread_max_vectors’: (n, 3) - max spread vectors, ‘glyph_types’: (n,) - glyph type markers, ‘pca_components’: (n, 3, 2) - PCA components, ‘num_glyphs’: int - count of full glyphs

}

Modules.SquidGlyphs.visualize_squid_glyphs_2d(mesh_2d, ax=None)[source]

Render 2D squid glyph mesh with matplotlib.

Parameters:

mesh_2ddict

From squid_glyphs_2d_mesh()

axmatplotlib.Axes, optional

Existing axis to draw on

Returns:

axmatplotlib.Axes

The axis with drawn glyphs

Modules.SquidGlyphs.visualize_squid_glyphs_3d(mesh_3d, point_values=None, show_edges=True, glyph_color='lightblue', cmap='RdBu_r', ax=None)[source]

Render 3D squid glyph mesh with pyvista.

Parameters:

mesh_3ddict

From squid_glyphs_3d_mesh()

point_valuesnumpy.ndarray, optional

Override mesh point_values for coloring

show_edgesbool

Show glyph edges (default: True)

glyph_colorstr

Solid color when no point_values (default: ‘lightblue’)

cmapstr

Colormap for scalar coloring (default: ‘RdBu_r’)

axpyvista.Plotter, optional

Existing plotter to use

Returns:

plotterpyvista.Plotter

The plotter with drawn glyphs