API reference#

Predefined string variables#

Names below are ordinary string variables, available without declarations. User bindings take priority; the equivalent quoted value remains legal. Contextual meaning belongs to parameter documentation, not variable hover.

Variable	Type	String value
`auto`	`string`	`"auto"`
`axes`	`string`	`"axes"`
`bar`	`string`	`"bar"`
`bevel`	`string`	`"bevel"`
`both`	`string`	`"both"`
`bottom`	`string`	`"bottom"`
`bottom_center`	`string`	`"bottom_center"`
`bottom_left`	`string`	`"bottom_left"`
`bottom_right`	`string`	`"bottom_right"`
`boundary`	`string`	`"boundary"`
`box`	`string`	`"box"`
`butt`	`string`	`"butt"`
`cartesian`	`string`	`"cartesian"`
`center`	`string`	`"center"`
`centered`	`string`	`"centered"`
`chord`	`string`	`"chord"`
`circle`	`string`	`"circle"`
`cm`	`string`	`"cm"`
`contain`	`string`	`"contain"`
`container`	`string`	`"container"`
`count`	`string`	`"count"`
`cover`	`string`	`"cover"`
`cross`	`string`	`"cross"`
`dash`	`string`	`"dash"`
`dash_dot`	`string`	`"dash_dot"`
`dashed`	`string`	`"dashed"`
`deg`	`string`	`"deg"`
`density`	`string`	`"density"`
`diamond`	`string`	`"diamond"`
`display`	`string`	`"display"`
`dot`	`string`	`"dot"`
`dots`	`string`	`"dots"`
`dotted`	`string`	`"dotted"`
`double`	`string`	`"double"`
`end`	`string`	`"end"`
`evenodd`	`string`	`"evenodd"`
`horizontal`	`string`	`"horizontal"`
`in`	`string`	`"in"`
`inch`	`string`	`"inch"`
`incoming`	`string`	`"incoming"`
`inline`	`string`	`"inline"`
`inout`	`string`	`"inout"`
`italic`	`string`	`"italic"`
`justify`	`string`	`"justify"`
`left`	`string`	`"left"`
`linear`	`string`	`"linear"`
`local`	`string`	`"local"`
`log`	`string`	`"log"`
`long_dash`	`string`	`"long_dash"`
`lower`	`string`	`"lower"`
`major`	`string`	`"major"`
`mathjax_newcm`	`string`	`"mathjax-newcm"`
`mathjax_tex`	`string`	`"mathjax-tex"`
`mid`	`string`	`"mid"`
`middle_left`	`string`	`"middle_left"`
`middle_right`	`string`	`"middle_right"`
`miter`	`string`	`"miter"`
`mm`	`string`	`"mm"`
`none`	`string`	`"none"`
`nonzero`	`string`	`"nonzero"`
`normal`	`string`	`"normal"`
`offset`	`string`	`"offset"`
`open`	`string`	`"open"`
`out`	`string`	`"out"`
`outgoing`	`string`	`"outgoing"`
`parent`	`string`	`"parent"`
`plain`	`string`	`"plain"`
`plot_bottom_center`	`string`	`"plot_bottom_center"`
`plot_bottom_left`	`string`	`"plot_bottom_left"`
`plot_bottom_right`	`string`	`"plot_bottom_right"`
`plot_center`	`string`	`"plot_center"`
`plot_middle_left`	`string`	`"plot_middle_left"`
`plot_middle_right`	`string`	`"plot_middle_right"`
`plot_top_center`	`string`	`"plot_top_center"`
`plot_top_left`	`string`	`"plot_top_left"`
`plot_top_right`	`string`	`"plot_top_right"`
`polar`	`string`	`"polar"`
`post`	`string`	`"post"`
`pre`	`string`	`"pre"`
`probability`	`string`	`"probability"`
`pt`	`string`	`"pt"`
`px`	`string`	`"px"`
`rad`	`string`	`"rad"`
`radar`	`string`	`"radar"`
`raster`	`string`	`"raster"`
`ratex_katex`	`string`	`"ratex-katex"`
`raw`	`string`	`"raw"`
`right`	`string`	`"right"`
`round`	`string`	`"round"`
`scientific`	`string`	`"scientific"`
`shortest`	`string`	`"shortest"`
`single`	`string`	`"single"`
`slash`	`string`	`"slash"`
`solid`	`string`	`"solid"`
`square`	`string`	`"square"`
`start`	`string`	`"start"`
`stealth`	`string`	`"stealth"`
`stretch`	`string`	`"stretch"`
`symlog`	`string`	`"symlog"`
`target`	`string`	`"target"`
`top`	`string`	`"top"`
`top_center`	`string`	`"top_center"`
`top_left`	`string`	`"top_left"`
`top_right`	`string`	`"top_right"`
`triangle`	`string`	`"triangle"`
`triangle_down`	`string`	`"triangle_down"`
`triple`	`string`	`"triple"`
`upper`	`string`	`"upper"`
`vector`	`string`	`"vector"`
`vertical`	`string`	`"vertical"`
`x`	`string`	`"x"`
`y`	`string`	`"y"`

canvas#

Create a page with physical dimensions, a background and a default geometry unit. Place material with add. Unitless geometry initially uses mm; font sizes and line widths use pt.

Returns: A page that accepts placed material.

Required: size.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`name`	string	Canvas title or unique named-axis identifier	"Untitled"
`size`	(length, length) / canvas unit	Page (width,height); both lengths must be positive; auto is unsupported	—
`unit`	"mm" \| "cm" \| "in" \| "inch" \| "pt" \| "px"	Default unit for bare geometry lengths; excludes data and typography `mm`: Millimeters `cm`: Centimeters `in`: Inches `inch`: Inches `pt`: Points, 1/72 inch `px`: Layout pixels converted using layout_dpi	mm
`layout_dpi`	number	Conversion between px and physical lengths; independent of export DPI	96
`stylesheet`	string \| string[]	.lcss path or ordered list of paths	—
`class`	string	Space-separated LCSS class names	""
`background`	paint	Background paint for the object region, separate from text or lines	none
`font_family`	string \| string[]	System family, font file path or ordered list. No body fonts are bundled; missing glyphs warn and render as boxes.	system sans-serif
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	继承 / inherit
`font_weight`	integer	Font weight, 100–900	400
`font_style`	"normal" \| "italic"	Normal or italic `normal`: Upright font style `italic`: Italic font style	normal
`color`	color	Text color or base series color	—
`line_height`	length / pt	Text line height; unitless values are pt	1.2 × font_size

Minimal complete example#

1# Minimal complete example: canvas2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(text("Physical page",font_size=12pt),offset=(5mm,5mm))

# Minimal complete example: canvas
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(text("Physical page",font_size=12pt),offset=(5mm,5mm))

Concepts and common errors · Composition source

image#

Define reusable image material from a local file. add controls size, crop and contain/cover/stretch fitting; paths resolve relative to the defining file. Accepts PNG, JPEG, BMP, WebP, GIF, ICO, PNM, TGA, safe SVG, and single-page unsigned 8/16-bit grayscale/RGB TIFF with optional alpha. GIF and animated WebP use the first frame; 16-bit intensities are not stretched.

Returns: material

Positional parameters: src.

Required: src.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`src`	string	Local resource path relative to the defining file	—
`size`	(length \| auto, length \| auto) / canvas unit	Physical (width,height); auto preserves aspect or natural layout	—
`class`	string	Space-separated LCSS class names	""
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: image2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(image(src="../assets/photo.png"),size=(55mm,auto),offset=(8mm,8mm))

# Minimal complete example: image
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(image(src="../assets/photo.png"),size=(55mm,auto),offset=(8mm,8mm))

Concepts and common errors · Composition source

text#

Create text material, recognizing inline mathematics in ordinary strings. Configure font fallback, size, color and a background box. size can constrain wrapping; raw strings disable automatic mathematics.

Returns: Reusable text material.

Positional parameters: content.

Required: content / spans.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`content`	string	Text content; $…$ enables math, raw strings disable automatic math	—
`spans`	(span \| formula)[]	Ordered span(...) and formula(...) items	—
`size`	(length \| auto, length \| auto) / canvas unit	Physical (width,height); auto preserves aspect or natural layout	—
`class`	string	Space-separated LCSS class names	""
`font_family`	string \| string[]	System family, font file path or ordered list. No body fonts are bundled; missing glyphs warn and render as boxes.	system sans-serif
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	10pt
`font_weight`	integer	Font weight, 100–900	400
`font_style`	"normal" \| "italic"	Normal or italic `normal`: Upright font style `italic`: Italic font style	normal
`color`	color	Text color or base series color	—
`line_height`	length / pt	Text line height; unitless values are pt	1.2 × font_size
`align`	"left" \| "center" \| "right" \| "justify"	Horizontal text alignment in its frame `left`: Left side or left alignment, according to the parameter `center`: Center alignment `right`: Right side or right alignment, according to the parameter `justify`: Justify within the available width	left
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: text2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(text("Wrapping preserves physical type size.",size=(45mm,auto),font_size=12pt),offset=(8mm,8mm))

# Minimal complete example: text
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(text("Wrapping preserves physical type size.",size=(45mm,auto),font_size=12pt),offset=(8mm,8mm))

Concepts and common errors · Composition source

span#

Define a run inside text(spans=[...]) with local font/color overrides. A span is not independently placed material.

Returns: value

Positional parameters: content.

Required: content.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`content`	string	Text content; $…$ enables math, raw strings disable automatic math	—
`class`	string	Space-separated LCSS class names	""
`font_family`	string \| string[]	System family, font file path or ordered list. No body fonts are bundled; missing glyphs warn and render as boxes.	system sans-serif
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	继承 / inherit
`font_weight`	integer	Font weight, 100–900	400
`font_style`	"normal" \| "italic"	Normal or italic `normal`: Upright font style `italic`: Italic font style	normal
`color`	color	Text color or base series color	—

Minimal complete example#

1# Minimal complete example: span2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(text(spans=[span("Red ",color="#e36b70"),span("bold",font_weight=700)],font_size=12pt),offset=(8mm,8mm))

# Minimal complete example: span
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(text(spans=[span("Red ",color="#e36b70"),span("bold",font_weight=700)],font_size=12pt),offset=(8mm,8mm))

Concepts and common errors · Composition source

formula#

Create formula material from LaTeX without dollar delimiters, or a run in text. Raw strings preserve backslashes; style selects inline/display layout.

Returns: material

Positional parameters: source.

Required: source.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`source`	string	LaTeX formula source without dollar delimiters	—
`class`	string	Space-separated LCSS class names	""
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	10pt (inherit in text)
`color`	color	Text color or base series color	#000000
`math_font`	"ratex-katex" \| "mathjax-newcm" \| "mathjax-tex"	RaTeX KaTeX formula fonts. Legacy mathjax-* names warn and map to ratex-katex. `ratex-katex`: Current default RaTeX mathematical font `mathjax-newcm`: Legacy name mapped to the current default font `mathjax-tex`: Legacy name mapped to the current default font	ratex-katex
`style`	"inline" \| "display"	Style object for plots; inline/display for explicit formulas `inline`: Inline mathematical layout `display`: Display mathematical layout	—
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: formula2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(formula(r"E=mc^2",style=display,font_size=16pt,math_font=ratex_katex),offset=(8mm,8mm))

# Minimal complete example: formula
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(formula(r"E=mc^2",style=display,font_size=16pt,math_font=ratex_katex),offset=(8mm,8mm))

Concepts and common errors · Composition source

rect#

Create a rectangle material. Set physical dimensions with size, interior paint with fill, the outline with border_*, and rounded corners with border_radius. Place it on the page with add.

Returns: Reusable rectangle material.

Required: size.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`size`	(length \| auto, length \| auto) / canvas unit	Physical (width,height); auto preserves aspect or natural layout	—
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	0.3mm (if border_color is set)
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: rect2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(40mm,25mm),border_radius=7mm,fill="#e6f2f3",border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: rect
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(40mm,25mm),border_radius=7mm,fill="#e6f2f3",border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

ellipse#

Define ellipse material with size=(width,height). fill and border_* control interior and outline; layout corners need not lie on the ellipse.

Returns: material

