Files
solidcraft/examples/demo/doc_shots.py
T
Jackson OurslandandClaude Opus 5.5 ca4f3ed1a0 Book: getting started, sheet metal and import/export get pictures (#10732)
* Book: sketching step by step, with three clips and a numbered screenshot

The sketching page now opens with a first sketch in four steps: start a sketch on the Top
plane, draw a 60 x 40 rectangle and a 12 mm circle with typed values, dimension the circle
until the sketch is fully constrained, and finish. Each step has a short clip, and the last a
screenshot numbering the Sketch tools, a constraint, a dimension, the sketch's state and
Finish Sketch.

doc_shots.py gains what these needed: a setup that runs before recording, so a clip starts
where the last one ended; sketch framing; Enter sent as two input frames; and clips that keep
their pauses (hovering a plane).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Book: the sketching page's general notes get a heading after Step by step

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Book: sketching adds Offset and Trim; the sketching figures again on 0.29.0

Two more clips after the sketching walkthrough: Offset draws the rectangle's outline 4 mm inside
it with one click (Chain), and Trim cuts a notch where a circle crosses the top side. All the
sketching figures are made again on SolidCraft 0.29.0, with the clips keeping a moment on each
result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Book: solid features step by step, with four clips

The solid features page now opens with the sketch from the sketching page made into an open
box in four steps, each with a short clip: extrude it 12 mm, shell it with the top open,
round its outer top edges, then make it 20 mm tall from the timeline while the shell and the
fillet rebuild. The panel table and what follows get a heading of their own.

doc_shots.py: the feature shots share their steps with the setups that lead up to the next
shot, and fail when a feature on the timeline carries a warning or an error, so no figure
shows one. Shell comes before Fillet for that reason: shelling through the rounds needed the
kernel's boolean retry. trim_idle.py takes --hold, the seconds of each idle stretch to keep
(default 0.1 as before); the doc clips keep 0.8 s, so a reader sees each result. The app gets
up to three minutes to answer on a busy machine.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Book: features add Hole and Circular Pattern; the Parameters dialog, numbered

The features walkthrough gains two steps before the timeline edit: a 4 mm hole on the box's
floor, then Circular Pattern repeating it four times around the tube. The edit at the end now
rebuilds all of it. The parameters page gets a screenshot of the Parameters dialog numbering
apply as you go, user parameters, model parameters by feature, an expression and its value.
The features clips are made again on SolidCraft 0.29.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Book: components and joints step by step, with three clips

The components and joints page now opens with a two-leaf hinge in three steps, each with a
short clip: the two bodies made into components from the Bodies folder's menu (the first one
grounded), a revolute joint on their barrel ends with Flip turning Leaf B the right way round,
and a drag that swings Leaf B about the hinge while grounded Leaf A stays put. What follows
gets a heading of its own.

doc_shots.py builds the leaves from commands, with Leaf B lifted and set back so the joint
visibly brings it into place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Book: assemblies add Drive Joints; the assembly clips again on 0.29.0

A fourth step drives the hinge with Drive Joints: the slider swings Leaf B while a ghost shows
where it started, and OK keeps the new angle. The assembly clips are made again on SolidCraft
0.29.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Book: getting started, sheet metal and import/export get pictures

Getting started gains a section on the start page: a numbered screenshot (new design, open,
import, recent, samples, the File menu) and a clip opening a sample from it. Sheet metal opens
with a tray in three steps, each with a clip: a base flange from a sketched rectangle, edge
flanges from two top edges, and the flat pattern with its bends. Import and export opens with
the File menu, numbered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 06:31:44 +00:00

1097 lines
40 KiB
Python

