Displaying vector images

PyLorentz.visualize.vector_show.show_2D(Vx: numpy.ndarray, Vy: numpy.ndarray, Vz: numpy.ndarray | None = None, num_arrows: int = 0, arrow_size: float | None = None, arrow_width: float | None = None, title: str | None = None, color: bool = True, cmap: str = 'hsv', origin: str = 'upper', save: str | None = None, figax: Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes] | None = None, rad: int | None = None, scale: float | None = None, **kwargs) → matplotlib.pyplot.Figure[source]

Display a 2D vector field with arrows and optional color mapping.

Parameters:

  • Vx (np.ndarray) – X-component of the vector field.

  • Vy (np.ndarray) – Y-component of the vector field.

  • Vz (np.ndarray, optional) – Z-component of the vector field.

  • num_arrows (int) – Number of arrows to plot along x and y axes.

  • arrow_size (float, optional) – Scale factor for arrow length.

  • arrow_width (float, optional) – Width of arrows.

  • title (str, optional) – Title of the plot.

  • color (bool) – Whether to display a colormap underneath the arrows.

  • cmap (str) – Colormap to use for color mapping.

  • origin (str) – Origin of the image coordinate system.

  • save (str, optional) – Path to save the figure.

  • figax (tuple, optional) – Figure and axes to plot on.

  • rad (int, optional) – Radius for the color wheel.

  • scale (float, optional) – Scale factor for the plot.

  • **kwargs – Additional keyword arguments for customization.

Returns:

The matplotlib figure object.

Return type:

plt.Figure

PyLorentz.visualize.vector_show.show_3D(Vx: numpy.ndarray, Vy: numpy.ndarray, Vz: numpy.ndarray, num_arrows: int = 15, ay: int | None = None, num_arrows_z: int = 15, arrow_size: float | None = None, show_all: bool = True) → None[source]

Display a 3D vector field with arrows, using color to represent vector direction.

Arrow color is determined by direction, with in-plane mapping to an HSV color-wheel and out of plane to white (+z) and black (-z).

Parameters:

  • Vx (np.ndarray) – (z, y, x) X-component of the vector field.

  • Vy (np.ndarray) – (z, y, x) Y-component of the vector field.

  • Vz (np.ndarray) – (z, y, x) Z-component of the vector field.

  • num_arrows (int) – Number of arrows to plot along the x-axis.

  • ay (int, optional) – Number of arrows to plot along the y-axis.

  • num_arrows_z (int) – Number of arrows to plot along the z-axis.

  • arrow_size (float, optional) – Scale factor for arrow length.

  • show_all (bool) – Whether to show all arrows with equal opacity.

Returns:

None

colorwheel functions

Creates RGB images from vector fields.

This module contains several routines for plotting colormaps from input data consisting of 2D images of the 2D or 3D vector field. A variety of colormaps are available using the Colorcet package.

https://colorcet.holoviz.org/user_guide/Continuous.html#cyclic-colormaps Good Colour Maps: How to Design Them, Peter Kovesi (2015) https://arxiv.org/abs/1509.03700

PyLorentz.visualize.colorwheel.roll_cmap(cmap: matplotlib.colors.Colormap | str, frac: float, invert: bool = False) → matplotlib.colors.Colormap[source]

Shifts a matplotlib colormap by rolling.

Parameters:

  • cmap (mpl.colors.Colormap | str) – The colormap to be shifted. Can be a colormap name or a Colormap object.

  • frac (float) – The fraction of the colorbar by which to shift (must be between 0 and 1).

  • invert (bool, optional) – Whether to invert the colormap. Defaults to False.

Returns:

The shifted colormap.

Return type:

mpl.colors.Colormap

PyLorentz.visualize.colorwheel.shift_cmap_center(cmap: matplotlib.colors.Colormap | str, vmin: float = -1, vmax: float = 1, midpointval: float = 0, invert: bool = False) → matplotlib.colors.Colormap[source]

