Expand description
§Plottery Runtime
Part of Plottery, a generative art engine for pen-plotters.
What a Plottery project compiles against besides plottery_lib: the parameter types, the PlotteryParams and PlotteryEnum derives and run_project, the entry point of the project’s binary. Creating, building and running projects is plottery_project.
Complete example projects with rendered previews are in examples/.
§Generate
src/generate.rs turns a Params struct into a Layer:
use plottery_lib::*;
use plottery_runtime::*;
#[derive(PlotteryParams)]
pub struct Params {
pub paper: Paper,
}
pub fn generate(params: Params) -> Layer {
let frame = params.paper.frame();
let mut l = Layer::new();
l.push(frame.outer_rect());
l.with_name("root").optimize_recursive()
}src/main.rs hands it to run_project, which the editor and CLI call. Run directly, cargo run svg opens the result as .svg and cargo run -- --help lists the other commands.
fn main() -> Result<(), Box<dyn std::error::Error>> {
plottery_runtime::run_project(generate)
}§Parameters
Every field of Params shows up in the editor:
use plottery_lib::*;
use plottery_runtime::*;
#[derive(PlotteryEnum)]
pub enum Style {
#[default]
Circles,
Squares,
}
#[derive(PlotteryParams)]
pub struct Params {
paper: Paper,
style: Style,
#[section("Points")]
num_points: i32,
/// distance between neighboring points in cm
#[value(2.0)]
#[range(0.5, 10.0)]
points_distance: f32,
}#[value(..)]sets the default.#[range(min, max)]turns a number into a slider and bounds aRange, also inside anOption.#[section("Name")]starts a collapsible section. It holds this field and all following ones until the next#[section]. The struct stays flat.///doc comments are shown as tooltips on the param labels.- Field names show lowercase with spaces (
circle_size→ “circle size”). Enum variants split CamelCase (SomeVariant→ “some variant”).
Field types and their widgets:
| Field type | Editor widget |
|---|---|
f32, i32 | number box; slider with #[range] |
bool | switch |
String | multi-line text box |
Paper | DIN A/B or custom size, orientation, margin in cm or as a fraction |
Range<f32>, Range<i32> | min and max boxes, clamped to #[range] |
Angle | number with a deg/rot/rad unit switch |
V2, V2i | x and y boxes; a V2 can also be picked by clicking the drawing |
Seed | number, dice button, recent seeds |
Easing | power, bias or s-curve, slider, curve preview |
ColorRgb | color picker and hex code |
NoiseSettings | perlin/simplex/worley, frequency per cm or per paper, octaves |
BundledFont | font picker with previews |
SystemFont | picker for the fonts installed on this machine and their styles; load() gives the Font |
ImagePath, SvgPath | file picker; copies the file into resources/ or links the original |
Curve2DNorm | curve editor on 0..1, double-click adds or removes points |
Curve2D | same curve plus the x and y range it maps to |
enum deriving PlotteryEnum (#[default] on one variant) | buttons up to four variants, dropdown beyond |
struct deriving PlotteryParams | its own collapsible section |
Option<T> | switch beside the widget, or in the section header for a struct; off hides it |
Vec<T> | list with add/remove; new items start at T’s default (a struct’s #[value]s) |
Option<Option<T>>, Vec<Option<T>> and Vec<Vec<T>> don’t compile. Option<Vec<T>> works.
Modules§
- angle_
unit - curve_
2d - curve_
2d_ norm - image_
path - param_
field - param_
text - Text form of param values for the CLI:
plottery paramsprints it,--setreads it. - project_
param - project_
param_ enum - project_
param_ file - project_
param_ optional - project_
param_ struct - project_
param_ value - project_
param_ vec - project_
params_ definition - project_
params_ list_ wrapper - seed
- svg_
path
Structs§
- Curve2D
- A 2D curve with domain mapping.
- Curve2D
Norm - A normalized 2D curve for transfer functions and easing curves.
- Domain
- A 2D domain defining x and y ranges.
- Image
Path - Path to a raster image chosen in the editor.
- Param
Field Error - The
Errortype, a wrapper around a dynamic error type. - Project
Param - Project
Param Enum - Value of a
#[derive(PlotteryEnum)]field: the selected variant and all variant names. - Project
Param File - Editor value of a file param (e.g.
crate::ImagePath): the current path plus recently used ones, newest first. - Project
Param Optional - Project
Param Seed - Editor value of a
Seedparam: the current seed plus recently used seeds, newest first. - Project
Param Struct - Project
Param Vec - Project
Params List Wrapper - Seed
- Seed for the global random number generator, see
plottery_lib::seed. - SvgPath
- Path to an svg file chosen in the editor.
Enums§
- Angle
Unit - Unit an
Angleparam is shown in. The value itself is stored in radians. - Message
Kind - First byte of a run stream message.
- Project
Param Value
Constants§
- PROTOCOL_
VERSION - Version of what the CLI and the editor exchange with a project binary: its subcommands, the piped params and the run stream. Changes with any of them, including the postcard layout of params and layers.
Traits§
- Param
Field - A type that can be used as a field of a
#[derive(PlotteryParams)]struct. - Plottery
Params - Implemented by
#[derive(PlotteryParams)]. - Ranged
Param Field - A
ParamFieldthat accepts#[range(min, max)].
Functions§
- file_
name_ of - param_
field_ from_ map - Looks up
nameinparamsand converts it. Used by the generatedtry_new_from_map. - param_
type_ mismatch - run_
project - write_
message - Project side: sends
layeras one message.
Derive Macros§
- Plottery
Enum - Derives
ParamFieldfor an enum of unit variants. Exactly one variant must be marked#[default]. - Plottery
Params - Derives
PlotteryParamsandParamFieldfor a struct of named fields.