povplot

A library for rendering triangular grids with Povray.

The functions triplot() (for matplotlib figures) and render_triplot() (standalone) render a 3D triangular grid using Povray, with an interface similar to matplotlib.axes.Axes.tripcolor(). If you want more control over the scene, use render() (standalone).

povplot.render(dst, *, scene, size, antialias=False, transparent=False, scene_args=None, nprocs=None, imgtype=None)

Render scene to dst using Jinja2 and Povray.

scene should be a valid Povray script. The script is preprocessed with Jinja2 with dictionary scene_args as context. Jinja2 is preloaded with a povplot module containing the following macros:

povplot.global_settings(assumed_gamma=1.0, mm_per_unit=10)

A global_settings statement with the following parameters.

Parameters:

Additional statements can be added to the body of the macro.

povplot.camera(location=(0, 0, 0), sky=(0, 1, 0), look_at=(0, 0, 1), focal_point=(0, 0, 1), focal_length=50)

A camera statement with the following parameters:

Parameters:

  • location (3d vector, default: (0,0,0)) – The location of the camera. See location.

  • look_at (3d vector, default: (0,0,1)) – The point the camera looks at. See look_at.

  • sky (3d vector, default: (0,1,0)) – This orientates the camera such that a line from location to sky is displayed upward. See sky.

  • focal_point (3d vector, default: (0,0,1)) – The focal point of the camera. See focal_point.

  • focal_length (float, default: 50) – The focal length of the camera. This defines the angle parameter based on the 35 mm equivalent focal length rule.

povplot.light_source_point(position=(0, 1, 0), color='srgb 1')

A simple point light statement.

Parameters:

  • position (3d vector, default: (0,1,0)) – The position of the point light source.

  • color (str, default: 'srgb 1') – The color of the point light source. See color expressions.

povplot.mesh2(vertices, triangles, normals=None, uv=None)

A triangular grid statement. Textures can be defined in the body of the macro.

Parameters:

  • vertices (numpy.ndarray with shape (nverts,3)) – The vertices of the triangulation.

  • triangles (numpy.ndarray with shape (ntriangles,3) and dtype int) – The indices of vertices defining the triangles.

  • normals (numpy.ndarray with shape (nverts,3), optional) – The outward normals at the vertices.

  • uv (numpy.ndarray with shape (nverts,2), optional) – UV-coordinate per vertex. This can be used for texture mapping. See uv mapping.

povplot.tripcolor(vertices, triangles, normals=None, values=None, cmap=None, norm=None, vmin=None, vmax=None)

Render a triangular grid with a matplotlib colormap.

Parameters:

  • vertices (numpy.ndarray with shape (nverts,3)) – The vertices of the triangulation.

  • triangles (numpy.ndarray with shape (ntriangles,3) and dtype int) – The indices of vertices defining the triangles.

  • normals (numpy.ndarray with shape (nverts,3), optional) – The outward normals at the vertices.

  • values (numpy.ndarray with shape (nverts,), optional) – The values of the vertices. These will be mapped to a color.

  • cmap (str or matplotlib.colors.Colormap, optional) – The name or an instance of a matplotlib colormap to be applied to the normalized values.

  • norm (matplotlib.colors.Normalize, optional) – The normalization of values to the range [0,1], applied before colormapping.

  • vmin (float, optional) – The minimum value of the normalization.

  • vmax (float, optional) – The maximum value of the normalization.

povplot.lines(vertices, lines, radius, color='srgb 0')

Render lines with a uniform color.

Parameters:

  • vertices (numpy.ndarray with shape (nverts,3)) – The vertices of the triangulation.

  • lines (numpy.ndarray with shape (nlines,2) and dtype int) – The indices of vertices defining the lines.

  • radius (float) – The radius of the lines.

  • color (str, default: 'srgb 0') –

    The color of the lines. See color expressions.