Required: size.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`size`	(length \| auto, length \| auto) / canvas unit	Physical (width,height); auto preserves aspect or natural layout	—
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	0.3mm (if border_color is set)
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: ellipse2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(ellipse(size=(45mm,25mm),fill="#e6f2f3",border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: ellipse
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(ellipse(size=(45mm,25mm),fill="#e6f2f3",border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

line#

Create a line using dx/dy or length/angle, with independent endpoint caps and heads. Zero length requires an explicit angle. Heads retain their size on short lines.

Returns: material

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`length`	length / canvas unit	Nonnegative line length; mutually exclusive with dx/dy	—
`angle`	angle / deg	Local direction: 0 right, 90 down; required explicitly for zero length	0deg
`dx`	length / canvas unit	Horizontal line displacement; requires dy, exclusive with length/angle	—
`dy`	length / canvas unit	Vertical line displacement; requires dx, exclusive with length/angle	—
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	#000000
`line_width`	length / pt	Open-line width; unitless values are pt	0.3pt
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`start_head`	head	Start head configuration; absent by default	—
`end_head`	head	End head configuration; absent by default	—
`start_cap`	"butt" \| "round" \| "square"	Independent endpoint cap; inherits line_cap `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	inherits line_cap
`end_cap`	"butt" \| "round" \| "square"	Independent endpoint cap; inherits line_cap `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	inherits line_cap

Minimal complete example#

1# Minimal complete example: line2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(line(length=55mm,angle=20deg,start_cap=round,end_head=head(shape=triangle,size=(6mm,5mm)),line_width=2mm),offset=(12mm,15mm))

# Minimal complete example: line
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(line(length=55mm,angle=20deg,start_cap=round,end_head=head(shape=triangle,size=(6mm,5mm)),line_width=2mm),offset=(12mm,15mm))

Concepts and common errors · Composition source

group#

Create a reusable container with local coordinates. Populate it before placement; first placement seals contents and reuse replays internal positioning dependencies.

Returns: material

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`class`	string	Space-separated LCSS class names	""
`font_family`	string \| string[]	System family, font file path or ordered list. No body fonts are bundled; missing glyphs warn and render as boxes.	system sans-serif
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	继承 / inherit
`font_weight`	integer	Font weight, 100–900	400
`font_style`	"normal" \| "italic"	Normal or italic `normal`: Upright font style `italic`: Italic font style	normal
`color`	color	Text color or base series color	—
`line_height`	length / pt	Text line height; unitless values are pt	1.2 × font_size
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: group2page=canvas(size=(100mm,75mm),background="#ffffff")3g=group()4a=g.add(rect(size=(35mm,20mm),fill="#e6f2f3"))5g.add(text("Reused"),target=a.center,anchor=center)6page.add(g,offset=(8mm,8mm))7page.add(g,offset=(55mm,38mm),rotation=15deg)

# Minimal complete example: group
page=canvas(size=(100mm,75mm),background="#ffffff")
g=group()
a=g.add(rect(size=(35mm,20mm),fill="#e6f2f3"))
g.add(text("Reused"),target=a.center,anchor=center)
page.add(g,offset=(8mm,8mm))
page.add(g,offset=(55mm,38mm),rotation=15deg)

Concepts and common errors · Composition source

path#

Define a path from original move_to/line_to/quad_to/cubic_to/arc_to/close commands. It may contain multiple subpaths; open subpaths support caps and heads.

Returns: material

Required: commands.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`commands`	path-command[]	Ordered path commands starting with move_to	—
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`start_head`	head	Start head configuration; absent by default	—
`end_head`	head	End head configuration; absent by default	—
`start_cap`	"butt" \| "round" \| "square"	Independent path endpoint cap, inheriting border_cap; internal dash caps are unaffected `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	inherits border_cap
`end_cap`	"butt" \| "round" \| "square"	Independent path endpoint cap, inheriting border_cap; internal dash caps are unaffected `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	inherits border_cap

Minimal complete example#

1# Minimal complete example: path2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(path(commands=[move_to(0mm,20mm),quad_to(20mm,0mm,40mm,20mm),line_to(40mm,35mm),close()],fill="#e6f2f3",border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: path
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(path(commands=[move_to(0mm,20mm),quad_to(20mm,0mm,40mm,20mm),line_to(40mm,35mm),close()],fill="#e6f2f3",border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

polygon#

Define an automatically closed polygon from at least three points. Node order determines traversal; fill_rule controls self-intersecting fills.

Returns: material

Required: points.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`points`	value	Point list; star uses an integer corner count, violin uses a KDE sample count	—
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: polygon2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(polygon(points=[(0mm,0mm),(40mm,0mm),(30mm,30mm)],fill="#e6f2f3"),offset=(10mm,10mm))

# Minimal complete example: polygon
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(polygon(points=[(0mm,0mm),(40mm,0mm),(30mm,30mm)],fill="#e6f2f3"),offset=(10mm,10mm))

Concepts and common errors · Composition source

polyline#

Define an open polyline from at least two points. line_* controls stroke, start_head/end_head locate at logical endpoints, and line_join controls corners.

Returns: material

Required: points.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`points`	value	Point list; star uses an integer corner count, violin uses a KDE sample count	—
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`start_head`	head	Start head configuration; absent by default	—
`end_head`	head	End head configuration; absent by default	—
`start_cap`	"butt" \| "round" \| "square"	Independent endpoint cap; inherits line_cap `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	inherits line_cap
`end_cap`	"butt" \| "round" \| "square"	Independent endpoint cap; inherits line_cap `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	inherits line_cap

Minimal complete example#

1# Minimal complete example: polyline2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(polyline(points=[(0mm,20mm),(20mm,0mm),(45mm,20mm)],line_color="#087f8c",line_width=1.5mm,line_join=round),offset=(10mm,10mm))

# Minimal complete example: polyline
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(polyline(points=[(0mm,20mm),(20mm,0mm),(45mm,20mm)],line_color="#087f8c",line_width=1.5mm,line_join=round),offset=(10mm,10mm))

Concepts and common errors · Composition source

arc#

Define an open circular arc with radius/start/end. Page angles point right at 0 and down at 90; caps and heads are supported without closing to a sector.

Returns: material

Required: radius, start, end.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`radius`	length / canvas unit	Geometric radius; normalized scalar for radial_gradient	—
`start`	value	Arc start angle; normalized start point for linear gradients	—
`end`	value	Arc end angle; normalized end point for linear gradients	—
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`start_head`	head	Start head configuration; absent by default	—
`end_head`	head	End head configuration; absent by default	—
`start_cap`	"butt" \| "round" \| "square"	Independent endpoint cap; inherits line_cap `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	inherits line_cap
`end_cap`	"butt" \| "round" \| "square"	Independent endpoint cap; inherits line_cap `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	inherits line_cap

Minimal complete example#

1# Minimal complete example: arc2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(arc(radius=20mm,start=0deg,end=120deg,line_width=1mm,end_head=head(shape=open)),offset=(15mm,15mm))

# Minimal complete example: arc
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(arc(radius=20mm,start=0deg,end=120deg,line_width=1mm,end_head=head(shape=open)),offset=(15mm,15mm))

Concepts and common errors · Composition source

sector#

Define a closed sector by radius and endpoint angles. Fill covers the region between center and arc; border_* controls the outline.

Returns: material

Required: radius, start, end.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`radius`	length / canvas unit	Geometric radius; normalized scalar for radial_gradient	—
`start`	value	Arc start angle; normalized start point for linear gradients	—
`end`	value	Arc end angle; normalized end point for linear gradients	—
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: sector2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(sector(radius=20mm,start=0deg,end=120deg,fill="#087f8c"),offset=(15mm,15mm))

# Minimal complete example: sector
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(sector(radius=20mm,start=0deg,end=120deg,fill="#087f8c"),offset=(15mm,15mm))

Concepts and common errors · Composition source

star#

Define a closed star with point count, outer/inner radii and rotation. inner_radius must be smaller than outer_radius.

Returns: material

Required: points, outer_radius, inner_radius.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`points`	value	Point list; star uses an integer corner count, violin uses a KDE sample count	—
`outer_radius`	length / canvas unit	Outer geometric radius	—
`inner_radius`	length / canvas unit	Inner geometric radius; physical hole radius for polar plots	0
`rotation`	value	Rotation about the instance center	0deg
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: star2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(star(points=5,outer_radius=20mm,inner_radius=9mm,fill="#e6f2f3",border_color="#087f8c"),offset=(15mm,15mm))

# Minimal complete example: star
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(star(points=5,outer_radius=20mm,inner_radius=9mm,fill="#e6f2f3",border_color="#087f8c"),offset=(15mm,15mm))

Concepts and common errors · Composition source

ring#

Define a ring with a transparent inner hole. inner_radius is smaller than outer_radius; the hole reveals underlying paint rather than covering it with background.

Returns: material

Required: outer_radius, inner_radius.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`outer_radius`	length / canvas unit	Outer geometric radius	—
`inner_radius`	length / canvas unit	Inner geometric radius; physical hole radius for polar plots	0
`class`	string	Space-separated LCSS class names	""
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: ring2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(ring(outer_radius=20mm,inner_radius=13mm,fill="#087f8c"),offset=(15mm,15mm))

# Minimal complete example: ring
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(ring(outer_radius=20mm,inner_radius=13mm,fill="#087f8c"),offset=(15mm,15mm))

Concepts and common errors · Composition source

box#

Create a rectangular region configuration for plot_area or crop. box draws nothing by itself; units depend on use, with crop using normalized 0–1 coordinates.

Returns: box

Required: size.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`offset`	(length, length) / canvas unit	Horizontal and vertical offset from the target	(0, 0)
`size`	(length \| auto, length \| auto) / canvas unit	Physical (width,height); auto preserves aspect or natural layout	—

Minimal complete example#

1# Minimal complete example: box2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(image(src="../assets/photo.png"),size=(60mm,auto),crop=box(offset=(0.25,0),size=(0.75,1)),offset=(10mm,10mm))

# Minimal complete example: box
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(image(src="../assets/photo.png"),size=(60mm,auto),crop=box(offset=(0.25,0),size=(0.75,1)),offset=(10mm,10mm))

Concepts and common errors · Composition source

instance.data#

Select an original-data point on a placed chart. Axis transforms, breaks, instance transforms and group replay resolve the reference again; the point must be in a valid visible domain.

Returns: anchor

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`category`	value	Radar category name	—
`value`	value	Input scalar, string or list element	—

Minimal complete example#

1# Minimal complete example: instance.data2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.scatter(x=[1,2,3],y=[1,3,2])5chart=page.add(p,offset=(7mm,6mm))6page.add(text("Peak"),target=chart.data(x=2,y=3),anchor=bottom_center,offset=(0mm,-2mm))

# Minimal complete example: instance.data
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.scatter(x=[1,2,3],y=[1,3,2])
chart=page.add(p,offset=(7mm,6mm))
page.add(text("Peak"),target=chart.data(x=2,y=3),anchor=bottom_center,offset=(0mm,-2mm))

Concepts and common errors · Composition source

instance.axis#

Select a named chart axis at its numeric start, physical midpoint or numeric end. Legacy transforms are retained; axes[name].spine.path provides explicit spine queries.

Returns: anchor

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`name`	string	Canvas title or unique named-axis identifier	—
`anchor`	"start" \| "center" \| "end"	Anchor on this instance used for alignment `start`: Start of the axis spine `center`: Midpoint of the axis spine `end`: End of the axis spine	top_left

Minimal complete example#

1# Minimal complete example: instance.axis2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.line(x=[0,1,2,3],y=[1,2,4,3])5chart=page.add(p,offset=(7mm,6mm))6page.add(ellipse(size=(2mm,2mm),fill="#e36b70"),anchor=center,target=chart.axis(name="x",anchor=center))

# Minimal complete example: instance.axis
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.line(x=[0,1,2,3],y=[1,2,4,3])
chart=page.add(p,offset=(7mm,6mm))
page.add(ellipse(size=(2mm,2mm),fill="#e36b70"),anchor=center,target=chart.axis(name="x",anchor=center))

Concepts and common errors · Composition source

add#

Place material in a canvas or group. Align its anchor to a target with an offset. Reuse the same material with independent size and styling for each placement.

Returns: A placed instance with measured dimensions and anchors for subsequent placement.

Positional parameters: material.

Required: material.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`size`	(length \| auto, length \| auto) / canvas unit	Physical (width,height); auto preserves aspect or natural layout	—
`fit`	"contain" \| "cover" \| "stretch"	contain preserves the whole image; cover crops; stretch distorts `contain`: Preserve aspect ratio and the complete content; unused space may remain `cover`: Preserve aspect ratio and fill the container; crop overflow `stretch`: Scale width and height independently to fill the target size	contain
`crop`	box (normalized 0–1)	Normalized crop region in the source image; coordinates are 0–1	—
`anchor`	"top_left" \| "top_center" \| "top_right" \| "middle_left" \| "center" \| "middle_right" \| "bottom_left" \| "bottom_center" \| "bottom_right" \| "start" \| "end" \| "plot_top_left" \| "plot_top_center" \| "plot_top_right" \| "plot_middle_left" \| "plot_center" \| "plot_middle_right" \| "plot_bottom_left" \| "plot_bottom_center" \| "plot_bottom_right" \| self selector	Source bounds name, line start/end, plot-only plot_* name, or a self geometry selector; targets belong to placed instances in the same container `top_left`: Top-left corner of the layout box `top_center`: Top-edge midpoint of the layout box `top_right`: Top-right corner of the layout box `middle_left`: Left-edge midpoint of the layout box `center`: Center of the layout box `middle_right`: Right-edge midpoint of the layout box `bottom_left`: Bottom-left corner of the layout box `bottom_center`: Bottom-edge midpoint of the layout box `bottom_right`: Bottom-right corner of the layout box `start`: Legacy start anchor for endpoint-bearing materials; retains legacy transform semantics `end`: Legacy end anchor for endpoint-bearing materials; retains legacy transform semantics `plot_top_left`: Plot-area box anchor; plot material only, transformed with the instance `plot_top_center`: Plot-area box anchor; plot material only, transformed with the instance `plot_top_right`: Plot-area box anchor; plot material only, transformed with the instance `plot_middle_left`: Plot-area box anchor; plot material only, transformed with the instance `plot_center`: Plot-area box anchor; plot material only, transformed with the instance `plot_middle_right`: Plot-area box anchor; plot material only, transformed with the instance `plot_bottom_left`: Plot-area box anchor; plot material only, transformed with the instance `plot_bottom_center`: Plot-area box anchor; plot material only, transformed with the instance `plot_bottom_right`: Plot-area box anchor; plot material only, transformed with the instance	top_left
`target`	anchor	Anchor on an instance in the same container; candidate collections require explicit indexing	parent.top_left
`offset`	(length, length) / canvas unit	Horizontal and vertical offset from the target	(0, 0)
`rotation`	angle	Rotate about the instance center; accepts a path anchor tangent_angle	0deg
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`class`	string	Space-separated LCSS class names	""
`font_family`	string \| string[]	System family, font file path or ordered list. No body fonts are bundled; missing glyphs warn and render as boxes.	system sans-serif
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	继承 / inherit
`font_weight`	integer	Font weight, 100–900	400
`font_style`	"normal" \| "italic"	Normal or italic `normal`: Upright font style `italic`: Italic font style	normal
`color`	color	Text color or base series color	—
`line_height`	length / pt	Text line height; unitless values are pt	1.2 × font_size
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`offset_space`	"container" \| "target"	Offset in container coordinates, or target tangent and left normal. `container`: Offsets follow the current container axes `target`: Offsets follow the target tangent and left normal	container

Minimal complete example#

1# Minimal complete example: add2page=canvas(size=(100mm,75mm),background="#ffffff")3material=rect(size=(25mm,18mm),fill="#087f8c")4a=page.add(material,offset=(10mm,10mm))5page.add(material,anchor=top_left,target=a.bottom_right,offset=(3mm,3mm))

# Minimal complete example: add
page=canvas(size=(100mm,75mm),background="#ffffff")
material=rect(size=(25mm,18mm),fill="#087f8c")
a=page.add(material,offset=(10mm,10mm))
page.add(material,anchor=top_left,target=a.bottom_right,offset=(3mm,3mm))

Concepts and common errors · Composition source

fuse#

Fuse visible outlines of two placed vector instances in one container; inputs leave drawing and references. Connecting a gap requires positive bridge_width; images/text/groups are unsupported.

Returns: instance

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`points`	value	Point list; star uses an integer corner count, violin uses a KDE sample count	—
`bridge_width`	length / canvas unit	Physical fusion bridge width	—
`junction`	value	Fusion junction mode	—
`radius`	length / canvas unit	Geometric radius; normalized scalar for radial_gradient	—
`fill`	paint	Interior color, gradient, pattern or image paint	none
`fill_rule`	value	Interior winding rule: nonzero/evenodd	nonzero
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: fuse2page=canvas(size=(100mm,75mm),background="#ffffff")3a=page.add(rect(size=(25mm,20mm),fill="#087f8c"),offset=(10mm,10mm))4b=page.add(rect(size=(25mm,20mm),fill="#087f8c"),offset=(30mm,10mm))5page.fuse(a,b,fill="#087f8c")

# Minimal complete example: fuse
page=canvas(size=(100mm,75mm),background="#ffffff")
a=page.add(rect(size=(25mm,20mm),fill="#087f8c"),offset=(10mm,10mm))
b=page.add(rect(size=(25mm,20mm),fill="#087f8c"),offset=(30mm,10mm))
page.fuse(a,b,fill="#087f8c")

Concepts and common errors · Composition source

linear_gradient#

Create linear-gradient paint with stops in 0–1 and start/end normalized to material bounds. Color alpha multiplies stop opacity.

Returns: paint

Required: stops.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`start`	value / scalar	Arc start angle; normalized start point for linear gradients	—
`end`	value / scalar	Arc end angle; normalized end point for linear gradients	—
`stops`	(number, color, number?)[] / scalar	At least two ordered (position 0–1, color[, opacity]) stops	—

Minimal complete example#

1# Minimal complete example: linear_gradient2page=canvas(size=(100mm,75mm),background="#ffffff")3paint=linear_gradient(stops=[(0,"#0072b2"),(1,"#ffffff90")])4page.add(rect(size=(60mm,30mm),fill=paint),offset=(10mm,10mm))

# Minimal complete example: linear_gradient
page=canvas(size=(100mm,75mm),background="#ffffff")
paint=linear_gradient(stops=[(0,"#0072b2"),(1,"#ffffff90")])
page.add(rect(size=(60mm,30mm),fill=paint),offset=(10mm,10mm))

Concepts and common errors · Composition source

radial_gradient#

Create radial-gradient paint with center/radius relative to bounds. Reuse the paint across different shapes; placement dimensions determine final rendering.

Returns: paint

Required: stops.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`center`	value / scalar	Gradient center coordinates or data center of color normalization	—
`radius`	value / scalar	Geometric radius; normalized scalar for radial_gradient	—
`stops`	(number, color, number?)[] / scalar	At least two ordered (position 0–1, color[, opacity]) stops	—

Minimal complete example#

1# Minimal complete example: radial_gradient2page=canvas(size=(100mm,75mm),background="#ffffff")3paint=radial_gradient(stops=[(0,"#ffffff"),(1,"#087f8c")])4page.add(ellipse(size=(60mm,35mm),fill=paint),offset=(10mm,10mm))

# Minimal complete example: radial_gradient
page=canvas(size=(100mm,75mm),background="#ffffff")
paint=radial_gradient(stops=[(0,"#ffffff"),(1,"#087f8c")])
page.add(ellipse(size=(60mm,35mm),fill=paint),offset=(10mm,10mm))

Concepts and common errors · Composition source

hatch#

Create slash/cross/dots pattern paint. spacing and line_width are physical dimensions; the pattern is confined to the material fill region.

Returns: paint

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`pattern`	"slash" \| "cross" \| "dots"	Repeating pattern: slash/cross/dots `slash`: Diagonal hatch pattern `cross`: Cross hatch pattern `dots`: Dot hatch pattern	slash
`color`	color	Text color or base series color	—
`background`	paint	Background paint for the object region, separate from text or lines	none
`spacing`	length / canvas unit	Physical pattern spacing	2mm
`line_width`	length / pt	Open-line width; unitless values are pt	—
`angle`	angle	Pattern rotation angle	0deg

Minimal complete example#

1# Minimal complete example: hatch2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(60mm,30mm),fill=hatch(pattern=cross,color="#087f8c",spacing=3mm,line_width=0.5pt)),offset=(10mm,10mm))

# Minimal complete example: hatch
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(60mm,30mm),fill=hatch(pattern=cross,color="#087f8c",spacing=3mm,line_width=0.5pt)),offset=(10mm,10mm))

Concepts and common errors · Composition source

image_fill#

Use a local image as paint inside a shape, with fit controlling adaptation. Unlike image material, paint is confined to the shape outline, including rounded rectangles.

Returns: paint

Required: src.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`src`	string	Local resource path relative to the defining file	—
`fit`	"contain" \| "cover" \| "stretch"	contain preserves the whole image; cover crops; stretch distorts `contain`: Preserve aspect ratio and the complete content; unused space may remain `cover`: Preserve aspect ratio and fill the container; crop overflow `stretch`: Scale width and height independently to fill the target size	contain

Minimal complete example#

1# Minimal complete example: image_fill2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(60mm,35mm),fill=image_fill(src="../assets/photo.png",fit=cover),border_radius=8mm),offset=(10mm,10mm))

# Minimal complete example: image_fill
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(60mm,35mm),fill=image_fill(src="../assets/photo.png",fit=cover),border_radius=8mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

table#

Read CSV or column-oriented JSON with unique nonempty headers and equal column lengths. d["column"] selects a column; null and empty CSV cells retain missing values.

Returns: table

Positional parameters: src.

Required: src.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`src`	string	Local resource path relative to the defining file	—

Minimal complete example#

1# Minimal complete example: table2page=canvas(size=(100mm,75mm),background="#ffffff")3d=table(src="../plot/first-plot.csv")4p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))5p.line(x=d["time"],y=d["signal"])6page.add(p,offset=(7mm,6mm))

# Minimal complete example: table
page=canvas(size=(100mm,75mm),background="#ffffff")
d=table(src="../plot/first-plot.csv")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.line(x=d["time"],y=d["signal"])
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

array#

Read a nonempty numeric vector/matrix from JSON. Matrices must be rectangular; null is missing. Inline data uses lists rather than array(values=...).

Returns: number[] | number[][]

Positional parameters: src.

Required: src.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`src`	string	Local resource path relative to the defining file	—

Minimal complete example#

1# Minimal complete example: array2page=canvas(size=(100mm,75mm),background="#ffffff")3x=array(src="observations.json")4p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))5p.scatter(x=x,y=[1,2,4,3],marker=circle)6page.add(p,offset=(7mm,6mm))

# Minimal complete example: array
page=canvas(size=(100mm,75mm),background="#ffffff")
x=array(src="observations.json")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.scatter(x=x,y=[1,2,4,3],marker=circle)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot#

Create a native plot with physical dimensions and add data through layer methods. Configure axes with x and y, or fix the drawing area with plot_area. Place the plot on the page with add.

Returns: A plot accepting data layers and page placement.

Required: size.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`size`	(length \| auto, length \| auto) / canvas unit	Physical (width,height); auto preserves aspect or natural layout	—
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`style`	plot_style	plot_style(...) configuration; supplies defaults not overridden by explicit parameters	—
`margins`	(length, length, length, length) / canvas unit	Plot margins (left,top,right,bottom); exclusive with plot_area	—
`plot_area`	box / canvas unit	Fixed physical plot area: box(offset=(left,top), size=(width,height))	—
`frame`	"axes" \| "box" \| "none" \| boolean	axes/box/none for plot frames; boolean for legend frames `axes`: Draw enabled axis spines only `box`: Draw the complete rectangular plot frame `none`: Do not draw this item	axes
`projection`	"cartesian" \| "polar" \| "radar"	Cartesian, polar, or radar projection `cartesian`: Cartesian horizontal and vertical coordinates `polar`: Angular and radial coordinates `radar`: Radar coordinates arranged by category	cartesian
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`angle_unit`	"deg" \| "rad"	Unit of polar angular data `deg`: Angles are expressed in degrees `rad`: Angles are expressed in radians	deg
`theta_zero`	value	Zero-angle direction: east/north/west/south	east
`theta_direction`	value	Increasing-angle direction: ccw/cw	ccw
`r_label_angle`	value	Angle for radial tick labels	—
`inner_radius`	length / canvas unit	Inner geometric radius; physical hole radius for polar plots	0
`categories`	string[]	Ordered radar category names	—
`category_labels`	(string \| text \| formula)[]	Displayed radar category labels, including math	—
`ranges`	(number, number)[]	Independent data domain of each radar category	—
`radar_frame`	value	Radar frame shape: polygon/circle	polygon
`class`	string	Space-separated LCSS class names	""
`font_family`	string \| string[]	System family, font file path or ordered list. No body fonts are bundled; missing glyphs warn and render as boxes.	system sans-serif
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	继承 / inherit
`font_weight`	integer	Font weight, 100–900	400
`font_style`	"normal" \| "italic"	Normal or italic `normal`: Upright font style `italic`: Italic font style	normal
`color`	color	Text color or base series color	—
`line_height`	length / pt	Text line height; unitless values are pt	1.2 × font_size
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: plot2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.line(x=[0,1,2,3],y=[1,2,4,3],label="Signal")5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.line(x=[0,1,2,3],y=[1,2,4,3],label="Signal")
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

axis#

Configure data domain, linear/log/symlog mapping, ticks, labels and breaks. Domains use original values; text/stroke dimensions are physical.

Returns: axis

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`font_family`	string \| string[]	System family, font file path or ordered list. No body fonts are bundled; missing glyphs warn and render as boxes.	system sans-serif
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	继承 / inherit
`font_weight`	integer	Font weight, 100–900	400
`font_style`	"normal" \| "italic"	Normal or italic `normal`: Upright font style `italic`: Italic font style	normal
`color`	color	Text color or base series color	—
`line_height`	length / pt	Text line height; unitless values are pt	1.2 × font_size
`notation`	"plain" \| "scientific" \| "offset"	plain/scientific/offset number display without changing data `plain`: Show tick numbers directly `scientific`: Use scientific notation for ticks `offset`: Show ticks with a shared offset	plain
`format`	value	D3 numeric format, such as .2f or .2e	—
`exponent`	value	Integer decimal exponent for offset notation	—
`exponent_offset`	length / canvas unit	Physical offset of the multiplier from its default position	(0,0)
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`label_offset`	length / canvas unit	Physical offset of an axis or colorbar title	(0,0)
`scale`	"linear" \| "log" \| "symlog"	linear/log/symlog axis transform, or shared color-scale object `linear`: Linear mapping `log`: Logarithmic mapping; values must be positive `symlog`: Linear near zero and logarithmic farther away	linear
`range`	(number, number)	Explicit axis data domain (minimum, maximum)	—
`ticks`	number[]	Increasing, unique major tick data values	—
`minor_ticks`	number[] \| auto	Minor tick values, or auto	—
`tick_direction`	"in" \| "out" \| "inout"	Tick direction: in, out, or both `in`: Ticks point into the plot area `out`: Ticks point out of the plot area `inout`: Ticks extend in both directions	out
`tick_length`	length / canvas unit	Physical major tick length	1.2mm
`minor_tick_length`	length / canvas unit	Physical minor tick length	0.6mm
`tick_labels`	boolean	Whether tick labels are shown	true
`tick_rotation`	value	Tick-label rotation angle	0deg
`tick_offset`	length / canvas unit	Physical tick-label displacement	(0,0)
`tick_font_size`	length / pt	Tick-label font size; unitless values are pt	继承字号 / inherit font_size
`tick_color`	color	Tick and tick-label color	—
`grid`	"none" \| "major" \| "both"	Major grid, all grid lines, or none `none`: No grid `major`: Major tick grid only `both`: Major and minor tick grids	none
`reverse`	boolean	Reverse the axis mapping	false
`constant`	value	Positive threshold for the linear region of symlog	1
`breaks`	value	Ordered intervals excluded from the axis domain	—
`break_gap`	length / canvas unit	Physical gap size; one value or one per gap	2mm
`segment_lengths`	value	Fixed physical length of each visible axis segment	—
`spine`	boolean	Whether to draw the axis spine	true
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`tick_text`	(string \| text \| formula)[]	Text or math labels, one per explicit tick	—
`break_mark_size`	value	Physical size of diagonal break marks	—

Minimal complete example#

1# Minimal complete example: axis2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4),ticks=[0,2,4],label="Time"),y=axis(range=(0,5),grid=major))4p.line(x=[0,1,2,3],y=[1,2,4,3])5page.add(p,offset=(7mm,6mm))

# Minimal complete example: axis
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4),ticks=[0,2,4],label="Time"),y=axis(range=(0,5),grid=major))
p.line(x=[0,1,2,3],y=[1,2,4,3])
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot_style#

Define shared chart/layer/decoration style defaults. Explicit call parameters win; this is not an inline/display string option.

Returns: plot_style

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`font_family`	string \| string[]	System family, font file path or ordered list. No body fonts are bundled; missing glyphs warn and render as boxes.	system sans-serif
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	8pt
`font_weight`	integer	Font weight, 100–900	400
`font_style`	"normal" \| "italic"	Normal or italic `normal`: Upright font style `italic`: Italic font style	normal
`color`	color	Text color or base series color	#222222
`line_height`	length / pt	Text line height; unitless values are pt	1.2 × font_size
`tick_font_size`	length / pt	Tick-label font size; unitless values are pt	继承字号 / inherit font_size
`label_font_size`	length / pt	Axis-label font size; unitless values are pt	继承字号 / inherit font_size
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	0.6pt
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`colors`	color[]	Nonempty color cycle, conveniently generated with palette(...)	—
`grid_color`	color	Grid-line color	#dddddd
`grid_line_width`	length / pt	Grid-line width; unitless values are pt	0.3pt
`grid_line_dash`	value	Grid dash pattern; unitless values are pt	[]

Minimal complete example#

1# Minimal complete example: plot_style2page=canvas(size=(100mm,75mm),background="#ffffff")3s=plot_style(font_size=9pt,line_width=1pt)4p=plot(size=(86mm,62mm),style=s)5p.line(x=[0,1,2,3],y=[1,2,4,3])6page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot_style
page=canvas(size=(100mm,75mm),background="#ffffff")
s=plot_style(font_size=9pt,line_width=1pt)
p=plot(size=(86mm,62mm),style=s)
p.line(x=[0,1,2,3],y=[1,2,4,3])
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

color_scale#

Define a shared numeric color mapping. Continuous norms use explicit bounds; boundary uses interval edges. Layers and standalone colorbars reference the same configuration.

Returns: color_scale

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`norm`	"linear" \| "log" \| "symlog" \| "centered" \| "boundary"	Color normalization: linear/log/symlog/centered/boundary `linear`: Linear mapping `log`: Logarithmic mapping; values must be positive `symlog`: Linear near zero and logarithmic farther away `centered`: Continuous color normalization split at center `boundary`: Discrete color normalization by boundaries	linear
`vmin`	value	Minimum data value of the color mapping	—
`vmax`	value	Maximum data value of the color mapping	—
`center`	value	Gradient center coordinates or data center of color normalization	—
`cmap`	string \| color[] \| cmap	Preset name, custom color list or cmap(...) handle	viridis
`constant`	value	Positive threshold for the linear region of symlog	1
`boundaries`	value	Ordered boundaries for discrete color normalization	—
`under`	value	Color below the scale minimum	—
`over`	value	Color above the scale maximum	—

Minimal complete example#

1# Minimal complete example: color_scale2page=canvas(size=(100mm,75mm),background="#ffffff")3s=color_scale(norm=linear,vmin=0,vmax=5,cmap=["#ffffff90","#087f8c"])4p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))5p.scatter(x=[0,1,2,3],y=[1,2,4,3],c=[0,2,4,5],color_scale=s)6page.add(p,offset=(7mm,6mm))

# Minimal complete example: color_scale
page=canvas(size=(100mm,75mm),background="#ffffff")
s=color_scale(norm=linear,vmin=0,vmax=5,cmap=["#ffffff90","#087f8c"])
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.scatter(x=[0,1,2,3],y=[1,2,4,3],c=[0,2,4,5],color_scale=s)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

legend#

Create independently placed legend material from existing layers. label supplies text and layer style supplies samples; add positions it on a page or group.

Returns: material

Required: layers.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`layers`	plot-layer[]	Existing layers represented by a shared legend	—
`style`	plot_style	plot_style(...) defaults; explicit parameters win	—
`position`	"top_left" \| "top_center" \| "top_right" \| "middle_left" \| "center" \| "middle_right" \| "bottom_left" \| "bottom_center" \| "bottom_right" \| (length,length)	Legend placement, statistical group position, or colorbar placement, depending on the owner `top_left`: Top-left corner of the layout box `top_center`: Top-edge midpoint of the layout box `top_right`: Top-right corner of the layout box `middle_left`: Left-edge midpoint of the layout box `center`: Center alignment `middle_right`: Right-edge midpoint of the layout box `bottom_left`: Bottom-left corner of the layout box `bottom_center`: Bottom-edge midpoint of the layout box `bottom_right`: Bottom-right corner of the layout box	top_right
`columns`	integer	Positive integer column count; row-major order	1
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	继承 / inherit
`background`	paint	Background paint for the object region, separate from text or lines	#ffffff
`frame`	enum \| boolean	axes/box/none for plot frames; boolean for legend frames	false
`title`	string \| text \| formula	Legend title with text or mathematics	—
`sample_width`	length / canvas unit	Physical legend-sample width	6mm
`gap`	length / canvas unit	Physical legend-item or colorbar-to-plot gap	—
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	1.2mm
`sample_gap`	length / canvas unit	Physical gap between a legend sample and its label	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: legend2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4layer=p.line(x=[0,1,2,3],y=[1,2,4,3],label="Signal")5page.add(p,offset=(7mm,6mm))6page.add(legend(layers=[layer]),offset=(10mm,5mm))

# Minimal complete example: legend
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
layer=p.line(x=[0,1,2,3],y=[1,2,4,3],label="Signal")
page.add(p,offset=(7mm,6mm))
page.add(legend(layers=[layer]),offset=(10mm,5mm))

Concepts and common errors · Composition source

colorbar#

Create standalone colorbar material from color_scale. length/thickness are physical and ticks share the numeric mapping; use add for placement.

Returns: material

Required: scale.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`scale`	"linear" \| "log" \| "symlog"	linear/log/symlog axis transform, or shared color-scale object `linear`: Linear mapping `log`: Logarithmic mapping; values must be positive `symlog`: Linear near zero and logarithmic farther away	—
`style`	plot_style	plot_style(...) defaults; explicit parameters win	—
`notation`	"plain" \| "scientific" \| "offset"	plain/scientific/offset number display without changing data `plain`: Show tick numbers directly `scientific`: Use scientific notation for ticks `offset`: Show ticks with a shared offset	plain
`format`	value	D3 numeric format, such as .2f or .2e	—
`exponent`	value	Integer decimal exponent for offset notation	—
`exponent_offset`	length / canvas unit	Physical offset of the multiplier from its default position	(0,0)
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`label_offset`	length / canvas unit	Physical offset of an axis or colorbar title	(0,0)
`position`	"left" \| "right" \| "top" \| "bottom" \| (length,length)	Legend placement, statistical group position, or colorbar placement, depending on the owner `left`: Left side or left alignment, according to the parameter `right`: Right side or right alignment, according to the parameter `top`: Top side `bottom`: Bottom side	—
`orientation`	"vertical" \| "horizontal"	vertical/horizontal orientation `vertical`: Vertical orientation `horizontal`: Horizontal orientation	vertical
`length`	length / canvas unit	Physical colorbar length	—
`thickness`	length / canvas unit	Physical colorbar thickness	3mm
`gap`	length / canvas unit	Physical legend-item or colorbar-to-plot gap	—
`ticks`	number[]	Increasing, unique major tick data values	—
`class`	string	Space-separated LCSS class names	""
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: colorbar2page=canvas(size=(100mm,75mm),background="#ffffff")3s=color_scale(vmin=0,vmax=5,cmap="viridis")4page.add(colorbar(scale=s,length=45mm,label="Value"),offset=(20mm,12mm))

# Minimal complete example: colorbar
page=canvas(size=(100mm,75mm),background="#ffffff")
s=color_scale(vmin=0,vmax=5,cmap="viridis")
page.add(colorbar(scale=s,length=45mm,label="Value"),offset=(20mm,12mm))

Concepts and common errors · Composition source

plot.add_axis#

Add a uniquely named axis to an unplaced chart. side chooses direction/location, layers select it with x_axis/y_axis, and same-side spacing needs explicit offset.

Returns: axis

Required: name, side, axis.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`name`	string	Canvas title or unique named-axis identifier	—
`side`	"left" \| "right" \| "top" \| "bottom"	Named-axis side: left/right/top/bottom `left`: Left side or left alignment, according to the parameter `right`: Right side or right alignment, according to the parameter `top`: Top side `bottom`: Bottom side	—
`offset`	(length, length) / canvas unit	Horizontal and vertical offset from the target	(0, 0)
`axis`	value	axis(...) configuration	—

Minimal complete example#

1# Minimal complete example: plot.add_axis2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.add_axis(name="right_y",side=right,axis=axis(range=(0,10),label="Second scale"))5p.line(x=[0,1,2,3],y=[1,2,4,3],y_axis="right_y")6page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.add_axis
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.add_axis(name="right_y",side=right,axis=axis(range=(0,10),label="Second scale"))
p.line(x=[0,1,2,3],y=[1,2,4,3],y_axis="right_y")
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.line#

Add a line layer connecting data points in order, optionally with markers. Choose named axes with x_axis and y_axis; polar plots use theta and r, and radar plots use values.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`marker`	"none" \| "circle" \| "square" \| "triangle" \| "triangle_down" \| "diamond"	Scatter or line marker shape `none`: No marker `circle`: Circular marker `square`: Square marker `triangle`: Upward triangle marker `triangle_down`: Downward triangle marker `diamond`: Diamond marker	circle
`marker_size`	length / canvas unit	Physical marker size, including its border	—
`marker_fill`	value	Marker interior color, or none	—
`marker_border_color`	color	Marker border color, or none	none
`marker_border_width`	length / pt	Marker border width; unitless values are pt	—
`fill`	paint	Interior color, gradient, pattern or image paint	none
`closed`	boolean	Connect the first and last points	false
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`zero_baseline`	value	Baseline at the visible edge of a logarithmic axis	—
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—

Minimal complete example#

1# Minimal complete example: plot.line2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.line(x=[0,1,2,3],y=[1,2,4,3],marker=circle)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.line
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.line(x=[0,1,2,3],y=[1,2,4,3],marker=circle)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.scatter#

Add a scatter layer. Set marker shape, physical size and border, or map numeric c values to colors through color_scale.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`marker`	"none" \| "circle" \| "square" \| "triangle" \| "triangle_down" \| "diamond"	Scatter or line marker shape `none`: No marker `circle`: Circular marker `square`: Square marker `triangle`: Upward triangle marker `triangle_down`: Downward triangle marker `diamond`: Diamond marker	circle
`marker_size`	length / canvas unit	Physical marker size, including its border	—
`marker_fill`	value	Marker interior color, or none	—
`marker_border_color`	color	Marker border color, or none	none
`marker_border_width`	length / pt	Marker border width; unitless values are pt	—
`c`	value	Numeric scatter color data	—
`color_scale`	color	Shared color_scale(...) object	—
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.scatter2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.scatter(x=[0,1,2,3],y=[1,2,4,3],marker=diamond)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.scatter
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.scatter(x=[0,1,2,3],y=[1,2,4,3],marker=diamond)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.errorbar#

Add error bars. xerr and yerr accept symmetric errors or separate lower and upper errors; cap_size sets the physical cap length.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`marker`	"none" \| "circle" \| "square" \| "triangle" \| "triangle_down" \| "diamond"	Scatter or line marker shape `none`: No marker `circle`: Circular marker `square`: Square marker `triangle`: Upward triangle marker `triangle_down`: Downward triangle marker `diamond`: Diamond marker	circle
`marker_size`	length / canvas unit	Physical marker size, including its border	—
`marker_fill`	value	Marker interior color, or none	—
`marker_border_color`	color	Marker border color, or none	none
`marker_border_width`	length / pt	Marker border width; unitless values are pt	—
`yerr`	number \| number[] \| (number[], number[])	Vertical errors: scalar, symmetric array, or lower/upper arrays	—
`xerr`	number \| number[] \| (number[], number[])	Horizontal errors: scalar, symmetric array, or lower/upper arrays	—
`cap_size`	length / canvas unit	Physical error-bar cap size	—
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.errorbar2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.errorbar(x=[1,2,3],y=[1,3,2],yerr=[0.2,0.4,0.3])5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.errorbar
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.errorbar(x=[1,2,3],y=[1,3,2],yerr=[0.2,0.4,0.3])
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.band#

Filled band layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`lower`	value	Lower data boundary of a band	—
`upper`	value	Upper data boundary of a band	—
`fill`	paint	Interior color, gradient, pattern or image paint	none
`hatch`	value	Layer hatch selector slash/cross; fill=hatch(...) also supports dots	—
`hatch_spacing`	value	Physical layer-hatch spacing	1.5mm
`hatch_width`	length / pt	Layer-hatch width; unitless values are pt	—
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.band2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.band(x=[0,1,2,3],lower=[0.5,1,2,1],upper=[1.5,3,4,3])5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.band
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.band(x=[0,1,2,3],lower=[0.5,1,2,1],upper=[1.5,3,4,3])
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.hline#

Horizontal reference line layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.hline2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.hline(y=2)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.hline
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.hline(y=2)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.vline#

Vertical reference line layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.vline2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.vline(x=2)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.vline
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.vline(x=2)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.bar#

Bar plot layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`data_width`	number / data	Width in data coordinates, independent of physical units	—
`angle_width`	number / angle	Polar bar angular width, using angle_unit	—
`fill`	paint	Interior color, gradient, pattern or image paint	none
`hatch`	value	Layer hatch selector slash/cross; fill=hatch(...) also supports dots	—
`hatch_spacing`	value	Physical layer-hatch spacing	1.5mm
`hatch_width`	length / pt	Layer-hatch width; unitless values are pt	—
`positions`	number[]	Bar centers in data coordinates	—
`values`	number[]	Observed samples for statistics, or bar values	—
`orientation`	"vertical" \| "horizontal"	vertical/horizontal orientation `vertical`: Vertical orientation `horizontal`: Horizontal orientation	vertical
`baseline`	value	Area or bar baseline in data coordinates	0
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`width_unit`	value	Angular unit of a polar bar width	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.bar2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.bar(positions=[1,2,3],values=[1,4,2],data_width=0.6)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.bar
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.bar(positions=[1,2,3],values=[1,4,2],data_width=0.6)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.step#

Step plot layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`where`	"pre" \| "mid" \| "post"	Step-change position: pre/mid/post `pre`: Extend steps on the left `mid`: Change value at interval midpoints `post`: Extend steps on the right	post
`fill`	paint	Interior color, gradient, pattern or image paint	none
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.step2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.step(x=[0,1,2,3],y=[1,2,4,3],where=post)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.step
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.step(x=[0,1,2,3],y=[1,2,4,3],where=post)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.area#

Area plot layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`baseline`	value	Area or bar baseline in data coordinates	0
`fill`	paint	Interior color, gradient, pattern or image paint	none
`hatch`	value	Layer hatch selector slash/cross; fill=hatch(...) also supports dots	—
`hatch_spacing`	value	Physical layer-hatch spacing	1.5mm
`hatch_width`	length / pt	Layer-hatch width; unitless values are pt	—
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.area2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.area(x=[0,1,2,3],y=[1,2,4,3])5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.area
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.area(x=[0,1,2,3],y=[1,2,4,3])
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.hist#

Histogram layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`values`	number[]	Observed samples for statistics, or bar values	—
`bins`	integer \| number[]	Positive histogram bin count or increasing edges	—
`weights`	value	Nonnegative weight of each observation	—
`orientation`	"vertical" \| "horizontal"	vertical/horizontal orientation `vertical`: Vertical orientation `horizontal`: Horizontal orientation	vertical
`fill`	paint	Interior color, gradient, pattern or image paint	none
`hatch`	value	Layer hatch selector slash/cross; fill=hatch(...) also supports dots	—
`hatch_spacing`	value	Physical layer-hatch spacing	1.5mm
`hatch_width`	length / pt	Layer-hatch width; unitless values are pt	—
`stat`	"count" \| "probability" \| "density"	Histogram statistic: count/probability/density `count`: Sample count in each bin `probability`: Probability per bin; all bins sum to one `density`: Probability density normalized by bin width	count
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.hist2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.hist(values=[0.2,0.8,1.1,1.2,2.4,3.1],bins=[0,1,2,3,4])5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.hist
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.hist(values=[0.2,0.8,1.1,1.2,2.4,3.1],bins=[0,1,2,3,4])
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.boxplot#

Box plot layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`values`	number[]	Observed samples for statistics, or bar values	—
`position`	value	Legend placement, statistical group position, or colorbar placement, depending on the owner	—
`data_width`	number / data	Width in data coordinates, independent of physical units	—
`outlier_size`	length / canvas unit	Physical outlier size	—
`fill`	paint	Interior color, gradient, pattern or image paint	none
`orientation`	"vertical" \| "horizontal"	vertical/horizontal orientation `vertical`: Vertical orientation `horizontal`: Horizontal orientation	vertical
`whisker`	value	Boxplot whisker length in interquartile ranges	1.5
`outliers`	boolean	Whether to show boxplot outliers	true
`median_color`	color	Median-line color	—
`median_line_width`	length / pt	Median-line width; unitless values are pt	—
`whisker_color`	color	Whisker color	—
`whisker_line_width`	length / pt	Whisker width; unitless values are pt	—
`outlier_marker`	"none" \| "circle" \| "square" \| "triangle" \| "triangle_down" \| "diamond"	Outlier marker shape `none`: No marker `circle`: Circular marker `square`: Square marker `triangle`: Upward triangle marker `triangle_down`: Downward triangle marker `diamond`: Diamond marker	—
`outlier_fill`	value	Outlier interior color	—
`outlier_border_color`	color	Outlier border color	—
`outlier_border_width`	length / pt	Outlier border width; unitless values are pt	—
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.boxplot2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.boxplot(values=[1,2,2,3,4,4],position=2)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.boxplot
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.boxplot(values=[1,2,2,3,4,4],position=2)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.violin#

Violin plot layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`values`	number[]	Observed samples for statistics, or bar values	—
`position`	value	Legend placement, statistical group position, or colorbar placement, depending on the owner	—
`data_width`	number / data	Width in data coordinates, independent of physical units	—
`bandwidth`	value	Positive kernel-density bandwidth	—
`points`	value	Point list; star uses an integer corner count, violin uses a KDE sample count	—
`fill`	paint	Interior color, gradient, pattern or image paint	none
`orientation`	"vertical" \| "horizontal"	vertical/horizontal orientation `vertical`: Vertical orientation `horizontal`: Horizontal orientation	vertical
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.violin2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.violin(values=[1,1.5,2,2.2,3,4],position=2)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.violin
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.violin(values=[1,1.5,2,2.2,3,4],position=2)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.ecdf#

Empirical cumulative distribution layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`values`	number[]	Observed samples for statistics, or bar values	—
`complementary`	value	Plot 1 minus the empirical CDF	false
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.ecdf2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.ecdf(values=[0.2,0.8,1.1,1.2,2.4,3.1])5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.ecdf
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.ecdf(values=[0.2,0.8,1.1,1.2,2.4,3.1])
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.heatmap#

Heatmap layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`z`	number[][]	Rectangular grid: rows are y and columns are x	—
`x_edges`	value	Increasing column edges, one more than the column count	—
`y_edges`	value	Increasing row edges, one more than the row count	—
`cmap`	string \| color[] \| cmap	Preset name, custom color list or cmap(...) handle	viridis
`vmin`	value	Minimum data value of the color mapping	—
`vmax`	value	Maximum data value of the color mapping	—
`color_scale`	color	Shared color_scale(...) object	—
`extent`	value	Data-grid bounds (xmin,xmax,ymin,ymax)	—
`origin`	"lower" \| "upper"	Whether the first heatmap row is at the bottom or top `lower`: First row at the bottom `upper`: First row at the top	lower
`mode`	"raster" \| "vector"	Raster or vector heatmap cells `raster`: Render heatmap cells as a raster `vector`: Render heatmap cells as vectors	raster
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.heatmap2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.heatmap(z=[[1,2,3],[2,4,2],[1,3,1]],extent=(0,4,0,5),origin=lower)5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.heatmap
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.heatmap(z=[[1,2,3],[2,4,2],[1,3,1]],extent=(0,4,0,5),origin=lower)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.contour#

Contours layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`line_color`	color	Open-line color; defaults to series or theme color	—
`line_width`	length / pt	Open-line width; unitless values are pt	—
`line_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Line pattern; double/triple retain transparent gaps `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`line_dash`	length[] / pt	Alternating painted and blank lengths; unitless values are pt	—
`line_dash_offset`	length / pt	Line dash phase; unitless values are pt	0
`line_cap`	"butt" \| "round" \| "square"	Open endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`line_join`	"miter" \| "round" \| "bevel"	Line segment join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`line_miter_limit`	value	Maximum miter extension relative to line width	4
`line_opacity`	value	Independent line opacity, 0–1	1
`z`	number[][]	Rectangular grid: rows are y and columns are x	—
`levels`	value	Increasing contour levels	—
`color_scale`	color	Shared color_scale(...) object	—
`cmap`	string \| color[] \| cmap	Preset name, custom color list or cmap(...) handle	viridis
`vmin`	value	Minimum data value of the color mapping	—
`vmax`	value	Maximum data value of the color mapping	—
`extent`	value	Data-grid bounds (xmin,xmax,ymin,ymax)	—
`periodic`	value	Close a regular polar field periodically	false
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.contour2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.contour(z=[[1,2,3],[2,4,2],[1,3,1]],levels=[1.5,2.5,3.5],extent=(0,4,0,5))5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.contour
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.contour(z=[[1,2,3],[2,4,2],[1,3,1]],levels=[1.5,2.5,3.5],extent=(0,4,0,5))
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.contourf#

Filled contours layer: add data to this plot, control its appearance with physical style parameters, and select data mappings with named-axis parameters.

Returns: A layer handle that can be included in a shared legend.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	axis \| number[]	Cartesian horizontal axis configuration or layer x data	—
`y`	axis \| number[]	Cartesian vertical axis configuration or layer y data	—
`x_axis`	value	Name of the horizontal axis bound to this layer	x
`y_axis`	value	Name of the vertical axis bound to this layer	y
`color`	color	Text color or base series color	—
`opacity`	number \| number[]	Opacity from 0 to 1, multiplied by parent opacity	1
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1
`z`	number[][]	Rectangular grid: rows are y and columns are x	—
`levels`	value	Increasing contour levels	—
`color_scale`	color	Shared color_scale(...) object	—
`cmap`	string \| color[] \| cmap	Preset name, custom color list or cmap(...) handle	viridis
`vmin`	value	Minimum data value of the color mapping	—
`vmax`	value	Maximum data value of the color mapping	—
`fill`	paint	Interior color, gradient, pattern or image paint	none
`extent`	value	Data-grid bounds (xmin,xmax,ymin,ymax)	—
`periodic`	value	Close a regular polar field periodically	false
`theta`	axis \| number[]	Polar angular axis configuration or angle data	—
`r`	axis \| number[]	Polar radial axis configuration or radial data	—
`values`	number[]	Observed samples for statistics, or bar values	—
`theta_edges`	value	Polar-cell angular edges	—
`r_edges`	value	Polar-cell radial edges	—
`thetaerr`	value	Angular error values	—
`rerr`	value	Radial error values	—
`wrap`	"shortest" \| "raw"	Connect across angular boundaries using shortest or raw `shortest`: Follow the shortest angular route across a period `raw`: Keep original angular differences, including multiple turns	shortest
`interpolation`	"polar" \| "chord"	Polar interpolation or straight chord segments `polar`: Interpolate in polar data coordinates before projection `chord`: Connect projected points with straight page chords	polar
`closed`	boolean	Connect the first and last points	false

Minimal complete example#

1# Minimal complete example: plot.contourf2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.contourf(z=[[1,2,3],[2,4,2],[1,3,1]],levels=[1.5,2.5,3.5],extent=(0,4,0,5))5page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.contourf
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.contourf(z=[[1,2,3],[2,4,2],[1,3,1]],levels=[1.5,2.5,3.5],extent=(0,4,0,5))
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

range#

Return a finite integer list excluding stop: one argument is stop, two are start/stop and three add step. step must be nonzero; at most 10,000 items.

Returns: integer[]

Positional parameters: start, stop, step.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`start`	integer	Start; a one-argument call means stop with start 0	—
`stop`	integer	Exclusive stop	—
`step`	integer	Nonzero increment; default 1	1

Minimal complete example#

1# Minimal complete example: range2page=canvas(size=(100mm,75mm),background="#ffffff")3for i in range(4) { page.add(rect(size=(10mm,10mm),fill="#087f8c"),offset=(10mm+i*16mm,20mm)) }

# Minimal complete example: range
page=canvas(size=(100mm,75mm),background="#ffffff")
for i in range(4) { page.add(rect(size=(10mm,10mm),fill="#087f8c"),offset=(10mm+i*16mm,20mm)) }

Concepts and common errors · Composition source

len#

Return list, dictionary or geometry collection size, or string length.

Returns: integer

Positional parameters: value.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`value`	value	Input scalar, string or list element	—

Minimal complete example#

1# Minimal complete example: len2page=canvas(size=(100mm,75mm),background="#ffffff")3values=[1,2,3]4page.add(text("Count: "+str(len(values))),offset=(10mm,10mm))

# Minimal complete example: len
page=canvas(size=(100mm,75mm),background="#ffffff")
values=[1,2,3]
page.add(text("Count: "+str(len(values))),offset=(10mm,10mm))

Concepts and common errors · Composition source

append#

Return a copy of a list with one item appended, without mutating the input. Reassign the result when accumulating values.

Returns: list

Positional parameters: list, value.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`list`	value	Input list	—
`value`	value	Input scalar, string or list element	—

Minimal complete example#

1# Minimal complete example: append2page=canvas(size=(100mm,75mm),background="#ffffff")3values=append([1,2],3)4page.add(text("New count: "+str(len(values))),offset=(10mm,10mm))

# Minimal complete example: append
page=canvas(size=(100mm,75mm),background="#ffffff")
values=append([1,2],3)
page.add(text("New count: "+str(len(values))),offset=(10mm,10mm))

Concepts and common errors · Composition source

str#

Convert supported numeric/boolean/string values to text, retaining length units. Use it in labels without evaluating arbitrary formatting expressions.

Returns: string

Positional parameters: value.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`value`	value	Input scalar, string or list element	—

Minimal complete example#

1# Minimal complete example: str2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(text("Measured: "+str(20mm)),offset=(10mm,10mm))

# Minimal complete example: str
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(text("Measured: "+str(20mm)),offset=(10mm,10mm))

Concepts and common errors · Composition source

abs#

Return absolute value while retaining numeric unit type. Accepts scalars or lengths, not material or lists.

Returns: number | length

Positional parameters: value.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`value`	value	Input scalar, string or list element	—

Minimal complete example#

1# Minimal complete example: abs2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(abs(-30mm),20mm),fill="#087f8c"),offset=(10mm,10mm))

# Minimal complete example: abs
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(abs(-30mm),20mm),fill="#087f8c"),offset=(10mm,10mm))

