绘图对象与方法#

操作流程#

尺寸分为三层，内容不会自动撑大页面或图表外框：

图表内部的 padding 参数名是 margins=(左,上,右,下)：绘图区宽度为外框宽度减去左右留白，高度同理。margins 与 plot_area 二选一；两者都省略时才使用自动留白。

布局长度用 mm/cm/in/pt/px；数据用无单位数值，科学单位写在标签中。标记 marker_size 是包围框直径/边长，不是面积。自动线性范围在数据两侧加 5% 留白；含热图时自动范围取单元格最外侧边界。常量数据自动展开。对数范围在 log10 空间扩展。

page.add(p,size=(..., auto)) 会重新计算图表布局，保持字号、线宽和标记尺寸；未覆盖的高度保留定义值。图表首次成功放置后封存，之后可再次放置，但不能继续添加图层、图例或色标。将图表放进 group 后再整体缩放 group，仍会缩放全部子内容。多面板的精确排版由用户指定各自的 plot_area 和绘图区锚点；没有自动对齐、等宽化或跨面板调整。

网格先绘制，图层按添加顺序绘制，随后绘制坐标轴和标签，最后绘制图例。网格和数据层分别裁剪到绘图区。图例支持四角定位或物理坐标定位，不执行自动避让。长标签、最终刻度仍重叠或图例放不下时给出 W_PLOT_LAYOUT，保留完整内容并继续输出。自动刻度仍会尝试减少数量，显式刻度保持原样；字号和固定绘图区不会自动缩小。

布局警告包含放置语句的源码位置；留白不足时还报告各侧大约缺少多少 mm。CLI 的 validate 和 render 将警告写入 stderr，仍可成功返回；Rust/WASM API 可读取 scene.warnings，Notebook 显示 Python warning。超出图表外框的内容允许绘制，但超出整张页面的部分仍会被导出页面边界裁剪。非正绘图区、非法轴范围、无效数据等无法正确计算的情况仍报错。

共同可选参数：color="#0072B2"、line_width=0.6 pt、opacity=1、label=""。填充带默认 opacity=0.2；其他图层为 1。颜色使用 #RGB/#RRGGBB。

原生路径不经过 DSL 的 10,000 条路径命令限制，也不进行几何简化或数据降采样。输入数组在添加图层时复制，后续修改原列表不会追溯修改图层。

line、scatter 和 errorbar 共用以下选项。折线和误差棒的标记默认 none，散点默认 circle；省略新选项仍为原有实心样式。

数据点与图例共用几何、填充、描边和逐点透明度。带标记的折线显示线与标记组合；误差棒图例按实际 xerr/yerr 显示相应杆线、端帽及可选标记。图例保留图层顺序，相同 label 不会自动合并。

1p.line(x=[0,1,2], y=[1,3,2], marker="diamond", marker_size=2 mm,2       marker_fill="none", marker_border_color="#222222", marker_border_width=0.5 pt,3       label="Measured")

可编辑源码 · SVG · PDF。可分别修改每个系列的标记、填充、线型与误差方向。

轴、图层图例和色标的 label 接受字符串、text(...) 或 formula(...)。字符串继承图表颜色和对应字号；文字／公式素材使用自身样式，保留指定字号、宽度和换行，不自动缩放。混排使用现有 text(spans=[...])；相对字体路径仍按定义素材的 .lay 文件解析。

1label = text(spans=[span("Energy "), formula(source=r"E_f", font_size=9 pt), span(" (eV)")],2             font_family="DejaVu Sans", font_size=9 pt)3p = plot(size=(100 mm,80 mm), x=axis(label=label),4         y=axis(label=formula(source=r"I-I_0", font_size=10 pt), notation="offset"))

坐标轴和 colorbar(...) 共用下列参数：

横轴倍率默认放在刻度下方靠右，纵轴倍率在上方靠左；tick_labels=false 也隐藏倍率。倍率和标签的实际尺寸参与外围空间测量。notation/format/exponent 只改变显示，数据及 chart.data(...) 均使用原始数值，线性／对数映射不变。固定留白或 plot_area 不足时只警告，不重排数据区域；手动多面板的位置保持不变。

横轴标题默认居中，与横轴倍率共用刻度下方的一行。只有两者在默认位置的实测边界重叠时，才把标题放到倍率下方，间隔 1.2 mm；公式上下标、文字宽度及换行均参与测量。没有横轴统一倍率时保留原有默认标题位置。

axis(label_offset=(dx,dy)) 独立微调轴标题，exponent_offset 独立微调倍率。先完成默认定位和上述碰撞处理，再施加偏移；移动倍率不会带动标题，移动标题也不会带动倍率。偏移沿图表局部物理坐标，x 向右、y 向下，随后随图表旋转或所在组缩放。纵轴标题旋转 90° 后仍按这两个局部方向平移。偏移造成标题与倍率重叠或空间不足时报告 W_PLOT_LAYOUT，保留用户设置。自动留白会测量所需空间；原有贴外框边缘的标题若被手动移到外框之外，也会保留位置并警告，可用 plot_area 明确预留空间。色标继续使用原有布局规则，也支持独立 label_offset。

1x = axis(label="Time (s)", notation="offset", exponent=-6,2         exponent_offset=(0 mm, -0.5 mm),3         label_offset=(0 mm, 0.5 mm))

更复杂的标题布局可使用独立的 page.add(text(...)) 或 group.add(text(...))，并以绘图区锚点定位。

可编辑源码 · SVG · PDF。两个绘图区明确设为 76 × 52 mm，页面左上角分别是 (30,32) mm 和 (134,32) mm；右图横轴标题向下 0.5 mm、倍率向上 0.5 mm，数据区域保持不变。

1h = plot(size=(80 mm,65 mm), x=axis(label="x"), y=axis(label="y"))2heat = h.heatmap(z=[[1,2,3],[4,5,6]], extent=(0,3,0,2),3                origin="lower", cmap="viridis", vmin=0, vmax=6)4h.colorbar(heat, label="Intensity", format=".1f")5page.add(h)

• z 是非空、等宽的二维数值矩阵。支持 x_edges/y_edges 非均匀边界、命名轴和独立断轴。
• extent=(xmin,xmax,ymin,ymax) 指最外侧单元格边界；默认 (0,列数,0,行数)。x/y 范围必须递增。
• origin="lower" 将矩阵首行放在底部；"upper" 将首行放在顶部。默认 lower。
• 配色支持 viridis/magma/inferno/plasma/cividis/rdbu/gray。vmin/vmax 默认取有效数据的最小/最大值，常量自动展开；超出颜色范围的值钳制到端点颜色。
• mode="raster" 为默认：每个单元格对应源图像一个像素，采用最近邻显示；不插值、不平滑、不随输出 DPI 重算数值。非均匀网格或高级空间坐标会使用矢量单元格保证映射准确；mode="vector" 输出逐格矩形，适合小矩阵，大矩阵可能产生很大的文件。
• h.colorbar(heat, label="...", format="...") 绑定该图表内特定热图的颜色范围。每个图表最多一个色标，默认位于右侧；旧调用保留线性归一化；color_scale 支持共享非线性标尺。轴、刻度、普通文字及色标保持矢量。四侧和手动定位见下节。

p.colorbar(heat, ...) 可绑定本图的热图或带颜色标尺的图层，且每图最多一个。省略新选项保持右侧默认外观。

1p.colorbar(heat, position="bottom", length=45 mm, thickness=3 mm,2           ticks=[0,2500,5000], notation="offset", exponent=3, format=".1f",3           label=formula(source=r"I", font_size=9 pt))4# 手动位置的替代调用（同一图表只调用一次 colorbar）：5# p.colorbar(heat, position=(3.5 mm,51 mm), orientation="horizontal", length=45 mm)

竖直色标从下到上增大，水平色标从左到右增大；颜色映射与绑定图层完全相同，包括共享非线性归一化。左右侧刻度朝外，上下侧刻度朝外；手动竖直色标刻度在右，手动水平色标刻度在下。色标倍率在竖直色带上方靠左，水平刻度外侧靠右；可用 exponent_offset 调整。

自动留白会测量侧边色标，固定留白和固定绘图区保持用户设置。手动色标不改变留白；溢出外框、长标签或重叠刻度会给出 W_PLOT_LAYOUT，仍保留长度、厚度、字号、位置和显式刻度。局部 p.colorbar(...) 绑定本图图层；跨图共享使用独立的 colorbar(scale=..., length=...) 素材，并让各图层使用同一个 color_scale，详见共享装饰。两种形式均不自动避让其他面板或手动装饰。

可编辑源码 · SVG · PDF。四幅热图的绘图区均为 52 × 36 mm，每幅分别定位；源码也提供手动水平色标替代参数。

1d = table(src="results.csv")2p.line(x=d["time"], y=d["signal"])3z = array(src="matrix.json")

table 接受带唯一非空表头的 CSV，或按列组织的 JSON：{"x":[0,1],"y":[2,3],"sample":["A","B"]}。各列必须等长且非空；允许保留字符串列，但传给绘图方法的列必须为数值。CSV 支持引号、列名中的逗号和 UTF-8 BOM；空单元格视为缺失，文字 NaN 不会自动当作缺失。

array 接受一维或二维数值 JSON。外部 JSON 使用 null 表示缺失；不接受 JSON NaN、Infinity、复数或布尔数组。数据采用 JavaScript number；超出安全整数范围的整数会拒绝。相对路径依据定义该数据的 .lay 文件解析，可用于组件模块。文件按单次编译缓存，下次编译会重新读取修改后的内容。

