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
todst
using Jinja2 and Povray.scene
should be a valid Povray script. The script is preprocessed with Jinja2 with dictionaryscene_args
as context. Jinja2 is preloaded with apovplot
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:
assumed_gamma (
float
, default:1.0
) – See assumed_gamma.mm_per_unit (
float
, default:10
) – See mm_per_unit.
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 fromlocation
tosky
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 dtypeint
) – 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 dtypeint
) – 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
ormatplotlib.colors.Colormap
, optional) – The name or an instance of a matplotlib colormap to be applied to the normalizedvalues
.norm (
matplotlib.colors.Normalize
, optional) – The normalization ofvalues
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 dtypeint
) – 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
orio.IOBase
) – The destination of the rendered image. Should be astr
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 withscene_args
.size (
tuple
of twoint
s) – 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 ondst
.
- 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
orio.IOBase
) – The destination of the rendered image. Should be astr
or path-like object, or a file opened for writing binary data.size (
tuple
of twoint
s) – 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 dtypeint
) – 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
ormatplotlib.colors.Colormap
, optional) – The name or an instance of a matplotlib colormap to be applied to the normalizedvalues
.norm (
matplotlib.colors.Normalize
, optional) – The normalization ofvalues
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 macropovplot.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 ondst
.
- 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 dtypeint
) – 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
ormatplotlib.colors.Colormap
, optional) – The name or an instance of a matplotlib colormap to be applied to the normalizedvalues
.norm (
matplotlib.colors.Normalize
, optional) – The normalization ofvalues
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 macropovplot.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 axesax
.hide_ticks (
bool
, default:True
) – Hide the ticks of the axesax
.
- Returns:
triplot – A matplotlib artist and scalar mappable.
- Return type:
- 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 length3
or4
, default:(1,1,1,0.5)
) – The background of the colorbar axes, margin included.
- Returns:
cax – The axes containing the colorbar.
- Return type:
- 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 dtypeint
) – 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
ormatplotlib.colors.Colormap
, optional) – The name or an instance of a matplotlib colormap to be applied to the normalizedvalues
.norm (
matplotlib.colors.Normalize
, optional) – The normalization ofvalues
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.