Visualization

See Live Plotting for user documentation!

Matplotlib

class libertem.viz.mpl.MPLLive2DPlot(dataset, udf, roi=None, channel=None, title=None, min_delta=0.5, udfresult=None, **kwargs)[source]

Matplotlib-based live plot

New in version 0.7.0.

Parameters:

  • dataset (DataSet) – The dataset on which the UDF will be run. This allows to determine the shape of the plots for initialization.

  • udf (UDF) – The UDF instance this plot is associated to. This needs to be the same instance that is passed to run_udf().

  • roi (numpy.ndarray or None) – Region of interest (ROI) that the UDF will be run on. This is necessary for UDFs where the extra_shape parameter of result buffers is a function of the ROI, such as PickUDF.

  • channel (misc) –

    Indicate the channel to be plotted.

    • None: The first plottable (2D) channel of the UDF is plotted.

    • str: The UDF result buffer name that should be plotted.

    • tuple(str, function(ndarray) -> ndarray): The UDF result buffer name that should be plotted together with a function that extracts a plottable result

    • function(udf_result, damage) -> (ndarray, damage): Function that derives a plottable 2D ndarray and damage indicator from the full UDF results and the processed nav space. See Live Plotting for more details!

  • title (str) – The plot title. By default UDF class name and channel name.

  • min_delta (float) – Minimum time span in seconds between updates to reduce overheads for slow plotting.

  • udfresult (UDFResults, optional) – UDF result to initialize the plot data and determine plot shape. If None (default), this is determined using dry_run() on the dataset, UDF and ROI. This parameter allows re-using buffers to avoid unnecessary dry runs.

  • **kwargs – Passed on to imshow

display()[source]

Show the plot, for example in the current Jupyter cell.

update(damage, force=False)[source]

Update the plot based on self.data.

Parameters:

force (bool) – Force an update, disabling any throttling mechanisms

bqplot

class libertem.viz.bqp.BQLive2DPlot(dataset, udf, roi=None, channel=None, title=None, min_delta=0.016666666666666666, udfresult=None)[source]

bqplot-image-gl-based live plot.

New in version 0.7.0.

Parameters:

  • dataset (DataSet) – The dataset on which the UDF will be run. This allows to determine the shape of the plots for initialization.

  • udf (UDF) – The UDF instance this plot is associated to. This needs to be the same instance that is passed to run_udf().

  • roi (numpy.ndarray or None) – Region of interest (ROI) that the UDF will be run on. This is necessary for UDFs where the extra_shape parameter of result buffers is a function of the ROI, such as PickUDF.

  • channel (misc) –

    Indicate the channel to be plotted.

    • None: The first plottable (2D) channel of the UDF is plotted.

    • str: The UDF result buffer name that should be plotted.

    • tuple(str, function(ndarray) -> ndarray): The UDF result buffer name that should be plotted together with a function that extracts a plottable result

    • function(udf_result, damage) -> (ndarray, damage): Function that derives a plottable 2D ndarray and damage indicator from the full UDF results and the processed nav space. See Live Plotting for more details!

  • title (str) – The plot title. By default UDF class name and channel name.

  • min_delta (float) – Minimum time span in seconds between updates to reduce overheads for slow plotting.

  • udfresult (UDFResults, optional) – UDF result to initialize the plot data and determine plot shape. If None (default), this is determined using dry_run() on the dataset, UDF and ROI. This parameter allows re-using buffers to avoid unnecessary dry runs.

display()[source]

Show the plot, for example in the current Jupyter cell.

update(damage, force=False)[source]

Update the plot based on self.data.

Parameters:

  • damage (numpy.ndarray Boolean array with the shape of) – self.data. It is True for all positions in self.data that contain finite values and have potentially been touched by the UDF. This can be used to extract the correct plot range by ignoring invalid buffer portions.

  • force (bool Force an update, disabling any throttling mechanisms) –

GMS

class libertem.viz.gms.GMSLive2DPlot(dataset, udf, roi=None, channel=None, title=None, min_delta=0.2, udfresult=None)[source]

Live plot for Gatan Microscopy Suite, Digital Micrograph (experimental).

This works with Python scripting within GMS

New in version 0.7.0.

Parameters:

  • dataset (DataSet) – The dataset on which the UDF will be run. This allows to determine the shape of the plots for initialization.

  • udf (UDF) – The UDF instance this plot is associated to. This needs to be the same instance that is passed to run_udf().

  • roi (numpy.ndarray or None) – Region of interest (ROI) that the UDF will be run on. This is necessary for UDFs where the extra_shape parameter of result buffers is a function of the ROI, such as PickUDF.

  • channel (misc) –

    Indicate the channel to be plotted.

    • None: The first plottable (2D) channel of the UDF is plotted.

    • str: The UDF result buffer name that should be plotted.

    • tuple(str, function(ndarray) -> ndarray): The UDF result buffer name that should be plotted together with a function that extracts a plottable result

    • function(udf_result, damage) -> (ndarray, damage): Function that derives a plottable 2D ndarray and damage indicator from the full UDF results and the processed nav space. See Live Plotting for more details!

  • title (str) – The plot title. By default UDF class name and channel name.

  • min_delta (float) – Minimum time span in seconds between updates to reduce overheads for slow plotting.

  • udfresult (UDFResults, optional) – UDF result to initialize the plot data and determine plot shape. If None (default), this is determined using dry_run() on the dataset, UDF and ROI. This parameter allows re-using buffers to avoid unnecessary dry runs.