Parameters:

  • dst (str, os.PathLike or io.IOBase) – The destination of the rendered image. Should be a str or path-like object, or a file opened for writing binary data.

  • scene (str) – The Povray scene to render. The scene is preprocessed using Jinja2 with scene_args.

  • size (tuple of two ints) – The size (width, height) of the rendered image.

  • antialias (bool, default: False) – Let Povray produce an antialiased image.

  • transparent (bool, default: False) – Let Povray produce an image with transparency.

  • scene_args (collections.abc.Mapping, optional) – Dictionary of scene arguments passed to Jinja2 when rendering the scene.

  • nprocs (int, default: 1) – Number of threads Povray may use to render the image.

  • imgtype (str, default: 'png') – The type of the rendered image: only 'png' is suppored. If absent the type is determined based on dst.

Raises:

PovrayError – If Povray returns an error.

povplot.render_triplot(dst, *, size, vertices, triangles, values, lines=None, line_radius=None, line_color=None, cmap=None, norm=None, vmin=None, vmax=None, normals=None, camera=None, mm_per_unit=10, antialias=False, transparent=False, nprocs=None, imgtype=None)

Render a triangular grid with Povray.

Parameters:

  • dst (str, os.PathLike or io.IOBase) – The destination of the rendered image. Should be a str or path-like object, or a file opened for writing binary data.

  • size (tuple of two ints) – The size (width, height) of the rendered image.

  • vertices (numpy.ndarray with shape (nverts,3)) – The vertices of the triangulation.

  • triangles (numpy.ndarray with shape (ntriangles,3) and dtype int) – The indices of vertices defining the triangles.

  • values (numpy.ndarray with shape (nverts,)) – The values of the vertices. These will be mapped to a color.

  • normals (numpy.ndarray with shape (nverts,3), optional) – The outward normals at the vertices.

  • cmap (str or matplotlib.colors.Colormap, optional) – The name or an instance of a matplotlib colormap to be applied to the normalized values.

  • norm (matplotlib.colors.Normalize, optional) – The normalization of values to the range [0,1], applied before colormapping.

  • vmin (float, optional) – The minimum value of the normalization.

  • vmax (float, optional) – The maximum value of the normalization.

  • camera (collections.abc.Mapping, optional) – The position and orientation of the camera. If absent the camera is positioned such that the triangulation is completely in view. While optional, users are encouraged to define the camera manually as the autopositioning may change in the future. See the Jinja2 macro povplot.camera() for the possible settings.

  • mm_per_unit (float, default: 10) –

  • antialias (bool, default: False) – Let Povray produce an antialiased image.

  • transparent (bool, default: False) – Let Povray produce an image with transparency.

  • nprocs (int, default: 1) – Number of threads Povray may use to render the image.

  • imgtype (str, default: 'png') – The type of the rendered image: only 'png' is suppored. If absent the type is determined based on dst.

Raises:

PovrayError – If Povray returns an error.

Example

The following example renders a unit square, subdivided in two triangles, with a linear color gradient:

>>> render_triplot('example.png',
...                vertices=[[0,0,0],[0,1,0],[1,0,0],[1,1,0]],
...                triangles=[[0,1,2],[1,3,2]],
...                values=[0,1,2,3],
...                size=(800,600))
povplot.triplot(ax, *, vertices, triangles, values, lines=None, line_radius=None, line_color=None, normals=None, cmap=None, norm=None, vmin=None, vmax=None, camera=None, mm_per_unit=10, antialias=False, transparent=False, nprocs=None, hide_frame=False, hide_ticks=True)

Plot a triangular grid in a matplotlib axes.

Parameters:

  • ax (matplotlib.axes.Axes) – The matplotlib axes to render into.

  • vertices (numpy.ndarray with shape (nverts,3)) – The vertices of the triangulation.

  • triangles (numpy.ndarray with shape (ntriangles,3) and dtype int) – The indices of vertices defining the triangles.

  • values (numpy.ndarray with shape (nverts,)) – The values of the vertices. These will be mapped to a color.

  • normals (numpy.ndarray with shape (nverts,3), optional) – The outward normals at the vertices.

  • cmap (str or matplotlib.colors.Colormap, optional) – The name or an instance of a matplotlib colormap to be applied to the normalized values.

  • norm (matplotlib.colors.Normalize, optional) – The normalization of values to the range [0,1], applied before colormapping.

  • vmin (float, optional) – The minimum value of the normalization.

  • vmax (float, optional) – The maximum value of the normalization.

  • camera (collections.abc.Mapping, optional) – The position and orientation of the camera. If absent the camera is positioned such that the triangulation is completely in view. While optional, users are encouraged to define the camera manually as the autopositioning may change in the future. See the Jinja2 macro povplot.camera() for the possible settings.

  • mm_per_unit (float, default: 10) –

  • antialias (bool, default: False) – Let Povray produce an antialiased image.

  • transparent (bool, default: False) – Let Povray produce an image with transparency.

  • nprocs (int, default: 1) – Number of threads Povray may use to render the image.

  • hide_frame (bool, default: False) – Hide the frame of the axes ax.

  • hide_ticks (bool, default: True) – Hide the ticks of the axes ax.

