weavingspace.weave_matrices

  1"""Functions to generate the matrices associated with woven patterns.
  2
  3Such patterns when repeated across a map area give the appearance of a woven
  4surface composed of criss-crossing strands.
  5
  6Implementation is based on ideas discussed in variously
  7
  8Glassner A. 2002. Digital weaving. 1. IEEE Computer Graphics and Applications
  922(6):108-118.
 10Glassner A. 2003. Digital weaving. 2. IEEE Computer Graphics and Applications
 1123(1):77-90.
 12Glassner A. 2003. Digital weaving. 3. IEEE Computer Graphics and Applications
 1323(2):80-83.
 14
 15and (unpublished)
 16
 17+ Griswold, R. 2006. Mathematical and Computational Topics in Weaving
 18https://www2.cs.arizona.edu/patterns/weaving/webdocs/mo/Griswold-MO.pdf
 19(accessed 29/10/21).
 20
 21where weaving is shown to be a matrix multiplication of tie-up, threading and
 22treadling matrices. An accessible introduction can be found at
 23https://www.youtube.com/watch?v=oMOSiag3dxg
 24"""
 25
 26from __future__ import annotations
 27
 28import numpy as np
 29
 30
 31def reps_needed(x1:int, x2:int) -> tuple[int]:
 32  """Return number of sequences of length x1 and x2 are needed to match lengths.
 33
 34  Args:
 35    x1 (int): length of first sequence.
 36    x2 (int): length of second sequence.
 37
 38  Returns:
 39    tuple[int]: (number of repeats of x1, number of repeats of x2).
 40
 41  """
 42  n = np.lcm(x1, x2)
 43  return tuple(i for i in (n // x1, n // x2))
 44
 45
 46def get_pattern(
 47    tie_up:np.ndarray,
 48    treadling:np.ndarray,
 49    threading:np.ndarray,
 50    warp_n:int,
 51    weft_n:int,
 52    rep:int = 1,
 53  ) -> np.ndarray:
 54  """Return a 0/1 encoded weave matrix.
 55
 56  Given tie_up, treadling and threading matrices. The following conditions
 57  must be satisfied to avoid non-conformable matrix error:
 58
 59    treadling.shape[1] == tie_up.shape[0]
 60    tie_up.shape[1] == threading.shape[0]
 61
 62  The "twill", "basket" and "plain" options should guarantee this. If the
 63  warp_n and weft_n values are not factors of treadling.shape[0] and
 64  threading.shape[1] respectively, the output matrix will be repeated as needed
 65  to make this match
 66
 67  Args:
 68    tie_up (np.ndarray): the tie up matrix.
 69    treadling (np.ndarray): the treadling matrix.
 70    threading (np.ndarray): the threading matrix.
 71    warp_n (int): the number of uniquely labelled warp threads.
 72    weft_n (int): the number of uniquely labelled weft threads.
 73    rep (int, optional): optional additional repetition of the output
 74      applied in both directions. Defaults to 1.
 75
 76  Returns:
 77    np.ndarray: the matrix weave pattern generated by the supplied parameters.
 78
 79  """
 80  pattern = (treadling @ tie_up @ threading > 0) + 0
 81  rep_warp = reps_needed(warp_n, pattern.shape[1])
 82  rep_weft = reps_needed(weft_n, pattern.shape[0])
 83  return np.tile(pattern, (rep_weft[1] * rep, rep_warp[1] * rep))
 84
 85
 86# Note that as currently written this function requires the warp and weft
 87# matrices to be the same size, which get_weave_pattern_matrix will ensure,
 88# but which may not be the case if called from elsewhere
 89def _encode_biaxial_weave(
 90    pattern:np.ndarray,
 91    warp:np.ndarray,
 92    weft:np.ndarray,
 93  ) -> np.ndarray:
 94  """Encode a biaxial weave pattern as below.
 95
 96    1 - warp is absent
 97    2 - weft is absent
 98    3 - both threads are absent
 99    4 - weft is on top
100    5 - warp is on top
101
102  Args:
103    pattern (np.ndarray): pattern matrix with 1 where warp is on top,
104      0 where weft is on top.
105    warp (np.ndarray): warp matrix where -1 values indicate absent threads.
106    weft (np.ndarray): weft matrix where -1 values indicate absent threads.
107
108  Returns:
109    np.ndarray: matrix of values encoded as above.
110
111  """
112  pattern = np.where(pattern == 1, 5, pattern)           # warp on top
113  pattern = np.where(pattern == 0, 4, pattern)           # weft on top
114  pattern = np.where(warp < 0, 1, pattern)               # warp absent
115  pattern = np.where(weft < 0, 2, pattern)               # weft absent
116  return np.where((warp < 0) & (weft < 0), 3, pattern)   # both absent
117
118
119def make_plain_pattern(
120    warp_n:int = 1,
121    weft_n:int = 1,
122  ) -> np.ndarray:
123  """Return plain weave (checkerboard) matrix.
124
125  Args:
126    warp_n (int, optional): number of warp thread labels. Defaults to 1.
127    weft_n (int, optional): number of weft thread labels. Defaults to 1.
128
129  Returns:
130    np.ndarray: 0/1 matrix where 1 = warp on top.
131
132  """
133  return make_twill_pattern(n = 1, warp_n = warp_n, weft_n = weft_n)
134
135
136def make_twill_pattern(
137    n:int|tuple[int] = 2,
138    warp_n:int = 2,
139    weft_n:int = 2,
140  ) -> np.ndarray:
141  """Return twill pattern matrix extended for warp and weft patterns.
142
143  n is the number of over-unders. With n = 1 we get a plain weave.
144
145  Args:
146    n (int|tuple[int], optional): specifies over-under sequence in
147      the weave. Defaults to 2.
148    warp_n (int, optional): number of warp thread labels. Defaults to 2.
149    weft_n (int, optional): number of weft thread labels. Defaults to 2.
150
151  Returns:
152    np.ndarray: _description_
153
154  """
155  tie_up = make_twill_matrix(n)
156  threading = np.diag(np.ones(tie_up.shape[0]))
157  treadling = np.diag(np.ones(tie_up.shape[1]))
158  return get_pattern(tie_up, treadling, threading, warp_n, weft_n)
159
160
161def make_over_under_row(n:int|tuple[int]) -> list[int]:
162  """Return a tuple of runs of 1s and 0s.
163
164  Returns a tuple of runs of 1s and 0s per supplied n.
165
166  If n is an integer, returned tuple will be a series of n 1s followed by
167  n 0s.
168
169  If n is a tuple of odd length it will be repeated to produce an even
170  length over-under sequence. This is required to avoid cases such as
171  e.g, (1,2,3) -> 100111 which repeated is 1001111001111, i.e. a (2,4)
172  pattern. Repeating it yields 100111011000 which is the requested pattern.
173
174  Args:
175    n (int|tuple[int]): requested over-under sequence. See details.
176
177  Returns:
178    list[int]: list of runs of 1s and 0s in the requested pattern.
179
180  """
181  over_under = n
182  if isinstance(over_under, int):
183    over_under = [n, n]
184  elif len(n) % 2 != 0:
185    over_under = n * 2
186  x = 1
187  row = []
188  for y in over_under:
189    row.extend([x] * y)
190    x = 1 - x
191  return row
192
193
194def wrap_row(
195    r:list,
196    by:int = 1,
197  ) -> list:
198  """Wrap the list r by number of positions.
199
200  Positive by will shift right.
201  Negative shifts left.
202
203  Args:
204    r (list): list to wrap.
205    by (int, optional): number of positions to shift by. Defaults to 1.
206
207  Returns:
208    list: wrapped list.
209
210  """
211  return r[-by:] + r[:-by]
212
213
214def make_twill_matrix(over_under:int|tuple[int]) -> np.ndarray:
215  """Make a twill 0/1 matrix.
216
217  Makes a matrix like
218
219    1 1 0 0
220    0 1 1 0
221    0 0 1 1
222    1 0 0 1
223
224  where the repeat runs in each row are lengths returned by
225  make_over_under_rown(n)
226
227  Args:
228    over_under (int|tuple[int]): over-under run specification. See
229      make_over_under_row().
230
231  Returns:
232    np.ndarray: a matrix of 0s and 1s.
233
234  """
235  row = make_over_under_row(over_under)
236  d = len(row)
237  out = []
238  for i in range(d):
239    row = wrap_row(row, 1)
240    out.extend(row)
241  return np.array(out).reshape(d, d)
242
243
244def make_basket_pattern(
245    n:int = 2,
246    warp_n:int = 2,
247    weft_n:int = 2,
248  ) -> np.ndarray:
249  """Return basket pattern matrix extended for warp and weft patterns.
250
251  Args:
252    n (int, optional): over under count. Defaults to 2.
253    warp_n (int, optional): number of warp thread labels. Defaults to 2.
254    weft_n (int, optional): number of weft thread labels. Defaults to 2.
255
256  Returns:
257    np.ndarray: _description
258
259  """
260  tie_up = make_basket_matrix(n)
261  threading = np.diag(np.ones(tie_up.shape[0]))
262  treadling = np.diag(np.ones(tie_up.shape[1]))
263  return get_pattern(tie_up, treadling, threading, warp_n, weft_n)
264
265
266def make_basket_matrix(n:int) -> np.ndarray:
267  """Return a basket weave pattern matrix.
268
269  Makes a matrix like
270
271    1 1 0 0
272    1 1 0 0
273    0 0 1 1
274    0 0 1 1
275
276  where the repeat runs in each row are length n
277
278  Args:
279    n (int): dimension of the 'basket' over-under pattern.
280
281  Returns:
282    np.ndarray: 0/1 matrix in basket weave pattern.
283
284  """
285  return np.array((([1] * n + [0] * n) * n) +
286          (([0] * n + [1] * n) * n)).reshape(n * 2, n * 2)
287
288
289def make_this_pattern(
290    tie_up:np.ndarray,
291    threading:np.ndarray = None,
292    treadling:np.ndarray = None,
293    warp_n:int = 1,
294    weft_n:int = 1,
295  ) -> np.ndarray:
296  """Pass through returns weave pattern matrix from supplied input.
297
298  This is just a pass through function which applies suitable size identity.
299  Could try to enforce
300
301    treadling.shape[1] == tie_up.shape[0] and
302    tie_up.shape[1] == threading.shape[0]
303
304  but unsure what would be an appropriate way to do this...
305
306  Args:
307    tie_up (np.ndarray): desired weave pattern.
308    threading (np.ndarray): desired threading pattern.
309    treadling (np.ndarray): desired treadling pattern.
310    warp_n (int, optional): number of warp thread labels. Defaults to 1.
311    weft_n (int, optional): number of weft thread labels. Defaults to 1.
312
313  Returns:
314    np.ndarray: resulting 0/1 weave pattern matrix.
315
316  """
317  threading = (np.diag(np.ones(tie_up.shape[0]))
318               if threading is None
319               else threading)
320  treadling = (np.diag(np.ones(tie_up.shape[1]))
321               if treadling is None
322               else treadling)
323  return get_pattern(tie_up, treadling, threading, warp_n, weft_n)
324
325
326def get_weave_pattern_matrix(
327    weave_type:str = "plain",
328    n:int|tuple[int] = 2,
329    warp:list[str]|tuple[str] = ("a", "b"),
330    weft:list[str]|tuple[str] = ("c", "d"),
331    tie_up:np.ndarray = None,
332    tr:np.ndarray = None,
333    th:np.ndarray = None,
334  ) -> np.ndarray:
335  """Return encoded weave pattern matrix.
336
337  See `_encode_biaxial_weave()` for the encoding.
338
339  Allowed weave_types: "plain", "twill", "basket", and "this" (pass-thru).
340  These are explained in the respective functions to which this function
341  delegates construction of the base matrices before applying the encoding.
342
343  Args:
344    weave_type (str, optional): one of "plain", "twill", "basket" or
345      "this". Defaults to "plain".
346    n (int|tuple[int], optional): over under pattern. See
347      make_over_under_row() for details. Defaults to 2.
348    warp (list[str]|tuple[str], optional): list of labels for warp
349      strands. Defaults to ["a", "b"].
350    weft (list[str]|tuple[str], optional): list of labels for weft
351      strands. Defaults to ["c", "d"].
352    tie_up (np.ndarray, optional): a weave pattern matrix to pass thru in
353      the "this" case. Defaults to make_twill_matrix((2, 2)).
354    tr (np.ndarray, optional): treadling matrix for the "this" case.
355      Defaults to None.
356    th (np.ndarray, optional): threading matrix for the "this" case.
357      Defaults to None.
358
359  Returns:
360    np.ndarray: encoded weave pattern matrix.
361
362  """
363  warps = [-1 if c == "-" else i for i, c in enumerate(warp)]
364  wefts = [-1 if c == "-" else i for i, c in enumerate(weft)]
365  width = len(warp)
366  height = len(weft)
367
368  if weave_type == "plain":
369    p = make_plain_pattern(warp_n = width, weft_n = height)
370  elif weave_type == "twill":
371    p = make_twill_pattern(n = n, warp_n = width, weft_n = height)
372  elif weave_type == "basket":
373    p = make_basket_pattern(n = n, warp_n = width, weft_n = height)
374  else:
375    p = make_this_pattern(tie_up = tie_up, threading = th, treadling = tr,
376                warp_n = width, weft_n = height)
377  nr, nc = p.shape
378  warp_threads = np.array(warps *
379      reps_needed(nc, len(warps))[1] * nr).reshape((nr, nc))
380  weft_threads = np.array(wefts *
381      reps_needed(nr, len(wefts))[1] * nc).reshape((nc, nr)).transpose()
382  # encode to reflect missing threads
383  return _encode_biaxial_weave(p, warp_threads, weft_threads)