Skip to content

Additional Python API

Functions exported by every viewer's package that aren't covered by the dedicated show* pages.

Function signatures on this page and on the config system page show only the shared parameters. Where a function needs to say which viewer it means, the keyword differs per viewer — see "Addressing a viewer" in your viewer's chapter: VS Code CAD Viewer, OCP Viewer, Jupyter CadQuery. build123d Studio has exactly one viewer and no addressing keyword.

Screenshots

  • save_screenshot(filename, polling=True, progress_only=False, timeout_s=2)

Save the current viewer view to a PNG. filename is taken relative to the current working directory unless it's absolute. With polling=True the call returns only after the file has been written, or after timeout_s seconds with a warning; this is what Animation.save_as_gif relies on internally.

The PNG has an alpha channel and its background is transparent: the viewer clears its canvas to alpha 0, and the file is that canvas as it is. That composites onto any page, and it surprises anyone who flattens it the quick way — Pillow's Image.open(f).convert("RGB") turns every transparent pixel black. Paste it onto a background instead:

from PIL import Image

shot = Image.open("part.png")
flat = Image.new("RGB", shot.size, "white")
flat.paste(shot, mask=shot.getchannel("A"))
flat.save("part-white.png")

In the PBR Studio the studio_background setting decides: TRANSPARENT keeps the alpha, every other value is painted into the picture.

Clear viewer

  • show_clear()

Clear the viewer (remove all currently shown objects, reset the navigation tree). The viewer shows the splash logo again until the next show* call.

Blueprint images

  • ImageFace

Re-exported from ocp_tessellate.cad_objects. Lets you place a 2-D image as a face in the scene — e.g. a photo or technical drawing to model against. See image_face.md.