Package {weaveDraft}

weaveDraft: Structural Analysis of Woven Textile Drafts from WIF Files

Description

Tools to import weaving drafts stored in the WIF (Weaving Information File) interchange format, rebuild the binary warp/weft drawdown, and compute simple structural descriptors: float length distributions, interlacement frequency, repeat size, and thread colour sequences.

Details

A typical workflow is

d <- weave_draft_from_wif("my_draft.wif")
plot(d)
weave_metrics(d)

Main functions

read_wif, weave_draft_from_wif, compute_drawdown, compute_drawdown_liftplan, float_lengths, interlacement_frequency, weave_repeat, weave_metrics, color_runs, plot.weave_draft.

Author(s)

Maintainer: Mark Joshua R. Secretario markjoshuasecretario@gmail.com

Construct a weave_draft object

Description

Wraps a binary drawdown matrix (and optional colour information) in an object of class "weave_draft" that the analysis and plotting functions of this package accept.

Usage

as_weave_draft(drawdown, meta = list(), colors = NULL)

Arguments

Value

An object of class "weave_draft".

Examples

plain <- outer(1:4, 1:4, function(i, j) (i + j) %% 2)
draft <- as_weave_draft(plain, meta = list(name = "plain weave"))
draft

Check that a WIF's two encodings agree

Description

Many WIF files store both a liftplan and a tie-up/treadling pair. This rebuilds the drawdown from each and compares them, which is a useful data quality check before analysis.

Usage

check_wif_consistency(wif)

Arguments

Value

A list with comparable (FALSE if the file has only one encoding), consistent (TRUE/FALSE, or NA if not comparable), and n_mismatch_picks, the number of picks whose rows differ.

Examples

f <- system.file("extdata", "gingham_plain.wif", package = "weaveDraft")
check_wif_consistency(read_wif(f))

Colour runs along the warp or weft

Description

Many traditional patterns, including colour-and-weave designs on a plain weave structure, live in the thread colours rather than in the interlacement. This function summarises the colour sequence of the warp (or weft) as runs of identical colours.

Usage

color_runs(draft, direction = c("warp", "weft"))

Arguments

Value

A data frame with one row per run: start and end (thread numbers), length, hex (the colour), and index (its palette index when the colour is in the palette, else NA).

Examples

f <- system.file("extdata", "gingham_plain.wif", package = "weaveDraft")
color_runs(weave_draft_from_wif(f), "warp")

Compute a drawdown from threading, tie-up and treadling

Description

Reconstructs the binary warp/weft interlacement matrix of a treadle-loom draft. Warp end j is "up" (value 1, warp visible on the face) on pick i when at least one of the shafts it is threaded through is raised by a treadle pressed on that pick. Internally this is the matrix product of the treadling, tie-up and threading indicator matrices.

Usage

compute_drawdown(
  threading,
  treadling,
  tieup,
  n_shafts = NULL,
  rising_shed = TRUE
)

Arguments

Details

For a sinking-shed loom (rising_shed = FALSE) the listed shafts are the ones that sink, so the result is inverted.

Value

An integer matrix with one row per weft pick and one column per warp end; 1 means warp up (on the face), 0 means weft on the face.

Examples

# Plain weave: two shafts, two treadles
compute_drawdown(
  threading = rep(1:2, 4),
  treadling = rep(1:2, 4),
  tieup = list(1L, 2L)
)

Compute a drawdown from threading and a liftplan

Description

Same as compute_drawdown for dobby-style drafts, where each pick directly lists the shafts raised (no tie-up or treadles).

Usage

compute_drawdown_liftplan(
  threading,
  liftplan,
  n_shafts = NULL,
  rising_shed = TRUE
)

Arguments

Value

An integer matrix, rows = weft picks, columns = warp ends.

Examples

compute_drawdown_liftplan(
  threading = c(1, 2, 3, 4),
  liftplan = list(c(1, 2), c(2, 3), c(3, 4), c(4, 1))
)

