How textiles-lab/autoknit works
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 Schedule · Interface.cpp Interface · Maekfile.js Maekfile · load_obj.cpp OBJ Loader
Components 21
User Interface
Interactive application for loading models and authoring constraints
Geometry Model
Mesh, embedding, and constraint representation on the surface
- OBJ Loader · Loads triangle meshes from OBJ files
load_obj.cpp - Shape · Core shape and surface geometry abstraction
Shape.hpp - Embedded Mesh · Mesh representation embedded for stitching operations
EmbeddedMesh.hpp - Planar Map · Planar embedding structure used for surface reasoning
EmbeddedPlanarMap.hpp - Embed DAG · Directed acyclic structure for embedded surface relations
embed_DAG.cpp - Load Cons · Reads saved user constraints from constraint files
ak-load_constraints.cpp - Embed Cons · Places constraints into the embedded mesh model
ak-embed_constraints.cpp
Tracing Pipeline
Peeling, chain extraction, and stitch-path tracing over the mesh
- Peel · Surface peeling and sampling over the mesh
ak-peel_chains-libgeodesic.cpp - Trace Graph · Builds traced stitch connectivity on the peeled surface
ak-trace_graph.cpp - Paths · Represents stitched paths embedded on the surface
ak-embedded_path.cpp - Link Chains · Connects chain segments across rows and levels
ak-link_chains.cpp - Optimal Link · Chooses low-cost chain connections
ak-optimal_link.cpp
Scheduling
Stitch assignment and transfer planning for knitting machines
- Schedule · Headless stitch-to-machine scheduler
schedule.cpp - Cost Model · Scores candidate machine layouts and schedules
ScheduleCost.cpp - Stitch · Stitch and needle/bed state used by the scheduler
Stitch.cpp - Transfers · Plans needle-bed transfers and bed movements
plan_transfers.cpp - Pipeline · Shared pipeline glue between tracing and scheduling
pipeline.hpp
Build & Runtime
Build tooling and JavaScript/Node handoff for knitout generation
- Maekfile · Single-file build definition for the project
Maekfile.js - Node Runtime · JavaScript helper runtime used to emit knitout
node_modules
Connections 22
- 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