Skip to content
TackoilPublic

About

Geometry, declared.

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Locus: deterministic geometry diagrams as code

Locus

Locus is a relational language and CLI for deterministic plane-geometry figures and technical diagrams. Declare geometric relationships, verify them with assertions, and export SVG or PNG.

Designed for AI agents and people, Locus provides structured diagnostics and stable JSON feedback so figures can be created, inspected, and revised through text. Diffable .locus source files make changes reproducible and auditable.

Under active development; breaking changes are expected. Only files starting with locus 0 beta 7 are accepted. The specification defines the current language and toolchain contract.

Quick start · Examples · CLI guide · Specification

Why Locus?

  • Geometry through relationships. Define distances, alignment, tangency, containment, and separation; derive further objects from those relationships.
  • Reusable diagrams. Compose functions, named instances, and ordered groups. Labels are measured before solving so text can determine shape sizes and layout.
  • Feedback for revision. Check assertions, inspect selected measurements, and use source-linked diagnostics to locate errors.
  • Self-contained rendering. Bundled text and math fonts support SVG and optional PNG output without installed fonts or an external TeX process.

Quick start

Install Rust with Cargo and rustup. The repository pins Rust 1.94.0 in rust-toolchain.toml.

Build and install the CLI from source:

git clone https://github.com/Tackoil/locus.git
cd locus
cargo install --locked --path crates/locus-cli
locus --version

Ensure Cargo's binary directory (usually ~/.cargo/bin) is on your PATH. Then validate and render a bundled example:

locus check examples/demonstrations/point_relations.locus
locus render examples/demonstrations/point_relations.locus -o figure.svg

Open figure.svg in a browser or image viewer. To run without installing, replace locus with cargo run --release --locked -p locus-cli --.

A triangle defined by relationships

Save this as triangle.locus:

locus 0 beta 7

style textbook

point A()
point B() where { align_center_y(A, B), hdist(A, B) == 4 }
point C() where { align_center_x(A, C), vdist(A, C) == 3 }
polygon triangle(A, B, C)

label lA(A, $A$) { dir: SW }
label lB(B, $B$) { dir: SE }
label lC(C, $C$) { dir: NW }

assert dist(B, C) == 5
assert area(triangle) == 6

The relations align the triangle's legs and set their lengths. The assertions verify the resulting hypotenuse and area.

locus check triangle.locus
locus render triangle.locus -o triangle.svg

Explore geometry and diagram examples, including tangent circles, flowcharts, sequence diagrams, architecture, and charts. The example corpus also covers stress workloads and rendering checks.

Check, inspect, revise

Use check as the validation step before rendering. Start with the default concise, deterministic plain text for agent feedback, then request specific measurements when investigating a problem:

locus check triangle.locus
locus inspect triangle.locus --distance B C
locus inspect triangle.locus --angle B A C
locus describe triangle.locus --json

Plain text is agent-oriented feedback, not a stable schema. Integrations should use --json, which remains the unchanged full, pretty-printed JSON with a stable schema. The temporary --human flag selects the existing rich human output and conflicts with --json; --compact has been removed. Angles are returned in radians; the middle point is the vertex.

For stricter visual validation, include annotation placement and fail on warnings:

locus check triangle.locus --layout --strict

Every check measures declared text and validates required routing, path-label placement, and clipping. --layout adds annotation collision diagnostics. Warnings are non-fatal unless --strict is set. Incomplete layout-preference settling can produce a warning even when hard requirements are satisfied, so visual review remains part of authoring.

Exit code Meaning
0 Success; all assertions pass
1 Failed assertions, or warnings with check --strict
2 Evaluation, construction, dependency, solve, or layout failure
3 Usage or parse error

Create and revise figures by writing or editing complete .locus source files directly. After saving changes, run locus check triangle.locus; once it passes, run locus render triangle.locus -o triangle.svg and review the image. See the CLI guide for report details and the authoring skill for the agent workflow.

Export and debug

locus render triangle.locus -o triangle.svg
locus render triangle.locus --stdout > triangle.svg

SVG is the default; output extensions do not select the format. The default background is transparent; use --background white for an opaque background. render --stdout still emits only the raw artifact, and fmt still emits formatted source rather than a status report (fmt --json emits the AST). Rendering evaluates the source independently and can export a figure with failed assertions, so a successful render does not replace check.

PNG requires the optional png build feature. From the repository root:

cargo run --release --locked -p locus-cli --features png -- \
  render triangle.locus --png --background white --dpi 300 -o triangle.png

Alternatively, add --features png to the installation command to enable locus render --png. See the rendering guide for DPI, font support, output options, and TeX limitations.

Capture solver and layout steps in an offline HTML viewer:

locus render triangle.locus -o triangle.svg --dump triangle.trace.json
locus visualize triangle.trace.json -o triangle.trace.html

Dump capture is opt-in and adds runtime and memory overhead. The viewer includes the source, intermediate results, geometry previews, and interactive relationships. Add --timings or --timings=json to any command for pipeline timing metrics on stderr.

Documentation and integrations

Resource Purpose
Language specification Normative syntax, relations, solver semantics, and CLI contract
CLI guide Detailed checks, diagnostics, rendering, dumps, and timings
Development guide Full validation commands, rejected-request archives, and license notice generation
Scene stages and compilation Source, evaluation, layout, and compiled-scene responsibilities and guarantees
Authoring skill Beta 7 authoring and verification workflow for agents
Drawing benchmark Native agent comparison of Locus and handwritten SVG on shared tasks
Zed extension Highlighting, diagnostics, completion, hover, navigation, and formatting
WebAssembly library Browser SVG rendering with the same measured solve/layout pipeline
Project website Introduction, demo gallery, browser playground, and documentation build

Development

See CONTRIBUTING.md for the contribution workflow and Rust style policy.

Run these checks from the repository root; the source audit requires Python 3:

python3 scripts/check_examples.py
cargo fmt --all -- --check
cargo clippy --workspace --all-features --all-targets -- -D warnings
cargo test --workspace --all-features --all-targets

Debug/dev CLI builds archive failed invocations, including source and submitted input, under .locus/rejected-requests/. Release builds disable this feature. See the development guide for archive controls and the full validation workflow.

Repository layout

Directory Contents
crates/ Rust libraries, CLI, language server, WebAssembly bindings, and crate-local tests
spec/ Normative specification and reference diagrams
examples/, tests/ Runnable figures, shared fixtures, expected outputs, and stress tests
docs/ CLI and development guides
scripts/ Source and third-party notice audits
ecosystem/ Tree-sitter grammar and Zed integration
skills/locus/, benchmarks/ Agent authoring reference and drawing benchmarks
assets/, website/ Project artwork and website
licenses/, vendor/ Third-party provenance and pinned dependency patches

License

Locus's own code is available under either the MIT license or the Apache License, Version 2.0, at your option. Dependencies and bundled fonts retain their own terms; preserve the applicable third-party notices when distributing them.

Before preparing a release: ordinary CLI builds include ReX, whose upstream license documentation is incomplete and whose generated tables have unresolved provenance questions. Review the ReX licensing investigation for the evidence and outstanding items.

About

Geometry, declared.

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages