# textiles-lab/autoknit architecture

> Architecture diagram of the GitHub repository textiles-lab/autoknit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/textiles-lab/autoknit
- Repository: https://github.com/textiles-lab/autoknit

## Overview

1. **What this repository is**
   - Autoknit is a native C++ pipeline for turning a triangle mesh into machine-knitting instructions.
   - The overall flow is: **OBJ mesh + user constraints → traced stitches → machine scheduling → generated JavaScript → knitout output**.

2. **Two main user-facing executables**
   - **`interface`** is the interactive front end. It loads the 3D model, lets a user place/edit constraints, runs the geometry/pipeline steps, and can save traced stitch data.
   - **`schedule`** is a headless combinatorial optimizer. It reads traced stitches and produces a JavaScript program that later emits knitout.

3. **Core data pipeline and file boundaries**
   - Input geometry comes from **`.obj`** files.
   - User-authored constraints are stored in **`.cons`** files.
   - The tracing stage writes stitched path data to **`.st`** files.
   - Scheduling emits **`.js`** files.
   - Running that JS with Node produces final **`.k` knitout** instructions.
   - These formats are the key architectural handoff points between subsystems.

4. **Geometry and mesh representation**
   - `load_obj.cpp`, `Shape.hpp`, `EmbeddedMesh.hpp`, `EmbeddedPlanarMap.hpp`, and `embed_DAG.*` form the geometric/modeling layer.
   - This layer holds the surface mesh, embedded graph structures, and planar/DAG representations used to reason about how stitches move over the mesh.

5. **Constraint specification and model interaction**
   - `Interface.cpp/.hpp` and `init.cpp` are responsible for the UI and application setup.
   - The interface supports placing, moving, deleting, and time-ordering constraints on the mesh surface.
   - Those constraints define where knitting must start/end or change direction, and they feed the automated pipeline.

6. **Peeling / tracing subsystem**
   - Files like `ak-peel_*`, `ak-trace_graph.cpp`, `ak-embedded_path.cpp`, `ak-interpolate_values.cpp`, and `ak-link_chains.cpp` implement the surface “peeling” and stitch tracing logic.
   - Conceptually, this subsystem converts constrained regions of the mesh into chains/rows/columns of stitch paths and tracks how they evolve across the surface.

7. **Linking and chain-graph logic**
   - The `ak-find_first_active_chains.cpp`, `ak-next_active_chains.cpp`, `ak-extract_level_chains.cpp`, `ak-optimal_link.cpp`, and related files handle chain activation, extraction, and linking between rows/levels.
   - This is the combinatorial bridge between geometric slices of the mesh and a stitch graph that can be scheduled.

8. **Scheduling and transfer planning**
   - `schedule.cpp`, `ScheduleCost.*`, `Stitch.*`, `plan_transfers.*`, and `pipeline.hpp` implement the machine-side assignment of stitches to needles/beds.
   - This stage searches for feasible and low-cost layouts, including transfers, bed shifts, collapses/expands, and winding minimization.
   - The `plan_transfers-*` files are a focused subsystem for generating and optimizing needle-bed transfer sequences.

9. **JavaScript generation and knitout emission**
   - The scheduler does not emit knitout directly; it writes a **JavaScript program**.
   - That JS uses helper functions in `node_modules/autoknit.js` to perform machine-specific operations such as cast-on, yarn handling, and transfers.
   - This makes the last stage adaptable to different knitting machines without recompiling the C++ core.

10. **External geometry dependency**
    - `libgeodesic/` is vendored in the repo and provides geodesic computations on triangle meshes.
    - It materially supports surface tracing/peeling, where shortest paths and distances over the mesh matter.

11. **Build and packaging**
    - The project is built with the single-file build tool **Maek** (`Maekfile.js`), not a traditional CMake layout.
    - It depends on **Eigen** for linear algebra and on **nest-libs** for runtime/build support libraries such as SDL2 and glm.
    - GitHub Actions are used to build prebuilt releases.

12. **Testing and validation**
    - The repository includes focused tests like `test_shape.cpp`, `test_flatten.cpp`, and `test_plan_transfers.cpp`, plus a shell test for a cactus example.
    - These tests align with the major pipeline boundaries: geometry, flattening/tracing, and transfer planning.