Concepts and common errors · Composition source

min#

Return the minimum of one or more values with compatible units. Input types must be compatible; the result retains units.

Returns: number | length

Positional parameters: values.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`values`	number[]	Observed samples for statistics, or bar values	—

Minimal complete example#

1# Minimal complete example: min2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(min(30mm,45mm),20mm),fill="#087f8c"),offset=(10mm,10mm))

# Minimal complete example: min
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(min(30mm,45mm),20mm),fill="#087f8c"),offset=(10mm,10mm))

Concepts and common errors · Composition source

max#

Return the maximum of one or more values with compatible units. Input types must be compatible; the result retains units.

Returns: number | length

Positional parameters: values.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`values`	number[]	Observed samples for statistics, or bar values	—

Minimal complete example#

1# Minimal complete example: max2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(max(30mm,45mm),20mm),fill="#087f8c"),offset=(10mm,10mm))

# Minimal complete example: max
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(max(30mm,45mm),20mm),fill="#087f8c"),offset=(10mm,10mm))

Concepts and common errors · Composition source

move_to#

Create a command beginning a subpath at x/y without connecting it to the previous one. Use only inside path(commands=...).

Returns: path-command

Positional parameters: x, y.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	length / canvas unit	Endpoint x; current geometry unit	—
`y`	length / canvas unit	Endpoint y; current geometry unit	—

