Tilings and tile sets¶

isotile.IsohedralTiling ¶

IsohedralTiling(
    tiling_type: int | TilingType,
    parameters: ArrayLike | None = None,
    *,
    edge_curves: Mapping[int, ArrayLike] | None = None,
    edge_curve_modes: Mapping[int, str] | None = None,
    frame: ArrayLike | None = None,
)

One of the 81 isohedral types at given parameters, placed by an affine frame.

A tile is identified by its cell (u, v), the parallelogram of the lattice spanned by translation_u and translation_v, and its aspect, the index of the tile within the cell.

Parameters:

tiling_type (int or TilingType) –

Type number (see tiling_types) or the type data.
parameters (array - like, default: None ) –

n_params values; the type's defaults when omitted. Any finite values for which the straight prototile is a valid simple polygon are accepted (see check_prototile).
edge_curves (mapping of int to (m, 2) array-like, default: None ) –

Curves for the edge shape ids (TilingType.edge_shape_ids): control points on the canonical edge, from (0, 0) to (1, 0). Every edge with the shape id gets the curve. The symmetry of the shape is enforced (see enforce_symmetry). Ids that are not given stay straight; an id of an I edge is an error.
edge_curve_modes (mapping of int to str, default: None ) –

"spline" (default) or "linear" for the shape ids in edge_curves, see interpolate.
frame ((2, 3) array-like, default: None ) –

Affine map from the type's native coordinates to world coordinates, applied to the vertices, translation vectors, aspects and edges. Identity when omitted.

Attributes:

type (TilingType) –

The data of the type.

Raises:

ValueError –

If the type, the number of parameters or the frame is invalid or if an edge curve is malformed (an id that is not a shape id or belongs to an I edge, points that do not run from (0, 0) to (1, 0)).
InvalidPrototileError –

If the prototile or its outline with the curves is not valid (see check_prototile); it is a ValueError and carries the report. The parameter setter keeps the previous state in that case.

Methods:

square –

Unit squares (type 76); the tile (0, 0) is [0, 1] x [0, 1].
hexagon –

Regular hexagons with circumradius 1 (type 20), centered at the origin for the tile (0, 0).
triangle –

Tiling by copies of a triangle that are related by point reflections about the edge midpoints (type 84).
quadrilateral –

Tiling by copies of a quadrilateral related by point reflections about the edge midpoints (type 46).
from_preset –

A tiling from a named preset, see list_presets.
with_frame –

The same type, parameters and edge curves with the frame replaced.
rotated –

A copy rotated counterclockwise about the world origin.
scaled –

A copy scaled about the world origin.
with_parameters –

The same type, edge curves and frame with the parameters replaced; this tiling is unchanged.
with_edge_curves –

The same type, parameters and frame with the edge curves replaced (None removes all curves).
prototile –

(M, 2) closed outline of the prototile in world coordinates, without the repeated first point.
edge_outlines –

One polyline per edge in world coordinates, from vertex i to vertex i + 1.
info –

Metadata of the type as in TilingType.info, for the current parameters.
describe –

Human-readable summary of the type with the current parameter values, see TilingType.describe.
to_dict –

The tiling as a JSON-compatible dict: type, parameters, edge curves and modes, frame.
from_dict –

The tiling that a dict from to_dict describes.
save –

Write the tiling to a JSON file, see isotile.io.save.
load –

Read a tiling from a JSON file written by save.
tiles –

The tiles with the given cells and aspects.
fill –

Tiles generated by the scanline fill of the rectangle, in scanline order, without repeats.
cover –

All tiles whose polygon overlaps the rectangle bounds with positive area.
fill_region –

Tiles that cover a region, with the tile size set by a tile count or given directly.

parameters `property` `writable` ¶

parameters: Array

(n_params,) current parameters. Assigning checks the prototile and raises InvalidPrototileError if it is invalid.

frame `property` ¶

frame: Array

(2, 3) affine map from native to world coordinates.

vertices `property` ¶

vertices: Array

(n_vertices, 2) prototile vertices.

aspects `property` ¶

aspects: Array

(n_aspects, 2, 3) affine transforms of the aspects.

translations `property` ¶

translations: Array

(2, 2) lattice translation vectors; row k is vector k.

translation_u `property` ¶

translation_u: Array

First lattice translation vector.

translation_v `property` ¶

translation_v: Array

Second lattice translation vector.

edge_transforms `property` ¶

edge_transforms: Array

(n_vertices, 2, 3) maps of the canonical edge (0, 0)-(1, 0) onto each prototile edge.

