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      rescale = True
508    ) -> "Tileable":
509    """Transform tiling by skewing.
510
511    Args:
512      xa (float, optional): x direction skew. Defaults to 0.0.
513      ya (float, optional): y direction skew. Defaults to 0.0.
514      independent_of_tiling (bool, optional): if True Tileable is skewed while
515        leaving the translation vectors untouched, so that it can change shape
516        independent from its situation when tiled. Defaults to False.
517      rescale (bool, optional): if True rescales the result so that overall
518        size and extent is more or less unaffected by the skew, otherwise the
519        simultaneous application of both x and y shears may dramatically alter
520        the size of tiling. Defaults to True.
521
522    Returns:
523      Tileable: the transformed Tileable.
524
525    """
526    result = copy.deepcopy(self)
527    area_0 = result.prototile.geometry[0].area
528    result.tiles.geometry = (self.tiles.geometry
529                             .skew(xa, ya, origin=(0, 0)))
530    if not independent_of_tiling:
531      result.prototile.geometry = (self.prototile.geometry
532                                   .skew(xa, ya, origin=(0, 0)))
533      result.regularised_prototile.geometry = (
534        self.regularised_prototile.geometry
535            .skew(xa, ya, origin=(0, 0)))
536      result._set_vectors_from_prototile()
537    if rescale and xa != 0 and ya != 0:
538      area_1 = result.prototile.geometry[0].area
539      sf = np.sqrt(area_0 / area_1)
540      return result.transform_scale(sf, sf, independent_of_tiling)
541    else:
542      return result
543
544
545  def _set_vectors_from_prototile(self) -> None:
546    """Set translation vectors by derivation from a prototile shape.
547
548    Intended to be used internally, after a transform_scale, _skew, or _rotate.
549
550    These are 'face to face' vectors of the prototile, so that a hexagonal tile
551    will have 3 vectors, not the minimal parallelogram pair. Also sets the
552    inverse vectors. See `Tileable.setup_vectors()` for details.
553    """
554    t = self.prototile.loc[0, "geometry"]
555    points = list(t.exterior.coords)[:-1] # each point once only no wrap
556    n_pts = len(points)
557    vec_dict = {}
558    if n_pts == 4:
559      vecs = [(q[0] - p[0], q[1] - p[1])
560          for p, q in zip(points, points[1:] + points[:1], strict = True)]
561      i = [1, 0, -1,  0]
562      j = [0, 1,  0, -1]
563      vec_dict = {(i, j): v for i, j, v in zip(i, j, vecs, strict = True)}
564    elif n_pts == 6:
565      vecs = [(q[0] - p[0], q[1] - p[1])
566          for p, q in zip(points, points[2:] + points[:2], strict = True)]
567      # hex grid coordinates associated with each of the vectors
568      i = [ 0,  1,  1,  0, -1, -1]
569      j = [ 1,  0, -1, -1,  0,  1]
570      k = [-1, -1,  0,  1,  1,  0]
571      vec_dict = {
572        (i, j, k): v for i, j, k, v in zip(i, j, k, vecs, strict = True)}
573    self.vectors = vec_dict
574
575
576  def _get_mean_translation(self):
577    return np.mean(
578      [np.sqrt(dx ** 2 + dy ** 2) for (dx, dy) in self.get_vectors()])
579
580
581  def plot(
582      self,
583      ax:plt.Axes = None,
584      show_prototile:bool = True,
585      show_reg_prototile:bool = True,
586      show_ids:str|bool = "tile_id",
587      show_vectors:bool = False,
588      r:int = 0,
589      prototile_edgecolour:str = "k",
590      reg_prototile_edgecolour:str = "r",
591      vector_edgecolour:str = "k",
592      alpha:float = 1.0,
593      r_alpha:float = 0.5,
594      cmap:list[str]|str|None = None,
595      figsize:tuple[float] = (8, 8),
596      **kwargs,                        # noqa: ANN003
597    ) -> plt.Axes:
598    """Plot Tileable on the supplied axis.
599
600    **kwargs are passed on to matplotlib.plot()
601
602    Args:
603      ax (_type_, optional): matplotlib axis to draw to. Defaults to None.
604      show_prototile (bool, optional): if `True` show the tile outline.
605        Defaults to `True`.
606      show_reg_prototile (bool, optional): if `True` show the regularised tile
607        outline. Defaults to `True`.
608      show_ids (str, optional): if `tile_id` show the tile_ids. If
609        `id` show index number. If None or `''` don't label tiles.
610        Defaults to `tile_id`.
611      show_vectors (bool, optional): if `True` show the translation
612        vectors (not the minimal pair, but those used by
613        `get_local_patch()`). Defaults to `False`.
614      r (int, optional): passed to `get_local_patch()` to show context if
615        greater than 0. Defaults to `0`.
616      r_alpha (float, optional): alpha setting for units other than the
617        central one. Defaults to 0.5.
618      prototile_edgecolour (str, optional): outline colour for the tile.
619        Defaults to `"k"`.
620      reg_prototile_edgecolour (str, optional): outline colour for the
621        regularised. Defaults to `"r"`.
622      vector_edgecolour (str, optional): colour for the translation vectors.
623        Defaults to `"k"`.
624      cmap (list[str], optional): colour map to apply to the central
625        tiles. Defaults to `None`.
626      figsize (tuple[float], optional): size of the figure.
627        Defaults to `(8, 8)`.
628
629    Returns:
630      pyplot.axes: to which calling context may add things.
631
632    """
633    w = self.prototile.loc[0, "geometry"].bounds[2] - \
634      self.prototile.loc[0, "geometry"].bounds[0]
635    n_cols = len(set(self.tiles.tile_id))
636    if n_cols > 12:
637      cm = "Spectral"
638    elif n_cols > 8:
639      cm = "Paired"
640    else:
641      cm = "Dark2"
642    if ax is None:
643      ax = self.tiles.plot(
644        column="tile_id", cmap=cm, figsize=figsize, alpha = alpha, **kwargs)
645    else:
646      self.tiles.plot(
647        ax=ax, column="tile_id", cmap=cm, figsize=figsize, **kwargs)
648    if show_ids not in [None, ""]:
649      do_label = True
650      if show_ids in ["tile_id", True]:
651        labels = self.tiles.tile_id
652      elif show_ids == "id":
653        labels = [str(i) for i in range(self.tiles.shape[0])]
654      else:
655        do_label = False
656      if do_label:
657        for ID, tile in zip(labels, self.tiles.geometry, strict = True):
658          ax.annotate(ID, (tile.centroid.x, tile.centroid.y),
659            ha = "center", va = "center", bbox = {"lw": 0, "fc": "#ffffff40"})
660    if r > 0:
661      self.get_local_patch(r=r).plot(
662        ax = ax, column = "tile_id", alpha = r_alpha, cmap = cm, **kwargs)
663    if show_prototile:
664      self.prototile.plot(ax = ax, ec = prototile_edgecolour, lw = 0.5,
665                          fc = "#00000000", **kwargs)
666    if show_vectors:  # note that arrows in mpl are dimensioned in plotspace
667      vecs = self.get_vectors()
668      for v in vecs[: len(vecs) // 2]:
669        ax.arrow(0, 0, v[0], v[1], color = vector_edgecolour, width = w * 0.002,
670          head_width = w * 0.05, length_includes_head = True, zorder = 3)
671    if show_reg_prototile:
672      self.regularised_prototile.plot(
673        ax = ax, ec = reg_prototile_edgecolour, fc = "#00000000",
674        lw = 1.5, zorder = 2, **kwargs)
675    return ax
676
677
678  def _get_legend_tiles(self) -> gpd.GeoDataFrame:
679    """Return the tiles augmented by a rotation column.
680
681    This base implementation may be overridden by specific tile unit types.
682    In particular see `weavingspace.weave_unit.WeaveUnit._get_legend_tiles()`.
683
684    Returns:
685      gpd.GeoDataFrame: the tiles GeoDataFrame with a rotation column added.
686
687    """
688    tiles = copy.deepcopy(self.tiles)
689    tiles["rotation"] = 0
690    return tiles
691
692
693  def _setup_default_tileable(self) -> None:
694    """Set up a default Tileable for when the TileUnit generators fail."""
695    # if we've somehow got to here without a base_shape, make it rectangular
696    if self.base_shape is None:
697      self.base_shape = TileShape.RECTANGLE
698    if self.spacing is None:
699      self.spacing = 1000
700    match self.base_shape:
701      case TileShape.HEXAGON:
702        ids = ["a"]
703        tiles = [tiling_utils.get_regular_polygon(self.spacing, 6)]
704        self.setup_vectors(*self._get_hex_vectors())
705      case TileShape.DIAMOND:
706        ids = ["a"]
707        tiles = [( self.spacing/2, 0), (0,  self.spacing * np.sqrt(3)/2),
708                 (-self.spacing/2, 0), (0, -self.spacing * np.sqrt(3)/2)]
709        self.setup_vectors(*self._get_diamond_vectors())
710      case TileShape.TRIANGLE:
711        ids = ["a", "b"]
712        t1 = tiling_utils.get_regular_polygon(self.spacing, 3)
713        t1 = affine.translate(t1, 0, -t1.bounds[1])
714        t2 = affine.rotate(t1, 180, origin = (0, 0))
715        tiles = [t1, t2]
716        self.setup_vectors(*self._get_diamond_vectors())
717      case _:
718        ids = ["a"]
719        tiles = [tiling_utils.get_regular_polygon(self.spacing, 4)]
720        self.setup_vectors(*self._get_square_vectors())
721    self.tiles = gpd.GeoDataFrame(data = {"tile_id": ids},
722                                  geometry = gpd.GeoSeries(tiles),
723                                  crs = 3857)
724    self.crs = 3857
725    self.prototile = self.get_prototile_from_vectors()
726    self.regularised_prototile = copy.deepcopy(self.prototile)
727
728
729  def _get_hex_vectors(self) -> list[tuple[float,float]]:
730    """Return three vectors for a hexagonal tiling.
731
732    Returns:
733        list[tuple[float]]: Translation vectors of a hexagonal tiling.
734
735    """
736    return [(v[0] * self.spacing, v[1] * self.spacing)
737            for v in [(0, 1), (np.sqrt(3)/2, 1/2), (np.sqrt(3)/2, -1/2)]]
738
739
740  def _get_square_vectors(self) -> list[tuple[float,float]]:
741    """Return two vectors for a square tiling.
742
743    Returns:
744        list[tuple[float]]: Translation vectors of a square tiling.
745
746    """
747    return [(v[0] * self.spacing, v[1] * self.spacing)
748            for v in [(1, 0), (0, 1)]]
749
750
751  def _get_diamond_vectors(self) -> list[tuple[float,float]]:
752    """Return two vectors for a diamond or triangular tiling.
753
754    Returns:
755        list[tuple[float]]: Translation vectors of a square tiling.
756
757    """
758    return [(v[0] * self.spacing, v[1] * self.spacing)
759            for v in [(1/np.sqrt(3), 1), (1/np.sqrt(3), -1)]]