Headless (no GUI)#
These functions render off-screen and write image, animation or diagram files.
They are suited to automation, tests, and batch pipelines where no window
should appear. The CamelCase names (Render_Image, Render_Turntable_Animation,
Render_Sweep_Animation, Render_Tree_Diagram, Render_Tree_Legend) are
aliases kept for older scripts.
Images and animations#
- pyvcad_rendering.render_image(vcad_object, filepath, settings=None, width=1920, height=1080, materials=None)[source]#
Render a single frame off-screen and save to
filepath(no GUI).- Parameters:
vcad_object (Node) – The design to render.
filepath (str) – Image file to write, for example
"part.png".settings (dict, optional) – View options, described below. Defaults to an iso-surface view at “high” quality.
width (int) – Image width in pixels.
height (int) – Image height in pixels.
materials (MaterialDefs, optional) – Material definitions for volume-fraction colouring. Defaults to
pyvcad.default_materials.
settingsis a dict of view options, for examplevisualized_attribute,quality,render_mode,scale_bar_palette(“auto” or a palette name),scalar_range_mode(“auto” or “fixed”) withscalar_range_min/scalar_range_max,colormap_reverse, camera keys andbackground_color. Analysis results can be shown with:below_range_color,above_range_color: an RGB colour (0-1 or 0-255) that paints values outside the colour range, for example walls thinner than a fixed range minimum in red. Pick a colour that stands out from the palette.mass_properties: True to compute pv.mass_properties at the render’s voxel size (withmaterials), or a pv.MassProperties report; draws the centre of mass, the principal axes and a caption with the numbers.mass_properties_density: uniform density in g/cm^3 for that computation.mass_properties_axes,mass_properties_caption: set False to hide the axes or the caption.
Example
>>> import pyvcad_rendering as viz >>> viz.render_image(part, "mass.png", settings={"mass_properties": True}, materials=materials)
- pyvcad_rendering.Render_Image(vcad_object, filepath, settings=None, width=1920, height=1080, materials=None)[source]#
Alias for
render_image().
- pyvcad_rendering.render_turntable_animation(vcad_object, output_dir, duration=3.0, fps=30, distance_multiplier=1.5, elevation_angle_deg=30.0, settings=None, width=1920, height=1080, output_format='gif', keep_frames=False, materials=None)[source]#
Orbit the camera around the design and write an animation under
output_dir(no GUI).- Parameters:
vcad_object (Node) – The design to render.
output_dir (str) – Directory for the output. It is created if missing. The animation is written as
animation.<format>and the frames asframe_NNN.png.duration (float) – Length of the orbit in seconds. The animation has
duration * fpsframes.fps (int) – Frames per second.
distance_multiplier (float) – Camera distance as a multiple of the bounding-box diagonal, or of the saved camera distance when
settingsholds a camera.elevation_angle_deg (float) – Camera elevation above the XY plane in degrees.
settings (dict, optional) – View options, as for
render_image().width (int) – Frame width in pixels.
height (int) – Frame height in pixels.
output_format (str) – “gif”, “webp”, “mp4”, “webm”, or “all” to write every format.
keep_frames (bool) – Keep the PNG frames after the animation is written.
materials (MaterialDefs, optional) – Material definitions for volume-fraction colouring. Defaults to
pyvcad.default_materials.
Example
>>> import pyvcad_rendering as viz >>> viz.render_turntable_animation(part, "turntable", duration=4.0, output_format="mp4")
- pyvcad_rendering.Render_Turntable_Animation(vcad_object, output_dir, duration=3.0, fps=30, distance_multiplier=1.5, elevation_angle_deg=30.0, settings=None, width=1920, height=1080, output_format='gif', keep_frames=False, materials=None)[source]#
Alias for
render_turntable_animation().
- pyvcad_rendering.render_sweep_animation(vcad_object, output_dir, axis='z', duration=3.0, fps=30, loop=False, pause_seconds=0.5, settings=None, width=1920, height=1080, output_format='gif', keep_frames=False, materials=None)[source]#
Sweep a clipping plane through the design and write an animation under
output_dir(no GUI).The plane moves from just below the bounding box to just above it along
axis, revealing the interior one section at a time.- Parameters:
vcad_object (Node) – The design to render.
output_dir (str) – Directory for the output. It is created if missing. The animation is written as
animation.<format>and the frames asframe_NNN.png.axis (str) – Sweep axis: “x”, “y” or “z”.
duration (float) – Length of one sweep in seconds. The sweep has
duration * fpsframes.fps (int) – Frames per second.
loop (bool) – Play the sweep forward and then backward.
pause_seconds (float) – Hold on the first and last frames for this long.
settings (dict, optional) – View options, as for
render_image().width (int) – Frame width in pixels.
height (int) – Frame height in pixels.
output_format (str) – “gif”, “webp”, “mp4”, “webm”, or “all” to write every format.
keep_frames (bool) – Keep the PNG frames after the animation is written.
materials (MaterialDefs, optional) – Material definitions for volume-fraction colouring. Defaults to
pyvcad.default_materials.
Example
>>> import pyvcad_rendering as viz >>> viz.render_sweep_animation(part, "sweep", axis="z", loop=True)
- pyvcad_rendering.Render_Sweep_Animation(vcad_object, output_dir, axis='z', duration=3.0, fps=30, loop=False, pause_seconds=0.5, settings=None, width=1920, height=1080, output_format='gif', keep_frames=False, materials=None)[source]#
Alias for
render_sweep_animation().
Tree diagrams#
Save a Mermaid diagram of a design’s node tree (built by
pyvcad.TreeDiagram) as .mmd source, or as .svg / .png
through the Mermaid CLI (mmdc).
- pyvcad_rendering.render_tree_diagram(tree_or_diagram, output_path, mermaid_command='mmdc')[source]#
Save a Mermaid diagram for an authored OpenVCAD tree.
- Parameters:
tree_or_diagram (Node | TreeDiagram) – The root node or a pre-built TreeDiagram.
output_path (str | Path) – Destination .mmd, .svg, or .png path.
mermaid_command (str) – Mermaid CLI executable or command prefix. Defaults to mmdc.
- Returns:
The Mermaid source used to generate the saved output.
- Return type:
str
- pyvcad_rendering.Render_Tree_Diagram(tree_or_diagram, output_path, mermaid_command='mmdc')[source]#
Alias for
render_tree_diagram().
- pyvcad_rendering.render_tree_legend(output_path, mermaid_command='mmdc')[source]#
Save the hardcoded OpenVCAD tree-diagram legend.
- Parameters:
output_path (str | Path) – Destination .mmd, .svg, or .png path.
mermaid_command (str) – Mermaid CLI executable or command prefix. Defaults to mmdc.
- Returns:
The Mermaid source used to generate the saved output.
- Return type:
str
- pyvcad_rendering.Render_Tree_Legend(output_path, mermaid_command='mmdc')[source]#
Alias for
render_tree_legend().
Profile plots#
Check a 2D sketch before turning it into a solid: plot_profile() draws profiles, sketches and
curves with matplotlib, with holes, loop directions and corners marked. See
Sketching and Extruding.
- pyvcad_rendering.plot_profile(profile, ax=None, show=True, filename=None, fill=True, show_corners=True, corner_angle=5.0, show_direction=True, title=None, labels=None, dpi=200)[source]#
Plots profiles, sketches and curves in 2D, to check a sketch before turning it into a solid.
Outlines are solid lines and holes dashed grey lines, each with an arrowhead showing which way it runs (outlines counter-clockwise, holes clockwise). The material is shaded, and the corners that
fillet()andchamfer()can pick are marked with open circles. Open curves (a sketch with an unclosed path, or a sweep path) are drawn as lines with square end markers.- Parameters:
profile – What to draw: a Profile, Polygon2, Sketch or Curve, or a list of them to overlay in different colours.
ax (matplotlib.axes.Axes, optional) – Axes to draw into. Defaults to a new figure.
show (bool, optional) – Whether to display the plot window. Defaults to True; set to False in headless scripts, for example together with
filename.filename (str, optional) – Save the figure to this image file (PNG, SVG, PDF, …).
fill (bool, optional) – Shade the material of profiles. Defaults to True.
show_corners (bool, optional) – Mark the corners of profiles. Defaults to True.
corner_angle (float, optional) – Mark only corners where the outline turns by more than this many degrees, so the vertices of a polygon approximation (an offset can be one) are not marked. Defaults to 5.
show_direction (bool, optional) – Draw an arrowhead on each loop and curve. Defaults to True.
title (str, optional) – The plot title. Defaults to a summary of the first profile (loops, holes, area).
labels (list[str], optional) – Legend labels, one per item drawn.
dpi (int, optional) – Resolution used when saving to
filename. Defaults to 200.
- Returns:
A tuple of the matplotlib figure and axes holding the plot.
Signed distance slices#
Plot a principal-plane slice of a node’s signed distance field with
matplotlib. VisualizeSDF() is the one-call version; SDFSliceSampler
and draw_sdf_slice() let you sample and draw slices yourself, for example
to step through offsets or embed the plot in your own figure.
- pyvcad_rendering.VisualizeSDF(object, offset=0.0, resolution=100, iso_surface=0.0, plane='xy', bandwidth=None, show=True, z_height=None)[source]#
Plots a slice of a node’s signed distance field as a heat map.
The slice plane is named by the two axes it spans, so any of the three principal planes can be visualized. For a slice at any angle, placed interactively, use the renderer’s SDF Slice tool.
- Parameters:
object – The OpenVCAD node to sample. It is prepared in place before sampling.
offset (float, optional) – Position of the slice along the axis that is not part of
plane. Defaults to 0.0.resolution (int, optional) – Number of samples along the longest in-plane dimension. Defaults to 100.
iso_surface (float, optional) – The signed distance value to draw as a contour. Defaults to 0.0.
plane (str, optional) – The slice plane named by its two axes (“xy”, “xz”, “yz”). Defaults to “xy”.
bandwidth (float, optional) – Bandwidth to prepare the tree with. Defaults to the bounding box diagonal so the whole slice carries values; lower it when a wide band is expensive to prepare (e.g. mesh backed trees).
show (bool, optional) – Whether to display the plot. Set to False to only build the figure, e.g. to save it from a headless script. Defaults to True.
z_height (float, optional) – Deprecated alias for
offset, kept for the original XY-only signature.
- Returns:
A tuple of the matplotlib figure and axes holding the plot.
- class pyvcad_rendering.SDFSliceSampler(node, bandwidth=None)[source]#
Samples principal-plane slices of a node’s signed distance field.
The node is prepared on demand at the spacing each slice needs and is only re-prepared when that spacing changes, so stepping the slice offset through the part reuses the same preparation.
- Parameters:
node – The OpenVCAD node to sample. It is prepared in place, so pass a
clone()when the original tree is in use elsewhere.bandwidth (float, optional) – Bandwidth to prepare the tree with. Defaults to the bounding box diagonal so the whole slice carries values; lower it when a wide band is expensive to prepare (e.g. mesh backed trees).
- sample(plane='xy', offset=0.0, resolution=100)[source]#
Sample one slice.
- Parameters:
plane (str, optional) – The slice plane named by its two axes (“xy”, “xz”, “yz”). Defaults to “xy”.
offset (float, optional) – Position of the slice along the axis that is not part of
plane. Defaults to 0.0.resolution (int, optional) – Number of samples along the longest in-plane dimension. Defaults to 100.
- Returns:
An
SDFSlice.
- class pyvcad_rendering.SDFSlice(values, h_coords, v_coords, plane_axes, offset)[source]#
A sampled 2D slice of a signed distance field.
valuesis indexed[vertical, horizontal]and holds NaN wherever the tree returned no value (outside the prepared band).- property extent#
[h_min, h_max, v_min, v_max]of the sample coordinates, formatplotlib.imshow.
- property fixed_name#
Name of the axis normal to the slice (“X”, “Y” or “Z”).
- property horizontal_name#
Name of the horizontal image axis (“X”, “Y” or “Z”).
- property title#
A plot title naming the fixed axis and the slice offset.
- property vertical_name#
Name of the vertical image axis (“X”, “Y” or “Z”).
- pyvcad_rendering.draw_sdf_slice(fig, ax, sdf_slice, iso_surface=0.0, theme=None)[source]#
Draw a sampled slice as a heat map with an iso-contour onto
ax.- Parameters:
fig – The matplotlib figure that owns
ax(the colorbar is added to it).ax – The axes to draw into.
sdf_slice (SDFSlice) – The slice to draw.
iso_surface (float, optional) – The signed distance value to draw as a contour. Defaults to 0.0.
theme (dict, optional) –
fg/bg/axiscolors for embedding in a themed UI. Defaults to matplotlib’s style.