Directional float ratio

Description

Mean warp float length divided by mean weft float length: a lightweight indicator of structural directionality. Values near 1 indicate a balanced structure; values far from 1 indicate warp- or weft-dominated floats. It describes the drawing only and is not a measured mechanical property.

Usage

directional_float_ratio(draft, side = c("face", "back", "both"))

Arguments

Value

A number, or NA if either mean float length is undefined.

Examples

f <- system.file("extdata", "diamond_liftplan.wif", package = "weaveDraft")
directional_float_ratio(weave_draft_from_wif(f))

Float length distributions

Description

Counts how many consecutive threads each thread passes over.

Usage

float_lengths(draft, side = c("face", "back", "both"))

Arguments

Details

A warp float is a run of consecutive picks over which one warp end stays up (a run of 1s down a column of the drawdown). A weft float is a run of consecutive warp ends over which one weft pick stays on the face (a run of 0s along a row). A length of 1 is a plain interlacement; longer floats give a looser, more lustrous, more snag-prone structure.

The side argument chooses which fabric side is described. On the "face" (default), warp floats are runs of 1s and weft floats are runs of 0s. On the "back" the roles of 0 and 1 swap. With "both" the runs of both values are pooled for each direction.

Floats are counted within the drawing only; no wrap-around is assumed at the edges.

Value

A list with integer vectors warp and weft, the float lengths pooled over all warp ends and all picks respectively.

Examples

f <- system.file("extdata", "twill_2_2.wif", package = "weaveDraft")
d <- weave_draft_from_wif(f)
table(float_lengths(d)$warp)

Mean and maximum float length

Description

Mean and maximum float length

Usage

mean_float_length(
  draft,
  direction = c("warp", "weft"),
  side = c("face", "back", "both")
)

max_float_length(
  draft,
  direction = c("warp", "weft"),
  side = c("face", "back", "both")
)

Arguments

Value

A single number, or NA if the draft has no floats of that kind (for example, no warp floats on the face of an all-zero drawdown).

Examples

f <- system.file("extdata", "twill_2_2.wif", package = "weaveDraft")
d <- weave_draft_from_wif(f)
mean_float_length(d, "warp")
max_float_length(d, "weft")

Interlacement frequency

Description

The fraction of adjacent cell pairs in which the drawdown changes between warp-up and weft-up. A plain weave interlaces at every opportunity (1); long-float structures such as satins score low. This is a common proxy for how tightly a fabric is bound.

Usage

interlacement_frequency(draft, direction = c("warp", "weft", "both"))

Arguments

Value

A number between 0 and 1, or NA if the draft is too small for the requested direction (fewer than 2 picks or ends).

Examples

f <- system.file("extdata", "gingham_plain.wif", package = "weaveDraft")
interlacement_frequency(weave_draft_from_wif(f), "both")

Plot a weave draft

Description

Draws either the binary drawdown (black = warp up) or, for drafts that carry colour information, a simulated fabric face (warp colour where the warp is up, weft colour elsewhere). The simulation is flat colour only; it ignores yarn thickness and thread spacing.

Usage

## S3 method for class 'weave_draft'
plot(
  x,
  type = c("drawdown", "fabric"),
  pick_origin = c("top", "bottom"),
  end_origin = c("left", "right"),
  main = NULL,
  ...
)

Arguments

Details

By default pick 1 is at the top and warp end 1 at the left. Weaving software often draws the drawdown with pick 1 at the bottom and/or end 1 at the right; use pick_origin and end_origin to match it. Axis labels always show the original pick and end numbers.

Value

x, invisibly.

Examples

f <- system.file("extdata", "gingham_plain.wif", package = "weaveDraft")
d <- weave_draft_from_wif(f)
plot(d)
plot(d, type = "fabric")

Read a WIF (Weaving Information File)

