Merge branch 'release-0.2.0' into 'master'

Release 0.2.0

Closes #45

See merge request empyre/empyre!30

src/empyre/vis/decorators.py

@@ -161,7 +161,7 @@ def quiverkey(quiv, field, axis=None, unit='', loc='lower right', **kwargs):
     quiv : Quiver instance
         The quiver instance returned by a call to quiver.
     field : `Field` or ndarray
-        The vector data as a `Field` or a numpy array (in the latter case, `vector=True` and `scale=1` are assumed).
+        The vector data as a `Field` or a numpy array (in the latter case, `vector=True` and `scale=1.0` are assumed).
     axis : :class:`~matplotlib.axes.AxesSubplot`, optional
         Axis to which the quiverkey is added, by default None, which will pick the last used axis via `gca`.
     unit: str, optional
@@ -183,7 +183,7 @@ def quiverkey(quiv, field, axis=None, unit='', loc='lower right', **kwargs):
     if axis is None:  # If no axis is set, find the current or create a new one:
         axis = plt.gca()
     if not isinstance(field, Field):  # Try to convert input to Field if it is not already one:
-        field = Field(data=np.asarray(field), scale=1, vector=True)
+        field = Field(data=np.asarray(field), scale=1.0, vector=True)
     length = field.amp.data.max()
     shift = 1 / field.squeeze().dim[1]  # equivalent to one pixel distance in axis coords!
     label = f'{length:.3g} {unit}'

src/empyre/vis/plot2d.py

@@ -34,7 +34,7 @@ def imshow(field, axis=None, cmap=None, **kwargs):
     Parameters
     ----------
     field : `Field` or ndarray
-        The image data as a `Field` or a numpy array (in the latter case, `vector=False` and `scale=1` are assumed).
+        The image data as a `Field` or a numpy array (in the latter case, `vector=False` and `scale=1.0` are assumed).
     axis : `matplotlib.axes.Axes` object, optional
         The axis to which the image should be added, by default None, which will pick the last use axis via `gca`.
     cmap : str or `matplotlib.colors.Colormap`, optional
@@ -59,7 +59,7 @@ def imshow(field, axis=None, cmap=None, **kwargs):
     """
     _log.debug('Calling imshow')
     if not isinstance(field, Field):  # Try to convert input to Field if it is not already one:
-        field = Field(data=np.asarray(field), scale=1, vector=False)
+        field = Field(data=np.asarray(field), scale=1.0, vector=False)
     assert not field.vector, 'Can only plot scalar fields!'
     # Get squeezed data and make sure it's 2D scalar:
     squeezed_field = field.squeeze()
@@ -104,7 +104,7 @@ def contour(field, axis=None, **kwargs):
     Parameters
     ----------
     field : `Field` or ndarray
-        The contour data as a `Field` or a numpy array (in the latter case, `vector=False` and `scale=1` are assumed).
+        The contour data as a `Field` or a numpy array (in the latter case, `vector=False` and `scale=1.0` are assumed).
     axis : `matplotlib.axes.Axes` object, optional
         The axis to which the contour should be added, by default None, which will pick the last use axis via `gca`.
 
@@ -124,7 +124,7 @@ def contour(field, axis=None, **kwargs):
     """
     _log.debug('Calling contour')
     if not isinstance(field, Field):  # Try to convert input to Field if it is not already one:
-        field = Field(data=np.asarray(field), scale=1, vector=False)
+        field = Field(data=np.asarray(field), scale=1.0, vector=False)
     assert not field.vector, 'Can only plot scalar fields!'
     # Get squeezed data and make sure it's 2D scalar:
     squeezed_field = field.squeeze()
@@ -156,7 +156,7 @@ def colorvec(field, axis=None, **kwargs):
     Parameters
     ----------
     field : `Field` or ndarray
-        The image data as a `Field` or a numpy array (in the latter case, `vector=True` and `scale=1` are assumed).
+        The image data as a `Field` or a numpy array (in the latter case, `vector=True` and `scale=1.0` are assumed).
     axis : `matplotlib.axes.Axes` object, optional
         The axis to which the image should be added, by default None, which will pick the last use axis via `gca`.
 