13. **How to draw the architecture**
    - A good diagram would show:
      - **User/UI layer**: `interface`
      - **Geometry + constraint layer**: OBJ loading and constraint editing
      - **Tracing layer**: peeling/linking/tracing over mesh geometry
      - **Scheduling layer**: stitch-to-needle assignment and transfer planning
      - **Codegen/runtime layer**: generated JS + Node helper library → knitout
    - The critical arrows are the file handoffs: `.obj/.cons → .st → .js → .k`.

Main entry points: [`schedule.cpp`](https://github.com/textiles-lab/autoknit/blob/master/schedule.cpp) (Schedule), [`Interface.cpp`](https://github.com/textiles-lab/autoknit/blob/master/Interface.cpp) (Interface), [`Maekfile.js`](https://github.com/textiles-lab/autoknit/blob/master/Maekfile.js) (Maekfile), [`load_obj.cpp`](https://github.com/textiles-lab/autoknit/blob/master/load_obj.cpp) (OBJ Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_interface["Interface<br/>ui app<br/>[Interface.cpp]"]
  node_init["Init<br/>setup<br/>[init.cpp]"]
end

subgraph group_geometry["Geometry Model"]
  node_load_obj["OBJ Loader<br/>mesh input<br/>[load_obj.cpp]"]
  node_shape["Shape<br/>surface model<br/>[Shape.hpp]"]
  node_embedded_mesh["Embedded Mesh<br/>mesh graph<br/>[EmbeddedMesh.hpp]"]
  node_planar_map["Planar Map<br/>embedding"]
  node_embed_dag["Embed DAG<br/>geometry graph<br/>[embed_DAG.cpp]"]
  node_load_constraints["Load Cons<br/>constraint io"]
  node_embed_constraints["Embed Cons<br/>constraint mapping"]
end

subgraph group_tracing["Tracing Pipeline"]
  node_peel["Peel<br/>surface tracing"]
  node_trace_graph["Trace Graph<br/>stitch tracing<br/>[ak-trace_graph.cpp]"]
  node_embedded_path["Paths<br/>path model"]
  node_link_chains["Link Chains<br/>chain linking<br/>[ak-link_chains.cpp]"]
  node_optimal_link["Optimal Link<br/>combinatorics"]
end

subgraph group_scheduling["Scheduling"]
  node_schedule["Schedule<br/>optimizer<br/>[schedule.cpp]"]
  node_schedule_cost["Cost Model<br/>optimization<br/>[ScheduleCost.cpp]"]
  node_stitch["Stitch<br/>machine state<br/>[Stitch.cpp]"]
  node_plan_transfers["Transfers<br/>transfer planner<br/>[plan_transfers.cpp]"]
  node_pipeline["Pipeline<br/>orchestration<br/>[pipeline.hpp]"]
end

subgraph group_runtime["Build & Runtime"]
  node_maek["Maekfile<br/>build system<br/>[Maekfile.js]"]
  node_runtime_lib["Node Runtime<br/>js runtime"]
end

node_init -->|"starts"| node_interface
node_interface -->|"loads"| node_load_obj
node_interface -->|"opens"| node_load_constraints
node_interface -->|"edits"| node_embed_constraints
node_load_obj -->|"builds"| node_shape
node_shape -->|"wraps"| node_embedded_mesh
node_embedded_mesh -->|"derives"| node_planar_map
node_planar_map -->|"organizes"| node_embed_dag
node_embed_constraints -->|"seeds"| node_peel
node_peel -->|"produces"| node_trace_graph
node_trace_graph -->|"materializes"| node_embedded_path
node_embedded_path -->|"segments"| node_link_chains
node_link_chains -->|"optimizes"| node_optimal_link
node_optimal_link -->|"feeds"| node_schedule
node_schedule -->|"scores"| node_schedule_cost
node_schedule -->|"assigns"| node_stitch
node_schedule -->|"plans"| node_plan_transfers
node_plan_transfers -->|"integrates"| node_pipeline
node_pipeline -->|"emits"| node_runtime_lib
node_maek -->|"builds"| node_interface
node_maek -->|"builds"| node_schedule
node_runtime_lib -->|"executes"| node_schedule

click node_interface "https://github.com/textiles-lab/autoknit/blob/master/Interface.cpp"
click node_init "https://github.com/textiles-lab/autoknit/blob/master/init.cpp"
click node_load_obj "https://github.com/textiles-lab/autoknit/blob/master/load_obj.cpp"
click node_shape "https://github.com/textiles-lab/autoknit/blob/master/Shape.hpp"
click node_embedded_mesh "https://github.com/textiles-lab/autoknit/blob/master/EmbeddedMesh.hpp"
click node_planar_map "https://github.com/textiles-lab/autoknit/blob/master/EmbeddedPlanarMap.hpp"
click node_embed_dag "https://github.com/textiles-lab/autoknit/blob/master/embed_DAG.cpp"
click node_load_constraints "https://github.com/textiles-lab/autoknit/blob/master/ak-load_constraints.cpp"
click node_embed_constraints "https://github.com/textiles-lab/autoknit/blob/master/ak-embed_constraints.cpp"
click node_peel "https://github.com/textiles-lab/autoknit/blob/master/ak-peel_chains-libgeodesic.cpp"
click node_trace_graph "https://github.com/textiles-lab/autoknit/blob/master/ak-trace_graph.cpp"
click node_embedded_path "https://github.com/textiles-lab/autoknit/blob/master/ak-embedded_path.cpp"
click node_link_chains "https://github.com/textiles-lab/autoknit/blob/master/ak-link_chains.cpp"
click node_optimal_link "https://github.com/textiles-lab/autoknit/blob/master/ak-optimal_link.cpp"
click node_schedule "https://github.com/textiles-lab/autoknit/blob/master/schedule.cpp"
click node_schedule_cost "https://github.com/textiles-lab/autoknit/blob/master/ScheduleCost.cpp"
click node_stitch "https://github.com/textiles-lab/autoknit/blob/master/Stitch.cpp"
click node_plan_transfers "https://github.com/textiles-lab/autoknit/blob/master/plan_transfers.cpp"
click node_pipeline "https://github.com/textiles-lab/autoknit/blob/master/pipeline.hpp"
click node_maek "https://github.com/textiles-lab/autoknit/blob/master/Maekfile.js"
click node_runtime_lib "https://github.com/textiles-lab/autoknit/tree/master/node_modules"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_interface,node_init toneBlue
class node_load_obj,node_shape,node_embedded_mesh,node_planar_map,node_embed_dag,node_load_constraints,node_embed_constraints toneAmber
class node_peel,node_trace_graph,node_embedded_path,node_link_chains,node_optimal_link toneMint
class node_schedule,node_schedule_cost,node_stitch,node_plan_transfers,node_pipeline toneRose
class node_maek,node_runtime_lib toneIndigo
```

## Components

### User Interface

Interactive application for loading models and authoring constraints

- [Interface](https://github.com/textiles-lab/autoknit/blob/master/Interface.cpp): ui app · Interactive front end for model viewing and constraint editing · `Interface.cpp`
- [Init](https://github.com/textiles-lab/autoknit/blob/master/init.cpp): setup · Application bootstrap and environment setup · `init.cpp`

### Geometry Model

Mesh, embedding, and constraint representation on the surface

- [OBJ Loader](https://github.com/textiles-lab/autoknit/blob/master/load_obj.cpp): mesh input · Loads triangle meshes from OBJ files · `load_obj.cpp`
- [Shape](https://github.com/textiles-lab/autoknit/blob/master/Shape.hpp): surface model · Core shape and surface geometry abstraction · `Shape.hpp`
- [Embedded Mesh](https://github.com/textiles-lab/autoknit/blob/master/EmbeddedMesh.hpp): mesh graph · Mesh representation embedded for stitching operations · `EmbeddedMesh.hpp`
- [Planar Map](https://github.com/textiles-lab/autoknit/blob/master/EmbeddedPlanarMap.hpp): embedding · Planar embedding structure used for surface reasoning · `EmbeddedPlanarMap.hpp`
- [Embed DAG](https://github.com/textiles-lab/autoknit/blob/master/embed_DAG.cpp): geometry graph · Directed acyclic structure for embedded surface relations · `embed_DAG.cpp`
- [Load Cons](https://github.com/textiles-lab/autoknit/blob/master/ak-load_constraints.cpp): constraint io · Reads saved user constraints from constraint files · `ak-load_constraints.cpp`
- [Embed Cons](https://github.com/textiles-lab/autoknit/blob/master/ak-embed_constraints.cpp): constraint mapping · Places constraints into the embedded mesh model · `ak-embed_constraints.cpp`

### Tracing Pipeline

Peeling, chain extraction, and stitch-path tracing over the mesh

- [Peel](https://github.com/textiles-lab/autoknit/blob/master/ak-peel_chains-libgeodesic.cpp): surface tracing · Surface peeling and sampling over the mesh · `ak-peel_chains-libgeodesic.cpp`
- [Trace Graph](https://github.com/textiles-lab/autoknit/blob/master/ak-trace_graph.cpp): stitch tracing · Builds traced stitch connectivity on the peeled surface · `ak-trace_graph.cpp`
- [Paths](https://github.com/textiles-lab/autoknit/blob/master/ak-embedded_path.cpp): path model · Represents stitched paths embedded on the surface · `ak-embedded_path.cpp`
- [Link Chains](https://github.com/textiles-lab/autoknit/blob/master/ak-link_chains.cpp): chain linking · Connects chain segments across rows and levels · `ak-link_chains.cpp`
- [Optimal Link](https://github.com/textiles-lab/autoknit/blob/master/ak-optimal_link.cpp): combinatorics · Chooses low-cost chain connections · `ak-optimal_link.cpp`

### Scheduling

Stitch assignment and transfer planning for knitting machines

- [Schedule](https://github.com/textiles-lab/autoknit/blob/master/schedule.cpp): optimizer · Headless stitch-to-machine scheduler · `schedule.cpp`
- [Cost Model](https://github.com/textiles-lab/autoknit/blob/master/ScheduleCost.cpp): optimization · Scores candidate machine layouts and schedules · `ScheduleCost.cpp`
- [Stitch](https://github.com/textiles-lab/autoknit/blob/master/Stitch.cpp): machine state · Stitch and needle/bed state used by the scheduler · `Stitch.cpp`
- [Transfers](https://github.com/textiles-lab/autoknit/blob/master/plan_transfers.cpp): transfer planner · Plans needle-bed transfers and bed movements · `plan_transfers.cpp`
- [Pipeline](https://github.com/textiles-lab/autoknit/blob/master/pipeline.hpp): orchestration · Shared pipeline glue between tracing and scheduling · `pipeline.hpp`

### Build & Runtime

Build tooling and JavaScript/Node handoff for knitout generation

- [Maekfile](https://github.com/textiles-lab/autoknit/blob/master/Maekfile.js): build system · Single-file build definition for the project · `Maekfile.js`
- [Node Runtime](https://github.com/textiles-lab/autoknit/tree/master/node_modules): js runtime · JavaScript helper runtime used to emit knitout · `node_modules`

## Connections

- Init → Interface: starts · Bootstraps the interactive application
- Interface → OBJ Loader: loads · Reads the mesh to display and edit
- Interface → Load Cons: opens · Loads saved constraint sets
- Interface → Embed Cons: edits · Places and updates constraints on the model
- OBJ Loader → Shape: builds · Creates the core shape representation
- Shape → Embedded Mesh: wraps · Feeds the embedded mesh model
- Embedded Mesh → Planar Map: derives · Builds planar reasoning structures
- Planar Map → Embed DAG: organizes · Forms directed embedding relations
- Embed Cons → Peel: seeds · Constraints guide tracing and peeling
- Peel → Trace Graph: produces · Converts peeled geometry into trace structure
- Trace Graph → Paths: materializes · Stores traced stitch paths on the surface
- Paths → Link Chains: segments · Breaks traced paths into chain connections
- Link Chains → Optimal Link: optimizes · Searches for better chain-to-chain links
- Optimal Link → Schedule: feeds · Provides chain structure to machine scheduling
- Schedule → Cost Model: scores · Evaluates schedule alternatives
- Schedule → Stitch: assigns · Maps traced stitches to machine state
- Schedule → Transfers: plans · Computes needle-bed transfers and shifts
- Transfers → Pipeline: integrates · Transfer planning is part of the overall pipeline
- Pipeline → Node Runtime: emits · Generates JavaScript that runs in Node with knitting helpers
- Maekfile → Interface: builds · Build tool compiles the native UI executable
- Maekfile → Schedule: builds · Build tool compiles the headless scheduler
- Node Runtime → Schedule: executes · Scheduled JavaScript is run to produce knitout output