Minimal complete example#

1# Minimal complete example: move_to2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(path(commands=[move_to(0mm,10mm),line_to(30mm,10mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: move_to
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(path(commands=[move_to(0mm,10mm),line_to(30mm,10mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

line_to#

Create a straight segment command from the current node to x/y. A preceding move_to is required; original node/segment identities are retained.

Returns: path-command

Positional parameters: x, y.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`x`	length / canvas unit	Endpoint x; current geometry unit	—
`y`	length / canvas unit	Endpoint y; current geometry unit	—

Minimal complete example#

1# Minimal complete example: line_to2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(path(commands=[move_to(0mm,10mm),line_to(30mm,10mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: line_to
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(path(commands=[move_to(0mm,10mm),line_to(30mm,10mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

quad_to#

Create a quadratic Bezier segment: cx/cy is the control and x/y the endpoint. Controls usually lie off-curve; t differs from arc-length fraction.

Returns: path-command

Positional parameters: cx, cy, x, y.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`cx`	length / canvas unit	Original control cx; current geometry unit	—
`cy`	length / canvas unit	Original control cy; current geometry unit	—
`x`	length / canvas unit	Endpoint x; current geometry unit	—
`y`	length / canvas unit	Endpoint y; current geometry unit	—

Minimal complete example#

1# Minimal complete example: quad_to2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(path(commands=[move_to(0mm,20mm),quad_to(15mm,0mm,30mm,20mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: quad_to
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(path(commands=[move_to(0mm,20mm),quad_to(15mm,0mm,30mm,20mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

cubic_to#

Create a cubic Bezier segment from two controls and an endpoint. controls queries retain originals and indices do not depend on render subdivisions.

Returns: path-command

Positional parameters: c1x, c1y, c2x, c2y, x, y.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`c1x`	length / canvas unit	Original control c1x; current geometry unit	—
`c1y`	length / canvas unit	Original control c1y; current geometry unit	—
`c2x`	length / canvas unit	Original control c2x; current geometry unit	—
`c2y`	length / canvas unit	Original control c2y; current geometry unit	—
`x`	length / canvas unit	Endpoint x; current geometry unit	—
`y`	length / canvas unit	Endpoint y; current geometry unit	—

Minimal complete example#

1# Minimal complete example: cubic_to2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(path(commands=[move_to(0mm,20mm),cubic_to(10mm,0mm,20mm,35mm,40mm,20mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: cubic_to
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(path(commands=[move_to(0mm,20mm),cubic_to(10mm,0mm,20mm,35mm,40mm,20mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

arc_to#

Create an elliptical arc command with radii, rotation, large_arc/sweep flags and endpoint. One command remains one original logical segment.

Returns: path-command

Positional parameters: rx, ry, rotation, large_arc, sweep, x, y.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`rx`	length / canvas unit	Ellipse horizontal radius; current geometry unit	—
`ry`	length / canvas unit	Ellipse vertical radius; current geometry unit	—
`rotation`	angle / deg	Ellipse rotation; deg/rad, unitless degrees	0deg
`large_arc`	boolean	Select the large arc	—
`sweep`	boolean	Traverse in the positive page-angle direction	—
`x`	length / canvas unit	Endpoint x; current geometry unit	—
`y`	length / canvas unit	Endpoint y; current geometry unit	—

Minimal complete example#

1# Minimal complete example: arc_to2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(path(commands=[move_to(0mm,20mm),arc_to(20mm,15mm,0deg,false,true,40mm,20mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: arc_to
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(path(commands=[move_to(0mm,20mm),arc_to(20mm,15mm,0deg,false,true,40mm,20mm)],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

close#

Create a command closing the current subpath to its start while preserving traversal. Closed start/end may coincide; seam-crossing intervals require explicit wrap=true.

Returns: path-command

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance

Minimal complete example#

1# Minimal complete example: close2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(path(commands=[move_to(0mm,0mm),line_to(30mm,0mm),line_to(15mm,20mm),close()],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

# Minimal complete example: close
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(path(commands=[move_to(0mm,0mm),line_to(30mm,0mm),line_to(15mm,20mm),close()],border_color="#087f8c",border_width=1mm),offset=(10mm,10mm))

Concepts and common errors · Composition source

plot.legend#

Add legend decoration to an unplaced chart, using labeled layers by default. position uses chart-local coordinates; legend(layers=...) creates standalone material.

Returns: decoration

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`layers`	plot-layer[]	Existing layers represented by a shared legend	—
`style`	plot_style	plot_style(...) configuration; supplies defaults not overridden by explicit parameters	—
`position`	"top_left" \| "top_center" \| "top_right" \| "middle_left" \| "center" \| "middle_right" \| "bottom_left" \| "bottom_center" \| "bottom_right" \| (length,length)	Legend placement, statistical group position, or colorbar placement, depending on the owner `top_left`: Top-left corner of the layout box `top_center`: Top-edge midpoint of the layout box `top_right`: Top-right corner of the layout box `middle_left`: Left-edge midpoint of the layout box `center`: Center alignment `middle_right`: Right-edge midpoint of the layout box `bottom_left`: Bottom-left corner of the layout box `bottom_center`: Bottom-edge midpoint of the layout box `bottom_right`: Bottom-right corner of the layout box	top_right
`columns`	integer	Positive integer column count; row-major order	1
`font_size`	length / pt	Font size in pt when unitless; inherits when omitted	继承 / inherit
`background`	paint	Background paint for the object region, separate from text or lines	#ffffff
`frame`	enum \| boolean	axes/box/none for plot frames; boolean for legend frames	false
`title`	string \| text \| formula	Legend title with text or mathematics	—
`sample_width`	length / canvas unit	Physical legend-sample width	6mm
`gap`	length / canvas unit	Physical legend-item or colorbar-to-plot gap	—
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	1.2mm
`sample_gap`	length / canvas unit	Physical gap between a legend sample and its label	—
`class`	string	Space-separated LCSS class names	""
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: plot.legend2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4p.line(x=[0,1,2,3],y=[1,2,4,3],label="Signal")5p.legend(position=top_left)6page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.legend
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
p.line(x=[0,1,2,3],y=[1,2,4,3],label="Signal")
p.legend(position=top_left)
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

plot.colorbar#

Add an internal colorbar for a chart layer. A layer reference determines mapping; position/length are chart-local. Use colorbar(scale=...) for a shared standalone bar.

Returns: decoration

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`scale`	"linear" \| "log" \| "symlog"	linear/log/symlog axis transform, or shared color-scale object `linear`: Linear mapping `log`: Logarithmic mapping; values must be positive `symlog`: Linear near zero and logarithmic farther away	—
`style`	plot_style	plot_style(...) configuration; supplies defaults not overridden by explicit parameters	—
`notation`	"plain" \| "scientific" \| "offset"	plain/scientific/offset number display without changing data `plain`: Show tick numbers directly `scientific`: Use scientific notation for ticks `offset`: Show ticks with a shared offset	plain
`format`	value	D3 numeric format, such as .2f or .2e	—
`exponent`	value	Integer decimal exponent for offset notation	—
`exponent_offset`	length / canvas unit	Physical offset of the multiplier from its default position	(0,0)
`label`	string \| text \| formula	Label: text, inline math, or a text definition	—
`label_offset`	length / canvas unit	Physical offset of an axis or colorbar title	(0,0)
`position`	"left" \| "right" \| "top" \| "bottom" \| (length,length)	Legend placement, statistical group position, or colorbar placement, depending on the owner `left`: Left side or left alignment, according to the parameter `right`: Right side or right alignment, according to the parameter `top`: Top side `bottom`: Bottom side	—
`orientation`	"vertical" \| "horizontal"	vertical/horizontal orientation `vertical`: Vertical orientation `horizontal`: Horizontal orientation	vertical
`length`	length / canvas unit	Physical colorbar length	—
`thickness`	length / canvas unit	Physical colorbar thickness	3mm
`gap`	length / canvas unit	Physical legend-item or colorbar-to-plot gap	—
`ticks`	number[]	Increasing, unique major tick data values	—
`class`	string	Space-separated LCSS class names	""
`background`	paint	Background paint for the object region, separate from text or lines	none
`padding`	length \| length[] / canvas unit	Inner spacing; one value or top, right, bottom, left	0
`border_radius`	length / canvas unit	Physical corner radius of the box	0
`border_color`	color	Closed-outline color; none disables the border	none
`border_width`	length / pt	Closed-outline width; unitless values are pt	—
`border_style`	"none" \| "solid" \| "dashed" \| "dotted" \| "dash_dot" \| "double" \| "triple"	Border line pattern, independent of fill `none`: Do not draw this item `solid`: Continuous solid stroke `dashed`: Dashed stroke; explicit dash values override the pattern `dotted`: Dotted stroke `dash_dot`: Dash-dot stroke `double`: Double compound stroke `triple`: Triple compound stroke	solid
`border_dash`	length[] / pt	Alternating border segments and gaps, in pairs	—
`border_dash_offset`	length / pt	Border dash phase; unitless values are pt	0
`border_cap`	"butt" \| "round" \| "square"	Outline dash endpoint shape `butt`: Flat cap; does not extend beyond the endpoint `round`: Round cap; extends half the stroke width `square`: Square cap; extends half the stroke width	butt
`border_join`	"miter" \| "round" \| "bevel"	Outline join `miter`: Extend edges to a pointed join, subject to the miter limit `round`: Join adjacent stroke edges with a circular arc `bevel`: Cut off the corner with a straight edge	miter
`border_miter_limit`	value	Maximum miter extension relative to line width	4
`border_opacity`	value	Independent border opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: plot.colorbar2page=canvas(size=(100mm,75mm),background="#ffffff")3p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))4layer=p.heatmap(z=[[1,2],[3,4]],extent=(0,4,0,5))5p.colorbar(layer,label="Value")6page.add(p,offset=(7mm,6mm))

# Minimal complete example: plot.colorbar
page=canvas(size=(100mm,75mm),background="#ffffff")
p=plot(size=(86mm,62mm),x=axis(range=(0,4)),y=axis(range=(0,5)))
layer=p.heatmap(z=[[1,2],[3,4]],extent=(0,4,0,5))
p.colorbar(layer,label="Value")
page.add(p,offset=(7mm,6mm))

Concepts and common errors · Composition source

ray#

Create a query ray with an origin and nonzero direction. The origin shares the path container; direction uses the selected measurement space.

Returns: ray

Required: origin, direction.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`origin`	"lower" \| "upper"	Anchor or coordinates in the container `lower`: First row at the bottom `upper`: First row at the top	—
`direction`	(number, number)	Nonzero direction in the selected measurement space	—

Minimal complete example#

1# Minimal complete example: ray2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6candidates=route.intersections(ray(origin=(0mm,30mm),direction=(1,0)))7for point in candidates { page.add(dot,anchor=center,target=point) }8page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

# Minimal complete example: ray
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
candidates=route.intersections(ray(origin=(0mm,30mm),direction=(1,0)))
for point in candidates { page.add(dot,anchor=center,target=point) }
page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

Concepts and common errors · Composition source

path.at#

Select by arc-length fraction or distance. Original parameter t requires segments[i]. Lengths use placed geometry by default.

Returns: path_anchor

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`fraction`	number	Arc-length fraction, 0–1	—
`distance`	length / canvas unit	Nonnegative arc length from the selected start, no greater than route length; exclusive with fraction/t	—
`t`	number	Original segment parameter, 0–1	—

Minimal complete example#

1# Minimal complete example: path.at2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6point=route.at(fraction=0.5)7page.add(dot,anchor=center,target=point)

# Minimal complete example: path.at
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
point=route.at(fraction=0.5)
page.add(dot,anchor=center,target=point)

Concepts and common errors · Composition source

path.nearest#

Return all globally nearest path positions in source order. Explicit indexing is required; infinitely many nearest points are diagnosed.

Returns: anchor_collection

Required: to.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`to`	anchor \| (length, length)	Reference anchor or coordinates in the same container	—

Minimal complete example#

1# Minimal complete example: path.nearest2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6candidates=route.nearest(to=curve.bounds.top_left)7for point in candidates { page.add(dot,anchor=center,target=point) }8page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

# Minimal complete example: path.nearest
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
candidates=route.nearest(to=curve.bounds.top_left)
for point in candidates { page.add(dot,anchor=center,target=point) }
page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

Concepts and common errors · Composition source

path.extrema#

Return local coordinate extrema in the selected space, excluding ordinary endpoints and constant intervals.

Returns: anchor_collection

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`axis`	"x" \| "y"	Query x or y extrema `x`: Horizontal coordinate in the selected space `y`: Vertical coordinate in the selected space	"y"

Minimal complete example#

1# Minimal complete example: path.extrema2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6candidates=route.extrema(axis=y)7for point in candidates { page.add(dot,anchor=center,target=point) }8page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

# Minimal complete example: path.extrema
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
candidates=route.extrema(axis=y)
for point in candidates { page.add(dot,anchor=center,target=point) }
page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

Concepts and common errors · Composition source

path.inflections#

Return smooth inflections where signed curvature changes sign.

Returns: anchor_collection

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance

Minimal complete example#

1# Minimal complete example: path.inflections2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6candidates=route.inflections()7for point in candidates { page.add(dot,anchor=center,target=point) }8page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

# Minimal complete example: path.inflections
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
candidates=route.inflections()
for point in candidates { page.add(dot,anchor=center,target=point) }
page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

Concepts and common errors · Composition source

path.corners#

Return nonsmooth joining nodes; choose direction explicitly with with_side.

Returns: anchor_collection

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance

Minimal complete example#

1# Minimal complete example: path.corners2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6candidates=route.corners()7for point in candidates { page.add(dot,anchor=center,target=point) }8page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

# Minimal complete example: path.corners
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
candidates=route.corners()
for point in candidates { page.add(dot,anchor=center,target=point) }
page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

Concepts and common errors · Composition source

path.intersections#

Return all path positions intersecting a ray. Preserve distinct self-intersection occurrences and diagnose continuous overlap.

Returns: anchor_collection

Positional parameters: ray.

Required: ray.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`ray`	ray	Ray created with ray(...)	—

Minimal complete example#

1# Minimal complete example: path.intersections2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6candidates=route.intersections(ray(origin=(0mm,30mm),direction=(1,0)))7for point in candidates { page.add(dot,anchor=center,target=point) }8page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

# Minimal complete example: path.intersections
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
candidates=route.intersections(ray(origin=(0mm,30mm),direction=(1,0)))
for point in candidates { page.add(dot,anchor=center,target=point) }
page.add(text("Candidates: "+str(len(candidates))),offset=(8mm,65mm))

Concepts and common errors · Composition source

path.between#

Select a continuous interval in traversal order. Endpoints must belong to the same instance and subpath.

Returns: geometry_path

Positional parameters: start, end.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`start`	path_anchor	Starting path position	—
`end`	path_anchor	Ending path position	—
`wrap`	boolean	Explicitly enable crossing a closed seam	false

Minimal complete example#

1# Minimal complete example: path.between2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6point=route.between(route.nodes[1],route.nodes[3]).at(fraction=0.5)7page.add(dot,anchor=center,target=point)

# Minimal complete example: path.between
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
point=route.between(route.nodes[1],route.nodes[3]).at(fraction=0.5)
page.add(dot,anchor=center,target=point)

Concepts and common errors · Composition source

path.in_space#

Choose the measurement space for lengths, nearest points and features. Resulting anchors remain in the current container.

Returns: geometry_path

Positional parameters: space.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`space`	"local" \| "parent"	local measures original geometry; parent measures in the current container `local`: Measure original local geometry; return container-coordinate anchors `parent`: Measure placed geometry in container coordinates	—

Minimal complete example#

1# Minimal complete example: path.in_space2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6point=route.in_space(local).at(fraction=0.5)7page.add(dot,anchor=center,target=point)

# Minimal complete example: path.in_space
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
point=route.in_space(local).at(fraction=0.5)
page.add(dot,anchor=center,target=point)

Concepts and common errors · Composition source

anchor.with_side#

Choose the incoming or outgoing direction at a corner. The positive normal is the left side along traversal.

Returns: path_anchor

Positional parameters: side.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`side`	"incoming" \| "outgoing"	Select incoming or outgoing direction `incoming`: Use the incoming tangent at the path position `outgoing`: Use the outgoing tangent at the path position	—

Minimal complete example#

1# Minimal complete example: anchor.with_side2page=canvas(size=(100mm,75mm),background="#ffffff")3curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))4route=curve.path.subpaths[0]5dot=ellipse(size=(2mm,2mm),fill="#e36b70")6corner=route.corners()[0].with_side(incoming)7page.add(line(length=8mm,line_color="#e36b70"),anchor=self.path.start,target=corner,rotation=corner.tangent_angle)

# Minimal complete example: anchor.with_side
page=canvas(size=(100mm,75mm),background="#ffffff")
curve=page.add(path(commands=[move_to(0mm,0mm),cubic_to(0mm,0mm,0mm,35mm,50mm,35mm),cubic_to(65mm,35mm,70mm,0mm,75mm,0mm),line_to(82mm,12mm)],border_color="#0072b2",border_width=0.7mm),offset=(8mm,15mm))
route=curve.path.subpaths[0]
dot=ellipse(size=(2mm,2mm),fill="#e36b70")
corner=route.corners()[0].with_side(incoming)
page.add(line(length=8mm,line_color="#e36b70"),anchor=self.path.start,target=corner,rotation=corner.tangent_angle)

Concepts and common errors · Composition source

head#

Reusable endpoint head configuration, not a placeable material. size gives along-direction and transverse physical dimensions.

Returns: head

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`shape`	"triangle" \| "open" \| "stealth" \| "dot" \| "diamond" \| "bar"	Preset head shape `triangle`: Closed triangular head; tip coincides with the logical endpoint `open`: Open V head; the shaft remains inside `stealth`: Closed concave head; tip coincides with the logical endpoint `dot`: Elliptical head centered on the endpoint `diamond`: Diamond head centered on the endpoint `bar`: Rectangular head centered on the endpoint	triangle
`size`	(length,length) / canvas unit	Head size retained on short lines; defaults derive from line width	—
`fill`	color	Fill; closed heads inherit line color, open heads default to none	—
`border_color`	color	Outline color; open heads inherit line color	—
`border_width`	length / pt	Outline width; open heads inherit line width	—
`opacity`	value	Head opacity, 0–1	1

Minimal complete example#

1# Minimal complete example: head2page=canvas(size=(100mm,75mm),background="#ffffff")3h=head(shape=diamond,size=(6mm,5mm),fill="#e36b70")4page.add(line(length=50mm,end_head=h,line_width=1.5mm),offset=(12mm,25mm))

# Minimal complete example: head
page=canvas(size=(100mm,75mm),background="#ffffff")
h=head(shape=diamond,size=(6mm,5mm),fill="#e36b70")
page.add(line(length=50mm,end_head=h,line_width=1.5mm),offset=(12mm,25mm))

Concepts and common errors · Composition source

rgb#

Create a RGB color with alpha=0–1.

Returns: color

Positional parameters: r, g, b.

Required: r, g, b.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`r`	number	sRGB r channel, 0–255; fractions are retained, alpha is separate	—
`g`	number	sRGB g channel, 0–255; fractions are retained, alpha is separate	—
`b`	number	sRGB b channel, 0–255; fractions are retained, alpha is separate	—
`alpha`	number	Color alpha, 0–1	1

Minimal complete example#

1# Minimal complete example: rgb2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(60mm,30mm),fill=rgb(255,80,40,alpha=0.6)),offset=(10mm,10mm))

# Minimal complete example: rgb
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(60mm,30mm),fill=rgb(255,80,40,alpha=0.6)),offset=(10mm,10mm))

Concepts and common errors · Composition source

hsv#

Create a HSV color with alpha=0–1.

Returns: color

Positional parameters: h, s, v.

Required: h, s, v.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`h`	angle / deg	Hue: deg/rad, unitless degrees; normalized modulo 360 degrees	—
`s`	number	Saturation, 0–1; the panel displays a percentage	—
`v`	number	Value, 0–1; the panel displays a percentage	—
`alpha`	number	Color alpha, 0–1	1

Minimal complete example#

1# Minimal complete example: hsv2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(60mm,30mm),fill=hsv(200deg,0.7,0.8,alpha=0.6)),offset=(10mm,10mm))

# Minimal complete example: hsv
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(60mm,30mm),fill=hsv(200deg,0.7,0.8,alpha=0.6)),offset=(10mm,10mm))

Concepts and common errors · Composition source

oklch#

Create a OKLCH color with alpha=0–1.

Returns: color

Positional parameters: l, c, h.

Required: l, c, h.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`l`	number	Perceptual lightness, 0–1; percentage in the panel	—
`c`	number	Nonnegative chroma; out-of-sRGB colors retain lightness/hue while chroma is reduced	—
`h`	angle / deg	Hue: deg/rad, unitless degrees; normalized modulo 360 degrees	—
`alpha`	number	Color alpha, 0–1	1

Minimal complete example#

1# Minimal complete example: oklch2page=canvas(size=(100mm,75mm),background="#ffffff")3page.add(rect(size=(60mm,30mm),fill=oklch(0.7,0.15,200deg,alpha=0.6)),offset=(10mm,10mm))

# Minimal complete example: oklch
page=canvas(size=(100mm,75mm),background="#ffffff")
page.add(rect(size=(60mm,30mm),fill=oklch(0.7,0.15,200deg,alpha=0.6)),offset=(10mm,10mm))

Concepts and common errors · Composition source

dict#

Create an empty dictionary or load an ordered nested JSON object; table validation remains strict.

Returns: dict

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`src`	string	Path to a JSON object file	—

Minimal complete example#

1# Ordered value dictionaries, safe updates and pair unpacking.2page=canvas(size=(100mm,70mm),background="#ffffff")3d=dict()4d["B"]={"label":"Beta","color":"#0072b2"}5d["A"]={"label":"Alpha","color":"#d55e00"}6copy=d7copy["B"]["label"]="Copy"8d=d.update({"C":{"label":"Gamma","color":"#009e73"}})9keys=d.keys()10values=d.values()11items=d.items()12fallback=d.get("missing",{"label":"Default"})13for i,(name,value) in enumerate(items) {14 if name in d {15  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))16  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))17 }18}

# Ordered value dictionaries, safe updates and pair unpacking.
page=canvas(size=(100mm,70mm),background="#ffffff")
d=dict()
d["B"]={"label":"Beta","color":"#0072b2"}
d["A"]={"label":"Alpha","color":"#d55e00"}
copy=d
copy["B"]["label"]="Copy"
d=d.update({"C":{"label":"Gamma","color":"#009e73"}})
keys=d.keys()
values=d.values()
items=d.items()
fallback=d.get("missing",{"label":"Default"})
for i,(name,value) in enumerate(items) {
 if name in d {
  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))
  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))
 }
}

Concepts and common errors · Composition source

enumerate#

Return index/value pairs for loop unpacking; start defaults to zero and input is limited to 10,000 items.

Returns: list

Positional parameters: seq, start.

Required: seq.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`seq`	iterable	List, dictionary or geometry collection	—
`start`	integer	Initial index	0

Minimal complete example#

1# Insertion order controls the layout; assigning a dictionary copies its values.2page=canvas(size=(150mm,90mm),background="#ffffff")3labels=dict()4labels["B"]="Baseline"5labels["A"]="Annealed"6copy=labels7copy["B"]="Changed copy"8labels=labels.update({"C":"Cold worked"})9keys=labels.keys()10values=labels.values()11items=labels.items()12default=labels.get("missing","No data")13colors=["#0072b2","#d55e00","#009e73"]14for i,(key,value) in enumerate(items) {15 card=group()16 card.add(rect(size=(42mm,55mm),fill=colors[i]))17 card.add(text(content=key,font_family="DejaVu Sans",font_size=20pt,color="#ffffff"),offset=(5mm,7mm))18 card.add(text(content=value,font_family="DejaVu Sans",font_size=8pt,color="#ffffff"),offset=(5mm,35mm))19 page.add(card,offset=(5mm+i*48mm,10mm))20}21for i,(key,value) in enumerate(zip(keys,values)) {22 page.add(text(content=f"{i+1}. {key} = {value}",font_family="DejaVu Sans",font_size=8pt),offset=(5mm+i*48mm,72mm))23}

# Insertion order controls the layout; assigning a dictionary copies its values.
page=canvas(size=(150mm,90mm),background="#ffffff")
labels=dict()
labels["B"]="Baseline"
labels["A"]="Annealed"
copy=labels
copy["B"]="Changed copy"
labels=labels.update({"C":"Cold worked"})
keys=labels.keys()
values=labels.values()
items=labels.items()
default=labels.get("missing","No data")
colors=["#0072b2","#d55e00","#009e73"]
for i,(key,value) in enumerate(items) {
 card=group()
 card.add(rect(size=(42mm,55mm),fill=colors[i]))
 card.add(text(content=key,font_family="DejaVu Sans",font_size=20pt,color="#ffffff"),offset=(5mm,7mm))
 card.add(text(content=value,font_family="DejaVu Sans",font_size=8pt,color="#ffffff"),offset=(5mm,35mm))
 page.add(card,offset=(5mm+i*48mm,10mm))
}
for i,(key,value) in enumerate(zip(keys,values)) {
 page.add(text(content=f"{i+1}. {key} = {value}",font_family="DejaVu Sans",font_size=8pt),offset=(5mm+i*48mm,72mm))
}

Concepts and common errors · Composition source

zip#

Combine positional iterable inputs into tuples, stopping at the shortest input; no arguments return an empty list.

Returns: list

Positional parameters: sequences.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`sequences`	iterable...	Lists, dictionaries or geometry collections	—

Minimal complete example#

1# Insertion order controls the layout; assigning a dictionary copies its values.2page=canvas(size=(150mm,90mm),background="#ffffff")3labels=dict()4labels["B"]="Baseline"5labels["A"]="Annealed"6copy=labels7copy["B"]="Changed copy"8labels=labels.update({"C":"Cold worked"})9keys=labels.keys()10values=labels.values()11items=labels.items()12default=labels.get("missing","No data")13colors=["#0072b2","#d55e00","#009e73"]14for i,(key,value) in enumerate(items) {15 card=group()16 card.add(rect(size=(42mm,55mm),fill=colors[i]))17 card.add(text(content=key,font_family="DejaVu Sans",font_size=20pt,color="#ffffff"),offset=(5mm,7mm))18 card.add(text(content=value,font_family="DejaVu Sans",font_size=8pt,color="#ffffff"),offset=(5mm,35mm))19 page.add(card,offset=(5mm+i*48mm,10mm))20}21for i,(key,value) in enumerate(zip(keys,values)) {22 page.add(text(content=f"{i+1}. {key} = {value}",font_family="DejaVu Sans",font_size=8pt),offset=(5mm+i*48mm,72mm))23}

# Insertion order controls the layout; assigning a dictionary copies its values.
page=canvas(size=(150mm,90mm),background="#ffffff")
labels=dict()
labels["B"]="Baseline"
labels["A"]="Annealed"
copy=labels
copy["B"]="Changed copy"
labels=labels.update({"C":"Cold worked"})
keys=labels.keys()
values=labels.values()
items=labels.items()
default=labels.get("missing","No data")
colors=["#0072b2","#d55e00","#009e73"]
for i,(key,value) in enumerate(items) {
 card=group()
 card.add(rect(size=(42mm,55mm),fill=colors[i]))
 card.add(text(content=key,font_family="DejaVu Sans",font_size=20pt,color="#ffffff"),offset=(5mm,7mm))
 card.add(text(content=value,font_family="DejaVu Sans",font_size=8pt,color="#ffffff"),offset=(5mm,35mm))
 page.add(card,offset=(5mm+i*48mm,10mm))
}
for i,(key,value) in enumerate(zip(keys,values)) {
 page.add(text(content=f"{i+1}. {key} = {value}",font_family="DejaVu Sans",font_size=8pt),offset=(5mm+i*48mm,72mm))
}

Concepts and common errors · Composition source

cmap#

Get an immutable named Matplotlib 3.11.2 colormap for sampling, palette lists and reversal.

Returns: cmap

Positional parameters: name.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`name`	string	Preset name, including _r and native aliases	viridis

Minimal complete example#

1# Preset discovery, sampling, colors and immutable reversal.2page=canvas(size=(100mm,60mm),background="#ffffff")3cm=cmap("viridis")4names=cmap_names(category="sequential")5colors=cm.colors(8)6reverse=cm.reversed()7accent=cm.sample(0.5)8cycle=palette("tab10",8)9for i,color in enumerate(colors) {10 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))11 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))12 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))13}

# Preset discovery, sampling, colors and immutable reversal.
page=canvas(size=(100mm,60mm),background="#ffffff")
cm=cmap("viridis")
names=cmap_names(category="sequential")
colors=cm.colors(8)
reverse=cm.reversed()
accent=cm.sample(0.5)
cycle=palette("tab10",8)
for i,color in enumerate(colors) {
 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))
 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))
 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))
}

Concepts and common errors · Composition source

cmap_names#

List canonical colormap names, optionally filtered by category and including reversed names; aliases are omitted.

Returns: list

Positional parameters: category, reversed.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`category`	string \| null	sequential/diverging/cyclic/qualitative/misc; null lists all	null
`reversed`	boolean	Whether to include _r names	false

Minimal complete example#

1# Preset discovery, sampling, colors and immutable reversal.2page=canvas(size=(100mm,60mm),background="#ffffff")3cm=cmap("viridis")4names=cmap_names(category="sequential")5colors=cm.colors(8)6reverse=cm.reversed()7accent=cm.sample(0.5)8cycle=palette("tab10",8)9for i,color in enumerate(colors) {10 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))11 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))12 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))13}

# Preset discovery, sampling, colors and immutable reversal.
page=canvas(size=(100mm,60mm),background="#ffffff")
cm=cmap("viridis")
names=cmap_names(category="sequential")
colors=cm.colors(8)
reverse=cm.reversed()
accent=cm.sample(0.5)
cycle=palette("tab10",8)
for i,color in enumerate(colors) {
 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))
 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))
 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))
}