@@ -185,7 +185,7 @@ def colorvec(field, axis=None, **kwargs):
     """
     _log.debug('Calling colorvec')
     if not isinstance(field, Field):  # Try to convert input to Field if it is not already one:
-        field = Field(data=np.asarray(field), scale=1, vector=True)
+        field = Field(data=np.asarray(field), scale=1.0, vector=True)
     assert field.vector, 'Can only plot vector fields!'
     assert len(field.dim) <= 3, 'Unusable for vector fields with dimension higher than 3!'
     assert len(field.dim) == field.ncomp, ('Assignment of vector components to dimensions is ambiguous!'
@@ -216,7 +216,7 @@ def cosine_contours(field, axis=None, gain='auto', cmap=None, **kwargs):
     Parameters
     ----------
     field : `Field` or ndarray
-        The contour data as a `Field` or a numpy array (in the latter case, `vector=False` and `scale=1` are assumed).
+        The contour data as a `Field` or a numpy array (in the latter case, `vector=False` and `scale=1.0` are assumed).
     axis : `matplotlib.axes.Axes` object, optional
         The axis to which the contour should be added, by default None, which will pick the last use axis via `gca`.
     gain : float or 'auto', optional
@@ -241,7 +241,7 @@ def cosine_contours(field, axis=None, gain='auto', cmap=None, **kwargs):
     """
     _log.debug('Calling cosine_contours')
     if not isinstance(field, Field):  # Try to convert input to Field if it is not already one:
-        field = Field(data=np.asarray(field), scale=1, vector=False)
+        field = Field(data=np.asarray(field), scale=1.0, vector=False)
     assert not field.vector, 'Can only plot scalar fields!'
     # Get squeezed data and make sure it's 2D scalar:
     squeezed_field = field.squeeze()