edge_reversed `property` ¶

edge_reversed: NDArray[bool_]

(n_vertices,) True where the edge is traversed against its shape direction (flip != rotate).

edge_shape_ids `property` ¶

edge_shape_ids: IntArray

(n_vertices,) id of the shape of each edge; edges with the same id have the same shape.

edge_shapes `property` ¶

edge_shapes: tuple[str, ...]

Shape of each edge: "I" (straight), "J", "U" or "S".

edge_curves `property` ¶

edge_curves: dict[int, Array]

Control points of the curve of each shape id that has one, with the symmetry of its shape enforced.

edge_curve_modes `property` ¶

edge_curve_modes: dict[int, str]

Interpolation mode ("spline" or "linear") of each shape id in edge_curves.

edges `property` ¶

edges: tuple[EdgeInfo, ...]

The edges of the prototile in order, with shape id, shape, reversal and curve.

area `property` ¶

area: float

Area of the straight prototile.

centroid `property` ¶

centroid: Array

Area centroid of the straight prototile.

inscribed_radius `property` ¶

inscribed_radius: float

Radius of the largest circle inside the straight prototile (to a relative accuracy of 1e-10).

square `classmethod` ¶

square() -> IsohedralTiling

Unit squares (type 76); the tile (0, 0) is [0, 1] x [0, 1].

hexagon `classmethod` ¶

hexagon(pointy_top: bool = True) -> IsohedralTiling

Regular hexagons with circumradius 1 (type 20), centered at the origin for the tile (0, 0).

With pointy_top the tiles have a vertex at the top; otherwise they are flat-top (a vertex at angle 0).

triangle `classmethod` ¶

triangle(
    vertices: ArrayLike | None = None,
) -> IsohedralTiling

Tiling by copies of a triangle that are related by point reflections about the edge midpoints (type 84).

vertices is any triangle as 3 points; the prototile equals it (up to the starting vertex and the orientation, which is counterclockwise). The default is the equilateral triangle with side 1.

quadrilateral `classmethod` ¶

quadrilateral(
    vertices: ArrayLike | None = None,
) -> IsohedralTiling

Tiling by copies of a quadrilateral related by point reflections about the edge midpoints (type 46).

vertices is any simple quadrilateral as 4 points, convex or not; the prototile equals it (up to the starting vertex and the orientation, which is counterclockwise). The default is the unit square. A self-intersecting quadrilateral raises ValueError.

from_preset `classmethod` ¶

from_preset(name: str, **overrides: Any) -> IsohedralTiling

A tiling from a named preset, see list_presets.

Parameters:

name (str) –

Preset name.
**overrides (Any, default: {} ) –

Replace arguments of the preset (parameters, edge_curves, edge_curve_modes, frame).

Raises:

ValueError –

If the name is unknown or the result is not a valid tiling.

with_frame ¶

with_frame(frame: ArrayLike) -> IsohedralTiling

The same type, parameters and edge curves with the frame replaced.

The prototile is not checked again: a frame does not change validity.

Raises:

ValueError –

If the frame is not a finite (2, 3) array with a regular linear part.

rotated ¶

rotated(angle_degrees: float) -> IsohedralTiling

A copy rotated counterclockwise about the world origin.

scaled ¶

scaled(factor: float) -> IsohedralTiling

A copy scaled about the world origin.

with_parameters ¶

with_parameters(parameters: ArrayLike) -> IsohedralTiling

The same type, edge curves and frame with the parameters replaced; this tiling is unchanged.

Raises:

InvalidPrototileError –

If the prototile or its outline with the curves is not valid at the parameters (a ValueError).
ValueError –

If the number of parameters is wrong.

with_edge_curves ¶

with_edge_curves(
    edge_curves: Mapping[int, ArrayLike] | None,
    edge_curve_modes: Mapping[int, str] | None = None,
) -> IsohedralTiling

The same type, parameters and frame with the edge curves replaced (None removes all curves).

Raises:

ValueError –

As the constructor, if the curves are malformed.
InvalidPrototileError –

If the outline is not valid (a ValueError).

prototile ¶

prototile(
    normalized: bool = False,
    *,
    curved: bool = True,
    n_points: int | None = None,
) -> Array

(M, 2) closed outline of the prototile in world coordinates, without the repeated first point.

The outline starts at vertex 0 and runs along the edges in order; each edge with a curve contributes its samples, the others only their start vertex. Without curves (or with curved=False) the outline is vertices.

With normalized the outline is translated so that the centroid of the straight prototile is at the origin and scaled to unit area of the straight prototile (the curved prototile has the same area).

