Python API#
Workflow#
In the Notebook Python environment, run python -m pip install laymesh to install all features, including native plots, NumPy/pandas data bindings and Matplotlib Figure import. You can also install a local wheel as described in installation. Python 3.10+ is required. The bridge invokes the existing CLI rather than implementing another parser. CLI lookup order is LAYMESH_CLI, the native executable inside the wheel, the repository's target/release/laymesh or target/debug/laymesh, and finally laymesh in PATH. No JavaScript CLI fallback is supported.
from laymesh import render_source, render_file, RenderResult, LayMeshBridgeError result = render_source( r"""page=canvas(size=(20 mm,10 mm))box=rect(size=(5 mm, 5 mm),fill="#087f8c")page.add(box,target=page.top_left)""")print(result.preview_svg.startswith('<svg'), result.output, result.saved_source)# True None None| Export | Arguments | Behavior |
|---|---|---|
render_source(source, *, namespace=None, base_dir=None, output=None, dpi=None, plot_dpi=300, save_source=None, show_warnings=None, quality=None, compression=None, background=None, webp_lossless=None, webp_method=None, webp_alpha_quality=None, webp_near_lossless=None) |
.lay source; {{name}} variables; asset/module base; optional SVG/PDF/PPTX or raster export path; raster/PDF image or SVG/PPTX fallback DPI; fallback plot DPI; saved expanded .lay name |
Returns an SVG preview and optionally writes an export and expanded source. Temporary source files are cleaned up; saved assets use a sibling .assets/ folder. |
render_file(file, *, namespace=None, output=None, dpi=None, plot_dpi=300, save_source=None, show_warnings=None, quality=None, compression=None, background=None, webp_lossless=None, webp_method=None, webp_alpha_quality=None, webp_near_lossless=None) |
Reads an existing .lay; asset paths resolve beside it |
Uses the same binding and rendering path without modifying the original. |
RenderResult |
preview_svg: str, output: Path|None, saved_source: Path|None |
Immutable dataclass. A preview is available even without output. |
LayMeshBridgeError |
Exception | Raised for binding, asset, CLI startup, or CLI result failures. |
namespace supports strings, Path, booleans, finite numbers, NumPy scalars, numeric lists/tuples, 1D/2D arrays, Series, DataFrames, dictionaries and Matplotlib Figure. A placeholder must be a single unquoted {{name}}; it does not evaluate Python expressions. Arrays and DataFrames can also feed native plots directly; see the plotting guide. Compatible Matplotlib figures are saved as safe SVG; unsupported SVG content emits a warning and falls back to PNG at plot_dpi. Repeated save_source overwrites only files marked as LayMesh-generated. See the Python/Jupyter guide.
%load_ext laymesh.ipython invokes load_ipython_extension(ipython) to register LayMeshMagics:
%laymesh figures/layout.lay -o figures/output.png --dpi 300%%laymesh -o figure.pdf --save-source figure.laypage = canvas(size=(100 mm, 70 mm))Both magics display a 192 DPI JPEG preview (quality 95, 4:4:4 sampling, white matte) from the Rust CPU renderer at double pixel density, independently of export DPI. Export and preview share one native compilation. Use --preview-dpi, --preview-quality and --preview-background to adjust the preview; --dpi, --quality and --background still apply only to the exported file. Transparency is composited onto the preview matte; a colored canvas retains its background. SVG remains an explicit export format, and the Python API retains preview_svg. Line magic reads a file; cell magic reads cell content. Both support -o/--output, --dpi, --plot-dpi, and --save-source. Default --plot-dpi is 300 and affects only Figure PNG fallback. load_ipython_extension lives in ipython.py, not the top-level laymesh exports.
show_warnings=False hides displayed warnings; True shows them; None follows LAYMESH_WARNINGS (default show). Both Notebook magics accept --warnings show|hide. Source development uses an editable install after building the Rust CLI; see installation.
Limits and related topics#
dsl-reference · Plot objects and methods · Rust/WASM API · CLI options
workflow#
Complete sources and executable verification fixtures for this workflow are listed in the feature coverage map. Follow this page’s input conditions and limits when composing features.
render_source and render_file also accept quality=None, compression=None, background=None, webp_lossless=None, webp_method=None, webp_alpha_quality=None, and webp_near_lossless=None. Magics accept the corresponding --quality, --compression, --background and --webp-* flags. Export formats and encoding options
render_source and render_file default to 1200 export DPI, support config=PATH, and accept pdf_image_compression, pdf_jpeg_quality, pdf_downsample, pdf_recompress_jpeg, pdf_preserve_16bit, pdf_preserve_alpha, pdf_alpha_background, pdf_auto_palette_limit, and pdf_auto_flatness_threshold. Notebook flags use --pdf-*; see export configuration for defaults and precedence.
Styles and animation#
Python sources use the same engine and style rules. Project themes hold repeated appearance, explicit parameters retain priority, and styles/resources travel with the project. See the style manual for syntax, offline libraries and selective shadow overrides, and the animation manual for keyframes, steps and export. New library and diagnostic support requires a build containing those changes.