weavingspace.weave_matrices

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