Robot firmware banner, canvas size in mm, and current/last job.

Render polylines (canvas mm, [[ [u,v], ... ], ...]) without drawing. Returns the diagnostic view (pink = pen-up travel, grey box = page) and, with simulate=true (default), what the arm will actually put on paper.

Draw polylines given in canvas millimetres: [[ [u,v], [u,v], ... ], ...]. Each inner list is one pen-down stroke. Returns a job_id. speed: G94 S, the max step size for PEN-DOWN moves (1 finest/slowest .. 30 coarsest/fastest, default 5). Not a speed dial: it is interpolation granularity. Pen-UP travel is G94 P, set by LINEUS_TRAVEL_SPEED. order: how strokes are sequenced. "human" (default) top row first, left to right within a row, never reversed. Looks like a person drawing. Costs more pen-up travel (~2.8x on text) but this machine is slow enough that it rarely matters. "fast" nearest-neighbour, may draw a stroke backwards. Least travel, but it hops between rows and looks chaotic to watch. "asis" exactly the order supplied, untouched — you control the sequence.

Render an SVG (paths/shapes, strokes only — fills are ignored) fitted into the box (x,y,w,h) in canvas mm (default: whole canvas). Returns a PNG.

Draw an SVG fitted into box (x,y,w,h) in canvas mm, aspect ratio kept. Line art works best; fills are not hatched. Returns a job_id.

Render single-stroke (Hershey) text fitted into box (x,y,w,h) mm. Use \n for new lines. Prefer the HANDWRITING faces -- print: neutral architect pancakes delight casual; cursive (welded, one stroke per word): italienne cursive2 brush allure. call list_fonts() for the measurements. Hershey names still work but most of them retrace every stem.

Write text with a single-stroke Hershey font fitted into box (x,y,w,h) mm. Prefer the handwriting faces: print neutral/architect, cursive italienne/ cursive2 (these weld into one stroke per word). See list_fonts(). For multi-line or MULTI-FONT text prefer a scene: draw_scene puts several fonts and alignment in one call. speed: G94 S, max step size for pen-down moves, 1 (finest) .. 30 (coarsest).

Render a declarative SCENE as a PNG without drawing. Prefer this over preview_paths: a scene is ~50x smaller than the coordinates it compiles to, and draw_scene given the SAME scene provably draws what you previewed.

scene = {"shapes": [ ...shape... ], "fit": [x,y,w,h] (optional, scales the lot)}

There is deliberately NO library of shapes -- a fixed catalogue would handle the
dull cases and send everything interesting back to pasting raw points. Curves are
EXPRESSIONS, so the vocabulary is open:

  {"param": {"t": [0, 6.2832, 200],
             "x": "33+5.5*cos(t)", "y": "30+5.5*sin(t)", "closed": true}}

is a circle; change the expressions and it is a spiral, rose, lissajous or
harmonograph. Variables: t, plus i and n inside "repeat". Functions: sin cos tan
asin acos atan atan2 sinh cosh tanh exp log sqrt hypot floor ceil fmod degrees
radians abs min max round pow sign clamp lerp; constants pi, tau, e.

Producers (exactly one per shape):
  "param"  {"t":[start,stop,steps], "x":expr, "y":expr, "closed":bool}
  "path"   [[u,v], ...]                      one stroke, the escape hatch
  "paths"  [[[u,v], ...], ...]               several strokes
  "text"   "a

b", or [{"s":"a","font":"timesr"}, {"s":"b","font":"scriptc"}] with "font", "align" (left|center|right), "leading" (default 1.4) "svg" "..." "doodle" "cat", with "pick" (index), "source" (auto|bundled|web) -- real drawings from Google's Quick, Draw!, single strokes in the order a person drew them. Call doodles() first to SEE the candidates and choose a pick. Modifiers (any producer): "fill" {"hatch":deg, "spacing":mm (default 1.15), "cross":bool, "outline":bool} -- hatching is how you get solid black here "transform" {"translate":[dx,dy], "rotate":deg, "scale":s|[sx,sy], "about":[x,y]} "box"/"fit" [x,y,w,h] scale this shape into a box "repeat" N, with i (0..N-1) and n available in the expressions

Draw a declarative scene (same object as preview_scene -- see it for the shape language). Compilation is deterministic and content-hashed, so passing the scene you previewed draws exactly what you saw. Returns a job_id and the scene_id.

Compile a scene and report what it would cost, WITHOUT drawing or rendering: stroke/point counts, bounding box, pen-up travel and any warnings.

Every typeface available to text, draw_text and a scene's "text" producer.

Two families, and the difference matters on paper:

HANDWRITING (fonts/, SIL OFL) -- real single-line handwriting faces, print and cursive. Each letter is drawn ONCE. Prefer these. HERSHEY -- the classic 1967 engraving set, kept for compatibility. Its bold and serif faces fake weight by RETRACING every stem (a capital H in rowmant is 27 strokes), which on a pen plotter reads as a scribble. Pass include_hershey=true to list them.

Three measurements decide whether a face works here, and they catch different failures -- all three were learned the hard way on paper: passes strokes per letter vs a human's. Catches retracing. aperture the width of a letter's opening (the gap in s/a/e/o/g) against the 1-2 mm the firmware's corner blending eats. Catches letters that close into blobs: brush at 0.89 mm turned "oo" into "rr" on the test sheet. joins for cursive, whether letters weld into one continuous stroke per word.

Worked example scenes: finished drawings that went through several rounds of critique on this machine. With no name, lists them. With a name, returns the scene -- pass it to preview_scene as-is, or modify it ("the cat, lying down") rather than starting from nothing. Each carries a _comment explaining what made it work.

Real doodles from Google's Quick, Draw! dataset (CC BY 4.0): single strokes, in the order a person drew them, so line width comes from the pen alone.

With no category: the curated categories bundled with the server, and every category that can be fetched from the web (345 in all). With a category: a NUMBERED CONTACT SHEET of candidates. Look at it and choose a pick, then use {"doodle": category, "pick": N, "box": [x,y,w,h]} in a scene.

source: "auto" (default) uses the curated set if the category has one, else fetches from the web; "web" always fetches -- more variety, NO human review; "bundled" never goes online. Fetched categories are cached on disk, which keeps preview and draw identical. Web candidates are ranked automatically but many are still scribbles or have the word written in them: that is what the contact sheet is for. Draw with order="asis" to replay a doodle exactly as its author drew it.

Progress of a drawing job.

Stop the current drawing, lift the pen and go home.

Lift the pen and move the arm to its home position.

Draws a frame around the canvas plus an 'F' in the top-left corner so a human can confirm the canvas orientation (F must read normally, top-left).