Skip to main content

Crate plottery_runtime

Crate plottery_runtime 

Source
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 a Range, also inside an Option.
  • #[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 typeEditor widget
f32, i32number box; slider with #[range]
boolswitch
Stringmulti-line text box
PaperDIN A/B or custom size, orientation, margin in cm or as a fraction
Range<f32>, Range<i32>min and max boxes, clamped to #[range]
Anglenumber with a deg/rot/rad unit switch
V2, V2ix and y boxes; a V2 can also be picked by clicking the drawing
Seednumber, dice button, recent seeds
Easingpower, bias or s-curve, slider, curve preview
ColorRgbcolor picker and hex code
NoiseSettingsperlin/simplex/worley, frequency per cm or per paper, octaves
BundledFontfont picker with previews
SystemFontpicker for the fonts installed on this machine and their styles; load() gives the Font
ImagePath, SvgPathfile picker; copies the file into resources/ or links the original
Curve2DNormcurve editor on 0..1, double-click adds or removes points
Curve2Dsame 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 PlotteryParamsits 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 params prints it, --set reads 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.
Curve2DNorm
A normalized 2D curve for transfer functions and easing curves.
Domain
A 2D domain defining x and y ranges.
ImagePath
Path to a raster image chosen in the editor.
ParamFieldError
The Error type, a wrapper around a dynamic error type.
ProjectParam
ProjectParamEnum
Value of a #[derive(PlotteryEnum)] field: the selected variant and all variant names.
ProjectParamFile
Editor value of a file param (e.g. crate::ImagePath): the current path plus recently used ones, newest first.
ProjectParamOptional
ProjectParamSeed
Editor value of a Seed param: the current seed plus recently used seeds, newest first.
ProjectParamStruct
ProjectParamVec
ProjectParamsListWrapper
Seed
Seed for the global random number generator, see plottery_lib::seed.
SvgPath
Path to an svg file chosen in the editor.

Enums§

AngleUnit
Unit an Angle param is shown in. The value itself is stored in radians.
MessageKind
First byte of a run stream message.
ProjectParamValue

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§

ParamField
A type that can be used as a field of a #[derive(PlotteryParams)] struct.
PlotteryParams
Implemented by #[derive(PlotteryParams)].
RangedParamField
A ParamField that accepts #[range(min, max)].

Functions§

file_name_of
param_field_from_map
Looks up name in params and converts it. Used by the generated try_new_from_map.
param_type_mismatch
run_project
write_message
Project side: sends layer as one message.

Derive Macros§

PlotteryEnum
Derives ParamField for an enum of unit variants. Exactly one variant must be marked #[default].
PlotteryParams
Derives PlotteryParams and ParamField for a struct of named fields.