xiuminglib.vis package¶
Submodules¶
xiuminglib.vis.anim module¶
-
xiuminglib.vis.anim.
make_anim
(imgs, duration=1, outpath=None)[source]¶ Writes a list of images into an animation.
In most cases, we need to label each image, for which you can use
vis.text.put_text()
.Parameters: - imgs (list(numpy.ndarray or str)) – An image is either a path or an
array (mixing ok, but arrays will need to be written to a temporary
directory). If array, should be of type
uint
and of shape H-by-W (grayscale) or H-by-W-by-3 (RGB). - duration (float, optional) – Duration of each frame in seconds.
- outpath (str, optional) – Where to write the output to (a .apng or .gif
file).
None
meansos.path.join(const.Dir.tmp, 'make_anim.gif')
.
- Writes
- An animation of the images.
- imgs (list(numpy.ndarray or str)) – An image is either a path or an
array (mixing ok, but arrays will need to be written to a temporary
directory). If array, should be of type
xiuminglib.vis.general module¶
This module should be imported before skimage
to avoid the
matplotlib
backend problem.
-
xiuminglib.vis.general.
axes3d_wrapper
(*args, func='scatter', labels=None, legend_fontsize=20, legend_loc=0, figsize=(14, 14), figtitle=None, figtitle_fontsize=20, xlabel=None, xlabel_fontsize=20, ylabel=None, ylabel_fontsize=20, zlabel=None, zlabel_fontsize=20, xticks=None, xticks_fontsize=10, xticks_rotation=0, yticks=None, yticks_fontsize=10, yticks_rotation=0, zticks=None, zticks_fontsize=10, zticks_rotation=0, grid=True, views=None, equal_axes=False, outpath=None, **kwargs)[source]¶ Convinience wrapper for
mpl_toolkits.mplot3d.Axes3D
functions.It saves plots directly to the disk without displaying.
Parameters: - *args – Positional parameters that the wrapped function takes. See
mpl_toolkits.mplot3d.Axes3D
. - **kwargs – Keyword parameters.
- func (str, optional) – Which pyplot function to invoke, e.g.,
'scatter'
. - labels (list(str), optional) – Labels for plot objects, to appear in
the legend. Use
None
for no label for a certain object.None
means no legend at all. - legend_loc (str, optional) – Legend location:
'best'
,'upper right'
,'lower left'
,'right'
,'center left'
,'lower center'
,'upper center'
,'center'
, etc. Effective only whenlabels
is notNone
. - figsize (tuple, optional) – Width and height of the figure in inches.
- figtitle (str, optional) – Figure title.
- xlabel (str, optional) – Label of x-axis.
- ylabel –
- zlabel –
- xticks (array_like, optional) – Tick values of x-axis.
None
means auto. - yticks –
- zticks –
- *_fontsize (int, optional) – Font size.
- *_rotation (float, optional) – Tick rotation in degrees.
- grid (bool, optional) – Whether to draw grid.
- views (list(tuple), optional) – List of elevation-azimuth angle pairs
(in degrees). A good set of views is
[(30, 0), (30, 45), (30, 90), (30, 135)]
. - equal_axes (bool, optional) – Whether to have the same scale for all axes.
- outpath (str, optional) – Path to which the visualization is saved to.
Should end with
'.png'
or'.pkl'
(for offline interactive viewing).None
meansos.path.join(const.Dir.tmp, 'axes3d_wrapper.png')
.
- Writes
- One or multiple (if
views
is provided) views of the 3D plot.
- One or multiple (if
- *args – Positional parameters that the wrapped function takes. See
-
xiuminglib.vis.general.
make_colormap
(low, high)[source]¶ Generates your own colormap for heatmap.
Parameters: Returns: Generated colormap.
Return type:
-
xiuminglib.vis.general.
pyplot_wrapper
(*args, ci=None, func='plot', labels=None, legend_fontsize=20, legend_loc=0, figsize=(14, 14), figtitle=None, figtitle_fontsize=20, xlabel=None, xlabel_fontsize=20, ylabel=None, ylabel_fontsize=20, xticks=None, xticks_locations=None, xticks_fontsize=10, xticks_rotation=0, yticks=None, yticks_locations=None, yticks_fontsize=10, yticks_rotation=0, xlim=None, ylim=None, grid=True, outpath=None, **kwargs)[source]¶ Convinience wrapper for
matplotlib.pyplot
functions.It saves plots directly to the disk without displaying.
Parameters: - *args – Positional parameters that the wrapped function takes. See
matplotlib.pyplot
. - **kwargs – Keyword parameters.
- ci (list(float) or list(list(float)), optional) – Confidence interval
for
x_i[j]
isy_i[j] +/- ci[i][j]
. Effective only whenfunc
is'plot'
. List of floats for one line, and list of lists of floats for multiple lines. - func (str, optional) – Which
pyplot
function to invoke, e.g.,'plot'
or'bar'
. - labels (list, optional) – Labels for plot objects, to appear in the
legend.
None
means no label for this object. - legend_loc (str, optional) – Legend location:
'best'
,'upper right'
,'lower left'
,'right'
,'center left'
,'lower center'
,'upper center'
,'center'
, etc. Effective only whenlabels
is notNone
. - figsize (tuple, optional) – Width and height of the figure in inches.
- figtitle (str, optional) – Figure title.
- xlabel (str, optional) – Label of x-axis.
- ylabel –
- xticks (array_like, optional) – Tick values of x-axis.
None
means auto. - yticks –
- xticks_locations (array_like, optional) – Locations of the ticks.
None
means starting from 0 and one next to another. - yticks_locations –
- *_fontsize (int, optional) – Font size.
- *_rotation (float, optional) – Tick rotation in degrees.
- xlim (list, optional) – Start and end values for x-axis.
None
means auto. - ylim –
- grid (bool, optional) – Whether to draw grid.
- outpath (str, optional) – Path to which the visualization is saved to.
None
meansos.path.join(const.Dir.tmp, 'pyplot_wrapper.png')
.
- Writes
- The plot.
- *args – Positional parameters that the wrapped function takes. See
xiuminglib.vis.geometry module¶
-
xiuminglib.vis.geometry.
depth_as_image
(depth_map, alpha_map=None, keep_alpha=False, outpath=None)[source]¶ Visualizes a(n) (aliased) depth map and an (anti-aliased) alpha map as a single depth image.
Output has black background, with bright values for closeness to the camera. If the alpha map is anti-aliased, the result depth map will be nicely anti-aliased.
Parameters: - depth_map (numpy.ndarray) – 2D array of (aliased) raw depth values.
- alpha_map (numpy.ndarray, optional) – 2D array of (anti-aliased) alpha values.
- keep_alpha (bool, optional) – Whether to keep alpha channel in output.
- outpath (str, optional) – Path to which the visualization is saved to.
None
meansos.path.join(const.Dir.tmp, 'depth_as_image.png')
.
- Writes
- The (anti-aliased) depth image.
-
xiuminglib.vis.geometry.
normal_as_image
(normal_map, alpha_map=None, keep_alpha=False, outpath=None)[source]¶ Visualizes the normal map by converting vectors to pixel values.
If not keeping alpha, the background is black, complying with industry standards (e.g., Adobe AE).
Parameters: - normal_map (numpy.ndarray) – H-by-W-by-3 array of normal vectors.
- alpha_map (numpy.ndarray, optional) – H-by-W array of alpha values.
- keep_alpha (bool, optional) – Whether to keep alpha channel in output.
- outpath (str, optional) – Path to which the visualization is saved to.
None
meansos.path.join(const.Dir.tmp, 'normal_as_image.png')
.
- Writes
- The normal image.
xiuminglib.vis.html module¶
-
class
xiuminglib.vis.html.
HTML
(title='Results', bgcolor='black', text_font='roboto', text_color='white')[source]¶ Bases:
object
HTML Builder.
-
__init__
(title='Results', bgcolor='black', text_font='roboto', text_color='white')[source]¶ Parameters:
-
xiuminglib.vis.matrix module¶
-
xiuminglib.vis.matrix.
matrix_as_heatmap
(mat, cmap='viridis', center_around_zero=False, outpath=None, contents_only=False, figtitle=None)[source]¶ Visualizes a matrix as heatmap.
Parameters: - mat (numpy.ndarray) – Matrix to visualize as heatmp. May contain NaN’s, which will be plotted white.
- cmap (str, optional) – Colormap to use.
- center_around_zero (bool, optional) – Whether to center colorbar around
0 (so that zero is no color, i.e., white). Useful when matrix
consists of both positive and negative values, and 0 means
“nothing”.
None
means default colormap and auto range. - outpath (str, optional) – Path to which the visualization is saved to.
None
meansos.path.join(const.Dir.tmp, 'matrix_as_heatmap.png')
. - contents_only (bool, optional) – Whether to plot only the contents
(i.e., no borders, axes, etc.). If
True
, the heatmap will be of exactly the same size as your matrix, useful when you want to plot heatmaps separately and later concatenate them into a single one. - figtitle (str, optional) – Figure title.
None
means no title.
- Writes
- A heatmap of the matrix.
-
xiuminglib.vis.matrix.
matrix_as_heatmap_complex
(*args, **kwargs)[source]¶ Wraps
matrix_as_heatmap()
for complex number support.Just pass in the parameters that
matrix_as_heatmap()
takes.'_mag'
and'_phase'
will be appended tooutpath
to produce the magnitude and phase heatmaps, respectively. Specifically, magnitude is computed bynumpy.absolute()
, and phase bynumpy.angle()
.- Writes
- A magnitude heatmap with
'_mag'
in its filename. - A phase heatmap with
'_phase'
in its filename.
- A magnitude heatmap with
xiuminglib.vis.plot module¶
-
class
xiuminglib.vis.plot.
Plot
(legend_fontsize=20, legend_loc=0, figsize=(14, 14), figtitle=None, figtitle_fontsize=20, xlabel=None, xlabel_fontsize=20, ylabel=None, ylabel_fontsize=20, zlabel=None, zlabel_fontsize=20, xlim=None, ylim=None, zlim=None, xticks=None, xticks_fontsize=10, xticks_rotation=0, yticks=None, yticks_fontsize=10, yticks_rotation=0, zticks=None, zticks_fontsize=10, zticks_rotation=0, grid=True, labels=None, outpath=None)[source]¶ Bases:
object
-
__init__
(legend_fontsize=20, legend_loc=0, figsize=(14, 14), figtitle=None, figtitle_fontsize=20, xlabel=None, xlabel_fontsize=20, ylabel=None, ylabel_fontsize=20, zlabel=None, zlabel_fontsize=20, xlim=None, ylim=None, zlim=None, xticks=None, xticks_fontsize=10, xticks_rotation=0, yticks=None, yticks_fontsize=10, yticks_rotation=0, zticks=None, zticks_fontsize=10, zticks_rotation=0, grid=True, labels=None, outpath=None)[source]¶ Plotter.
Parameters: - legend_fontsize (int, optional) – Legend font size.
- legend_loc (str, optional) – Legend location:
'best'
,'upper right'
,'lower left'
,'right'
,'center left'
,'lower center'
,'upper center'
,'center'
, etc. Effective only whenlabels
is notNone
. - figsize (tuple, optional) – Width and height of the figure in inches.
- figtitle (str, optional) – Figure title.
- *_fontsize (int, optional) – Font size.
- ?label (str, optional) – Axis labels.
- ?lim (array_like, optional) – Axis min. and max.
None
means auto. - ?ticks (array_like, optional) – Axis tick values.
None
means auto. - ?ticks_rotation (float, optional) – Tick rotation in degrees.
- grid (bool, optional) – Whether to draw grid.
- labels (list, optional) – Labels.
- outpath (str, optional) – Path to which the plot is saved to. Should
end with
'.png'
, andNone
means toconst.Dir.tmp
.
-
bar
(y, group_width=0.8)[source]¶ Bar plot.
Parameters: - y (array_like) – N-by-M array of N groups, each with M bars, or N-array of N groups, each with one bar.
- group_width (float, optional) – Width allocated to each group, shared by all bars within the group.
- Writes
- The bar plot.
-
line
(xy, width=None, marker=None, marker_size=None)[source]¶ Line/curve plot.
Parameters: - Writes
- The line plot.
-
scatter3d
(xyz, colors=None, size=None, equal_axes=False, views=None)[source]¶ 3D scatter plot.
Parameters: - xyz (array_like) – N-by-3 array of N points.
- colors (array_like or list(str) or str, optional) – If N-array, these values are colormapped. If N-list, its elements should be color strings. If a single color string, all points use that color.
- size (int, optional) – Scatter size.
- equal_axes (bool, optional) – Whether to have the same scale for all axes.
- views (list(tuple), optional) – List of elevation-azimuth angle pairs
(in degrees). A good set of views is
[(30, 0), (30, 45), (30, 90), (30, 135)]
.
- Writes
- One or multiple (if
views
is provided) views of the 3D plot.
- One or multiple (if
-
xiuminglib.vis.pt module¶
-
xiuminglib.vis.pt.
scatter_on_img
(pts, im, size=2, bgr=(0, 0, 255), outpath=None)[source]¶ Plots scatter on top of an image or just a white canvas, if you are being creative by feeding in just a white image.
Parameters: - pts (array_like) –
Pixel coordinates of the scatter point(s), of length 2 for just one point or shape N-by-2 for multiple points. Convention:
+-----------> dim1 | | | v dim0
- im (numpy.ndarray) – Image to scatter on. H-by-W (grayscale) or
H-by-W-by-3 (RGB) arrays of
unint
type. - size (float or array_like(float), optional) – Size(s) of scatter points. If array_like, must be of length N.
- bgr (tuple or array_like(tuple), optional) – BGR color(s) of scatter points. Each element \(\in [0, 255]\). If array_like, must be of shape N-by-3.
- outpath (str, optional) – Path to which the visualization is saved to.
None
meansos.path.join(const.Dir.tmp, 'scatter_on_img.png')
.
- Writes
- The scatter plot overlaid over the image.
- pts (array_like) –
-
xiuminglib.vis.pt.
uv_on_texmap
(uvs, texmap, ft=None, outpath=None, max_n_lines=None, dotsize=4, dotcolor='r', linewidth=1, linecolor='b')[source]¶ Visualizes which points on texture map the vertices map to.
Parameters: - uvs (numpy.ndarray) – N-by-2 array of UV coordinates. See
xiuminglib.blender.object.smart_uv_unwrap()
for the UV coordinate convention. - texmap (numpy.ndarray or str) – Loaded texture map or its path. If numpy.ndarray, can be H-by-W (grayscale) or H-by-W-by-3 (color).
- ft (list(list(int)), optional) – Texture faces used to connect the
UV points. Values start from 1, e.g.,
'[[1, 2, 3], [], [2, 3, 4, 5], ...]'
. - outpath (str, optional) – Path to which the visualization is saved to.
None
meansos.path.join(const.Dir.tmp, 'uv_on_texmap.png')
. - max_n_lines (int, optional) – Plotting a huge number of lines can be
slow, so set this to uniformly sample a subset to plot. Useless if
ft
isNone
. - dotsize (int or list(int), optional) – Size(s) of the UV dots.
- dotcolor (str or list(str), optional) – Their color(s).
- linewidth (float, optional) – Width of the lines connecting the dots.
- linecolor (str, optional) – Their color.
- Writes
- An image of where the vertices map to on the texture map.
- uvs (numpy.ndarray) – N-by-2 array of UV coordinates. See
xiuminglib.vis.text module¶
-
xiuminglib.vis.text.
put_text
(img, text, label_top_left_xy=None, font_size=None, font_color=(1, 0, 0), font_ttf=None)[source]¶ Puts text on image.
Parameters: - img (numpy.ndarray) – Should be of type
uint
and of shape H-by-W (grayscale) or H-by-W-by-3 (RGB). - text (str) – Text to be written on the image.
- label_top_left_xy (tuple(int), optional) – The XY coordinate of the label’s top left corner.
- font_size (int, optional) – Font size.
- font_color (tuple(float), optional) – Font RGB, normalized to \([0,1]\). Defaults to red.
- font_ttf (str, optional) – Path to the .ttf font file. Defaults to Arial.
Returns: The modified image with text.
Return type: - img (numpy.ndarray) – Should be of type
-
xiuminglib.vis.text.
text_as_image
(text, imsize=256, thickness=2, dtype='uint8', outpath=None, quiet=False)[source]¶ Rasterizes a text string into an image.
The text will be drawn in white to the center of a black canvas. Text size gets automatically figured out based on the provided thickness and image size.
Parameters: - text (str) – Text to be drawn.
- imsize (float or tuple(float), optional) – Output image height and width.
- thickness (float, optional) – Text thickness.
- dtype (str, optional) – Image type.
- outpath (str, optional) – Where to dump the result to.
None
means returning instead of writing it. - quiet (bool, optional) – Whether to refrain from logging.
Effective only when
outpath
is notNone
.
- Returns or Writes
- An image of the text.
xiuminglib.vis.video module¶
-
xiuminglib.vis.video.
make_comparison_video
(imgs1, imgs2, bar_width=4, bar_color=(1, 0, 0), sweep_vertically=False, sweeps=1, label1='', label2='', font_size=None, font_ttf=None, label1_top_left_xy=None, label2_top_left_xy=None, **make_video_kwargs)[source]¶ Writes two lists of images into a comparison video that toggles between two videos with a sweeping bar.
Parameters: - imgs? (list(numpy.ndarray)) – Each image should be of type
uint8
oruint16
and of shape H-by-W (grayscale) or H-by-W-by-3 (RGB). - bar_width (int, optional) – Width of the sweeping bar.
- bar_color (tuple(float), optional) – Bar and label RGB, normalized to \([0,1]\). Defaults to red.
- sweep_vertically (bool, optional) – Whether to sweep vertically or horizontally.
- sweeps (int, optional) – Number of sweeps.
- label? (str, optional) – Label for each video.
- font_size (int, optional) – Font size.
- font_ttf (str, optional) – Path to the .ttf font file. Defaults to Arial.
- label?_top_left_xy (tuple(int), optional) – The XY coordinate of the label’s top left corner.
- make_video_kwargs (dict, optional) – Keyword arguments for
make_video()
.
- Writes
- A comparison video.
- imgs? (list(numpy.ndarray)) – Each image should be of type
-
xiuminglib.vis.video.
make_video
(imgs, fps=24, outpath=None, method='matplotlib', dpi=96, bitrate=-1)[source]¶ Writes a list of images into a grayscale or color video.
Parameters: - imgs (list(numpy.ndarray)) – Each image should be of type
uint8
oruint16
and of shape H-by-W (grayscale) or H-by-W-by-3 (RGB). - fps (int, optional) – Frame rate.
- outpath (str, optional) – Where to write the video to (a .mp4 file).
None
meansos.path.join(const.Dir.tmp, 'make_video.mp4')
. - method (str, optional) – Method to use:
'matplotlib'
,'opencv'
,'video_api'
. - dpi (int, optional) – Dots per inch when using
matplotlib
. - bitrate (int, optional) – Bit rate in kilobits per second when using
matplotlib
; reasonable values include 7200.
- Writes
- A video of the images.
- imgs (list(numpy.ndarray)) – Each image should be of type