Returns:

triplot – A matplotlib artist and scalar mappable.

Return type:

AxesTriplot

Raises:

PovrayError – If Povray returns an error.

Example

The following example renders a unit square, subdivided in two triangles, with a linear color gradient:

>>> import matplotlib.figure
>>> fig = matplotlib.figure.Figure()
>>> ax = fig.add_subplot(111)
>>> im = triplot(ax,
...              vertices=[[0,0,0],[0,1,0],[1,0,0],[1,1,0]],
...              triangles=[[0,1,2],[1,3,2]],
...              values=[0,1,2,3])
>>> fig.colorbar(im, ax=ax)
povplot.overlay_colorbar(fig, sm, *, colorbar_width=0.2, label_width=0.5, margin=0.2, background=(1, 1, 1, 0.5))

Add a colorbar to a matplotlib figure.

Parameters:

  • fig (matplotlib.figure.Figure) – The figure to add the colorbar to.

  • sm (matplotlib.cm.ScalarMappable) – The ScalarMappable to which the colorbar applies.

  • colorbar_width (float, default: 0.2) – The width of the colorbar.

  • label_width (float, default: 0.5) – The size reserved for the tick labels.

  • margin (float, default: 0.2) – The margin around the colorbar.

  • background (tuple of length 3 or 4, default: (1,1,1,0.5)) – The background of the colorbar axes, margin included.

Returns:

cax – The axes containing the colorbar.

Return type:

matplotlib.axes.Axes

class povplot.AxesTriplot(*, vertices, triangles, values, lines=None, line_radius=None, line_color=None, normals=None, camera=None, antialias=False, transparent=False, nprocs=None, cmap=None, norm=None, mm_per_unit=10)

Bases: Artist, ScalarMappable

A matplotlib artist for rendering a triangular grid with Povray.

Parameters:

  • vertices (numpy.ndarray with shape (nverts,3)) – The vertices of the triangulation.

  • triangles (numpy.ndarray with shape (ntriangles,3) and dtype int) – The indices of vertices defining the triangles.

  • values (numpy.ndarray with shape (nverts,)) – The values of the vertices. These will be mapped to a color.

  • normals (numpy.ndarray with shape (nverts,3), optional) – The outward normals at the vertices.

  • cmap (str or matplotlib.colors.Colormap, optional) – The name or an instance of a matplotlib colormap to be applied to the normalized values.

  • norm (matplotlib.colors.Normalize, optional) – The normalization of values to the range [0,1], applied before colormapping.

  • camera (collections.abc.Mapping, optional) – The position and orientation of the camera. If absent the camera is positioned such that the triangulation is completely in view. While optional, users are encouraged to define the camera manually as the autopositioning may change in the future.

  • mm_per_unit (float, default: 10) –

  • antialias (bool, default: False) – Let Povray produce an antialiased image.

  • transparent (bool, default: False) – Let Povray produce an image with transparency.

  • nprocs (int, default: 1) – Number of threads Povray may use to render the image.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, array=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, norm=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Properties:

agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: scalar or None animated: bool array: array-like or None clim: (vmin: float, vmax: float) clip_box: .Bbox clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: .Colormap or str or None figure: .Figure gid: str in_layout: bool label: object norm: .Normalize or None path_effects: .AbstractPathEffect picker: None or bool or float or callable rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None transform: .Transform url: str visible: bool zorder: float

exception povplot.PovrayError(returncode, stderr, script, script_args)

Bases: Exception

Povray error.

returncode

The return code of Povray.

stderr

The captured stderr of Povray.

script

The unrendered script. See also rendered_script.

script_args

The arguments used to render the script.

property rendered_script

The rendered script as passed to Povray.