Formula

A CAD-style workbench for formulas you can watch, drag and take apart. 39 live, interactive formulas, from polar coordinates to the Lorenz attractor, sorting algorithms, pathfinding and proofs, each one a resizable viewport on an infinite drafting canvas. Every formula ships with its reference docs, step-by-step derivations, and working Python, TypeScript and Rust code. Written in Rust on egui/eframe; runs natively and in the browser (WebAssembly).

Showcase · Gallery · The workbench · Sheet files · Run · Develop

Highlights

• Live viewports on an infinite canvas. Place any formula with a click (or drag out its size), then move, resize, duplicate, lock, hide and undo, with snapping and smart guides, like a CAD drawing. Every viewport keeps animating, at any zoom.
• Hands on. Drag points, paint cells, draw walls, orbit 3D views, scrub through every step of an algorithm like a video.
• The Inspector explains it. Each formula's equations and controls, its full reference documentation, a Derive tab that works the equations out with the viewport's own numbers one operation at a time, and code to copy or download.
• Export. Python (numpy + matplotlib), TypeScript and Rust (macroquad) programs, LaTeX with the current parameter values, and a ready-to-run Jupyter notebook.
• Sheets. Save the whole board, with every formula's settings, as a plain-text .fwb file.
• Native and web. In the browser, index.html#mandelbrot links straight to a formula.

Showcase

Gallery

Every formula in the tool library, in its order. Click a picture for the formula's reference doc; the links under it open the example program in each language. Type the three-letter alias on the command line to place it.

Coordinate Systems & Projections

Curves & Interpolation

Physics & Network Layouts

Data Scaling & Normalization

Fractals & Generative Patterns

Chaos & Dynamical Systems

Geometry & Spatial Analysis

Linear Algebra

Statistics & Trend Analysis

Animation & Easing

Color & Accessibility

Sorting

All sorting viewports share one list (random, nearly sorted, reversed or few unique). Play, pause, step, step back and scrub through every comparison, swap and write; four skins; sound.

Graphs & Trees

The searches share one grid: draw walls and mud, drag the start and goal, make a maze. Every run can be played, stepped and scrubbed.

Proofs & Derivations

The workbench