Parameters:

normalized (bool, default: False ) –
curved (bool, default: True ) –

Replace the edges by their curves.
n_points (int, default: None ) –

Samples per spline edge, see interpolate. It only sets how finely the outline is drawn; validity does not depend on it.

edge_outlines ¶

edge_outlines(
    curved: bool = True, *, n_points: int | None = None
) -> list[Array]

One polyline per edge in world coordinates, from vertex i to vertex i + 1.

Parameters:

curved (bool, default: True ) –

Use the curves; otherwise every edge is the segment between its vertices.
n_points (int, default: None ) –

Samples per spline edge, see interpolate.

Returns:

list of (k_i, 2) ndarray –

Edge i has at least 2 points (its end vertices); consecutive edges share their end points.

info ¶

info() -> dict[str, Any]

Metadata of the type as in TilingType.info, for the current parameters.

Adds the key parameter_values (the current parameters) and, in each entry of parameters, the key value. default_parameters and default keep the type's defaults.

describe ¶

describe() -> str

Human-readable summary of the type with the current parameter values, see TilingType.describe.

to_dict ¶

to_dict() -> dict[str, Any]

The tiling as a JSON-compatible dict: type, parameters, edge curves and modes, frame.

The format is described in isotile.io.

from_dict `classmethod` ¶

from_dict(data: Mapping[str, Any]) -> IsohedralTiling

The tiling that a dict from to_dict describes.

Raises:

ValueError –

If the data are not a valid version 1.x tiling.

save ¶

save(path: str | Path) -> None

Write the tiling to a JSON file, see isotile.io.save.

load `classmethod` ¶

load(path: str | Path) -> IsohedralTiling

Read a tiling from a JSON file written by save.

tiles ¶

tiles(cell: ArrayLike, aspect: ArrayLike) -> TileSet

The tiles with the given cells and aspects.

Parameters:

cell ((n, 2) array-like of int) –

Cells (u, v).
aspect (int or (n,) array-like of int) –

Aspect of each tile; a single value applies to all cells.

Returns:

TileSet –

Raises:

ValueError –

If an aspect is outside [0, n_aspects).

fill ¶

fill(bounds: Bounds) -> TileSet

Tiles generated by the scanline fill of the rectangle, in scanline order, without repeats.

Every cell whose origin lies in the rectangle (floor on the lower side, 1e-7 slack on the upper side, one extra row at the top) contributes all its aspects. Tiles near the boundary may reach outside the rectangle and tiles outside it may reach in; use cover for exact coverage.

Parameters:

bounds ((x0, y0, x1, y1)) –

The rectangle.

Returns:

TileSet –

cover ¶

cover(
    bounds: Bounds, *, outline: Outline = None
) -> TileSet

All tiles whose polygon overlaps the rectangle bounds with positive area.

Parameters:

bounds ((x0, y0, x1, y1)) –

The rectangle.
outline (('straight', 'curved', None), default: "straight" ) –

The polygon of a tile that is tested: the straight-edge polygon, or the polygon with the edge curves (TileSet.outlines at the default sampling). With "curved" the tiles cover the rectangle completely, also where the curves of a tile reach into it while its straight polygon does not. None means "curved" if the tiling has an edge curve (any entry of edge_curves) and "straight" otherwise; a tiling without edge curves always takes the straight test, and "straight" gives the tiles of the straight test for any tiling.

Returns:

TileSet –

The tiles sorted by cell u, then v, then aspect.

Raises:

ValueError –

If the rectangle does not have x1 > x0 and y1 > y0 (a region of zero width or height has no positive-area overlap) or has non-finite bounds, or if outline is not "straight", "curved" or None.

Notes

A tile that only touches the rectangle at a point or along an edge is not included. The overlap area must exceed 1e-9 times the tile area, which separates real overlaps from rounding errors at contacts. The test is exact for any simple polygon, convex or not: after a bounding-box prefilter the polygon is clipped against the four sides of the rectangle (Sutherland-Hodgman, vectorized over the tiles) and the area of the result is measured. With outline="curved" the polygon is the sampled curved outline; the prefilter is the bounding box of the convex hull of the outline; tiles whose hull lies inside the rectangle are kept without clipping, so only the tiles along the boundary of the rectangle are clipped.

fill_region ¶

fill_region(
    bounds: Bounds,
    *,
    n_tiles: int | None = None,
    tile_size: float | None = None,
    margin: float = 0.0,
    offset: tuple[float, float] = (0.0, 0.0),
    outline: Outline = None,
) -> TileSet