#!/usr/bin/env python3
"""doc_shots.py [--list] [SHOT...]: capture the user guide's screenshots and short clips from the
real app, so every figure can be made again with one command when the UI changes.
python3 examples/demo/doc_shots.py # every shot
python3 examples/demo/doc_shots.py ui-tour/window # one shot
python3 examples/demo/doc_shots.py --list
Each shot starts a fresh SolidCraft (its own settings folder, so your preferences never show) in
an Xvfb screen, drives it over the control channel the way a person would (enclosure_ui_mcp.py's
Demo: the pointer glides to a button and clicks it, values are typed), and writes
docs/book/src/media/<page>/<name>.png (a still, with numbered callouts where the shot asks for
them) or .mp4 (a clip, with the drawn pointer and click ripples of overlay.py, idle stretches cut by
trim_idle.py). Shots are the functions below; the page that shows a shot explains it.
Needs Xvfb, ffmpeg (x11grab) and Pillow, and a release build of the app (`--app`, default
$CARGO_TARGET_DIR/release/solidcraft, else target/release/solidcraft). Every new file needs an
ATTRIBUTION row (attribution/pending/).
"""
import argparse
import json
import os
import secrets
import shutil
import socket
import subprocess
import sys
import tempfile
import time
from pathlib import Path
HERE = Path(__file__).resolve().parent
ROOT = HERE.parent.parent
sys.path.insert(0, str(HERE))
from enclosure_ui_mcp import Demo # noqa: E402
from overlay import cursor_sprite, ripple_sprite # noqa: E402
# The window every shot is taken in: the book column shows it at about 60 %.
SIZE = (1280, 800)
FPS = 30
MEDIA = ROOT / "docs/book/src/media"
FONT = "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf"
# Callout disc colours (an original blue with a white rim, legible on dark and light).
CALLOUT_FILL = (40, 120, 230)
CALLOUT_RIM = (255, 255, 255)
SHOTS = {}
def shot(name, kind, start="empty", setup=None):
"""Register a shot: `kind` is "still" or "clip"; `start` is "empty" (a new design) or
"sample" (the built-in sample plate); `setup(d)`, when given, runs first and is not
recorded."""
def register(f):
SHOTS[name] = (kind, start, f, setup)
return f
return register
# -- the app ------------------------------------------------------------------------------------
def free_port():
with socket.socket() as s:
s.bind(("127.0.0.1", 0))
return s.getsockname()[1]
class App:
"""A fresh SolidCraft on DISPLAY with its own settings, the control channel on a free port."""
def __init__(self, exe, display, start, work):
self.port = free_port()
self.token = secrets.token_hex(32)
os.environ["SOLIDCRAFT_CONTROL_TOKEN"] = self.token
settings = Path(work) / "settings"
settings.mkdir(parents=True, exist_ok=True)
env = dict(
os.environ,
DISPLAY=display,
SOLIDCRAFT_SETTINGS_DIR=str(settings),
XDG_DATA_HOME=str(Path(work) / "data"),
XDG_CONFIG_HOME=str(Path(work) / "config"),
XDG_CACHE_HOME=str(Path(work) / "cache"),
SOLIDCRAFT_RENDERER="cpu",
LANG="en_US.UTF-8",
)
argv = [exe, "--control", str(self.port)] + (["--sample"] if start == "sample" else [])
self.log = open(Path(work) / "app.log", "w")
self.p = subprocess.Popen(argv, env=env, stdout=self.log, stderr=subprocess.STDOUT)
self.wait_ready()
def wait_ready(self):
from enclosure_mcp import control
for _ in range(1800):
if self.p.poll() is not None:
raise RuntimeError(f"the app exited ({self.p.returncode}); see {self.log.name}")
try:
r = control(self.port, "ui.inspect")
if r.get("ok") and r.get("result", {}).get("viewport"):
return
except OSError:
pass
time.sleep(0.1)
raise RuntimeError("the app did not answer on its control port within 3 minutes")
def close(self):
from enclosure_mcp import control
try:
control(self.port, "app.quit", {"force": True})
self.p.wait(10)
except Exception:
self.p.kill()
self.p.wait()
self.log.close()
class Shot(Demo):
"""Demo, plus what a doc shot needs: engine commands, the crop and the callouts."""
def __init__(self, port, log):
super().__init__(port, None, log, speed=1.0, minimum_caption=0)
self.crop = None # (x, y, w, h) in window points; None: the whole window
self.callouts = [] # [(x, y)] in window points, numbered from 1 in order
self.keep_pauses = False # a clip whose pauses matter (hovering) keeps them
def execute(self, command, params=None):
self.settle_camera()
r = self.ui("engine.execute", {"command": command, "params": params or {}})
self.settle_camera()
return r
def enter(self):
"""Enter as two input frames: pressed and released in one frame, a sketch value box
misses it."""
self.ui("ui.key", {"key": "Enter", "pressed": True})
time.sleep(0.1)
self.ui("ui.key", {"key": "Enter", "pressed": False})
self.wait(0.4)
self.settle_camera()
def type(self, text, enter=True):
self.ui("ui.text", {"text": text})
self.wait(0.4)
if enter:
self.enter()
def sketch_scale(self):
"""Points per millimetre in the open sketch."""
a, b = self.at(sketch=[0, 0]), self.at(sketch=[10, 0])
return abs(b[0] - a[0]) / 10
def frame_sketch(self, centre, scale):
"""Look at `centre` (mm on a sketch on XY) at `scale` points per mm, keeping the view's
direction."""
cam = self.ui("ui.inspect")["camera"]
self.ui("ui.camera", {"target": [centre[0], centre[1], 0], "distance": cam["distance"] * self.sketch_scale() / scale})
self.settle_camera()
def handle(self, name):
"""The handle's screen point, or None when it isn't drawn."""
return next(((h["x"], h["y"]) for h in self.ui("ui.handles") if h["name"] == name), None)
def prepare(self):
"""The same starting window for every shot: SIZE, the default layout, no start page."""
self.ui("ui.resize", {"width": SIZE[0], "height": SIZE[1]})
for _ in range(100):
vp = self.ui("ui.inspect").get("viewport") or [0, 0, 0, 0]
if vp[0] + vp[2] >= SIZE[0] - 10:
break
time.sleep(0.1)
if self.ui("ui.home").get("open"):
self.ui("ui.home", {"open": False})
self.pos = (SIZE[0] * 0.6, SIZE[1] * 0.55)
self.settle_camera()
# -- capture ------------------------------------------------------------------------------------
def run_shot(name, exe, display, keep):
kind, start, f, setup = SHOTS[name]
work = Path(tempfile.mkdtemp(prefix="doc-shot-"))
out = MEDIA / f"{name}.{'png' if kind == 'still' else 'mp4'}"
out.parent.mkdir(parents=True, exist_ok=True)
app = App(exe, display, start, work)
try:
log = open(work / "steps.log", "w")
d = Shot(app.port, log)
d.prepare()
if setup:
setup(d)
d.settle_camera()
log.seek(0)
log.truncate()
if kind == "still":
f(d)
d.settle_camera()
raw = work / "window.png"
r = d.ui("ui.screenshot", {"path": str(raw)})
if r and r.get("hidden"):
raise RuntimeError("the window was not presented")
still(raw, out, d.crop, d.callouts)
else:
clip(d, f, display, work, out)
finally:
app.close()
if keep:
print(f" work files: {work}", file=sys.stderr)
else:
shutil.rmtree(work, ignore_errors=True)
print(f"{out.relative_to(ROOT)}: {out.stat().st_size // 1024} KB")
def still(raw, out, crop, callouts):
from PIL import Image, ImageDraw, ImageFont
img = Image.open(raw).convert("RGB")
lo, hi = img.getextrema()[0]
if hi - lo < 8:
raise RuntimeError(f"{raw}: the screenshot is blank")
draw = ImageDraw.Draw(img)
font = ImageFont.truetype(FONT, 17)
for i, (x, y) in enumerate(callouts, 1):
r = 15
draw.ellipse([x - r - 2, y - r - 2, x + r + 2, y + r + 2], fill=CALLOUT_RIM)
draw.ellipse([x - r, y - r, x + r, y + r], fill=CALLOUT_FILL)
draw.text((x, y), str(i), font=font, fill=CALLOUT_RIM, anchor="mm")
if crop:
x, y, w, h = crop
img = img.crop((x, y, x + w, y + h))
img.save(out, optimize=True)
# Screen captures are mostly flat colour: a 256-colour palette keeps them sharp at a third of
# the size. Keep it only when it is smaller.
q = out.with_suffix(".q.png")
img.quantize(256, method=Image.Quantize.MEDIANCUT, dither=Image.Dither.NONE).save(q, optimize=True)
if q.stat().st_size < out.stat().st_size:
q.replace(out)
else:
q.unlink()
def clip(d, f, display, work, out):
raw = work / "raw.mp4"
ff = subprocess.Popen(
["ffmpeg", "-loglevel", "info", "-nostats", "-y", "-f", "x11grab", "-draw_mouse", "0", "-video_size", f"{SIZE[0]}x{SIZE[1]}", "-framerate", str(FPS), "-i", display, "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-pix_fmt", "yuv444p", str(raw)],
stderr=open(work / "ffmpeg.log", "w"),
)
try:
time.sleep(1.0)
d.mark(start=True)
f(d)
d.settle_camera()
time.sleep(0.8)
finally:
ff.send_signal(2)
ff.wait(30)
log = (work / "ffmpeg.log").read_text()
start = float(log.split("start: ", 1)[1].split(",", 1)[0])
composite(work, raw, start, d.crop, out, d.keep_pauses)
def composite(work, raw, start, crop, out, keep_pauses=False):
"""The drawn pointer and click ripples over the recording, cropped, idle cut, H.264."""
marks = [json.loads(line) for line in open(work / "steps.log") if line.strip()]
cursor_sprite(str(work / "cursor.png"))
ripple_sprite(str(work / "ripple.png"))
pts, clicks = [], []
for i, m in enumerate(marks):
t = m["t"] - start
if "cursor" in m:
pts.append((t, *m["cursor"]))
if m.get("click"):
clicks.append((t, *m["cursor"]))
elif "drag_start" in m:
end = next((n for n in marks[i + 1 :] if "drag_end" in n), None)
if end:
(x0, y0), (x1, y1), t1 = m["drag_start"], end["drag_end"], end["t"] - start
n = max(2, int((t1 - t) * FPS))
pts += [(t + (t1 - t) * k / n, x0 + (x1 - x0) * k / n, y0 + (y1 - y0) * k / n) for k in range(n + 1)]
pts.sort()
cmds = [f"{t:.3f} [enter] overlay@cur x {x:.1f}, [enter] overlay@cur y {y:.1f};" for t, x, y in pts]
cmds += [f"{t:.3f} [enter] overlay@rip x {x - 22:.1f}, [enter] overlay@rip y {y - 22:.1f};" for t, x, y in clicks]
(work / "cursor.cmd").write_text("\n".join(sorted(cmds, key=lambda c: float(c.split()[0]))) + "\n")
ripple = "+".join(f"between(t,{t:.3f},{t + 0.28:.3f})" for t, _, _ in clicks) or "0"
cx, cy = (pts[0][1], pts[0][2]) if pts else (-100, -100)
x, y, w, h = crop or (0, 0, *SIZE)
w, h = w // 2 * 2, h // 2 * 2
graph = f"[0:v][2:v]overlay@rip=x=-100:y=-100:enable='{ripple}':shortest=1[v1];[v1][1:v]overlay@cur=x={cx}:y={cy}:shortest=1,sendcmd=f={work / 'cursor.cmd'},crop={w}:{h}:{x}:{y}"
if labels(work, marks, start, w, h):
graph += f",ass={work / 'labels.ass'}"
graph += "[v]"
full = work / "full.mp4"
subprocess.run(
["ffmpeg", "-loglevel", "error", "-y", "-i", str(raw), "-loop", "1", "-i", str(work / "cursor.png"), "-loop", "1", "-i", str(work / "ripple.png"), "-filter_complex", graph, "-map", "[v]", "-c:v", "libx264", "-crf", "14", "-pix_fmt", "yuv420p", str(full)],
check=True,
)
if keep_pauses:
subprocess.run(["ffmpeg", "-loglevel", "error", "-y", "-i", str(full), "-c:v", "libx264", "-crf", "26", "-pix_fmt", "yuv420p", "-movflags", "+faststart", str(out)], check=True)
else:
# Idle stretches shortened, not removed: a reader needs a moment on each result.
subprocess.run([sys.executable, str(HERE / "trim_idle.py"), str(full), str(out), "--crf", "26", "--hold", "0.8"], check=True)
def labels(work, marks, start, w, h):
"""The shot's d.caption() labels (which button does what) in the clip's top-left corner,
each until the next one. False when the shot has none."""
caps = [m for m in marks if "caption" in m]
if not caps:
return False
def ts(t):
t = max(t, 0.0)
return f"{int(t // 3600)}:{int(t % 3600 // 60):02}:{t % 60:05.2f}"
head = f"""[Script Info]
ScriptType: v4.00+
PlayResX: {w}
PlayResY: {h}
[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Label,DejaVu Sans,24,&H00FFFFFF,&H00FFFFFF,&H40000000,&H40000000,1,0,0,0,100,100,0,0,3,8,0,7,24,24,24,1
[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
"""
end = marks[-1]["t"] - start + 5
lines = []
for i, m in enumerate(caps):
a = m["t"] - start
b = caps[i + 1]["t"] - start if i + 1 < len(caps) else end
if m["caption"]:
lines.append(f"Dialogue: 0,{ts(a)},{ts(b)},Label,,0,0,0,,{m['caption']}")
(work / "labels.ass").write_text(head + "\n".join(lines) + "\n")
return True
# -- the shots ----------------------------------------------------------------------------------
# ui-tour.md
@shot("ui-tour/window", "still", start="sample")
def ui_tour_window(d):
"""The window, numbered in the order ui-tour.md describes it: 1 title bar, 2 toolbar,
3 browser, 4 viewport, 5 axis view, 6 navigation bar, 7 timeline, 8 command search."""
d.key("Escape")
d.ui("ui.move", {"x": 5, "y": 400})
names = {h["name"]: (h["x"], h["y"]) for h in d.ui("ui.handles")}
vp = d.ui("ui.inspect")["viewport"]
# Each callout sits in empty space beside what it names.
want = [
("titlebar:assistant", (-46, 0)),
("ribbon:add_tab", (36, 0)),
("browser:header", (0, 0)),
(None, (vp[0] + vp[2] * 0.33, vp[1] + vp[3] * 0.8)),
("axis_view:-x", (-44, 0)),
("nav:slot:orbit", (-40, 0)),
("history:play", (0, -36)),
("ribbon:search", (-100, 0)),
]
for name, (dx, dy) in want:
if name is None:
d.callouts.append((dx, dy))
elif name in names:
x, y = names[name]
d.callouts.append((x + dx, y + dy))
else:
raise RuntimeError(f"no handle {name}; the window's handles changed")
@shot("ui-tour/navigate", "clip", start="sample")
def ui_tour_navigate(d):
"""Orbit (right drag), pan (middle drag), zoom (wheel) and back with the axis view's Home."""
vp = d.ui("ui.inspect")["viewport"]
# The viewport right of the browser, down to the navigation bar.
d.crop = (262, vp[1] + 126, SIZE[0] - 262, 590)
c = (vp[0] + vp[2] * 0.62, vp[1] + vp[3] * 0.5)
d.glide(c, 0.6)
d.caption("Right-drag: orbit")
d.orbit(240, 0, steps=70)
d.orbit(0, 40, steps=30)
d.wait(0.6)
d.caption("Middle-drag: pan")
d.drag(d.pos, (d.pos[0] - 160, d.pos[1] - 40), button="middle", steps=50)
d.wait(0.6)
d.caption("Wheel: zoom at the pointer")
for delta in (40, 40, 40, -40, -40, -40):
d.ui("ui.scroll", {"x": d.pos[0], "y": d.pos[1], "delta": delta})
time.sleep(0.25)
d.settle_camera()
d.wait(0.6)
d.caption("Home: back to the starting view")
d.click(d.at(handle="axis_view:home"), dur=0.6, settle=0.3)
d.ui("ui.view", {"view": "fit"})
d.settle_camera()
d.wait(1.0)
# sketching.md: one sketch on the Top (XY) plane, a 60 x 40 rectangle from the origin and a
# 12 mm hole placed 20 mm from two sides, step by step. Each clip starts where the last ends.
RECT = (60, 40)
HOLE = (20, 20, 12)
def top_sketch(d):
"""A sketch open on the Top plane, framed on where the rectangle will go."""
d.execute("sketch.create", {"plane": "XY"})
d.ui("ui.view", {"view": "top"})
d.settle_camera()
d.frame_sketch((RECT[0] / 2, RECT[1] / 2 - 4), 7.5)
def draw_rectangle(d):
d.tool("sketch.rectangle.two_point")
d.click(d.at(sketch=[0, 0]), dur=0.6, settle=0.3)
d.glide(d.at(sketch=[RECT[0] * 0.7, RECT[1] * 0.7]), 0.8)
d.wait(0.3)
d.type(str(RECT[0]), enter=False)
d.key("Tab")
d.type(str(RECT[1]), enter=False)
# A click places the shape at the typed size, wherever the pointer is.
d.click(d.pos, dur=0.1, settle=0.4)
d.key("Escape")
def draw_circle(d):
# Off its final place, so the dimensions visibly move it there.
d.tool("sketch.circle.center")
d.click(d.at(sketch=[HOLE[0] - 4, HOLE[1] + 5]), dur=0.6, settle=0.3)
# Down and right: the diameter box opens above the pointer, and over it the tool can't see
# the pointer move.
d.glide(d.at(sketch=[HOLE[0] + 4, HOLE[1] - 1]), 0.5)
d.type(str(HOLE[2]), enter=False)
d.click(d.pos, dur=0.1, settle=0.4)
d.key("Escape")
def drawn(d):
top_sketch(d)
draw_rectangle(d)
draw_circle(d)
if len(d.execute("sketch.inspect")["curves"]) != 5:
raise RuntimeError("the rectangle and the circle were not drawn")
def dimension_hole(d):
"""Dimension the hole's centre from the left side, then from the bottom."""
d.tool("sketch.dimension")
centre = lambda: d.at(sketch=d.hole_centre()) # noqa: E731
d.click(centre(), dur=0.6, settle=0.2)
d.click(d.at(sketch=[0, RECT[1] * 0.85]), dur=0.5, settle=0.2)
d.click(d.at(sketch=[HOLE[0] / 2, RECT[1] + 7]), dur=0.5, settle=0.3)
d.type(str(HOLE[0]))
d.click(centre(), dur=0.6, settle=0.2)
d.click(d.at(sketch=[RECT[0] * 0.8, 0]), dur=0.5, settle=0.2)
d.click(d.at(sketch=[RECT[0] * 0.75, HOLE[1] / 2]), dur=0.5, settle=0.3)
d.type(str(HOLE[1]))
d.key("Escape")
def hole_centre(d):
sk = d.execute("sketch.inspect")
c = next(c for c in sk["curves"] if c["type"] == "circle")
return list(c["center_at"])
Shot.hole_centre = hole_centre
@shot("sketching/create", "clip")
def sketching_create(d):
"""New Sketch, hover the planes (each lights up), click Top: the view turns to face it."""
d.keep_pauses = True
d.caption("New Sketch")
d.tool("sketch.create")
o = d.at(world=[0, 0, 0])
d.caption("Hover a plane: it lights up")
d.glide((o[0] + 20, o[1] - 45), 0.8)
d.wait(1.0)
d.glide((o[0] + 62, o[1] + 1), 0.6)
d.wait(1.0)
d.caption("Click it: the sketch opens facing you")
d.click((o[0] + 62, o[1] + 1), dur=0.2, settle=1.5)
plane = d.execute("sketch.inspect")["plane"]
if plane["x_dir"] != [1.0, 0.0, 0.0] or plane["y_dir"] != [0.0, 1.0, 0.0]:
raise RuntimeError(f"the sketch went on the wrong plane: {plane}")
d.wait(1.0)
@shot("sketching/draw", "clip", setup=top_sketch)
def sketching_draw(d):
"""A rectangle from the origin with its sides typed (60 Tab 40, click), then a circle with
its diameter typed: each typed value becomes a dimension."""
d.caption("Rectangle: click the origin, type 60, Tab, 40, click")
draw_rectangle(d)
d.wait(0.8)
d.caption("Circle: click its centre, type 12, click")
draw_circle(d)
d.wait(1.2)
@shot("sketching/dimension", "clip", setup=drawn)
def sketching_dimension(d):
"""Dimension the hole's centre from two sides: the sketch turns fully constrained."""
d.caption("Dimension: click the centre, then a side, place it, type 20")
dimension_hole(d)
if d.execute("sketch.inspect").get("dof") != 0:
raise RuntimeError("the sketch is not fully constrained")
d.caption("Fully constrained: nothing left to move")
d.wait(2.0)
NOTCH = (45, RECT[1], 14) # a circle centred on the top side, for Trim
def offset_outline(d, label=lambda text: None):
label("Offset: click the outline, type 4, Enter")
d.tool("sketch.offset")
d.click(d.at(sketch=[RECT[0] / 2, 0]), dur=0.6, settle=0.8)
d.wait(0.4)
d.ui("ui.key", {"key": "A", "cmd": True})
d.type("4")
d.key("Escape")
if len(d.execute("sketch.inspect")["curves"]) != 9:
raise RuntimeError("the offset did not add four curves")
def notch_circle(d):
d.tool("sketch.circle.center")
d.click(d.at(sketch=[NOTCH[0], NOTCH[1]]), dur=0.2, settle=0.3)
d.glide(d.at(sketch=[NOTCH[0] + 7, NOTCH[1] - 4]), 0.3)
d.type(str(NOTCH[2]), enter=False)
d.click(d.pos, dur=0.1, settle=0.4)
d.key("Escape")
def offset_and_notch(d):
drawn(d)
dimension_hole(d)
offset_outline(d)
notch_circle(d)
time.sleep(6) # the "Dimension applied" notice fades
def dimensioned(d):
drawn(d)
dimension_hole(d)
time.sleep(6)
@shot("sketching/offset", "clip", setup=dimensioned)
def sketching_offset(d):
"""Offset the rectangle's outline 4 mm inward: one click picks the whole chain."""
offset_outline(d, d.caption)
d.wait(1.5)
@shot("sketching/trim", "clip", setup=offset_and_notch)
def sketching_trim(d):
"""Trim a notch: click the piece of the top side inside the circle, then the arc above it."""
d.caption("Trim: click each piece to remove")
d.tool("sketch.trim")
r = NOTCH[2] / 2
before = len(d.execute("sketch.inspect")["curves"])
d.click(d.at(sketch=[NOTCH[0] - r / 2, NOTCH[1]]), dur=0.6, settle=0.8)
d.click(d.at(sketch=[NOTCH[0], NOTCH[1] + r]), dur=0.6, settle=0.8)
d.key("Escape")
if len(d.execute("sketch.inspect")["curves"]) == before:
raise RuntimeError("Trim removed nothing")
d.caption("")
d.glide((SIZE[0] * 0.55, SIZE[1] * 0.85), 0.6)
d.wait(1.5)
@shot("sketching/parts", "still", setup=drawn)
def sketching_parts(d):
"""The finished sketch, numbered: 1 the Sketch tab's tools, 2 a constraint, 3 a dimension,
4 the sketch's state, 5 Finish Sketch."""
dimension_hole(d)
d.ui("ui.move", {"x": 5, "y": 600})
time.sleep(6) # the "Dimension applied" notice fades
sel = d.ui("ui.selection")
dims = sel.get("dimensions") or []
if not dims:
raise RuntimeError("no dimensions drawn")
names = {h["name"]: (h["x"], h["y"]) for h in d.ui("ui.handles")}
left = d.at(sketch=[0, RECT[1] / 2])
d.callouts += [
(names["toolbar:sketch.line"][0] - 2, names["toolbar:sketch.line"][1] + 56),
(left[0] - 34, left[1] + 26),
(dims[0]["x"], dims[0]["y"] - 30),
(names["sketch_palette:status_header"][0] - 128, names["sketch_palette:status_header"][1] + 8),
(names["sketch_palette:finish"][0] - 130, names["sketch_palette:finish"][1]),
]
# features.md: the sketch above made solid, hollowed, rounded and edited from the timeline. Shell
# comes before Fillet: a shell through rounded edges needs the kernel's boolean retry (a warning
# on the timeline), and a 1.5 mm round on the 2 mm wall's outer edge needs nothing.
HEIGHT = 12
TOP_EDGES = [[RECT[0] / 2, 0, HEIGHT], [RECT[0], RECT[1] / 2, HEIGHT], [RECT[0] / 2, RECT[1], HEIGHT], [0, RECT[1] / 2, HEIGHT]]
TOP = [RECT[0] * 0.75, RECT[1] * 0.75, HEIGHT]
def model_view(d):
"""The same three-quarter view for every feature clip, the part left of the dialog."""
d.ui("ui.camera", {"target": [RECT[0] / 2 + 6, RECT[1] / 2, HEIGHT / 2], "yaw": -0.7854, "pitch": 0.6155, "distance": 125})
d.settle_camera()
def features(d):
return [h["name"].split(":", 1)[1] for h in d.ui("ui.handles") if h["name"].startswith("timeline:")]
def wait_feature(d, name):
"""Wait for `name` on the timeline (a shell can take a few seconds to build), and fail on a
feature with a warning or an error: a figure must not show one."""
for _ in range(300):
if name in features(d):
d.settle_camera()
r = d.execute("timeline.inspect", {"feature": name})
if r.get("warning") or r.get("error"):
raise RuntimeError(f"{name}: {r.get('warning') or r.get('error')}")
return
time.sleep(0.1)
raise RuntimeError(f"no {name} on the timeline: {features(d)}")
def typed(d, value):
"""Replace the focused value and press Enter (Enter is OK in a feature dialog)."""
d.wait(0.4)
d.ui("ui.key", {"key": "A", "cmd": True})
d.type(value)
def extrude(d, label=lambda text: None):
label("Extrude: click the profile")
d.tool("solid.extrude")
d.click(d.at(world=[RECT[0] * 0.8, RECT[1] * 0.8, 0]), dur=0.6, settle=0.8)
label("Drag the arrow, or type the distance: 12, Enter")
a = d.at(handle="arrow")
d.drag(a, (a[0], a[1] - 50), steps=40)
typed(d, str(HEIGHT))
wait_feature(d, "Extrude1")
def shell(d, label=lambda text: None):
label("Shell: click the face to remove")
d.tool("solid.shell")
d.click(d.at(world=TOP), dur=0.6, settle=0.8)
label("Wall thickness: 2, Enter")
typed(d, "2")
wait_feature(d, "Shell1")
def fillet(d, label=lambda text: None):
label("Fillet: click the edges to round")
d.tool("solid.fillet")
for edge in TOP_EDGES:
d.click(d.at(world=edge), dur=0.4, settle=0.3)
label("Radius: 1.5, Enter")
typed(d, "1.5")
wait_feature(d, "Fillet1")
HOLE_AT = [32, 20, 2] # on the box's floor, beside the tube
TUBE_RIM = [HOLE[0] - HOLE[2] / 2, HOLE[1], HEIGHT] # on the tube's top circle: the pattern's axis
def hole(d, label=lambda text: None):
label("Hole: click where it goes, set the diameter, OK")
d.tool("solid.hole")
d.click(d.at(world=HOLE_AT), dur=0.6, settle=1.0)
d.click(d.at(handle="dialog:Diameter"), dur=0.6, settle=0.3)
d.ui("ui.key", {"key": "A", "cmd": True})
d.type("4", enter=False)
d.click(d.at(handle="dialog:ok"), dur=0.6, settle=1.0)
wait_feature(d, "Hole1")
def pattern(d, label=lambda text: None):
label("Circular Pattern: Features, pick Hole1 on the timeline")
d.tool("solid.pattern.circular", panel="panel:MODEL:ARRANGE")
d.click(d.at(handle="dialog:Object Type"), dur=0.6, settle=0.5)
d.click(d.at(handle="dialog:Object Type:Features"), dur=0.4, settle=0.5)
d.click(d.at(handle="timeline:Hole1"), dur=0.6, settle=0.6)
label("Axis: click the tube's rim. Quantity: 4, Enter")
d.click(d.at(handle="dialog:Axis"), dur=0.6, settle=0.4)
d.click(d.at(world=TUBE_RIM), dur=0.6, settle=1.0)
typed(d, "4")
wait_feature(d, "CircularPattern1")
def sketched(d):
drawn(d)
dimension_hole(d)
d.tool("sketch.finish")
model_view(d)
time.sleep(6) # the "Dimension applied" notice fades
def extruded(d):
sketched(d)
extrude(d)
def shelled(d):
extruded(d)
shell(d)
def filleted(d):
shelled(d)
fillet(d)
def holed(d):
filleted(d)
hole(d)
def patterned(d):
holed(d)
pattern(d)
@shot("features/extrude", "clip", setup=sketched)
def features_extrude(d):
"""Extrude the sketch's profile: drag the arrow, type 12, Enter."""
extrude(d, d.caption)
d.wait(1.5)
@shot("features/shell", "clip", setup=extruded)
def features_shell(d):
"""Shell: pick the top face to open, keep the 2 mm wall, Enter; then a turn to look in."""
shell(d, d.caption)
d.caption("")
d.orbit(0, 60, steps=40)
d.wait(1.5)
@shot("features/fillet", "clip", setup=shelled)
def features_fillet(d):
"""Fillet the four outer top edges: pick them, type 1.5, Enter."""
fillet(d, d.caption)
d.wait(1.5)
@shot("features/hole", "clip", setup=filleted)
def features_hole(d):
"""A 4 mm hole in the floor beside the tube."""
hole(d, d.caption)
d.wait(1.5)
@shot("features/pattern", "clip", setup=holed)
def features_pattern(d):
"""The hole repeated four times around the tube."""
pattern(d, d.caption)
d.wait(1.5)
@shot("parameters/dialog", "still", setup=patterned)
def parameters_dialog(d):
"""Change Parameters, numbered: 1 apply as you go, 2 user parameters, 3 model parameters
grouped by feature, 4 an expression, 5 its value."""
d.tool("parameters.change")
d.wait(1.0)
d.ui("ui.move", {"x": 5, "y": 600})
n = {h["name"]: (h["x"], h["y"]) for h in d.ui("ui.handles")}
x0, y0 = n["dialog:title"][0] - 400, n["dialog:title"][1] - 22
d.crop = (int(x0), int(y0), 800, 500)
# Wide rows' handles are their middles: each number goes in the gap beside its item, measured
# from the rows it belongs to.
d.callouts += [
(x0 + 290, n["params:apply_live"][1]),
(x0 + 165, n["dialog:table:user:add"][1]),
(x0 + 165, n["dialog:section:Sketch1"][1]),
(n["dialog:Expression"][0] - 95, n["dialog:cell:d1"][1]),
(n["dialog:report:value:d1"][0] + 30, n["dialog:report:value:d1"][1] - 32),
]
@shot("features/edit", "clip", setup=patterned)
def features_edit(d):
"""Double-click Extrude1 on the timeline, make it 20 mm: everything after it follows."""
d.caption("Double-click a feature on the timeline")
t = d.at(handle="timeline:Extrude1")
d.glide(t, 0.8)
d.ui("ui.click", {"x": t[0], "y": t[1], "double": True})
d.mark(cursor=list(t), click=True)
d.wait(1.2)
d.settle_camera()
d.caption("Change it: 20, Enter. The features after it follow")
typed(d, "20")
for name in ("Extrude1", "Shell1", "Fillet1", "Hole1", "CircularPattern1"):
wait_feature(d, name)
if features(d)[-1:] != ["CircularPattern1"]:
raise RuntimeError(f"the timeline did not rebuild: {features(d)}")
# Off the timeline (a feature under the pointer lights up its body), nothing selected.
d.glide((SIZE[0] * 0.55, SIZE[1] * 0.75), 0.8)
for _ in range(10):
d.key("Escape")
if not d.ui("ui.selection")["selection"]:
break
time.sleep(0.5)
d.wait(2.0)
# assemblies.md: two loose hinge leaves made into components, joined by a revolute joint on
# their barrels, then swung by a drag. Leaf B starts lifted and set back, so the joint visibly
# brings it into place.
B_LIFT = (25, 20) # mm along Y and Z
def hinge_view(d):
d.ui("ui.camera", {"target": [26, 40, 8], "yaw": -0.7854, "pitch": 0.6155, "distance": 150})
d.settle_camera()
def loose_leaves(d):
"""Leaf A (its barrel on the far side) and Leaf B (its barrel on the near side), as bodies."""
dy, dz = B_LIFT
d.execute("solid.box", {"length": 40, "width": 30, "height": 3, "corner": [0, 0, 0], "body_name": "Leaf A"})
d.execute("solid.cylinder", {"base": [0, 33, 4], "axis": [1, 0, 0], "radius": 4, "height": 40, "operation": "join", "targets": ["Leaf A"]})
d.execute("solid.box", {"length": 40, "width": 30, "height": 3, "corner": [0, 36 + dy, dz], "body_name": "Leaf B"})
d.execute("solid.cylinder", {"base": [0, 33 + dy, 4 + dz], "axis": [1, 0, 0], "radius": 4, "height": 40, "operation": "join", "targets": ["Leaf B"]})
hinge_view(d)
def components(d, label=lambda text: None):
label("Right-click Bodies: Create Components from Bodies")
b = d.at(handle="row:Bodies")
d.glide(b, 0.8)
d.ui("ui.click", {"x": b[0], "y": b[1], "button": "right"})
d.mark(cursor=list(b), click=True)
d.wait(0.8)
d.click(d.at(handle="menu:component.from_bodies"), dur=0.6, settle=1.0)
rows = {h["name"] for h in d.ui("ui.handles") if h["name"].startswith("row:")}
if not {"row:Leaf A:1", "row:Leaf B:1"} <= rows:
raise RuntimeError(f"no components: {sorted(rows)}")
def leaves(d):
loose_leaves(d)
components(d)
def joint(d, label=lambda text: None):
label("Joint: click Leaf B's barrel end, then Leaf A's")
d.click(d.at(handle="tab:ASSEMBLE"), dur=0.6, settle=0.5)
d.tool("joint.create")
dy, dz = B_LIFT
d.click(d.at(world=[40, 33 + dy, 8 + dz]), dur=0.6, settle=0.8)
d.click(d.at(world=[40, 33, 8]), dur=0.6, settle=1.0)
label("Type: Revolute. Flip turns Leaf B the right way round")
d.click(d.at(handle="dialog:Type"), dur=0.5, settle=0.6)
d.click(d.at(handle="dialog:Type:Revolute"), dur=0.4, settle=0.8)
d.click(d.at(handle="dialog:Flip"), dur=0.6, settle=1.2)
d.click(d.at(handle="dialog:ok"), dur=0.6, settle=1.5)
if "row:Joint1" not in {h["name"] for h in d.ui("ui.handles")}:
raise RuntimeError("no Joint1 in the browser")
def joined(d):
leaves(d)
joint(d)
@shot("assemblies/components", "clip", setup=loose_leaves)
def assemblies_components(d):
"""Two bodies become two components; the first is grounded (the pin)."""
components(d, d.caption)
d.caption("Each body is a component now; the first is grounded (the pin)")
d.glide(d.at(handle="row:Leaf A:1"), 0.8)
d.wait(2.0)
@shot("assemblies/joint", "clip", setup=leaves)
def assemblies_joint(d):
"""A revolute joint on the two barrels: Leaf B drops into place beside Leaf A."""
joint(d, d.caption)
d.caption("")
d.glide((SIZE[0] * 0.55, SIZE[1] * 0.8), 0.6)
d.wait(1.5)
@shot("assemblies/drag", "clip", setup=joined)
def assemblies_drag(d):
"""Drag Leaf B: it turns about the joint, and grounded Leaf A stays put."""
d.caption("Drag Leaf B: it can only turn about the hinge")
p = d.at(world=[30, 55, 3])
d.drag(p, (p[0] + 10, p[1] - 170), steps=70)
d.wait(0.8)
d.drag(d.pos, (d.pos[0] - 5, d.pos[1] + 90), steps=50)
d.wait(0.8)
d.caption("Leaf A is grounded: it stays where it is")
p = d.at(world=[20, 10, 3])
d.drag(p, (p[0] - 80, p[1] + 40), steps=40)
d.wait(1.5)
@shot("assemblies/drive", "clip", setup=joined)
def assemblies_drive(d):
"""Drive Joints: the slider turns the hinge through its angle, OK keeps it there."""
d.caption("Drive Joints: drag the slider, or type the angle")
d.tool("joint.drive")
s = d.at(handle="drive_slider:0")
d.drag(s, (s[0] - 80, s[1]), steps=60)
d.wait(0.6)
d.drag(d.pos, (d.pos[0] + 45, d.pos[1]), steps=40)
d.wait(0.6)
d.click(d.at(handle="dialog:ok"), dur=0.6, settle=1.0)
d.caption("")
d.glide((SIZE[0] * 0.55, SIZE[1] * 0.85), 0.6)
d.wait(1.5)
# getting-started.md: the start page, and a sample opened from it.
def start_page(d):
d.ui("ui.home", {"open": True})
d.wait(2.0)
d.ui("ui.move", {"x": 700, "y": 790})
d.settle_camera()
@shot("getting-started/start", "still", setup=start_page)
def getting_started_start(d):
"""The start page, numbered: 1 new design, 2 open, 3 import, 4 recent designs, 5 samples,
6 the File menu."""
n = {h["name"]: (h["x"], h["y"]) for h in d.ui("ui.handles")}
left = n["home:new_mm"][0] - 154 # the tiles' left edge
d.callouts += [
(n["home:new_mm"][0] + 128, n["home:new_mm"][1] - 18),
(n["home:open_tile"][0] + 112, n["home:open_tile"][1] - 18),
(n["home:import"][0] + 128, n["home:import"][1] - 18),
(left + 105, n["home:import"][1] + 81),
(left + 105, n["home:sample:0"][1] - 112),
(n["home:recover"][0] + 100, n["home:recover"][1] + 32),
]
@shot("getting-started/sample", "clip", setup=start_page)
def getting_started_sample(d):
"""Open a sample from the start page and turn it to look round."""
d.caption("Click a sample to open it")
d.click(d.at(handle="home:sample:0"), dur=0.8, settle=2.0)
for _ in range(50):
if not d.ui("ui.home").get("open"):
break
time.sleep(0.2)
else:
raise RuntimeError("the sample did not open")
d.settle_camera()
d.caption("")
d.wait(0.8)
d.orbit(220, 0, steps=60)
d.wait(1.5)
# sheet-metal.md: a tray: a base flange from a sketched rectangle, two edge flanges, flat pattern.
PLATE = (80, 50)
def sheet_view(d):
d.ui("ui.camera", {"target": [PLATE[0] / 2, PLATE[1] / 2, 8], "yaw": -0.7854, "pitch": 0.6155, "distance": 170})
d.settle_camera()
def plate_sketch(d):
d.execute("sketch.create", {"plane": "XY"})
d.execute("sketch.rectangle.two_point", {"p0": [0, 0], "p1": list(PLATE)})
d.execute("sketch.finish")
sheet_view(d)
d.click(d.at(handle="tab:SHEET METAL"), dur=0.2, settle=0.6)
def base_flange(d, label=lambda text: None):
label("Flange: click the sketch's profile, OK")
d.tool("sheet.flange")
d.click(d.at(world=[PLATE[0] * 0.75, PLATE[1] * 0.8, 0]), dur=0.6, settle=1.0)
d.click(d.at(handle="dialog:ok"), dur=0.6, settle=1.0)
wait_feature(d, "BaseFlange1")
def edge_flanges(d, label=lambda text: None):
label("Flange again: click two top edges, height 20, Enter")
d.tool("sheet.flange")
top = 2.5 # the default rule's thickness
for y in (0, PLATE[1]):
d.click(d.at(world=[PLATE[0] / 2, y, top]), dur=0.6, settle=0.8)
typed(d, "20")
wait_feature(d, "EdgeFlange1")
def base(d):
plate_sketch(d)
base_flange(d)
def tray(d):
base(d)
edge_flanges(d)
@shot("sheet-metal/base", "clip", setup=plate_sketch)
def sheet_metal_base(d):
"""A base flange from a sketched rectangle, at the rule's thickness."""
base_flange(d, d.caption)
d.wait(1.5)
@shot("sheet-metal/flange", "clip", setup=base)
def sheet_metal_flange(d):
"""Edge flanges up from two top edges, bent at the rule's radius."""
edge_flanges(d, d.caption)
d.wait(1.5)
@shot("sheet-metal/flat", "clip", setup=tray)
def sheet_metal_flat(d):
"""Flat Pattern: the part unfolded with its bend lines and bend table."""
d.caption("Flat Pattern: the part unfolded, with its bends")
d.tool("sheet.flat_pattern")
d.wait(2.5)
d.settle_camera()
d.click(d.at(handle="dialog:cancel"), dur=0.8, settle=1.0)
d.caption("")
d.wait(1.0)
# files.md: the File menu, where opening, inserting, saving and exporting start.
@shot("files/menu", "still", start="sample")
def files_menu(d):
"""The File menu, numbered: 1 open, 2 insert into this design, 3 save, 4 export, 5 design
properties."""
d.click(d.at(handle="appbar:file"), dur=0.2, settle=0.8)
d.ui("ui.move", {"x": 700, "y": 790})
d.settle_camera()
n = {h["name"]: (h["x"], h["y"]) for h in d.ui("ui.handles")}
right = n["menu:Open…"][0] + 135 # past the shortcuts, inside the menu's right edge
d.crop = (0, 0, 640, 800)
d.callouts += [
(right + 40, n["menu:Open…"][1]),
(right + 40, (n["menu:Insert STEP…"][1] + n["menu:Insert Design…"][1]) / 2),
(right + 40, (n["menu:Save"][1] + n["menu:Save As JSON…"][1]) / 2),
(right + 40, (n["menu:Export STL…"][1] + n["menu:Export Design as JSON…"][1]) / 2),
(right + 40, n["menu:Design Properties…"][1]),
]
# -- main ---------------------------------------------------------------------------------------
def main():
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("shots", nargs="*", help="shot names, or a page (ui-tour); default every shot")
ap.add_argument("--list", action="store_true")
ap.add_argument("--app", default=str(Path(os.environ.get("CARGO_TARGET_DIR") or ROOT / "target") / "release/solidcraft"))
ap.add_argument("--display", default=":97", help="the Xvfb display to start (or use, with --no-xvfb)")
ap.add_argument("--no-xvfb", action="store_true", help="use a display that is already running")
ap.add_argument("--keep", action="store_true", help="keep each shot's work folder")
a = ap.parse_args()
if a.list:
for name, (kind, start, f, _) in SHOTS.items():
print(f"{name:32} {kind:5} {start:6} {(f.__doc__ or '').split(chr(10))[0]}")
return
names = [n for n in SHOTS if not a.shots or n in a.shots or n.split("/")[0] in a.shots]
if a.shots and not names:
sys.exit(f"no such shot: {' '.join(a.shots)} (--list)")
xvfb = None
if not a.no_xvfb:
xvfb = subprocess.Popen(["Xvfb", a.display, "-screen", "0", f"{SIZE[0]}x{SIZE[1]}x24", "-nolisten", "tcp"], stderr=subprocess.DEVNULL)
time.sleep(1.0)
try:
for n in names:
print(f"{n} ...", file=sys.stderr)
run_shot(n, a.app, a.display, a.keep)
finally:
if xvfb:
xvfb.terminate()
if __name__ == "__main__":
main()