Shifts a matplotlib colormap such that the center is moved and the scaling is consistent.

Parameters:

  • cmap (mpl.colors.Colormap | str) – The colormap to be shifted. Can be a colormap name or a Colormap object.

  • vmin (float, optional) – Minimum value for scaling. Defaults to -1.

  • vmax (float, optional) – Maximum value for scaling. Defaults to 1.

  • midpointval (float, optional) – Value at the center of the colormap. Defaults to 0.

  • invert (bool, optional) – Whether to invert the colormap. Defaults to False.

Returns:

The shifted colormap.

Return type:

mpl.colors.Colormap

PyLorentz.visualize.colorwheel.get_cmap(cmap: str | None = None, **kwargs) → matplotlib.colors.Colormap[source]

Take a colormap or string input and return a Colormap object.

Parameters:

cmap (str | None, optional) –

String corresponding to a colorcet colormap name, a mpl.colors.LinearSegmentedColormap object, or a mpl.colors.ListedColormap object. Defaults to None -> matplotlib gray. Cmap string options include:

  • All matplotlib colormap names

  • ”linear” -> mpl gray

  • ”diverging” -> mpl coolwarm

  • ”linear_cbl” -> cet CBL1 – colorblind-safe linear

  • ”diverging_cbl” -> cet CBD1 – colorblind-safe linear

  • ”cet_rainbow” -> cet R1 – a good rainbow colormap

  • ”legacy4fold” -> cet C2 – 4-fold colormap oriented as was the original PyLorentz default

  • ”purehsv” -> mpl hsv – true hsv

  • ”6fold” or “hsv” -> cet C6 – an improved hsv wheel

  • ”4fold” -> cet C7

  • ”isoluminant” -> cet C10

Keyword Arguments:

  • shift (float, optional) – The amount to shift the colormap by in radians. Defaults to 0.

  • invert (bool, optional) – Whether to invert the colormap. Defaults to False.

Raises:

TypeError – If the input type is not recognized.

Returns:

Matplotlib.colors.Colormap object.

Return type:

mpl.colors.Colormap

PyLorentz.visualize.colorwheel.color_im(vx: numpy.ndarray, vy: numpy.ndarray, vz: numpy.ndarray | None = None, cmap: str | matplotlib.colors.Colormap | None = None, rad: int | None = None, background: str = 'black', **kwargs) → numpy.ndarray[source]

Make the RGB image from vector maps. Takes 2D array inputs for x, y, (and optionally z) vector components.

Unless otherwise specified, the color intensity corresponds to the magnitude of the in-plane vector component normalized to the vector with the largest in-plane magnitude. If a z-component is given, it will map from black (negative) to white (positive).

Good colormaps are notoriously difficult to design [1], and cyclic colormaps especially so. We recommend and use colormaps provided by the Colorcet package [2], with the default being CET_C6, a nice 6-fold improved-hsv colorwheel. Other colormaps we suggest include: - C7: A nice 4-fold map - C10: Isoluminescent 4-fold map

these can be specified with strings as detailed in get_cmap(). Additionally, any matplotlib or colorcet Colormap object can be passed and will be used here.

[1] Kovesi, Peter. “Good colour maps: How to design them.” arXiv preprint arXiv:1509.03700 (2015). [2] https://colorcet.holoviz.org

Parameters:

  • vx (np.ndarray) – (M x N) array consisting of the x-component of the vector field.

  • vy (np.ndarray) – (M x N) array consisting of the y-component of the vector field.

  • vz (np.ndarray | None, optional) – (M x N) array consisting of the z-component of the vector field. If vz is given, black corresponds to z<0 and white to z>0. Default is None.

  • cmap (str | mpl.colors.Colormap | None, optional) – Specification for the colormap to be used. This is passed to get_cmap() which returns the colormap object if a string is given. Defaults to None -> colorcet.cm.CET_C7.

  • rad (int | None, optional) – Radius of color-wheel in pixels. Set rad = 0 to remove color-wheel. Default is None -> height/16.

  • background (str, optional) –

    • ‘black’ – (default) magnetization magnitude corresponds to value.

    • ’white’ – magnetization magnitude corresponds to saturation.

    • if vz is given, this argument will not do anything. Default “black”