Concepts and common errors · Composition source

palette#

Create a palette: categorical colors cycle in native order, sequential colors sample evenly, and cyclic maps omit the repeated endpoint.

Returns: list

Positional parameters: name, n.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`name`	string	Preset name	tab10
`n`	integer \| null	0–10,000; null uses the native LUT size	null

Minimal complete example#

1# Preset discovery, sampling, colors and immutable reversal.2page=canvas(size=(100mm,60mm),background="#ffffff")3cm=cmap("viridis")4names=cmap_names(category="sequential")5colors=cm.colors(8)6reverse=cm.reversed()7accent=cm.sample(0.5)8cycle=palette("tab10",8)9for i,color in enumerate(colors) {10 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))11 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))12 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))13}

# Preset discovery, sampling, colors and immutable reversal.
page=canvas(size=(100mm,60mm),background="#ffffff")
cm=cmap("viridis")
names=cmap_names(category="sequential")
colors=cm.colors(8)
reverse=cm.reversed()
accent=cm.sample(0.5)
cycle=palette("tab10",8)
for i,color in enumerate(colors) {
 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))
 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))
 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))
}

Concepts and common errors · Composition source

dict.keys#

Return dictionary keys as a list in insertion order.

Returns: list

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance

Minimal complete example#

1# Ordered value dictionaries, safe updates and pair unpacking.2page=canvas(size=(100mm,70mm),background="#ffffff")3d=dict()4d["B"]={"label":"Beta","color":"#0072b2"}5d["A"]={"label":"Alpha","color":"#d55e00"}6copy=d7copy["B"]["label"]="Copy"8d=d.update({"C":{"label":"Gamma","color":"#009e73"}})9keys=d.keys()10values=d.values()11items=d.items()12fallback=d.get("missing",{"label":"Default"})13for i,(name,value) in enumerate(items) {14 if name in d {15  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))16  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))17 }18}