@@ -274,7 +274,7 @@ def quiver(field, axis=None, color_angles=False, cmap=None, n_bin='auto', bin_wi
     Parameters
     ----------
     field : `Field` or ndarray
-        The vector data as a `Field` or a numpy array (in the latter case, `vector=True` and `scale=1` are assumed).
+        The vector data as a `Field` or a numpy array (in the latter case, `vector=True` and `scale=1.0` are assumed).
     axis : `matplotlib.axes.Axes` object, optional
         The axis to which the image should be added, by default None, which will pick the last use axis via `gca`.
     color_angles : bool, optional
@@ -312,7 +312,7 @@ def quiver(field, axis=None, color_angles=False, cmap=None, n_bin='auto', bin_wi
     """
     _log.debug('Calling quiver')
     if not isinstance(field, Field):  # Try to convert input to Field if it is not already one:
-        field = Field(data=np.asarray(field), scale=1, vector=True)
+        field = Field(data=np.asarray(field), scale=1.0, vector=True)
     assert field.vector, 'Can only plot vector fields!'
     assert len(field.dim) <= 3, 'Unusable for vector fields with dimension higher than 3!'
     assert len(field.dim) == field.ncomp, ('Assignment of vector components to dimensions is ambiguous!'

src/empyre/vis/plot3d.py

+# -*- coding: utf-8 -*-
+# Copyright 2020 by Forschungszentrum Juelich GmbH
+# Author: J. Caron
+#
+"""This module provides functions for 3D plots based on the `mayavi` library."""
+
+
+import logging
+
+import numpy as np
+
+from . import colors
+
+
+__all__ = ['contour3d', 'mask3d', 'quiver3d']
+
+_log = logging.getLogger(__name__)
+
+
+# TODO: Docstrings and signature!
+
+def contour3d(field, title='Field Distribution', contours=10, opacity=0.25, size=None, new_fig=True, **kwargs):
+    """Plot a field as a 3D-contour plot.
+
+    Parameters
+    ----------
+    title: string, optional
+        The title for the plot.
+    contours: int, optional
+        Number of contours which should be plotted.
+    opacity: float, optional
+        Defines the opacity of the contours. Default is 0.25.
+
+    Returns
+    -------
+    plot : :class:`mayavi.modules.vectors.Vectors`
+        The plot object.
+
+    """
+    _log.debug('Calling contour3d')
+    try:
+        from mayavi import mlab
+    except ImportError:
+        _log.error('This extension recquires the mayavi package!')
+        return
+    if size is None:
+        size = (750, 700)
+    if new_fig:
+        mlab.figure(size=size, bgcolor=(0.5, 0.5, 0.5), fgcolor=(0., 0., 0.))
+    zzz, yyy, xxx = np.indices(field.dim) + np.reshape(field.scale, (3, 1, 1, 1)) / 2  # shifted by half of scale!
+    zzz, yyy, xxx = zzz.T, yyy.T, xxx.T  # Transpose because of VTK order!
+    field_amp = field.amp.data.T  # Transpose because of VTK order!
+    if not isinstance(contours, (list, tuple, np.ndarray)):  # Calculate the contours:
+        contours = list(np.linspace(field_amp.min(), field_amp.max(), contours))
+    extent = np.ravel(list(zip((0, 0, 0), field_amp.shape)))
+    cont = mlab.contour3d(xxx, yyy, zzz, field_amp, contours=contours, opacity=opacity, **kwargs)
+    mlab.outline(cont, extent=extent)
+    mlab.axes(cont, extent=extent)
+    mlab.title(title, height=0.95, size=0.35)
+    mlab.orientation_axes()
+    cont.scene.isometric_view()
+    return cont
+
+
+def mask3d(field, title='Mask', threshold=0, grid=True, labels=True,
+           orientation=True, size=None, new_fig=True, **kwargs):
+    """Plot the mask as a 3D-contour plot.
+
+    Parameters
+    ----------
+    title: string, optional
+        The title for the plot.
+    threshold : float, optional
+        A pixel only gets masked, if it lies above this threshold . The default is 0.
+
+    Returns
+    -------
+    plot : :class:`mayavi.modules.vectors.Vectors`
+        The plot object.
+
+    """
+    _log.debug('Calling mask3d')
+    try:
+        from mayavi import mlab
+    except ImportError:
+        _log.error('This extension recquires the mayavi package!')
+        return
+    if size is None:
+        size = (750, 700)
+    if new_fig:
+        mlab.figure(size=size, bgcolor=(0.5, 0.5, 0.5), fgcolor=(0., 0., 0.))
+    zzz, yyy, xxx = np.indices(field.dim) + np.reshape(field.scale, (3, 1, 1, 1)) / 2  # shifted by half of scale!
+    zzz, yyy, xxx = zzz.T, yyy.T, xxx.T  # Transpose because of VTK order!
+    mask = field.mask.data.T.astype(int)  # Transpose because of VTK order!
+    extent = np.ravel(list(zip((0, 0, 0), mask.shape)))
+    cont = mlab.contour3d(xxx, yyy, zzz, mask, contours=[1], **kwargs)
+    if grid:
+        mlab.outline(cont, extent=extent)
+    if labels:
+        mlab.axes(cont, extent=extent)
+        mlab.title(title, height=0.95, size=0.35)
+    if orientation:
+        oa = mlab.orientation_axes()
+        oa.marker.set_viewport(0, 0, 0.4, 0.4)
+        mlab.draw()
+    engine = mlab.get_engine()
+    scene = engine.scenes[0]
+    scene.scene.isometric_view()
+    return cont
+
+
+def quiver3d(field, title='Vector Field', limit=None, cmap='jet', mode='2darrow',
+             coloring='angle', ar_dens=1, opacity=1.0, grid=True, labels=True,
+             orientation=True, size=(700, 750), new_fig=True, view='isometric',
+             position=None, bgcolor=(0.5, 0.5, 0.5)):
+    """Plot the vector field as 3D-vectors in a quiverplot.
+
+    Parameters
+    ----------
+    title : string, optional
+        The title for the plot.
+    limit : float, optional
+        Plotlimit for the vector field arrow length used to scale the colormap.
+    cmap : string, optional
+        String describing the colormap which is used for amplitude encoding (default is 'jet').
+    ar_dens: int, optional
+        Number defining the arrow density which is plotted. A higher ar_dens number skips more
+        arrows (a number of 2 plots every second arrow). Default is 1.
+    mode: string, optional
+        Mode, determining the glyphs used in the 3D plot. Default is '2darrow', which
+        corresponds to 2D arrows. For smaller amounts of arrows, 'arrow' (3D) is prettier.
+    coloring : {'angle', 'amplitude'}, optional
+        Color coding mode of the arrows. Use 'angle' (default) or 'amplitude'.
+    opacity: float, optional
+        Defines the opacity of the arrows. Default is 1.0 (completely opaque).
+
+    Returns
+    -------
+    plot : :class:`mayavi.modules.vectors.Vectors`
+        The plot object.
+
+    """
+    _log.debug('Calling quiver_plot3D')
+    try:
+        from mayavi import mlab
+    except ImportError:
+        _log.error('This extension recquires the mayavi package!')
+        return
+    if limit is None:
+        limit = np.max(np.nan_to_num(field.amp))
+    ad = ar_dens
+    # Create points and vector components as lists:
+    zzz, yyy, xxx = (np.indices(field.dim) + 1 / 2)
+    zzz = zzz[::ad, ::ad, ::ad].ravel()
+    yyy = yyy[::ad, ::ad, ::ad].ravel()
+    xxx = xxx[::ad, ::ad, ::ad].ravel()
+    x_mag = field.data[::ad, ::ad, ::ad, 0].ravel()
+    y_mag = field.data[::ad, ::ad, ::ad, 1].ravel()
+    z_mag = field.data[::ad, ::ad, ::ad, 2].ravel()
+    # Plot them as vectors:
+    if new_fig:
+        mlab.figure(size=size, bgcolor=(0.5, 0.5, 0.5), fgcolor=(0., 0., 0.))
+    if coloring == 'angle':  # Encodes the full angle via colorwheel and saturation:
+        _log.debug('Encoding full 3D angles')
+        vecs = mlab.quiver3d(xxx, yyy, zzz, x_mag, y_mag, z_mag, mode=mode, opacity=opacity,
+                             scalars=np.arange(len(xxx)), line_width=2)
+        vector = np.asarray((x_mag.ravel(), y_mag.ravel(), z_mag.ravel()))
+        rgb = colors.CMAP_CIRCULAR_DEFAULT.rgb_from_vector(vector)
+        rgba = np.hstack((rgb, 255 * np.ones((len(xxx), 1), dtype=np.uint8)))
+        vecs.glyph.color_mode = 'color_by_scalar'
+        vecs.module_manager.scalar_lut_manager.lut.table = rgba
+        mlab.draw()
+    elif coloring == 'amplitude':  # Encodes the amplitude of the arrows with the jet colormap:
+        _log.debug('Encoding amplitude')
+        vecs = mlab.quiver3d(xxx, yyy, zzz, x_mag, y_mag, z_mag,
+                             mode=mode, colormap=cmap, opacity=opacity, line_width=2)
+        mlab.colorbar(label_fmt='%.2f')
+        mlab.colorbar(orientation='vertical')
+    else:
+        raise AttributeError('Coloring mode not supported!')
+    vecs.glyph.glyph_source.glyph_position = 'center'
+    vecs.module_manager.vector_lut_manager.data_range = np.array([0, limit])
+    extent = np.ravel(list(zip((0, 0, 0), (field.dim[2], field.dim[1], field.dim[0]))))
+    if grid:
+        mlab.outline(vecs, extent=extent)
+    if labels:
+        mlab.axes(vecs, extent=extent)
+        mlab.title(title, height=0.95, size=0.35)
+    if orientation:
+        oa = mlab.orientation_axes()
+        oa.marker.set_viewport(0, 0, 0.4, 0.4)
+        mlab.draw()
+    engine = mlab.get_engine()
+    scene = engine.scenes[0]
+    if view == 'isometric':
+        scene.scene.isometric_view()
+    elif view == 'x_plus_view':
+        scene.scene.x_plus_view()
+    elif view == 'y_plus_view':
+        scene.scene.y_plus_view()
+    if position:
+        scene.scene.camera.position = position
+    return vecs

src/empyre/vis/tools.py

@@ -23,7 +23,7 @@ __all__ = ['new', 'savefig', 'calc_figsize', 'use_style', 'copy_mpl_stylesheets'
 _log = logging.getLogger(__name__)
 
 
-def new(nrows=1, ncols=1, mode='image', figsize=None, textwidth=None, width_scale=1, aspect=None, **kwargs):
+def new(nrows=1, ncols=1, mode='image', figsize=None, textwidth=None, width_scale=1.0, aspect=None, **kwargs):
     R"""Convenience function for the creation of a new subplot grid (wraps `~matplotlib.pyplot.subplots`).
 
     If you use the `textwidth` parameter, plot sizes are fitting into publications with LaTeX. Requires two stylesheets
@@ -110,7 +110,7 @@ def savefig(fname, **kwargs):
         plt.savefig(fname, **kwargs)
 
 
-def calc_figsize(textwidth, width_scale=1, aspect=1):
+def calc_figsize(textwidth, width_scale=1.0, aspect=1):
     R"""Helper function to calculate the figure size from various parameters. Useful for publications via LaTeX.
 
     Parameters