Area	What it does
Toolbar	Select (V) and Pan (H), undo/redo, zoom; one button per category with a menu of its tools
Browser (left)	Tool library (click to place, double-click to place beside the drawing) and the list of viewports with show/hide and lock
Canvas	Infinite drafting plane with an adaptive grid, origin axes, rulers, crosshair, navigator (with zoom, fit and 1:1 buttons) and title block
Inspector (right)	Properties: name, X/Y/W/H, lock, the equations and the formula's controls. Docs: the full reference. Derive: the formula explained step by step: Prev / Next reveal one step at a time, "Plug in current values" works the equations out with the viewport's numbers one operation per step (distance, lerp, polar, rotation, luminance, normalization, easing and the proof tools), and authored derivations explain where the equations come from. Code: Python, TypeScript and Rust, with Copy and Download (Save on desktop), plus LaTeX (the equations with the viewport's current values) and a Jupyter Notebook (.ipynb). The maximize button widens it for reading
Command line	Type a tool alias (LOR, BEZ, MAN, VOR, …) or name to place it, or a command: fit, zoom 150, del, dup, undo, redo, grid, snap, ortho, latex (copy the selection's equations as LaTeX), ipynb (export it as a notebook), plot <expression> (place an expression plotter, e.g. plot r = 1 + cos(3θ)), derive (open the Derive tab), open [file] and save [name] (sheet files), help
Status bar	Pointer coordinates, current tool, SNAP / GRID / ORTHO toggles, zoom, viewport count, fps

Working with viewports:

• Select a viewport by clicking it or its title tab; Shift adds to the selection. Drag on empty canvas for a window selection (left to right: fully inside) or crossing selection (right to left: touching).
• Use the selected (active) viewport: dragging inside it goes to the formula, so you can move Bézier control points, draw Life cells or orbit the Lorenz attractor.
• Move by dragging the title tab, or an inactive viewport. Moves snap to the grid and to the edges and centers of other viewports, with dashed guides; ORTHO (or Shift) keeps a move on one axis.
• Resize with the eight grips; Shift keeps the aspect ratio. A viewport cannot shrink below the size its formula needs. The selected viewport shows its width and height as dimension lines.
• Navigate with the wheel (zoom about the pointer), pinch, middle-drag or Shift+wheel (pan), F (fit all), Shift+F (fit selection), Ctrl+0 (100%), or by clicking the navigator.
• Edit with Ctrl+Z / Ctrl+Y, Ctrl+D (duplicate), Del, arrow keys (nudge; Shift for ×10), and right-click menus on viewports and the canvas.

Formulas are drawn at their natural size (one world unit is one point) on a layer that egui scales and translates as a whole, so every formula keeps its own layout at any zoom, and lines stay crisp. The layout, every formula's settings, the camera, theme and settings are saved between sessions.

Sorting visualizer

Sorting viewports share one list per sheet, so a shuffle in one shows up in every other and algorithms can be compared on the same input. Each algorithm runs once on the shared list inside a Recorder that logs every operation (Compare, Swap, Write, Sorted, pivot/minimum/key markers, recursion Enter/Exit, and counting sort's tallies). The viewport replays that log at the chosen speed, and seeking backwards replays from the start, so you can scrub through a run like a video. Bars use one color language: blue unsorted, red comparing, amber swapping or writing, green in final place, plus purple for selection's minimum or insertion's key and pink for quick sort's pivot. Heap sort draws the heap as a tree for lists of up to 63 values; counting sort shows its tally histogram and output array.

• Skins: bars, radial (a clock face; swaps sweep a curve across it), color spectrum (value as hue, so an unsorted list is a jumbled rainbow that settles into a gradient) and dot scatter.
• Sound: each step plays the touched value as a pitch, frequency = 150 + X_norm · 650 Hz, and a finished run ends with a rising sweep. The browser build uses the Web Audio API; the desktop build uses cpal when built with --features native-audio.
• Keys: while a sorting viewport is selected, Space plays or pauses and the Left and Right arrows step back and forward.
• Presets: Nearly sorted has just two or three values out of place, which is where insertion sort shines; Few unique is where 3-way quick sort leaves the 2-way version behind.

The Sorting race runs the chosen algorithms on the same list at the same steps per second, so fewer operations means an earlier finish. Each lane shows comparisons and swaps + writes live, and, once it finishes, a measured time from actually running that algorithm (without recording) on this machine.

Sheet files

A sheet (.fwb) saves the whole board in a plain-text file you can keep, share or edit by hand: the viewports with every formula's settings (sliders, toggles, dragged points, painted Life cells), the data viewports share (the sorting list, the pathfinding grid, the MST graph), the camera, the canvas settings and the panels.

• File menu: New sheet, Open... (Ctrl+O), Save (Ctrl+S), Save As... (Ctrl+Shift+S), Recent (the last eight, desktop only) and Examples (Linear algebra basics, Sorting showdown, Pathfinding lab).
• Command line: open path/to/lesson.fwb, open (shows the dialog), save (to the current file, else exports/sheets/untitled.fwb) and save lesson (to exports/sheets/lesson.fwb).
• Drag and drop a .fwb file onto the window to open it.
• In the browser, Save downloads the sheet, and Save As first asks for a file name.

Opening a sheet replaces the board and can be undone in one step. A sheet keeps its saved view, unless that view would leave viewports off screen (say, a sheet saved on a larger monitor); then it zooms to fit. Duplicate (Ctrl+D) copies a viewport together with its settings. The title bar shows the file name, with a dot (•) while there are unsaved changes. Panning, zooming and switching tabs don't count as changes, and neither does a running animation. A sheet from a newer version of the app, or a damaged file, is refused with the line number and the board is kept. Unknown tools, sections, keys and parameters are skipped and listed in the command log.

FWB 1
; Formula Workbench sheet

SECTION HEADER
  app 0.1.0
  title "Sorting showdown"
ENDSEC

SECTION CAMERA
  center 680.0 479.0
  zoom 0.79
ENDSEC

SECTION SHARED
  sorting {"dist":"nearly_sorted","n":60,"seed":3,"skin":"bars"}
ENDSEC

SECTION VIEWPORT
  uid 1
  tool bubble-sort
  title VP-01
  rect 0.0 0.0 640.0 372.0
  locked false
  hidden false
  param speed 80
ENDSEC

Each line is a key and a value. A value is JSON, except that a list of numbers is written with spaces (rect 0 0 640 480) and a simple word needs no quotes (tool lerp). param lines are the formula's settings (its save_state). Missing keys keep their defaults; SETTINGS and UI sections work the same way (theme dark, tab docs, grid false).

Run

Download the desktop app for macOS (universal), Windows or Linux (x86_64) from the latest release. The macOS app is not notarized: the first time, right-click Formula.app and choose Open (or run xattr -dr com.apple.quarantine Formula.app). On Linux it needs ALSA (libasound2) for sound.

Native, from source:

cargo run --release
# with sound on the sorting viewports (Linux needs the ALSA headers: libasound2-dev)
cargo run --release --features native-audio

On Linux you need the usual windowing libraries (libxkbcommon-x11, an OpenGL driver).

Web:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.129   # must match the wasm-bindgen version in Cargo.lock
cargo build --release --lib --target wasm32-unknown-unknown
wasm-bindgen --target web --no-typescript --out-dir pkg target/wasm32-unknown-unknown/release/formula.wasm
python3 -m http.server   # then open http://localhost:8000 (or http://localhost:8000/#lorenz)

The hosted version is at https://formula.vachagan.dev: a landing page (web/index.html) with the workbench under /app/. scripts/deploy-web.sh builds it and publishes it to the server described in deploy/zimaos/.

The example programs in assets/content/<id>/ (the same code as the Inspector's Code tab) run on their own:

pip install numpy matplotlib && python main.py              # Python
tsc main.ts                                                 # TypeScript: load main.js in any page
cargo new demo && cd demo && cargo add [email protected]        # Rust: replace src/main.rs, then
cargo run --release

Develop

cargo test                                   # every test (fast)
cargo fmt --check
cargo clippy --all-targets -- -D warnings

Layout

src/
  main.rs            native entry point
  web.rs             browser entry point and #id deep links
  app.rs             shell: wires the panels and the canvas together; saves the workspace, sets the title
  content.rs         embedded reference docs and code (table generated by build.rs)
  cad/               the workbench
    canvas.rs        layers, input routing, placing / selecting / moving / resizing, commands
    camera.rs        pan and zoom with smoothing, fit, grid steps (UI-free)
    board.rs         viewports, z-order, selection, smart guides, saved layout (UI-free)
    history.rs       undo / redo
    overlay.rs       grid, rulers, frames, grips, dimensions, guides, crosshair, navigator
    chrome.rs        menu bar, toolbar, Browser, command line, status bar, help
    inspector.rs     Properties, Docs, Derive and Code tabs
    markdown.rs      the docs renderer      highlight.rs  syntax highlighting
    icons.rs         line-art tool and UI icons   theme.rs  graphite and drafting-paper themes
    export.rs        copy, download (web) and save (desktop)
    notebook.rs      Jupyter notebook export
    fwb.rs           the .fwb text format: sections, entries, values (UI-free)
    sheet.rs         a whole board as a sheet, lenient reading with warnings, examples (UI-free)
    files.rs         current file, unsaved mark, Recent list, file dialogs
  formula.rs         the `Formula` trait, `Palette`, `MathText` equation builder
  latex.rs           equations as LaTeX
  draw.rs            drawing helpers: polygon fill, lerp/gradients, draggable handles
  rng.rs             small seeded random number generator
  state.rs           saving and loading formula settings field by field
  expr/              expression engine (UI-free): lexer, Pratt parser, eval, math and code printers
  derive.rs          derivation steps, and plugging values into an expression one operation at a time
  audio.rs           tones: Web Audio in the browser, cpal on desktop (feature native-audio)
  formulas/
    mod.rs           the tool catalogue (`TOOLS`), category names, glyph-coverage test
    polar.rs  projection.rs  lerp.rs  bezier.rs  lissajous.rs
    force.rs  normalize.rs  mandelbrot.rs  flowfield.rs  life.rs  lorenz.rs
    distance.rs  rotation.rs  voronoi.rs  regression.rs  easing.rs  luminance.rs
    matrix/          matrix transformation
    sorting/         algorithms.rs (records every step, UI-free), data.rs (shared list),
                     skin.rs (bars / radial / spectrum / dots), race.rs, mod.rs (player and view)
    graphs/          pathfinding, binary search tree, minimum spanning trees
    replay.rs        step-through player shared by sorting, pathfinding, MST and the BST
    fourier/         epicycles: math.rs (UI-free), animals.rs, mod.rs (view)
    expression/      plotter: plot.rs (view and sampling, UI-free), export.rs (code generation), mod.rs
    proofs/          quadratic.rs, pythagoras.rs, euler.rs (math in plain functions with tests)
assets/animals.json  animal outlines
assets/content/<id>/ doc.md, main.py, main.ts, main.rs for every tool
assets/sheets/       example sheets (File > Examples)
build.rs             embeds assets/content and assets/sheets
docs/media/          the README's screenshots and GIFs (generated by tools/capture)
tools/capture/       headless rendering library + the binary that renders docs/media (a separate crate)

Adding a formula

1. Create a module under src/formulas/ and implement formula::Formula for its state. Required: id, name, category, summary, equations, paint (draws the stage every frame) and controls. Optional: notes ("Where it's used"), details, stage_height, is_animating, and stage_sense + interact for dragging or clicking on the stage. Optional: min_size (the smallest viewport it lays out in), handle_keys (keyboard shortcuts while it is the active viewport) and wants_scroll (keep the mouse wheel for itself).
2. Add a tool! line to TOOLS in formulas/mod.rs with its id, name, category and a three-letter command alias. Use one of the category constants, or add a new one; the toolbar and library group tools by category automatically.
3. Add assets/content/<id>/ with doc.md (the ten sections listed in content::SECTIONS), main.py, main.ts and main.rs. cargo test checks that every tool has all four.
4. Save the settings: a serde State struct with state() and apply() (clamping every value), and crate::state_hooks!() in the impl Formula. cargo test checks that every tool saves its state, that it round-trips, and that absurd values are clamped.
5. Regenerate the screenshots (below) and add a card for it to the README's gallery. cargo test checks that every tool has one.

The workbench takes care of placing, selecting, moving and resizing viewports, the panels, theming, undo and saving the layout. Each viewport has its own instance of the formula. Use the Palette colors (x, y, trace, fill, …) so new formulas match the existing ones in both light and dark mode. Keep the math in plain functions with unit tests, as every module here does. egui's bundled font lacks some symbols (′ ∈ → ᵢ ᵣ, combining accents like x̄); cargo test fails if a formula's text uses a character with no glyph.

To add a sorting algorithm, add a variant to Algorithm, write it against Recorder, and add its text to info() in sorting/mod.rs; the tests check every algorithm sorts correctly and leaves no state behind.

Regenerating the screenshots

Every picture in this README is rendered headlessly by tools/capture, a separate crate that drives the real workbench with egui_kittest and wgpu at a fixed frame time, so each run draws the same frames. It writes a PNG of every tool, the showcase GIFs, hero.gif and inspector.png to docs/media/. The GIFs need ffmpeg on the PATH.

cargo run --release --manifest-path tools/capture/Cargo.toml

The showcase list, the hero board and how long each tool runs before its picture is taken are at the top of tools/capture/src/main.rs.

Credits

Silhouettes adapted from game-icons.net by Lorc, Delapouite and contributors, licensed CC BY 3.0. Outlines were traced and simplified.