Description

Parses a ‘.wif’ file, the open, text-based, INI-style weaving interchange format written by WeavePoint, Fiberworks, ArahWeave and most other weaving software.

Usage

read_wif(path)

Arguments

Details

The reader extracts the sections needed to rebuild a drawdown: [WEAVING], [WARP], [WEFT], [THREADING], and either [LIFTPLAN] (dobby-style, one entry per pick listing the shafts raised) or [TIEUP] plus [TREADLING] (treadle-loom style). Files may contain both encodings; both are kept. If colour sections ([COLOR PALETTE], [COLOR TABLE], [WARP COLORS], [WEFT COLORS]) are present they are converted to hexadecimal colours. Unknown sections are ignored.

Section and key names are matched case-insensitively. Windows (CRLF) line endings and non-UTF-8 text in notes are tolerated. Full-line comments beginning with a semicolon or hash are ignored. Duplicate sections or keys and malformed integer indices are rejected. Missing thread entries are treated as inactive. Unusable colours fall back to neutral grey.

Value

An object of class "wif", a list with elements:

source_file

The path that was read.

shafts, treadles

Declared numbers of shafts and treadles (NA if not declared).

rising_shed

Logical; TRUE for a rising-shed loom.

n_warp, n_weft

Number of warp ends and weft picks.

threading

List with one integer vector per warp end: the shafts that end is threaded through.

liftplan

List with one integer vector per pick (shafts raised), or NULL if the file has no liftplan.

treadling

List with one integer vector per pick (treadles pressed), or NULL.

tieup

List whose element i holds the shafts raised by treadle i, or NULL.

has_liftplan, has_tieup

Logical flags for the two encodings.

colors

NULL, or a list with palette (data frame), warp and weft (hex colour per thread).

See Also

weave_draft_from_wif to go straight to a drawdown, check_wif_consistency to compare the two encodings.

Examples

f <- system.file("extdata", "twill_2_2.wif", package = "weaveDraft")
wif <- read_wif(f)
wif

Build a weave_draft from a WIF file

Description

Reads a WIF file (or takes an object from read_wif), reconstructs the drawdown and returns a weave_draft.

Usage

weave_draft_from_wif(
  x,
  style = c("auto", "liftplan", "tieup_treadling"),
  name = NULL
)

Arguments

Details

If the file contains both a liftplan and a tie-up/treadling pair, style = "auto" uses the liftplan, which states the sheds directly. Use check_wif_consistency to confirm the two encodings agree.

Value

A weave_draft object.

Examples

f <- system.file("extdata", "gingham_plain.wif", package = "weaveDraft")
draft <- weave_draft_from_wif(f)
draft

One-row summary of a draft's structural metrics

Description

Collects the main structural descriptors of a draft in a one-row data frame, convenient for comparing many drafts with rbind.

Usage

weave_metrics(draft, side = c("face", "back", "both"))

Arguments

Value

A one-row data frame with columns name, draft_style, shafts, picks, ends, repeat_picks, repeat_ends, mean_warp_float, mean_weft_float, max_warp_float, max_weft_float, interlace_warp, interlace_weft, interlace_both and float_ratio.

Examples

f <- system.file("extdata", "twill_2_2.wif", package = "weaveDraft")
weave_metrics(weave_draft_from_wif(f))

Detect the repeat of a drawdown

Description

Finds the smallest number of picks and of ends after which the drawdown repeats. A partial final repeat is allowed, but the repeat must fit at least min_repeats times, so a pattern that only matches itself over a tiny overlap is not reported as repeating.

Usage

weave_repeat(draft, min_repeats = 2)

Arguments

Value

A named integer vector with picks (repeat length down the rows, along warp threads) and ends (repeat length across the columns, along weft threads).

Examples

f <- system.file("extdata", "twill_2_2.wif", package = "weaveDraft")
weave_repeat(weave_draft_from_wif(f))