---
title: "Getting started with weaveDraft"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with weaveDraft}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 5,
                      fig.height = 5)
library(weaveDraft)
```

## What a WIF file holds

Weaving software saves a draft as a WIF text file. It lists which shaft each
warp end passes through (the *threading*) and which shafts rise on each weft
pick, either directly (a *liftplan*) or through treadles (a *tie-up* plus a
*treadling*). From these, `weaveDraft` rebuilds the **drawdown**: a binary
matrix with one row per pick and one column per warp end, where 1 means the
warp end is up on the fabric face.

## Load a draft

```{r load}
f <- system.file("extdata", "twill_2_2.wif", package = "weaveDraft")
twill <- weave_draft_from_wif(f)
twill
plot(twill)
```

## Structural descriptors

```{r metrics}
weave_metrics(twill)
```

* `mean_warp_float` / `mean_weft_float`: average number of threads a thread
  passes over before interlacing (1 = plain interlacement).
* `interlace_*`: how often the drawdown changes state; 1 for a plain weave.
* `repeat_picks` / `repeat_ends`: size of the smallest repeating unit.

## Structure versus colour

Some patterns live entirely in the thread colours. The bundled `gingham`
draft is a plain weave, structurally the simplest cloth possible, yet it shows
a clear check pattern.

```{r gingham}
g <- weave_draft_from_wif(system.file("extdata", "gingham_plain.wif",
                                      package = "weaveDraft"))
weave_metrics(g)[, c("interlace_both", "mean_warp_float", "repeat_picks")]
plot(g)                    # the structure: a plain weave
plot(g, type = "fabric")   # the structure seen through its colours
color_runs(g, "warp")
```

Structural metrics alone describe the first picture; colour sequences
describe the second. For colour-and-weave textiles, report both.

## Two encodings, one check

Many files store both a liftplan and a tie-up with treadling.
`check_wif_consistency()` rebuilds the drawdown from each and compares them:

```{r consistency}
check_wif_consistency(read_wif(system.file("extdata", "gingham_plain.wif",
                                           package = "weaveDraft")))
```

## Your own drawdown

Any 0/1 matrix can be analysed:

```{r own}
satin <- outer(0:9, 0:9, function(i, j) as.integer((j - 2 * i) %% 5 == 0))
s <- as_weave_draft(satin, meta = list(name = "5-end satin"))
weave_metrics(s)[, c("mean_warp_float", "mean_weft_float", "interlace_both")]
```