# Ordered value dictionaries, safe updates and pair unpacking.
page=canvas(size=(100mm,70mm),background="#ffffff")
d=dict()
d["B"]={"label":"Beta","color":"#0072b2"}
d["A"]={"label":"Alpha","color":"#d55e00"}
copy=d
copy["B"]["label"]="Copy"
d=d.update({"C":{"label":"Gamma","color":"#009e73"}})
keys=d.keys()
values=d.values()
items=d.items()
fallback=d.get("missing",{"label":"Default"})
for i,(name,value) in enumerate(items) {
 if name in d {
  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))
  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))
 }
}

Concepts and common errors · Composition source

dict.values#

Return values in insertion order, preserving units and object types.

Returns: list

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance

Minimal complete example#

1# Ordered value dictionaries, safe updates and pair unpacking.2page=canvas(size=(100mm,70mm),background="#ffffff")3d=dict()4d["B"]={"label":"Beta","color":"#0072b2"}5d["A"]={"label":"Alpha","color":"#d55e00"}6copy=d7copy["B"]["label"]="Copy"8d=d.update({"C":{"label":"Gamma","color":"#009e73"}})9keys=d.keys()10values=d.values()11items=d.items()12fallback=d.get("missing",{"label":"Default"})13for i,(name,value) in enumerate(items) {14 if name in d {15  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))16  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))17 }18}

