Matplotlib Utilities

matplotlib_utils.axes_equal_3d(ax=None)

Mimic Matlab’s axis equal command. The matplotlib’s command ax.set_aspect(“equal”) only works for 2D plots, but not for 3D plots (those generated with projection=”3d”).

Parameters:

ax: axes, optional

The axes whose x,y,z axis to be equalized. If not specified, default to plt.gca().

matplotlib_utils.draw_with_fixed_lims(ax, draw_fcn)

Perform plot without changing the xlims and ylims of the axes.

Save the xlim and ylim of ax before a drawing action, and restore them after the drawing. This is typically useful when one first does an imshow and then makes some annotation with plot, which will change the limits if not using this function.

matplotlib_utils.impixelinfo(ax=None, image=None)

Mimic Matlab’s impixelinfo function that shows the image pixel information as the cursor swipes through the figure.

Parameters:

ax: axes

The axes that tracks cursor movement and prints pixel information. We require the ax.images list to be non-empty, and if more than one images present in that list, we examine the last (newest) one. If not specified, default to ‘plt.gca()’.

image: ndarray

If specified, use this image‘s pixel instead of ax.images[-1]‘s. The replacement image must have the same dimension as ax.images[-1], and we will still be using the extent of the latter when tracking cursor movement.

Returns:

None

matplotlib_utils.implay(volume, fps=20, ax=None, **kw)

Play a sequence of image in volume as a video.

Parameters:

volume: ndarray

The video volume to be played. Its size can be either MxNxK (for single-channel image per frame) or MxNxCxK (for multi-channel image per frame).

fps: int, optional

The frame rate of the video.

ax: axes, optional

The axes in which the video to be played. If not specified, default to plt.gca().

**kw: key-value pairs

Other parameters to be passed to ax.imshow, e.g. cmap=”gray”, vmin=0, vmax=1, etc.

matplotlib_utils.imshow(ax, img, xlim=None, ylim=None, **kw)

Enhance ax.imshow with coordinate limits.

Parameters:

ax: axes

The axes in which an image will be drawn.

img: ndarray

The 2D image to be drawn.

xlim, ylim: 2-tuple, optional

This will set the extent parameter of ax.imshow, which is relatively inconvenient to set directly because of the half-pixel issue. Default: (0, num_cols-1), (0, num_rows-1).

**kw: key-value pairs

Other parameters to be passed to ax.imshow. The extent will be ignored if presented.

Returns:

The AxesImage returned by ax.imshow.

matplotlib_utils.tight_subplot(num_rows, num_cols, plot_index, gap=0.01, marg_h=0.01, marg_w=0.01, fig=None)

Add a tight subplot axis to the current (or a given) figure.

Parameters:

num_rows, num_cols: int

Number of rows / columns.

plot_index: int

The index to the subplot.

gap: float between (0,1), optional

The gap between axes, scalar or 2-tuple (gap_h, gap_w).

marg_h: float between (0,1), optional

The margins in height, scalar or 2-tuple (lower, upper).

marg_w: float between (0,1), optional

The margins in width, scalar or 2-tuple (left, right).

fig: Figure, optional

Figure to which the new axes to be added to. Default to plt.gcf() if not specified.

Returns:

The newly added axes.