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.

settings is a dict of view options, for example visualized_attribute, quality, render_mode, scale_bar_palette (“auto” or a palette name), scalar_range_mode (“auto” or “fixed”) with scalar_range_min / scalar_range_max, colormap_reverse, camera keys and background_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 (with materials), 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 as frame_NNN.png.

  • duration (float) – Length of the orbit in seconds. The animation has duration * fps frames.

  • 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 settings holds 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 as frame_NNN.png.

  • axis (str) – Sweep axis: “x”, “y” or “z”.

  • duration (float) – Length of one sweep in seconds. The sweep has duration * fps frames.

  • 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() and chamfer() 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).

axis_range(axis)[source]#

Return the bounding box (min, max) along an axis index.

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.

values is 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, for matplotlib.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/axis colors for embedding in a themed UI. Defaults to matplotlib’s style.