Keyword Arguments:

  • modulo (bool) – Whether to map the direction or orientation of the vector field. modulo = True will modulo the vectors by pi. Default False.

  • shift (float) – Rotate the colorwheel and orientation map by the specified amount in radians. Default 0.

  • invert (bool) – Whether or not to invert the directions of the orientation map. Default False.

  • mag_cutoff (bool) – Normally the color intensity (saturation/value) corresponds to the magnitude of the vector, scaled relative to the largest vector in the image. If mag_cutoff = True (specifying uniform_magnitude), then all vectors larger with a magnitude larger than mag_cutoff_cutoff * max_magnitude will be displayed while others will map to background colors or z-direction if vz is given. Default False. Value [0,1], specifying the magnitude, as a fraction of the maximum vector length in the image, above which a vector will be plotted. Default 0.5.

  • HSL (bool) – When give a z-component, this function normally maps vector orientation to hue and vector magnitude to saturation/value, with black/white corresponding to if the vector points in/out of the page. This can cause problems as scaling RGB values can make it appear that there is strong in-plane signal where there really isn’t. An improvement is to use a HSL color space and map vector orientation to hue, z-component to lightness, and in-plane magnitude to saturation. Setting HSL=True will use this type of mapping, and set the colormap to a true hsv colormap, as more complex color maps get distorted when changing the saturation and lightness independently. Default False.

Returns:

Numpy array (M x N x 3) containing the RGB color image.

Return type:

np.ndarray

PyLorentz.visualize.colorwheel.make_colorwheel(rad: int, cmap: matplotlib.colors.Colormap, background: str = 'black', core: str | None = None, **kwargs) → numpy.ndarray[source]

Makes an RGB image of a colorwheel for a given colormap.

Parameters:

  • rad (int) – Radius of the colormap in pixels.

  • cmap (mpl.colors.Colormap) – Matplotlib Colormap object.

  • background (str, optional) – Background color. Defaults to “black”.

  • core (str | None, optional) – Core color. Defaults to background color.

Keyword Arguments:

  • modulo (bool) – Whether to map the direction or orientation of the vector field. modulo = True will modulo the vectors by pi. Default False.

  • mag_cutoff (bool) – Cutoff value (0-1) for colormap showing orientation only, no magnitude.

Returns:

Numpy array (rad*2 x rad*2 x 3) containing the RGB color image.

Return type:

np.ndarray

PyLorentz.visualize.colorwheel.make_colorwheelz(rad: int, cmap: matplotlib.colors.Colormap, outside: str = 'black', **kwargs) → numpy.ndarray[source]

Makes an RGB image of a colorwheel where z-direction corresponds to black/white.

Parameters:

  • rad (int) – Radius of the colormap in pixels.

  • cmap (mpl.colors.Colormap) – Matplotlib Colormap object.

  • outside (str, optional) – Whether the outside portion of the colormap will be black or white. Inside color will necessarily be the opposite. Defaults to “black”.

Keyword Arguments:

  • modulo (bool) – Whether to map the direction or orientation of the vector field. modulo = True will modulo the vectors by pi. Default False.

  • mag_cutoff (bool) – Ring colormap showing orientation only, no magnitude.

  • HSL (bool) – Use HSL color space for mapping. Defaults to False.

Returns:

Numpy array (rad*2 x rad*2 x 3) containing the RGB color image.

Return type:

np.ndarray

PyLorentz.visualize.colorwheel.dist4(dim, shifted=True) → numpy.ndarray[source]

4-fold symmetric distance map (center is 0) even at small radii centered in the middle (i.e. fft shifted) by default