Tiles that cover a region, with the tile size set by a tile count or given directly.

The tile area is the area of the straight prototile. The frame of this tiling gives the orientation (its linear part is scaled by tile_size / sqrt(area)); its own scale and position are replaced: the type's native origin is placed at the center of the region.

The lattice is anchored at the center of the region (after the margin is applied). A region that is expanded by the same amount on all four sides therefore keeps the lattice at the same tile size: every tile of the region is a tile of the expanded region. offset moves the anchor.

Parameters:

bounds ((x0, y0, x1, y1)) –

The region, a rectangle.
n_tiles (int, default: None ) –

Target number of tiles. The tile size is sqrt(region_area / n_tiles), so the tiles that fit into the area have that count; the tiles along the boundary that reach into the region come on top.
tile_size (float, default: None ) –

Square root of the area of one tile. Give exactly one of n_tiles and tile_size.
margin (float, default: 0.0 ) –

The region is expanded on every side by margin times its width (left and right) or height (top and bottom).
offset ((u, v), default: (0.0, 0.0) ) –

The lattice is anchored at the center of the region plus u * translation_u + v * translation_v of the placed tiling, so u and v are in multiples of the two translation vectors. Changing u or v by an integer gives the same tile set; a fraction moves the lattice relative to the region.
outline (('straight', 'curved', None), default: "straight" ) –

The polygon of a tile that is tested for overlap, see cover; None selects the curved polygon for a tiling with edge curves.

Returns:

TileSet –

cover of the expanded region by the resulting tiling (the tiles that overlap the region with positive area), available as tiles.tiling.

Raises:

ValueError –

If both or neither of n_tiles and tile_size are given, if a value is not positive, if the bounds are empty, if margin <= -0.5 or if offset is not a pair of finite numbers.

isotile.TileSet `dataclass` ¶

TileSet(
    tiling: IsohedralTiling,
    cell: IntArray,
    aspect: IntArray,
    transforms: Array,
)

Tiles of a tiling: cell (u, v), aspect and affine transform of each tile.

Attributes:

tiling (IsohedralTiling) –

The tiling that the tiles belong to.
cell ((n, 2) int) –

Columns u and v: the tile's cell in the basis of the translation vectors.
aspect ((n,) int) –

Index of the tile within its cell.
transforms ((n, 2, 3)) –

Affine map of the prototile onto each tile.

Methods:

select –

The tiles that a boolean mask or an integer index array selects.
vertices –

(n, n_vertices, 2) straight-edge tile polygons, in world coordinates.
outlines –

(n, M, 2) tile outlines in world coordinates: the prototile outline mapped onto each tile.
polygons –

The tiles as a list of shapely polygons (needs the shapely extra), with curved edges by default.
to_geojson –

The tiles as a GeoJSON FeatureCollection dict (no shapely needed).
save_geojson –

Write to_geojson as a JSON file (UTF-8, ending with a newline).
colors –

(n,) color index of each tile from the type's coloring table.
adjacency –

(n, n) boolean sparse adjacency from the lattice table of the type.
neighbors –

Indices of the tiles adjacent to tile i, sorted.
neighbor_lists –

Sorted indices of the adjacent tiles of every tile, from one adjacency matrix.

centroids `property` ¶

centroids: Array

(n, 2) centroids of the tiles.

select ¶

select(mask: NDArray[bool_] | IntArray) -> TileSet

The tiles that a boolean mask or an integer index array selects.

Parameters:

mask ((n,) array of bool or of int) –

Boolean mask over the tiles, or indices of the tiles to keep.

Returns:

TileSet –

vertices ¶

vertices() -> Array

(n, n_vertices, 2) straight-edge tile polygons, in world coordinates.

outlines ¶

outlines(
    curved: bool = True, *, n_points: int | None = None
) -> Array

(n, M, 2) tile outlines in world coordinates: the prototile outline mapped onto each tile.

With curved (the default) the edges are replaced by their curves, see IsohedralTiling.prototile; otherwise the outlines are vertices. Tiles that share an edge share the points of its curve.

polygons ¶

polygons(
    curved: bool = True, *, n_points: int | None = None
) -> list[Any]

The tiles as a list of shapely polygons (needs the shapely extra), with curved edges by default.

The polygons are the outlines of the tiles.

Raises:

ImportError –

If shapely is not installed.

to_geojson ¶

to_geojson(
    properties: Mapping[str, ArrayLike] | None = None,
    *,
    curved: bool = True,
    n_points: int | None = None,
) -> dict[str, Any]