# Ordered value dictionaries, safe updates and pair unpacking.
page=canvas(size=(100mm,70mm),background="#ffffff")
d=dict()
d["B"]={"label":"Beta","color":"#0072b2"}
d["A"]={"label":"Alpha","color":"#d55e00"}
copy=d
copy["B"]["label"]="Copy"
d=d.update({"C":{"label":"Gamma","color":"#009e73"}})
keys=d.keys()
values=d.values()
items=d.items()
fallback=d.get("missing",{"label":"Default"})
for i,(name,value) in enumerate(items) {
 if name in d {
  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))
  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))
 }
}

Concepts and common errors · Composition source

dict.items#

Return key/value pairs in insertion order for loop unpacking.

Returns: list

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance

Minimal complete example#

1# Ordered value dictionaries, safe updates and pair unpacking.2page=canvas(size=(100mm,70mm),background="#ffffff")3d=dict()4d["B"]={"label":"Beta","color":"#0072b2"}5d["A"]={"label":"Alpha","color":"#d55e00"}6copy=d7copy["B"]["label"]="Copy"8d=d.update({"C":{"label":"Gamma","color":"#009e73"}})9keys=d.keys()10values=d.values()11items=d.items()12fallback=d.get("missing",{"label":"Default"})13for i,(name,value) in enumerate(items) {14 if name in d {15  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))16  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))17 }18}

