> For the complete documentation index, see [llms.txt](https://docs.tempoweave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tempoweave.com/help-by-menu-tabs/design-menu/block-substitution.md).

# Block Substitution

### What It Does

Block Substitution takes a simple profile draft and expands it into a full weave structure by applying a weave template. Your profile draft defines the block layout — which blocks are active where — and the template defines how each block is actually woven (the specific interlacement, tie-down threads, and shaft assignments within each block).

This is how weavers traditionally work with block weaves: you design the pattern at the block level (simple, fast), then substitute in the actual weave structure (Huck, Overshot, Summer and Winter, etc.) to produce the full threading, tie-up, and treadling needed at the loom.

***

### Location

* **Ribbon**: Design tab > Section Assembly group > Block Substitution button (toggle)

The Block Substitution panel opens as a dockable tool window.

***

### The Panel

#### Template List

The upper portion shows all available weave templates in a list with columns:

* **Name** — Template name (e.g., "Spot Bronson," "Summer & Winter 4-Block")
* **Type** — Weave category (Huck, Overshot, Summer and Winter, etc.)
* **Shafts** — Number of shafts in the template pattern
* **Treadles** — Number of treadles per block

Click a template to select it and see its details in the info panel below.

#### Template Management

**Add** — Create a new template entry. Opens the template editor.

**Edit** — Modify the selected template's settings. The editor also offers two buttons next to the **File Name** field:

* **`…` Browse** — Pick a `.wif` from anywhere on disk; the file is copied into the templates folder for you.
* **`✎` Edit Template WIF** — Open the selected template's `.wif` in a new editor tab so you can change threading / treadling / tieup directly. Saving in that tab writes back to the templates folder, so the next Apply picks up the edits automatically. Especially useful on macOS where the `_blocktemplates` folder lives inside the invisible `~/Library` directory.
* **`↺` Reset to Bundled** — Restore a bundled template's `.wif` (and matching PNG preview) from the version that shipped with the app. Auto-hidden for user-added templates that have no bundled source.

**Delete** — Remove the selected template from the library.

**Reveal Folder** — Open the per-platform templates folder in Finder / Explorer / your file manager. Drop additional `.wif` files in directly if you prefer to work outside the dialog.

#### Info Panel

The lower portion shows details about the selected template:

* **Template Name** — Bold, full display
* **Type** — The weave family
* **Stats**:
  * Shafts (in the template)
  * Treadles per Block
  * Tie Shafts (warp tie-down thread count)
  * Tie Treadles (weft tie treadle count)
* **Special Properties** (when applicable):
  * Huck Style (Type A, B, C, or D)
  * Has Weft Background
  * Tie-up Pattern Reverse
  * Pattern Warp Wrap
  * Pattern Step value
* **Preview Image** — A small visual showing what the template's weave pattern looks like

#### Apply Button

Generates the expanded draft from the selected template applied to your profile.

***

### How It Works

#### What You Need: A Profile Draft

A profile draft is a simplified block representation of your design. Each shaft represents a "block" and each treadle represents a block activation. For example, a 2-block profile draft has 2 shafts and 2 treadles, with a simple tie-up showing which blocks are active.

The profile defines *where* each block appears in the design — the template defines *how* each block is woven.

The profile can be either a **tie-up draft** or a **liftplan draft**:

* **Tie-up profiles** — Each pick presses a treadle, and the tie-up says which blocks that treadle activates. Picks that press more than one treadle activate all of their blocks at once.
* **Liftplan profiles** — Each shaft is a block, and each pick simply lifts the block(s) it activates. A pick lifting shafts 1 and 3 weaves pattern in blocks A and C together. Liftplan profiles produce a **liftplan result**: the generated draft comes out as a liftplan too, ready for dobby looms, with each pick lifting the combined shafts of its expanded structure.

#### The Substitution Process

When you click **Apply**, the generator:

1. **Reads your profile draft** — Identifies the block layout from your threading and treadling + tie-up (or liftplan)
2. **Reads the template** — Loads the template's weave structure, including its threading pattern, treadling, and tie-up
3. **Builds shaft and treadle maps** — Determines how the template's shafts and treadles are distributed across your profile blocks:
   * **Tie shafts/treadles** are shared across all blocks (they provide the ground structure)
   * **Pattern shafts/treadles** are multiplied per block (each block gets its own set)
4. **Expands the threading** — Each profile thread is expanded into the template's threading pattern, mapped to the correct shaft group for that block
5. **Builds the tie-up** — The template's tie-up is expanded across all block combinations, with special handling for Huck variants, weft backgrounds, and other template-specific rules
6. **Expands the treadling** — Each profile pick is expanded into the template's treadling pattern, mapped to the correct treadle group
7. **Creates the output** — A new WIF file with the complete expanded structure

#### Template Types

Different template types have different substitution rules:

**Bronson / Bateman** — Spot-pattern weaves where a base of plain weave alternates with isolated pattern floats.

**Crackle** — A 4-shaft block weave with a broken-twill texture that gives the weave its name.

**Huck** — Lace-producing templates with tie shafts and pattern shafts. Four variants (A, B, C, D) control whether blocks produce lace openings, warp floats, weft floats, or opposite-parity lace.

**Overshot** — Traditional American block weave with pattern floats over a plain weave ground. Uses stepping patterns and block sequences.

**Summer and Winter / 3 Tie / 4 Tie / Double Two Tie** — Tie-unit weaves with independent pattern blocks. Produce reversible fabric; the number of tie shafts in the name corresponds to the per-block tie count.

**Diversified Plain** — A multi-block weave alternating fine and coarse threads to produce distinct color blocks against a plain-weave ground.

**Double Weave** — Two interleaved cloths joined at block boundaries.

**Custom** — User-defined templates that follow the general shaft/treadle mapping rules.

***

### The Template Editor

When adding or editing a template:

**Name** — A descriptive name for the template.

**File Name** — The WIF file containing the template's weave structure. Click **Browse** to select a file.

**Type** — The weave family (Huck, Overshot, Summer and Winter, Double Weave, Custom, etc.).

**Template Shafts** — Total shafts in the template pattern.

**Block Treadles** — Treadles per block in the pattern.

**Warp Tie Count** — Number of tie-down shaft rows.

**Weft Tie Treadles** — Number of tie treadles.

**Pattern Warp Step** — For overshot patterns, the step value for progressive shaft assignment.

**Weft Background** — The template has a separate background pattern for non-active blocks.

**Tie-up Pattern Reverse** — Inverts the block selection logic in the tie-up.

**Pattern Warp Wrap** — Wraps pattern shafts when they exceed the maximum, preventing shaft overflow.

**Huck Style** — Enables special Huck lace handling. Choose variant A, B, C, or D.

***

### How to Use It

1. **Create a profile draft** — Set up a simple block design:
   * Thread with shaft numbers representing blocks (shaft 1 = block A, shaft 2 = block B, etc.)
   * Treadle with treadle numbers representing block activations
   * Set up a tie-up showing which blocks are active for each treadle
   * Or, in a liftplan draft, just lift each pick's block shaft(s) — no tie-up needed
2. Open **Block Substitution** from the Design tab
3. **Browse the template library** — Click templates to see their details and preview
4. **Select a template** that matches the weave you want
5. Click **Apply**
6. The generated draft opens as a preview — review the expanded threading, tie-up, and treadling
7. Save the generated draft if satisfied

***

### Step-by-Step Example: Huck Lace from a Profile

You have a 3-block profile draft for a lace scarf and want to apply a Huck lace template:

1. Your profile has 3 shafts (3 blocks), 3 treadles, and a simple tie-up
2. Open **Block Substitution**
3. Select a Huck template (e.g., "Huck Lace 8-Shaft, Type A")
4. The info panel shows: 8 shafts, 4 treadles per block, 2 tie shafts, Huck Style Type A
5. Click **Apply**
6. The generator creates a full draft with:
   * Threading: tie-down threads + pattern threads for each of the 3 blocks
   * Tie-up: Huck lace connections for all block combinations
   * Treadling: expanded treadle sequence
7. Review and save

### Step-by-Step Example: Overshot from a Simple Profile

You have a 4-block profile and want traditional overshot:

1. Thread your profile: 4 shafts representing 4 blocks
2. Design a simple treadling sequence in the profile
3. Open **Block Substitution**, select an Overshot template
4. Apply — the generator expands each profile block into the overshot threading pattern with tabby ties and pattern treadles
5. The result is a complete overshot draft ready for the loom

***

### Tips

* **Profile drafts are simple** — Keep your profile draft minimal: one shaft per block, one treadle per block activation. The template handles all the complexity.
* **Preview before saving** — Generated drafts open as unsaved previews. Review the structure before committing.
* **Try different templates** — Apply different templates to the same profile to compare how the same block layout looks in Huck vs. Overshot vs. Summer and Winter.
* **Huck variants matter** — The four Huck types (A, B, C, D) produce very different fabrics from the same profile. Type A gives lace, Type B gives warp floats, Type C gives weft floats, Type D gives opposite-parity lace.
* **Check shaft limits** — Block substitution can produce drafts with many shafts (blocks × pattern shafts + tie shafts). Make sure the result fits your loom. The maximum is 128 shafts.
* **Custom templates** — You can create your own templates by designing a weave structure in a WIF file and adding it to the template library with the appropriate settings.
* **Template files** — Templates are stored as WIF files in the templates folder. The template library catalog is saved automatically.

***

### Going Deeper: Authoring Templates

To **edit** the bundled templates, or **author** new ones for the Complex Weavers community (or your own block-substitution library), see the companion Block Substitution Authoring Guide. It covers:

* Where the templates live on each operating system
* The anatomy of a template WIF, including the `*WarpPattern` / `*TieShafts` section markers
* What each flag in the editor (Block Treadles, Warp Tie Count, Pattern Warp Step, Pattern Warp Wrap, Weft Background, Tie-up Pattern Reverse, Huck Style) actually does to the output
* Step-by-step walkthroughs for editing a bundled template and building a new one from scratch
* The new **Edit Template WIF** (`✎`) and **Reset to Bundled** (`↺`) buttons in the Edit Templates dialog
* A troubleshooting playbook for the common authoring mistakes

***

### Quick Reference

| Action          | How                                      |
| --------------- | ---------------------------------------- |
| Open panel      | Design tab > Block Substitution (toggle) |
| Select template | Click in template list                   |
| View details    | See info panel below list                |
| Apply template  | Click Apply button                       |
| Add template    | Click Add, configure in editor           |
| Edit template   | Select + click Edit                      |
| Delete template | Select + click Delete                    |

| Profile Draft            | Block Substitution Output                    |
| ------------------------ | -------------------------------------------- |
| 1 shaft per block        | Multiple shafts per block + tie shafts       |
| 1 treadle per activation | Multiple treadles per block + tie treadles   |
| Simple tie-up            | Full expanded tie-up with block interactions |
| N threads                | N × template pattern width threads           |

| Template Type     | Characteristic                         |
| ----------------- | -------------------------------------- |
| Huck              | Lace with tie-down threads, 4 variants |
| Overshot          | Pattern floats over plain weave ground |
| Summer and Winter | Reversible, independent blocks         |
| Custom            | User-defined substitution rules        |

Start with a Profile Draft to use Block Substitution: 

{% embed url="<https://vimeo.com/1202475470>" %}
Creating a Simple Profile Draft
{% endembed %}

*more videos in process... will be available soon.*