The tiles as a GeoJSON FeatureCollection dict (no shapely needed).

Each tile is a Polygon feature whose ring is the tile outline, closed by repeating the first point and oriented counterclockwise. The properties of a feature are cell ([u, v]), aspect and color of the tile, plus the entries of properties. The dict can be passed to json.dumps.

Parameters:

properties (mapping of str to (n,) array-like, default: None ) –

Further properties: the value of each key for the tile i is element i. A key that is already a property of the tile replaces it.
curved (bool, default: True ) –

Use the curved edges, as in outlines.
n_points (int, default: None ) –

Samples per spline edge, see interpolate.

Raises:

ValueError –

If a value of properties does not have one element per tile.

save_geojson ¶

save_geojson(
    path: str | Path,
    properties: Mapping[str, ArrayLike] | None = None,
    *,
    curved: bool = True,
    n_points: int | None = None,
) -> None

Write to_geojson as a JSON file (UTF-8, ending with a newline).

An existing file is overwritten. The arguments are those of to_geojson.

colors ¶

colors() -> IntArray

(n,) color index of each tile from the type's coloring table.

adjacency ¶

adjacency(kind: AdjacencyKind = 'edge') -> csr_array

(n, n) boolean sparse adjacency from the lattice table of the type.

Pairs where one tile is not in the set are dropped.

Parameters:

kind (('edge', 'vertex', 'vertex-only'), default: "edge" ) –

"edge": the tiles share an edge; "vertex": they share an edge or a vertex; "vertex-only": they share exactly a vertex.

Returns:

csr_array –

Symmetric boolean matrix; entry (i, j) is true if tile j is adjacent to tile i.

neighbors ¶

neighbors(i: int, kind: AdjacencyKind = 'edge') -> IntArray

Indices of the tiles adjacent to tile i, sorted.

Parameters:

i (int) –

Index of the tile in this tile set.
kind (('edge', 'vertex', 'vertex-only'), default: "edge" ) –

Kind of adjacency, see adjacency.

Notes

Each call builds the adjacency matrix of the whole tile set. For the neighbors of many tiles use neighbor_lists, which builds it once.

neighbor_lists ¶

neighbor_lists(
    kind: AdjacencyKind = "edge",
) -> list[IntArray]

Sorted indices of the adjacent tiles of every tile, from one adjacency matrix.

Parameters:

kind (('edge', 'vertex', 'vertex-only'), default: "edge" ) –

Kind of adjacency, see adjacency.

Returns:

list of (k,) int arrays –

Entry i equals neighbors(i, kind); the list is empty for an empty tile set.

Tilings and tile sets¶

isotile.IsohedralTiling ¶

parameters property writable ¶

frame property ¶

vertices property ¶

aspects property ¶

translations property ¶

translation_u property ¶

translation_v property ¶

edge_transforms property ¶

edge_reversed property ¶

edge_shape_ids property ¶

edge_shapes property ¶

edge_curves property ¶

edge_curve_modes property ¶

edges property ¶

area property ¶

centroid property ¶

inscribed_radius property ¶

square classmethod ¶

hexagon classmethod ¶

triangle classmethod ¶

quadrilateral classmethod ¶

from_preset classmethod ¶

with_frame ¶

rotated ¶

scaled ¶

with_parameters ¶

with_edge_curves ¶

prototile ¶

edge_outlines ¶

info ¶

describe ¶

to_dict ¶

from_dict classmethod ¶

save ¶

load classmethod ¶

tiles ¶

fill ¶

cover ¶

fill_region ¶

isotile.TileSet dataclass ¶

centroids property ¶

select ¶

vertices ¶

outlines ¶

polygons ¶

to_geojson ¶

save_geojson ¶

colors ¶

adjacency ¶

neighbors ¶

neighbor_lists ¶

parameters `property` `writable` ¶

frame `property` ¶

vertices `property` ¶

aspects `property` ¶

translations `property` ¶

translation_u `property` ¶

translation_v `property` ¶

edge_transforms `property` ¶

edge_reversed `property` ¶

edge_shape_ids `property` ¶

edge_shapes `property` ¶

edge_curves `property` ¶

edge_curve_modes `property` ¶

edges `property` ¶

area `property` ¶

centroid `property` ¶

inscribed_radius `property` ¶

square `classmethod` ¶

hexagon `classmethod` ¶

triangle `classmethod` ¶

quadrilateral `classmethod` ¶

from_preset `classmethod` ¶

from_dict `classmethod` ¶

load `classmethod` ¶

isotile.TileSet `dataclass` ¶

centroids `property` ¶