缺失数据触发带源码位置及数量的 W_PLOT_MISSING：折线和填充带在缺失行断开，散点和误差棒跳过缺失行，热图缺失单元格透明。长度不匹配、无有效点、负误差、非法对数值、不规则矩阵和非有限范围报错。普通数据图层不排序或补点；统计方法按明确规则计算描述统计，不修改输入数组。

限制与相关主题#

dsl-reference · Rust/WASM API · Python API · CLI 参数

固定布局与科研样式#

plot_area=box(offset=(左,上), size=(宽,高)) 的四个值都是物理长度，相对于图表外框。左、上非负，宽、高为正，边界须为有限值；超出 size 时给出警告并保留设置。它与固定四边 margins 的区别是：覆盖外框 size=(width, height) 时，绘图区位置和尺寸仍固定，只有外围空间改变。字号、刻度、轴标签、图例或色标的修改也不会挤压绘图区；空间不足会报带源码位置的 W_PLOT_LAYOUT 并继续出图。锁定模式下，轴标签和色标标签随各自坐标轴定位，不会漂到扩大的外框边缘。

1page = canvas(size=(120 mm, 90 mm), background="#ffffff")2p = plot(size=(100 mm, 70 mm), plot_area=box(offset=(20 mm, 10 mm), size=(60 mm, 40 mm)),3         x=axis(label="Time (s)", range=(0, 2)),4         y=axis(label="Signal", range=(0, 4)))5p.line(x=[0, 1, 2], y=[0, 3, 1])6chart = page.add(p, anchor="plot_top_left", offset=(30 mm, 20 mm))7peak = chart.data(x=1, y=3)8pointer = page.add(line(end_head=head(), dx=-10 mm, dy=8 mm, line_width=0.5 pt),9                   anchor="end", target=peak)10page.add(text(content="Peak", font_size=8 pt), anchor=bottom_left,11         target=pointer.start, offset=(1 mm, -1 mm))

• chart.data(x=..., y=...) 返回已放置图表实例的数据锚点。x/y 是有限、无单位的数值，支持线性轴、正值对数轴和自动范围。锚点按该实例最终绘图区计算，不改变数据范围；修改轴范围并重新编译后，标注仍对应同一数据值。端点允许使用，超出轴范围报错，不静默钳制。
• 标注的 offset 是同一容器中的物理位移。可以把文字移到绘图区外；文字、箭头等是独立页面元素，不受数据层裁剪，也不自动避让或计入图表外框。
• 图表实例有九个绘图区锚点：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。可作为 target=chart.plot_top_left，也可用字符串 anchor="plot_top_left" 将数据区域直接定位到页面。
• anchor="start"/"end" 可定位线段和箭头端点；pointer.start/end 可继续放置文字。绘图区和端点锚点随实例旋转；原有九个外框锚点仍取旋转后的轴对齐外接框。新增锚点名须在 anchor 中加引号，没有新增保留字。
• 目标与标注必须位于同一画布或组内。图表及标注一同放入 group 后，整体缩放和旋转会同步作用于两者；此时物理尺寸也按已有 group 规则缩放。每个图表实例均可单独定位和微调。

数据值、绘图区锚点和物理偏移可以直接组合。anchor 指所放元素自身的对齐点，target 指目标位置；下例的位移沿页面坐标方向，而非图表旋转后的局部方向：

1page.add(text(content="Peak", font_size=8 pt), anchor=bottom_left,2         target=chart.data(x=1, y=3), offset=(2 mm, -2 mm))3page.add(text(content="(a)", font_size=9 pt),4         target=chart.plot_top_left, offset=(2 mm, 2 mm))

可编辑源码 · SVG · PDF。示例绘图区为 88 × 55 mm，左上角固定在页面 (26, 20) mm；峰值箭头、阈值文字和标题分别放置。

新增选项均显式启用，省略时保持原有样式。它们不会修改 plot_area、数据范围、图表放置锚点或其他面板。自动留白模式仍会根据实际轴文字测量留白；需要固定数据区域时使用 plot_area。固定留白或固定绘图区周围空间不足时继续输出并报告 W_PLOT_LAYOUT，不缩小字号、不平移或压缩绘图区。

手动图例可以放在绘图区外，不会为它自动增加留白或改变外框尺寸。超出图表外框时给出警告并保留坐标。图例不会检测与轴标签或数据的遮挡；使用者应保留所需空间。网格在数据后方，可能被不透明热图遮住。组缩放仍按现有规则缩放其中的文字、刻度和图例。

可编辑源码 · SVG · PDF。两个绘图区分别明确设为 64 × 45 mm，左上角由使用者指定在页面 (20, 26) mm 和 (115, 26) mm；这个示例没有调用自动对齐。

扩展图层与投影#

多轴与断轴 · 柱图与阶梯 · 直方图与 ECDF · 箱线图与小提琴 · 热图与等高线 · 极坐标投影 · 极坐标图层 · 雷达图