# Ordered value dictionaries, safe updates and pair unpacking.
page=canvas(size=(100mm,70mm),background="#ffffff")
d=dict()
d["B"]={"label":"Beta","color":"#0072b2"}
d["A"]={"label":"Alpha","color":"#d55e00"}
copy=d
copy["B"]["label"]="Copy"
d=d.update({"C":{"label":"Gamma","color":"#009e73"}})
keys=d.keys()
values=d.values()
items=d.items()
fallback=d.get("missing",{"label":"Default"})
for i,(name,value) in enumerate(items) {
 if name in d {
  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))
  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))
 }
}

Concepts and common errors · Composition source

dict.get#

Look up a string key; return default when missing, or null by default.

Returns: value

Positional parameters: key, default.

Required: key.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`key`	string	Dictionary key	—
`default`	value	Default for a missing key	null

Minimal complete example#

1# Ordered value dictionaries, safe updates and pair unpacking.2page=canvas(size=(100mm,70mm),background="#ffffff")3d=dict()4d["B"]={"label":"Beta","color":"#0072b2"}5d["A"]={"label":"Alpha","color":"#d55e00"}6copy=d7copy["B"]["label"]="Copy"8d=d.update({"C":{"label":"Gamma","color":"#009e73"}})9keys=d.keys()10values=d.values()11items=d.items()12fallback=d.get("missing",{"label":"Default"})13for i,(name,value) in enumerate(items) {14 if name in d {15  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))16  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))17 }18}

# Ordered value dictionaries, safe updates and pair unpacking.
page=canvas(size=(100mm,70mm),background="#ffffff")
d=dict()
d["B"]={"label":"Beta","color":"#0072b2"}
d["A"]={"label":"Alpha","color":"#d55e00"}
copy=d
copy["B"]["label"]="Copy"
d=d.update({"C":{"label":"Gamma","color":"#009e73"}})
keys=d.keys()
values=d.values()
items=d.items()
fallback=d.get("missing",{"label":"Default"})
for i,(name,value) in enumerate(items) {
 if name in d {
  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))
  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))
 }
}

Concepts and common errors · Composition source

dict.update#

Return a merged dictionary; existing keys keep their position and new keys append. The original remains unchanged.

Returns: dict

Positional parameters: other.

Required: other.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`other`	dict	Dictionary to merge	—

Minimal complete example#

1# Ordered value dictionaries, safe updates and pair unpacking.2page=canvas(size=(100mm,70mm),background="#ffffff")3d=dict()4d["B"]={"label":"Beta","color":"#0072b2"}5d["A"]={"label":"Alpha","color":"#d55e00"}6copy=d7copy["B"]["label"]="Copy"8d=d.update({"C":{"label":"Gamma","color":"#009e73"}})9keys=d.keys()10values=d.values()11items=d.items()12fallback=d.get("missing",{"label":"Default"})13for i,(name,value) in enumerate(items) {14 if name in d {15  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))16  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))17 }18}

# Ordered value dictionaries, safe updates and pair unpacking.
page=canvas(size=(100mm,70mm),background="#ffffff")
d=dict()
d["B"]={"label":"Beta","color":"#0072b2"}
d["A"]={"label":"Alpha","color":"#d55e00"}
copy=d
copy["B"]["label"]="Copy"
d=d.update({"C":{"label":"Gamma","color":"#009e73"}})
keys=d.keys()
values=d.values()
items=d.items()
fallback=d.get("missing",{"label":"Default"})
for i,(name,value) in enumerate(items) {
 if name in d {
  page.add(rect(size=(18mm,8mm),fill=value["color"]),offset=(8mm,8mm+i*18mm))
  page.add(text(content=f"{name}: {value['label']}",font_family="DejaVu Sans",font_size=10pt),offset=(30mm,8mm+i*18mm))
 }
}

Concepts and common errors · Composition source

cmap.sample#

Sample a finite normalized position, clamping values outside zero to one.

Returns: color

Positional parameters: t.

Required: t.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`t`	number	Finite normalized position	—

Minimal complete example#

1# Preset discovery, sampling, colors and immutable reversal.2page=canvas(size=(100mm,60mm),background="#ffffff")3cm=cmap("viridis")4names=cmap_names(category="sequential")5colors=cm.colors(8)6reverse=cm.reversed()7accent=cm.sample(0.5)8cycle=palette("tab10",8)9for i,color in enumerate(colors) {10 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))11 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))12 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))13}

# Preset discovery, sampling, colors and immutable reversal.
page=canvas(size=(100mm,60mm),background="#ffffff")
cm=cmap("viridis")
names=cmap_names(category="sequential")
colors=cm.colors(8)
reverse=cm.reversed()
accent=cm.sample(0.5)
cycle=palette("tab10",8)
for i,color in enumerate(colors) {
 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))
 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))
 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))
}

Concepts and common errors · Composition source

cmap.colors#

Return a palette with native size by default; categorical colors cycle, sequential maps sample evenly and cyclic maps omit the repeated endpoint.

Returns: list

Positional parameters: n.

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance
`n`	integer \| null	0–10,000; null uses native size	null

Minimal complete example#

1# Preset discovery, sampling, colors and immutable reversal.2page=canvas(size=(100mm,60mm),background="#ffffff")3cm=cmap("viridis")4names=cmap_names(category="sequential")5colors=cm.colors(8)6reverse=cm.reversed()7accent=cm.sample(0.5)8cycle=palette("tab10",8)9for i,color in enumerate(colors) {10 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))11 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))12 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))13}

# Preset discovery, sampling, colors and immutable reversal.
page=canvas(size=(100mm,60mm),background="#ffffff")
cm=cmap("viridis")
names=cmap_names(category="sequential")
colors=cm.colors(8)
reverse=cm.reversed()
accent=cm.sample(0.5)
cycle=palette("tab10",8)
for i,color in enumerate(colors) {
 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))
 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))
 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))
}

Concepts and common errors · Composition source

cmap.reversed#

Return a reversed colormap using Matplotlib native reversed lookup tables.

Returns: cmap

Parameter	Allowed type / unit	Meaning and choices	Default / inheritance

Minimal complete example#

1# Preset discovery, sampling, colors and immutable reversal.2page=canvas(size=(100mm,60mm),background="#ffffff")3cm=cmap("viridis")4names=cmap_names(category="sequential")5colors=cm.colors(8)6reverse=cm.reversed()7accent=cm.sample(0.5)8cycle=palette("tab10",8)9for i,color in enumerate(colors) {10 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))11 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))12 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))13}

# Preset discovery, sampling, colors and immutable reversal.
page=canvas(size=(100mm,60mm),background="#ffffff")
cm=cmap("viridis")
names=cmap_names(category="sequential")
colors=cm.colors(8)
reverse=cm.reversed()
accent=cm.sample(0.5)
cycle=palette("tab10",8)
for i,color in enumerate(colors) {
 page.add(rect(size=(10mm,12mm),fill=color),offset=(10mm+i*10mm,8mm))
 page.add(rect(size=(10mm,12mm),fill=reverse.sample(i/7)),offset=(10mm+i*10mm,24mm))
 page.add(rect(size=(10mm,8mm),fill=cycle[i]),offset=(10mm+i*10mm,40mm))
}

Concepts and common errors · Composition source