weavingspace.weave_unit

  1"""The `WeaveUnit` subclass of `weavingspace.tileable.Tileable`.
  2
  3Implements tileable geometric patterns constructed by specifying 2- and 3-axial
  4weaves.
  5
  6Examples:
  7  Explain usage here...
  8
  9"""
 10
 11from __future__ import annotations
 12
 13import itertools
 14import logging
 15from dataclasses import dataclass
 16from typing import TYPE_CHECKING
 17
 18import geopandas as gpd
 19import numpy as np
 20import pandas as pd
 21import shapely.affinity as affine
 22import shapely.geometry as geom
 23import shapely.ops
 24
 25from weavingspace import (
 26  Loom,
 27  Tileable,
 28  TileShape,
 29  WeaveGrid,
 30  tiling_utils,
 31  weave_matrices,
 32)
 33
 34if TYPE_CHECKING:
 35  from collections.abc import Iterable
 36
 37
 38@dataclass
 39class WeaveUnit(Tileable):
 40  """Extend Tileable to allow for tiles that appear like woven patterns."""
 41
 42  weave_type:str = "plain"
 43  """type of weave pattern, one of `plain`, `twill`, `basket`, `cube`, `hex` or
 44  `this`. Defaults to `plain`."""
 45  aspect:float = 1.
 46  """width of strands relative to the `spacing`. Defaults to 1.0."""
 47  n:int|tuple[int] = (2, 2)
 48  """number of over-under strands in biaxial weaves. Only one item is
 49  required in a plain weave. Twill and basket patterns expect an even number of
 50  entries in the tuple."""
 51  strands:str = "a|b|c"
 52  """specification of the strand labels along each axis. Defaults to `a|b|c`."""
 53  _tie_up:np.ndarray = None
 54  """optional tie-up array to pass through for `this` weave type."""
 55  _tr:np.ndarray = None
 56  """optional treadling array to pass through for `this` weave type."""
 57  _th:np.ndarray = None
 58  """optional threading array to pass through for `this` weave type."""
 59
 60  def __init__(self, **kwargs:float|str) -> None:
 61    super().__init__(**kwargs)
 62
 63
 64  def _setup_tiles(self) -> None:
 65    """Set up weave unit."""
 66    if self.weave_type in ("hex", "cube"):
 67      self.base_shape = TileShape.HEXAGON
 68      self._setup_triaxial_weave_unit()
 69    else:
 70      self.base_shape = TileShape.RECTANGLE
 71      self._setup_biaxial_weave_unit()
 72
 73
 74  def _setup_regularised_prototile(self) -> None:
 75    """Set up regularised prototile fully containing all tile elements.
 76
 77    The work is carried out by the two methods  that follow _regularise_tiles()
 78    and _merge_fragments().
 79    """
 80    self._regularise_tiles()
 81    # it's prudent to do some cleanup given all the manipulation of geometries
 82    # carried out to generate the regularised prototile. But note that the
 83    # regularised prototile has no functional purpose, so it's OK if it has,
 84    # for example, additional points along line segments.
 85    self.regularised_prototile.geometry = tiling_utils.repair_polygon(
 86      self.regularised_prototile.geometry)
 87
 88
 89  def _setup_biaxial_weave_unit(self) -> None:
 90    """Set up weave tiles GeoDataFrame and tile GeoDataFrame."""
 91    warp_threads, weft_threads, _ = \
 92      tiling_utils.get_strand_ids(self.strands)
 93    if self.weave_type == "basket" and isinstance(self.n, (list, tuple)):
 94      self.n = self.n[0]
 95    p = weave_matrices.get_weave_pattern_matrix(
 96      weave_type = self.weave_type, n = self.n, warp = warp_threads,
 97      weft = weft_threads, tie_up = self._tie_up, tr = self._tr,
 98      th = self._th)
 99    self._make_shapes_from_coded_weave_matrix(
100      Loom(p), strand_labels = [weft_threads, warp_threads, []])
101    bb = self.tiles.total_bounds
102    w = (bb[2] - bb[0]) // self.spacing * self.spacing
103    h = (bb[3] - bb[1]) // self.spacing * self.spacing
104    self.setup_vectors((0, h), (w, 0))
105
106
107  def _get_triaxial_weave_matrices(self,
108      strands_1:list[str]|tuple[str] = ("a",),
109      strands_2:list[str]|tuple[str] = ("b",),
110      strands_3:list[str]|tuple[str] = ("c",),
111    ) -> Loom:
112    """Return encoded weave pattern matrix as Loom of three biaxial matrices.
113
114    Allowed weave_types: "cube" or "hex".
115
116    "hex" is not flexible and will fail with any strand label lists that are
117    not length 3 or include more than one non-blank "-" item. You can
118    generate the "hex" weave with the default settings in any case!
119
120    Strand lists should be length 3 or length 1. "cube" tolerates more
121    than "hex" for the items in the strand lists.
122
123    Defaults will produce 'mad weave'.
124
125    Args:
126      strands_1 (list[str]|tuple[str], optional): list of labels
127      for warp strands. Defaults to ["a"].
128      strands_2 (list[str]|tuple[str], optional): list of labels
129      for weft strands. Defaults to ["b"].
130      strands_3 (list[str]|tuple[str], optional): list of labels
131      for weft strands. Defaults to ["c"].
132
133    Returns:
134      Loom: which combines the three biaxial weaves 12, 23 and 31 implied
135      by the strand label lists.
136
137    """
138    if self.weave_type == "hex":
139      loom = Loom(
140        weave_matrices.get_weave_pattern_matrix(
141          weave_type = "this", tie_up = np.ones((6, 6)),
142          warp = strands_1, weft = strands_2),
143        weave_matrices.get_weave_pattern_matrix(
144          weave_type = "this", tie_up = np.ones((6, 6)),
145          warp = strands_2, weft = strands_3),
146        weave_matrices.get_weave_pattern_matrix(
147          weave_type = "this", tie_up = np.ones((6, 6)),
148          warp = strands_3, weft = strands_1))
149    else: # "cube"
150      loom = Loom(
151      # Note n = (1,2,1,2) is required here to force 6x6 twill
152        weave_matrices.get_weave_pattern_matrix(
153          weave_type = "twill", n = (1, 2, 1, 2),
154          warp = strands_1, weft = strands_2),
155        weave_matrices.get_weave_pattern_matrix(
156          weave_type = "twill", n = (1, 2, 1, 2),
157          warp = strands_2, weft = strands_3),
158        weave_matrices.get_weave_pattern_matrix(
159          weave_type = "twill", n = (1, 2, 1, 2),
160          warp = strands_3, weft = strands_1))
161    return loom
162
163
164  def _setup_triaxial_weave_unit(self) -> None:
165    """Return weave tiles GeoDataFrame and tile GeoDataFrame."""
166    strands_1, strands_2, strands_3 = \
167      tiling_utils.get_strand_ids(self.strands)
168    loom = self._get_triaxial_weave_matrices(
169      strands_1 = strands_1, strands_2 = strands_2, strands_3 = strands_3)
170    self._make_shapes_from_coded_weave_matrix(
171      loom, strand_labels = [strands_1, strands_2, strands_3])
172    self.setup_vectors((0, 6 * self.spacing),
173                       (3 * self.spacing * np.sqrt(3),  3 * self.spacing),
174                       (3 * self.spacing * np.sqrt(3), -3 * self.spacing))
175
176
177  def _make_shapes_from_coded_weave_matrix(
178      self,
179      loom:Loom, strand_labels:list[list[str]] = (["a"], ["b"], ["c"]),
180    ) -> None:
181    """Set up weave tiles and prototile GeoDataFrames in a dictionary.
182
183    Builds the geometries associated with a given weave supplied as
184    'loom' containing the coordinates in an appropriate grid (Cartesian or
185    triangular) and the orderings of the strands at each coordinate location
186
187    Args:
188      loom (Loom): matrix or stack of matrices representing the weave
189      pattern.
190      strand_labels (list[list[str]], optional): list of lists of labels
191      for strands in each direction. Defaults to [["a"], ["b"], ["c"]]
192
193    """
194    grid = WeaveGrid(loom.n_axes, loom.orientations, self.spacing)
195    # expand the list of strand labels if needed in each direction
196    labels = [thread * int(np.ceil(dim // len(thread)))
197              for dim, thread in zip(loom.dimensions, strand_labels,
198                                     strict = False)]
199    weave_polys = []
200    strand_ids = []
201    cells = []
202    for k, strand_order in zip(loom.indices, loom.orderings, strict = True):
203      IDs = [thread[coord] for coord, thread in zip(k, labels, strict = True)]
204      cells.append(grid.get_grid_cell_at(k))
205      if strand_order is None:
206        continue  # No strands present
207      if strand_order == "NA":
208        continue  # Inconsistency in layer order
209      n_slices = [len(ID) for ID in IDs]
210      next_polys = grid.get_visible_cell_strands(
211        width = self.aspect, coords = k,
212        strand_order = strand_order, n_slices = n_slices)
213      weave_polys.extend(next_polys)
214      next_labels = [list(IDs[i]) for i in strand_order]  # list of lists
215      next_labels = list(itertools.chain(*next_labels))   # flatten
216      strand_ids.extend(next_labels)
217    # sometimes empty polygons make it to here, so
218    # filter those out along with the associated IDs
219    real_polys = [not p.is_empty for p in weave_polys]
220    weave_polys = [
221      p for p, b in zip(weave_polys, real_polys, strict = True) if b]
222    strand_ids = [
223      ID for ID, b in zip(strand_ids, real_polys, strict = True) if b]
224    # note that the tile is important for the biaxial case, which makes it
225    # a little hard to understand why the behaviour is so different in
226    # the biaxial and triaxial cases; however below seems to work...
227    if loom.n_axes == 3:
228      tile = grid.get_tile_from_cells(cells)
229      shift = (0, 0)
230    else:
231      tile = tiling_utils.safe_union(gpd.GeoSeries(cells), as_polygon = True)
232      shift = (-tile.centroid.x, -tile.centroid.y)
233      tile = grid.get_tile_from_cells(tile)
234    self.tiles = self._get_weave_tiles_gdf(weave_polys, strand_ids, shift)
235    self.prototile = gpd.GeoDataFrame(
236      geometry = gpd.GeoSeries([tile]), crs = self.crs)
237
238
239  def _get_weave_tiles_gdf(
240      self, polys:list[geom.Polygon], strand_ids:list[str],
241      offset:tuple[float]) -> gpd.GeoDataFrame:
242    """Make a GeoDataFrame from weave tile polygons, labels, etc.
243
244    Args:
245      polys (list[Polygon | MultiPolygon]): list of weave tile
246        polygons.
247      strand_ids (list[str]): list of strand labels.
248      offset (tuple[float]): offset to centre the weave tiles on the
249        tile.
250
251    Returns:
252      geopandas.GeoDataFrame: GeoDataFrame clipped to the tile, with
253        margin applied.
254
255    """
256    weave = gpd.GeoDataFrame(
257      data = {"tile_id": strand_ids},
258      geometry = gpd.GeoSeries([affine.translate(p, offset[0], offset[1])
259                                for p in polys]))
260    weave = weave[weave.tile_id != "-"]
261    weave.geometry = gpd.GeoSeries(
262      [tiling_utils.get_clean_polygon(p) for p in weave.geometry])
263
264    # some buffering is required if aspect is 1 to safely dissolve and
265    # explode weave unit tiles that meet at corners
266    if self.aspect == 1:
267      # grow for dissolve
268      weave.geometry = weave.geometry.buffer(
269        # self.spacing * tiling_utils.RESOLUTION,
270        tiling_utils.RESOLUTION,
271        join_style = "mitre", cap_style = "square")
272      weave = weave.dissolve(by = "tile_id", as_index = False)
273      # shrink by more to explode into separate polygons
274      weave.geometry = weave.geometry.buffer(
275        # -2 * self.spacing * tiling_utils.RESOLUTION,
276        -2 * tiling_utils.RESOLUTION,
277        join_style = "mitre", cap_style = "square")
278      weave = weave.explode(ignore_index = True)
279      weave.geometry = weave.geometry.buffer(
280        # self.spacing * tiling_utils.RESOLUTION,
281        tiling_utils.RESOLUTION,
282        join_style = "mitre", cap_style = "square")
283    else: # aspect < 1 is fine without buffering
284      weave = weave.dissolve(by = "tile_id", as_index = False)
285      weave = weave.explode(ignore_index = True)
286    weave.geometry = gpd.GeoSeries(
287      [tiling_utils.get_clean_polygon(p) for p in weave.geometry])
288    return weave.set_crs(self.crs)
289
290
291  def _get_axis_from_label(self, label:str = "a", strands:str = None):
292    """Determine the axis of a tile_id from the strands spec string.
293
294    Args:
295      label (str, optional): the tile_id. Defaults to "a".
296      strands (str, optional): the strand spec. Defaults to the WeaveUnit
297      strands attribute.
298
299    Returns:
300      _type_: the axis in which the supplied tile is found.
301
302    """
303    if strands == None:
304      strands = self.strands
305    index = strands.index(label)
306    return strands[:index].count("|")
307
308
309  def _get_legend_tiles(self) -> gpd.GeoDataFrame:
310    """Return tiles suitable for use in a legend representation.
311
312    One tile for each tile_id value will be chosen, close to the
313    centre of the prototile extent, and not among the smallest tiles present
314    (for example not a short length of strand mostly hidden by other
315    strands)
316
317    Returns:
318      gpd.GeoDataFrame: the chosen tiles.
319
320    """
321    angles = ((0, 240, 120)
322              if self.weave_type in ("hex", "cube")
323              else (90, 0))
324    tile_ids = pd.Series.unique(self.tiles.tile_id)
325    groups = self.tiles.groupby("tile_id")
326    tiles, rotations = [], []
327    for id in tile_ids:
328      candidates = groups.get_group(id)
329      axis = self._get_axis_from_label(id, self.strands)
330      tiles.append(
331        self._get_most_central_large_tile(candidates, tiles))
332      rotations.append(-angles[axis] + self.rotation)
333    return gpd.GeoDataFrame(
334      data = {"tile_id": tile_ids, "rotation": rotations},
335      crs = self.crs,
336      geometry = gpd.GeoSeries(tiles))
337
338
339  def _get_most_central_large_tile(self, tiles:gpd.GeoDataFrame,
340          other_tiles:list[geom.Polygon]) -> geom.Polygon:
341    """Get a large tile close to the centre of the WeaveUnit.
342
343    Args:
344      tiles (gpd.GeoDataFrame): the set of tiles to choose from.
345
346    Returns:
347      geom.Polygon: the chosen, large central tile.
348
349    """
350    areas = [g.area for g in tiles.geometry]
351    min_area, max_area = min(areas), max(areas)
352    if min_area / max_area > 0.5:
353      geoms = list(tiles.geometry)
354    else:
355      mean_log_a = np.mean(np.log(areas))
356      geoms = [g for g, a in zip(tiles.geometry, areas)
357              if np.log(a) > mean_log_a]
358    if len(other_tiles) == 0 or self.weave_type in ("cube", "hex"):
359      d = [g.centroid.distance(geom.Point(0, 0)) for g in geoms]
360    else:
361      c = geom.MultiPolygon(other_tiles).centroid
362      d = [geom.MultiPolygon([g] + other_tiles).centroid.distance(c)
363          for g in geoms]
364    return geoms[d.index(min(d))]
365
366
367  def _get_legend_key_shapes(
368      self,
369      polygon:geom.Polygon,
370      counts:Iterable = [1] * 25,
371      angle:float = 0,
372      radial:bool = False,
373    ) -> list[geom.Polygon]:
374    """Return polygons obtained by slicing polygon crosswise into n slices.
375
376    Orientation of the polygon is indicated by the angle.
377
378    The returned list of polygons can be used to form a colour ramp in a
379    legend.
380
381    Args:
382      polygon (geom.Polygon): the weave strand polygon to slice.
383      counts (Iterable, optional): an iterable list of the numbers of
384        slices in each category. Defaults to [1] * 25.
385      angle (float, optional): orientation of the polygon. Defaults to 0.
386      radial (bool, optional): ignored by WeaveUnit.
387
388    Returns:
389      list[geom.Polygon]: a list of polygons.
390
391    """
392    c = polygon.centroid
393    g = affine.rotate(polygon, -angle, origin = c)
394    width, height, left, bottom = \
395      tiling_utils.get_width_height_left_bottom(gpd.GeoSeries([g]))
396    margin = width / 50
397    total = sum(counts)
398    cuts = list(np.cumsum(counts))
399    cuts = [0] + [c / total for c in cuts]
400    cuts = [left + c * width for c in cuts]
401    bottom = bottom - margin
402    top = bottom + height + 2 * margin
403    slices = []
404    for l, r in zip(cuts[:-1], cuts[1:], strict = True):
405      # we add a margin to left and right so that they overplot; otherwise in
406      # rendering matplotlib leaves small gaps which give a washed out look
407      # to the fill colour!
408      slice = geom.Polygon([(l - margin, bottom), (r + margin, bottom),
409                            (r + margin,    top), (l - margin,    top)])
410      slices.append(slice.intersection(g))
411    return [affine.rotate(s, angle, origin = c) for s in slices]