display()[source]

Use DM.ShowImage() to create an image display.

update(damage, force=False)[source]

Update the plot based on self.data.

Parameters:

  • damage (numpy.ndarray Boolean array with the shape of) – self.data. It is True for all positions in self.data that contain finite values and have potentially been touched by the UDF. This can be used to extract the correct plot range by ignoring invalid buffer portions.

  • force (bool Force an update, disabling any throttling mechanisms) –

Base classes and functions

class libertem.viz.base.Dummy2DPlot(dataset, udf, roi=None, channel=None, title=None, min_delta=0, udfresult=None)[source]

No-op plot. This is useful for test and example code to not attempt displaying matplotlib plots in a headless environment or during batch operation.

display()[source]

Show the plot, for example in the current Jupyter cell.

update(damage, force=False)[source]

Update the plot based on self.data.

Parameters:

  • damage (numpy.ndarray Boolean array with the shape of) – self.data. It is True for all positions in self.data that contain finite values and have potentially been touched by the UDF. This can be used to extract the correct plot range by ignoring invalid buffer portions.

  • force (bool Force an update, disabling any throttling mechanisms) –

class libertem.viz.base.Live2DPlot(dataset, udf, roi=None, channel=None, title=None, min_delta=0, udfresult=None)[source]

Base plotting class for interactive use. Please see the subclasses for concrete details.

New in version 0.7.0.

Parameters:

  • dataset (DataSet) – The dataset on which the UDF will be run. This allows to determine the shape of the plots for initialization.

  • udf (UDF) – The UDF instance this plot is associated to. This needs to be the same instance that is passed to run_udf().

  • roi (numpy.ndarray or None) – Region of interest (ROI) that the UDF will be run on. This is necessary for UDFs where the extra_shape parameter of result buffers is a function of the ROI, such as PickUDF.

  • channel (misc) –

    Indicate the channel to be plotted.

    • None: The first plottable (2D) channel of the UDF is plotted.

    • str: The UDF result buffer name that should be plotted.

    • tuple(str, function(ndarray) -> ndarray): The UDF result buffer name that should be plotted together with a function that extracts a plottable result

    • function(udf_result, damage) -> (ndarray, damage): Function that derives a plottable 2D ndarray and damage indicator from the full UDF results and the processed nav space. See Live Plotting for more details!

  • title (str) – The plot title. By default UDF class name and channel name.

  • min_delta (float) – Minimum time span in seconds between updates to reduce overheads for slow plotting.

  • udfresult (UDFResults, optional) – UDF result to initialize the plot data and determine plot shape. If None (default), this is determined using dry_run() on the dataset, UDF and ROI. This parameter allows re-using buffers to avoid unnecessary dry runs.

display()[source]

Show the plot, for example in the current Jupyter cell.

extract(udf_results: dict[str, BufferWrapper], damage: BufferWrapper) → tuple[ndarray, ndarray][source]

Extract plotting data from UDF result.

Parameters:

  • udf_results (UDF result) – (Partial) UDF result

  • damage (BufferWrapper) – BufferWraper with kind='nav' and dtype=bool that indicates the area of the nav dimension that has been processed by the UDF already.

Returns:

It returns the data and damage of a UDF result buffer indicated by channel if that is a string, or a numpy.ndarray and damage derived from the UDF results by calling channel with this method’s arguments if it is callable.

Return type:

(numpy.ndarray, damage)

get_udf()[source]

Returns the associated UDF instance

new_data(udf_results: dict[str, BufferWrapper], damage, force: bool = False)[source]

This method is called with the raw udf_results any time a new partition has finished processing.

The damage parameter is filtered to only cover finite values of self.data and passed to self.update(), which should then be implemented by a subclass.

update(damage, force=False)[source]

Update the plot based on self.data.

Parameters:

  • damage (numpy.ndarray Boolean array with the shape of) – self.data. It is True for all positions in self.data that contain finite values and have potentially been touched by the UDF. This can be used to extract the correct plot range by ignoring invalid buffer portions.

  • force (bool Force an update, disabling any throttling mechanisms) –

libertem.viz.base.visualize_simple(result, colormap=None, logarithmic=False, vmin=None, vmax=None, damage=None)[source]

Normalize and visualize result with colormap and return the resulting RGBA data as an array.

Parameters:

  • result (numpy.ndarray) – 2d array of intensity values

  • colormap (matplotlib colormap or None) – colormap used for visualizing intensity values, defaults to matplotlib.cm.gist_earth

Returns:

A numpy array of shape (Y, X, 4) containing RGBA data, suitable for passing to Image.fromarray in PIL.

Return type:

np.array

libertem.common.viz.encode_image(result, save_kwargs: dict | None = None) → BytesIO[source]

Save the RGBA data in result to an image with parameters save_kwargs passed to PIL.Image.save.

Parameters:

  • result (numpy.ndarray) – Array of RGB values; shape (height, width, 3)

  • save_kwargs (dict or None) – dict of kwargs passed to Pillow when saving the image, can be used to set the file format, quality, …

Returns:

a buffer containing the result image (as PNG/JPG/… depending on save_kwargs)

Return type:

BytesIO