weavingspace.tileable

  1"""Implements Tileable and TileShape.
  2
  3`Tileable` should not be called directly, but is instead accessed from the
  4`weavingspace.tile_unit.TileUnit` or `weavingspace.weave_unit.WeaveUnit`
  5constructors.
  6
  7Several methods of `weavingspace.tileable.Tileable` are generally useful and
  8can be accessed through its subclasses.
  9"""
 10
 11import copy
 12from dataclasses import dataclass
 13from enum import Enum
 14
 15import geopandas as gpd
 16import numpy as np
 17import shapely.affinity as affine
 18import shapely.geometry as geom
 19from matplotlib import pyplot as plt
 20
 21from weavingspace import tiling_utils
 22
 23
 24class TileShape(Enum):
 25  """The available base tile shapes.
 26
 27  NOTE: the TRIANGLE type does not persist, but should be converted to a
 28  DIAMOND or HEXAGON type during `Tileable` construction.
 29  """
 30
 31  RECTANGLE = "rectangle"
 32  HEXAGON = "hexagon"
 33  TRIANGLE = "triangle"
 34  DIAMOND = "diamond"
 35
 36
 37@dataclass
 38class Tileable:
 39  """Class to represent a tileable set of tile geometries."""
 40
 41  tiles:gpd.GeoDataFrame|None = None
 42  """the geometries with associated `title_id` attribute encoding their
 43  different colouring."""
 44  prototile:gpd.GeoDataFrame|None = None
 45  """the tileable polygon (rectangle, hexagon or diamond)"""
 46  spacing:float = 1000.0
 47  """the tile spacing effectively the resolution of the tiling. Defaults to
 48  1000"""
 49  base_shape:TileShape = TileShape.RECTANGLE
 50  """the tile shape. Defaults to 'RECTANGLE'"""
 51  vectors:dict[tuple[int,...],tuple[float,...]]|None = None
 52  """translation vector symmetries of the tiling"""
 53  regularised_prototile:gpd.GeoDataFrame|None = None
 54  """polygon containing the tiles of this tileable, usually a union of its
 55  tile polygons"""
 56  crs:int = 3857
 57  """coordinate reference system of the tile. Most often an ESPG code but
 58  any valid geopandas CRS specification is valid. Defaults to 3857 (i.e. Web
 59  Mercator)."""
 60  rotation:float = 0.0
 61  """cumulative rotation of the tileable."""
 62  debug:bool = False
 63  """if True prints debug messages. Defaults to False."""
 64
 65  # Tileable constructor called by subclasses - should not be used directly
 66  def __init__(self,      # noqa: D107
 67               **kwargs,  # noqa: ANN003
 68              ) -> None:
 69    for k, v in kwargs.items():
 70      if isinstance(v, str):
 71        # make any string arguments lower case
 72        self.__dict__[k] = v.lower()
 73      else:
 74        self.__dict__[k] = v
 75    # delegate making the tiles back to the subclass _setup_tiles() method
 76    # which is implemented differently by TileUnit and WeavUnit. It will return
 77    # a message if there's a problem.
 78    # There might be a try... except... way to do this more 'properly', but we
 79    # prefer to return something even if it's not what was requested - along
 80    # with an explanation / suggestion
 81    message = self._setup_tiles()
 82    if message is not None: # there was a problem
 83      print(message)
 84      self._setup_default_tileable()
 85    else:
 86      self.prototile = self.get_prototile_from_vectors()
 87      self._setup_regularised_prototile()
 88
 89
 90  def setup_vectors(
 91        self,
 92        *args,  # noqa: ANN002
 93      ) -> None:
 94    """Set up translation vectors of a Tileable.
 95
 96    Initialised from either two or three supplied tuples. Two non-parallel
 97    vectors are sufficient for a tiling to work, but usually three will be
 98    supplied for tiles with a hexagonal base tile. We also store the reverse
 99    vectors - this is for convenience when finding a 'local patch'. This method
100    is preferred during Tileable initialisation.
101
102    The vectors are stored in a dictionary indexed by their
103    coordinates, e.g.
104
105      {( 1,  0): ( 100, 0), ( 0,  1): (0,  100),
106       (-1,  0): (-100, 0), ( 0, -1): (0, -100)}
107
108    For a tileable of type `TileShape.HEXAGON`, the indexing tuples
109    have three components. See https://www.redblobgames.com/grids/hexagons/
110    """
111    vectors = list(args)
112    # extend list to include the inverse vectors too
113    for v in args:
114      vectors = [*vectors, (-v[0], -v[1])]
115    if len(vectors) == 4:
116      i = [1, 0, -1,  0]
117      j = [0, 1,  0, -1]
118      self.vectors = {
119        (i, j): v for i, j, v in zip(i, j, vectors, strict = True)}
120    else:
121      i = [ 0,  1,  1,  0, -1, -1]
122      j = [ 1,  0, -1, -1,  0,  1]
123      k = [-1, -1,  0,  1,  1,  0]
124      self.vectors = {
125        (i, j, k): v for i, j, k, v in zip(i, j, k, vectors, strict = True)}
126
127
128  def get_vectors(
129      self,
130      as_dict: bool = False,
131      ) -> list[tuple[float,...]]|dict[tuple[int,...],tuple[float,...]]:
132    """Return symmetry translation vectors as floating point pairs.
133
134    Optionally returns the vectors in a dictionary indexed by offsets in grid
135    coordinates, e.g.
136
137      {( 1,  0): ( 100, 0), ( 0,  1): (0,  100),
138       (-1,  0): (-100, 0), ( 0, -1): (0, -100)}
139
140    Returns:
141      dict[tuple[int],tuple[float]]|list[tuple[float]]: either the vectors as a
142        list of float tuples, or a dictionary of those vectors indexed by
143        integer coordinate tuples.
144
145    """
146    if as_dict:
147      return self.vectors
148    return list(self.vectors.values())
149
150
151  def get_prototile_from_vectors(self) -> gpd.GeoDataFrame:
152    r"""Contruct and returns a prototile unit based on vectors of the Tileable.
153
154    For rectangular tilings the prototile is formed by points
155    at diagonal corners defined by the halved vectors. By inspection, each edge
156    of the prototile is the resultant of adding two of the four vectors.
157
158      ----
159     |\  /|
160     | \/ |
161     | /\ |
162     |/  \|
163      ----
164
165    In the hexagonal case we form three such quadrilaterals (but don't halve the
166    vectors, because we need the extended length) and intersect them to find a
167    hexagonal shape. This guarantees that each vector will connect two opposite
168    faces of the hexagon, as desired. This seems the most elegant approach by
169    geometric construction.
170
171    The prototile is not uniquely defined. The shape returned by this method is
172    not guaranteed to be the most 'obvious' one that a human might construct!
173
174    Returns:
175      gpd.GeoDataFrame: A suitable prototile shape for the tiling wrapped in a
176        GeoDataFrame.
177
178    """
179    vecs = self.get_vectors()
180    if len(vecs) == 4:
181      v1, v2, v3, v4 = [(x / 2, y / 2) for (x, y) in vecs]
182      prototile = geom.Polygon([(v1[0] + v2[0], v1[1] + v2[1]),
183                                (v2[0] + v3[0], v2[1] + v3[1]),
184                                (v3[0] + v4[0], v3[1] + v4[1]),
185                                (v4[0] + v1[0], v4[1] + v1[1])])
186    else:
187      v1, v2, v3, v4, v5, v6 = vecs
188      q1 = geom.Polygon([v1, v2, v4, v5])
189      q2 = geom.Polygon([v2, v3, v5, v6])
190      q3 = geom.Polygon([v3, v4, v6, v1])
191      prototile = q3.intersection(q2).intersection(q1)
192    return gpd.GeoDataFrame(
193      geometry = gpd.GeoSeries([prototile]),
194      crs = self.crs)
195
196
197  def _regularise_tiles(self) -> None:
198    """Combine tiles with same tile_id into single tiles.
199
200    This is used where some tile fragments might be on opposite sides of the
201    initial Tileable, but would end up touching after tiling. Most likely to be
202    applicable to WeaveUnit Tileables.
203
204    Also adjusts the `Tileable.regularised_prototile` attribute accordingly.
205    """
206    self.regularised_prototile = copy.deepcopy(self.prototile)
207    # This preserves order while finding uniques, unlike list(set()).
208    # Reordering ids might cause confusion when colour palettes
209    # are not assigned explicitly to each id, but in the order
210    # encountered in the tile_id Series of the GeoDataFrame.
211    tiles, tile_ids = [], []
212    ids = list(self.tiles.tile_id.unique())
213    for ID in ids:
214      fragment_set = list(
215        self.tiles[self.tiles.tile_id == ID].geometry)
216      merge_result = self._merge_fragments(fragment_set)
217      tiles.extend(merge_result)
218      tile_ids.extend([ID] * len(merge_result))
219
220    self.tiles = gpd.GeoDataFrame(
221      data = {"tile_id": tile_ids},
222      crs = self.crs,
223      geometry = gpd.GeoSeries([tiling_utils.get_clean_polygon(t)
224                                for t in tiles]))
225
226    self.regularised_prototile = \
227      self.regularised_prototile.explode(ignore_index = True)
228    if self.regularised_prototile.shape[0] > 1:
229      self.regularised_prototile.geometry = tiling_utils.get_largest_polygon(
230        self.regularised_prototile.geometry)
231
232
233  def _merge_fragments(
234      self,
235      fragments:list[geom.Polygon],
236    ) -> list[geom.Polygon]:
237    """Merge a set of polygons if they touch under the translation vectors.
238
239    Called by `regularise_tiles()` to combine tiles in a tile unit that
240    may be fragmented as supplied but will combine after tiling into single
241    tiles. This step makes for more efficient implementation of the
242    tiling of map regions, and also adds to the woven look in particular
243    where it means that 'threads' go beyond the edges of the tile shapes.
244
245    Args:
246      fragments (list[geom.Polygon]): A set of polygons to merge.
247
248    Returns:
249      list[geom.Polygon]: A minimal list of merged polygons.
250
251    """
252    if len(fragments) == 1:
253      return [f for f in fragments if not f.is_empty]
254    fragments = [f for f in fragments if not f.is_empty]
255    prototile = self.prototile.loc[0, "geometry"]
256    reg_prototile = copy.deepcopy(
257      self.regularised_prototile.loc[0, "geometry"])
258    changes_made = True
259    while changes_made:
260      changes_made = False
261      for v in self.vectors.values():
262        # empty list to collect the new fragments
263        # assembled in this iteration
264        next_frags = []
265        t_frags = [affine.translate(f, v[0], v[1]) for f in fragments]
266        # build a set of any near matching pairs of
267        # fragments and their translated copies
268        matches = set()
269        for i, f1 in enumerate(fragments):
270          for j, f2, in enumerate(t_frags):
271            if i < j and tiling_utils.touch_along_an_edge(f1, f2):
272              matches.add((i, j))
273        # determine which of these when unioned has the larger area in common
274        # with the prototile
275        done_frags = set()
276        for i, j in matches:
277          f1, f2 = fragments[i], t_frags[j]
278          u1 = f1.buffer(tiling_utils.RESOLUTION * 2,
279                         join_style = "mitre", cap_style = "square").union(
280            f2.buffer(tiling_utils.RESOLUTION * 2,
281                      join_style = "mitre", cap_style = "square"))
282          u2 = affine.translate(u1, -v[0], -v[1])
283          if prototile.intersection(u1).area > prototile.intersection(u2).area:
284            u1 = u1.buffer(-tiling_utils.RESOLUTION * 2,
285                           join_style = "mitre", cap_style = "square")
286            u2 = u2.buffer(-tiling_utils.RESOLUTION * 2,
287                           join_style = "mitre", cap_style = "square")
288            next_frags.append(u1)
289            reg_prototile = reg_prototile.union(u1).difference(u2)
290          else:
291            u1 = u1.buffer(-tiling_utils.RESOLUTION * 2,
292                           join_style = "mitre", cap_style = "square")
293            u2 = u2.buffer(-tiling_utils.RESOLUTION * 2,
294                           join_style = "mitre", cap_style = "square")
295            next_frags.append(u2)
296            reg_prototile = reg_prototile.union(u2).difference(u1)
297          changes_made = True
298          done_frags.add(i)
299          done_frags.add(j)
300        fragments = [f for i, f in enumerate(fragments)
301                     if i not in done_frags] + next_frags
302    self.regularised_prototile.loc[0, "geometry"] = reg_prototile
303    return [f for f in fragments if not f.is_empty] # don't return any duds
304
305
306  def get_local_patch(
307      self,
308      r:int = 1,
309      include_0:bool = False,
310    ) -> gpd.GeoDataFrame:
311    """Return a GeoDataFrame with translated copies of the Tileable.
312
313    The geodataframe takes the same form as the `Tileable.tile` attribute.
314
315    Args:
316      r (int, optional): the number of 'layers' out from the unit to
317        which the translate copies will extendt. Defaults to `1`.
318      include_0 (bool, optional): If True includes the Tileable itself at
319        (0, 0). Defaults to `False`.
320
321    Returns:
322      gpd.GeoDataFrame: A GeoDataframe of the tiles extended by a number
323        of 'layers'.
324
325    """
326    # a dictionary of all the vectors we need, starting with (0, 0)
327    three_vecs = len(next(iter(self.vectors.keys()))) == 3
328    vecs = {(0, 0, 0): (0, 0)} if three_vecs else {(0, 0): (0, 0)}
329    steps = r if three_vecs else r * 2
330    # a dictionary of the last 'layer' of added vectors
331    last_vecs = copy.deepcopy(vecs)
332    # get the translation vectors in a dictionary indexed by coordinates
333    # we keep track of the sum of vectors using the (integer) coordinates
334    # to avoid duplication of moves due to floating point inaccuracies
335    vectors = self.get_vectors(as_dict = True)
336    for i in range(steps):
337      new_vecs = {}
338      for k1, v1 in last_vecs.items():
339        for k2, v2 in vectors.items():
340          # add the coordinates to make a new key...
341          new_key = tuple([k1[i] + k2[i] for i in range(len(k1))])
342          # if we haven't reached here before store the actual vector
343          if new_key not in vecs:
344            new_vecs[new_key] = (v1[0] + v2[0], v1[1] + v2[1])
345      # extend the vectors and set the last layer to the set just added
346      vecs = vecs | new_vecs
347      last_vecs = new_vecs
348    if not include_0:  # throw away the identity vector
349      vecs.pop((0, 0, 0) if three_vecs else (0, 0))
350    ids, tiles = [], []
351    # we need to add the translated prototiles in order of their distance from
352    # tile 0, esp. in the square case, i.e. something like this:
353    #
354    #      5 4 3 4 5
355    #      4 2 1 2 4
356    #      3 1 0 1 3
357    #      4 2 1 2 4
358    #      5 4 3 4 5
359    #
360    # this is important for topology detection, where filtering back to the
361    # local patch of radius 1 is simplified if prototiles have been added in
362    # this order. We use the vector index tuples not the euclidean distances
363    # because this is more resistant to odd effects for non-convex tiles
364    extent = self.get_prototile_from_vectors().loc[0, "geometry"]
365    extent = affine.scale(extent,
366                          2 * r + tiling_utils.RESOLUTION,
367                          2 * r + tiling_utils.RESOLUTION)
368    vector_lengths = {index: np.sqrt(sum([_ ** 2 for _ in index]))
369                      for index in vecs}
370    ordered_vector_keys = [k for k, v in sorted(vector_lengths.items(),
371                                                key = lambda item: item[1])]
372    for k in ordered_vector_keys:
373      v = vecs[k]
374      if geom.Point(v[0], v[1]).within(extent):
375        ids.extend(self.tiles.tile_id)
376        tiles.extend(
377          self.tiles.geometry.apply(affine.translate, xoff = v[0], yoff = v[1]))
378    return gpd.GeoDataFrame(
379      data = {"tile_id": ids}, crs=self.crs,
380      geometry = gpd.GeoSeries(tiles))
381
382
383  # applicable to both TileUnits and WeaveUnits
384  def inset_tiles(
385      self,
386      inset:float = 0) -> "Tileable":
387    """Return a new Tileable with an inset applied around the tiles.
388
389    Works by applying a negative buffer of specfied size to all tiles.
390    Tiles that collapse to zero area are removed and the tile_id
391    attribute updated accordingly.
392
393    NOTE: this method is likely to not preserve the relative area of tiles.
394
395    Args:
396      inset (float, optional): The distance to inset. Defaults to `0`.
397
398    Returns:
399      "Tileable": the new inset Tileable.
400
401    """
402    inset_tiles, inset_ids = [], []
403    for p, ID in zip(self.tiles.geometry, self.tiles.tile_id, strict = True):
404      b = p.buffer(-inset, join_style = "mitre", cap_style = "square")
405      if not b.area <= 0:
406        inset_tiles.append(b)
407        inset_ids.append(ID)
408    result = copy.deepcopy(self)
409    result.tiles = gpd.GeoDataFrame(
410      data={"tile_id": inset_ids},
411      crs=self.crs,
412      geometry=gpd.GeoSeries(inset_tiles),
413    )
414    return result
415
416
417  def scale_tiles(
418      self,
419      sf:float = 1,
420      individually:bool = False,
421    ) -> "Tileable":
422    """Scales the tiles by the specified factor, centred on (0, 0).
423
424    Args:
425      sf (float, optional): scale factor to apply. Defaults to 1.
426      individually (bool, optional): if True scaling is applied to each tiling
427        element centred on its centre, rather than with respect to the Tileable.
428        Defaults to False.
429
430    Returns:
431      TileUnit: the scaled TileUnit.
432
433    """
434    if individually:
435      self.tiles.geometry = gpd.GeoSeries(
436        [affine.scale(g, sf, sf) for g in self.tiles.geometry])
437    else:
438      self.tiles.geometry = self.tiles.geometry.scale(sf, sf, origin = (0, 0))
439    return self
440
441
442  def transform_scale(
443      self,
444      xscale:float = 1.0,
445      yscale:float = 1.0,
446      independent_of_tiling:bool = False,
447    ) -> "Tileable":
448    """Transform tileable by scaling.
449
450    Args:
451      xscale (float, optional): x scale factor. Defaults to 1.0.
452      yscale (float, optional): y scale factor. Defaults to 1.0.
453      independent_of_tiling (bool, optional): if True Tileable is scaled while
454        leaving the translation vectors untouched, so that it can change size
455        independent from its spacing when tiled. Defaults to False.
456
457    Returns:
458      Tileable: the transformed Tileable.
459
460    """
461    result = copy.deepcopy(self)
462    result.tiles.geometry = self.tiles.geometry.scale(
463      xscale, yscale, origin=(0, 0))
464    if not independent_of_tiling:
465      result.prototile.geometry = self.prototile.geometry.scale(
466        xscale, yscale, origin=(0, 0))
467      result.regularised_prototile.geometry = \
468        self.regularised_prototile.geometry.scale(xscale, yscale, origin=(0, 0))
469      result._set_vectors_from_prototile()
470    return result
471
472
473  def transform_rotate(
474      self,
475      angle:float = 0.0,
476      independent_of_tiling:bool = False,
477    ) -> "Tileable":
478    """Transform tiling by rotation.
479
480    Args:
481      angle (float, optional): angle to rotate by. Defaults to 0.0.
482      independent_of_tiling (bool, optional): if True Tileable is rotated while
483        leaving the translation vectors untouched, so that it can change
484        orientation independent from its position when tiled. Defaults to False.
485
486    Returns:
487      Tileable: the transformed Tileable.
488
489    """
490    result = copy.deepcopy(self)
491    result.tiles.geometry = self.tiles.geometry.rotate(angle, origin=(0, 0))
492    if not independent_of_tiling:
493      result.prototile.geometry = \
494        self.prototile.geometry.rotate(angle, origin=(0, 0))
495      result.regularised_prototile.geometry = \
496        self.regularised_prototile.geometry.rotate(angle, origin=(0, 0))
497      result._set_vectors_from_prototile()
498      result.rotation = self.rotation + angle
499    return result
500
501
502  def transform_skew(
503      self,
504      xa:float = 0.0,
505      ya:float = 0.0,
506      independent_of_tiling:bool = False,
507    ) -> "Tileable":
508    """Transform tiling by skewing.
509
510    Args:
511      xa (float, optional): x direction skew. Defaults to 0.0.
512      ya (float, optional): y direction skew. Defaults to 0.0.
513      independent_of_tiling (bool, optional): if True Tileable is skewed while
514        leaving the translation vectors untouched, so that it can change shape
515        independent from its situation when tiled. Defaults to False.
516
517    Returns:
518      Tileable: the transformed Tileable.
519
520    """
521    result = copy.deepcopy(self)
522    result.tiles.geometry = self.tiles.geometry.skew(xa, ya, origin=(0, 0))
523    if not independent_of_tiling:
524      result.prototile.geometry = \
525        self.prototile.geometry.skew(xa, ya, origin=(0, 0))
526      result.regularised_prototile.geometry = \
527        self.regularised_prototile.geometry.skew(xa, ya, origin=(0, 0))
528      result._set_vectors_from_prototile()
529    return result
530
531
532  def _set_vectors_from_prototile(self) -> None:
533    """Set translation vectors by derivation from a prototile shape.
534
535    Intended to be used internally, after a transform_scale, _skew, or _rotate.
536
537    These are 'face to face' vectors of the prototile, so that a hexagonal tile
538    will have 3 vectors, not the minimal parallelogram pair. Also sets the
539    inverse vectors. See `Tileable.setup_vectors()` for details.
540    """
541    t = self.prototile.loc[0, "geometry"]
542    points = list(t.exterior.coords)[:-1] # each point once only no wrap
543    n_pts = len(points)
544    vec_dict = {}
545    if n_pts == 4:
546      vecs = [(q[0] - p[0], q[1] - p[1])
547          for p, q in zip(points, points[1:] + points[:1], strict = True)]
548      i = [1, 0, -1,  0]
549      j = [0, 1,  0, -1]
550      vec_dict = {(i, j): v for i, j, v in zip(i, j, vecs, strict = True)}
551    elif n_pts == 6:
552      vecs = [(q[0] - p[0], q[1] - p[1])
553          for p, q in zip(points, points[2:] + points[:2], strict = True)]
554      # hex grid coordinates associated with each of the vectors
555      i = [ 0,  1,  1,  0, -1, -1]
556      j = [ 1,  0, -1, -1,  0,  1]
557      k = [-1, -1,  0,  1,  1,  0]
558      vec_dict = {
559        (i, j, k): v for i, j, k, v in zip(i, j, k, vecs, strict = True)}
560    self.vectors = vec_dict
561
562
563  def plot(
564      self,
565      ax:plt.Axes = None,
566      show_prototile:bool = True,
567      show_reg_prototile:bool = True,
568      show_ids:str|bool = "tile_id",
569      show_vectors:bool = False,
570      r:int = 0,
571      prototile_edgecolour:str = "k",
572      reg_prototile_edgecolour:str = "r",
573      vector_edgecolour:str = "k",
574      alpha:float = 1.0,
575      r_alpha:float = 0.5,
576      cmap:list[str]|str|None = None,
577      figsize:tuple[float] = (8, 8),
578      **kwargs,                        # noqa: ANN003
579    ) -> plt.Axes:
580    """Plot Tileable on the supplied axis.
581
582    **kwargs are passed on to matplotlib.plot()
583
584    Args:
585      ax (_type_, optional): matplotlib axis to draw to. Defaults to None.
586      show_prototile (bool, optional): if `True` show the tile outline.
587        Defaults to `True`.
588      show_reg_prototile (bool, optional): if `True` show the regularised tile
589        outline. Defaults to `True`.
590      show_ids (str, optional): if `tile_id` show the tile_ids. If
591        `id` show index number. If None or `''` don't label tiles.
592        Defaults to `tile_id`.
593      show_vectors (bool, optional): if `True` show the translation
594        vectors (not the minimal pair, but those used by
595        `get_local_patch()`). Defaults to `False`.
596      r (int, optional): passed to `get_local_patch()` to show context if
597        greater than 0. Defaults to `0`.
598      r_alpha (float, optional): alpha setting for units other than the
599        central one. Defaults to 0.5.
600      prototile_edgecolour (str, optional): outline colour for the tile.
601        Defaults to `"k"`.
602      reg_prototile_edgecolour (str, optional): outline colour for the
603        regularised. Defaults to `"r"`.
604      vector_edgecolour (str, optional): colour for the translation vectors.
605        Defaults to `"k"`.
606      cmap (list[str], optional): colour map to apply to the central
607        tiles. Defaults to `None`.
608      figsize (tuple[float], optional): size of the figure.
609        Defaults to `(8, 8)`.
610
611    Returns:
612      pyplot.axes: to which calling context may add things.
613
614    """
615    w = self.prototile.loc[0, "geometry"].bounds[2] - \
616      self.prototile.loc[0, "geometry"].bounds[0]
617    n_cols = len(set(self.tiles.tile_id))
618    cm = ("Dark2" if n_cols <= 8 else "Paired") if cmap is None else cmap
619    if ax is None:
620      ax = self.tiles.plot(
621        column="tile_id", cmap=cm, figsize=figsize, alpha = alpha, **kwargs)
622    else:
623      self.tiles.plot(
624        ax=ax, column="tile_id", cmap=cm, figsize=figsize, **kwargs)
625    if show_ids not in [None, ""]:
626      do_label = True
627      if show_ids in ["tile_id", True]:
628        labels = self.tiles.tile_id
629      elif show_ids == "id":
630        labels = [str(i) for i in range(self.tiles.shape[0])]
631      else:
632        do_label = False
633      if do_label:
634        for ID, tile in zip(labels, self.tiles.geometry, strict = True):
635          ax.annotate(ID, (tile.centroid.x, tile.centroid.y),
636            ha = "center", va = "center", bbox = {"lw": 0, "fc": "#ffffff40"})
637    if r > 0:
638      self.get_local_patch(r=r).plot(
639        ax = ax, column = "tile_id", alpha = r_alpha, cmap = cm, **kwargs)
640    if show_prototile:
641      self.prototile.plot(ax = ax, ec = prototile_edgecolour, lw = 0.5,
642                          fc = "#00000000", **kwargs)
643    if show_vectors:  # note that arrows in mpl are dimensioned in plotspace
644      vecs = self.get_vectors()
645      for v in vecs[: len(vecs) // 2]:
646        ax.arrow(0, 0, v[0], v[1], color = vector_edgecolour, width = w * 0.002,
647          head_width = w * 0.05, length_includes_head = True, zorder = 3)
648    if show_reg_prototile:
649      self.regularised_prototile.plot(
650        ax = ax, ec = reg_prototile_edgecolour, fc = "#00000000",
651        lw = 1.5, zorder = 2, **kwargs)
652    return ax
653
654
655  def _get_legend_tiles(self) -> gpd.GeoDataFrame:
656    """Return the tiles augmented by a rotation column.
657
658    This base implementation may be overridden by specific tile unit types.
659    In particular see `weavingspace.weave_unit.WeaveUnit._get_legend_tiles()`.
660
661    Returns:
662      gpd.GeoDataFrame: the tiles GeoDataFrame with a rotation column added.
663
664    """
665    tiles = copy.deepcopy(self.tiles)
666    tiles["rotation"] = 0
667    return tiles
668
669
670  def _setup_default_tileable(self) -> None:
671    """Set up a default Tileable for when the TileUnit generators fail."""
672    # if we've somehow got to here without a base_shape, make it rectangular
673    if self.base_shape is None:
674      self.base_shape = TileShape.RECTANGLE
675    if self.spacing is None:
676      self.spacing = 1000
677    match self.base_shape:
678      case TileShape.HEXAGON:
679        ids = ["a"]
680        tiles = [tiling_utils.get_regular_polygon(self.spacing, 6)]
681        self.setup_vectors(*self._get_hex_vectors())
682      case TileShape.DIAMOND:
683        ids = ["a"]
684        tiles = [( self.spacing/2, 0), (0,  self.spacing * np.sqrt(3)/2),
685                 (-self.spacing/2, 0), (0, -self.spacing * np.sqrt(3)/2)]
686        self.setup_vectors(*self._get_diamond_vectors())
687      case TileShape.TRIANGLE:
688        ids = ["a", "b"]
689        t1 = tiling_utils.get_regular_polygon(self.spacing, 3)
690        t1 = affine.translate(t1, 0, -t1.bounds[1])
691        t2 = affine.rotate(t1, 180, origin = (0, 0))
692        tiles = [t1, t2]
693        self.setup_vectors(*self._get_diamond_vectors())
694      case _:
695        ids = ["a"]
696        tiles = [tiling_utils.get_regular_polygon(self.spacing, 4)]
697        self.setup_vectors(*self._get_square_vectors())
698    self.tiles = gpd.GeoDataFrame(data = {"tile_id": ids},
699                                  geometry = gpd.GeoSeries(tiles),
700                                  crs = 3857)
701    self.crs = 3857
702    self.prototile = self.get_prototile_from_vectors()
703    self.regularised_prototile = copy.deepcopy(self.prototile)
704
705
706  def _get_hex_vectors(self) -> list[tuple[float,float]]:
707    """Return three vectors for a hexagonal tiling.
708
709    Returns:
710        list[tuple[float]]: Translation vectors of a hexagonal tiling.
711
712    """
713    return [(v[0] * self.spacing, v[1] * self.spacing)
714            for v in [(0, 1), (np.sqrt(3)/2, 1/2), (np.sqrt(3)/2, -1/2)]]
715
716
717  def _get_square_vectors(self) -> list[tuple[float,float]]:
718    """Return two vectors for a square tiling.
719
720    Returns:
721        list[tuple[float]]: Translation vectors of a square tiling.
722
723    """
724    return [(v[0] * self.spacing, v[1] * self.spacing)
725            for v in [(1, 0), (0, 1)]]
726
727
728  def _get_diamond_vectors(self) -> list[tuple[float,float]]:
729    """Return two vectors for a diamond or triangular tiling.
730
731    Returns:
732        list[tuple[float]]: Translation vectors of a square tiling.
733
734    """
735    return [(v[0] * self.spacing, v[1] * self.spacing)
736            for v in [(1/np.sqrt(3), 1), (1/np.sqrt(3), -1)]]