quickpaver.gen_triangular_tiling#

quickpaver.gen_triangular_tiling(surface_to_cover: Polygon | MultiPolygon, edge_length: float, anisotropy_ratio: float = 1.0, alignment_point: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None) → Tuple[MultiPolygon, Dict[int, List[int]]][source]#

Generate a triangular tiling covering a given surface.

The tiling is generated from a triangular vertex lattice. Each elementary parallelogram of the lattice is split into two triangles, which guarantees exact edge sharing and avoids the centre/parity shift issues that can occur when triangles are generated independently from alternating centres.

The triangular lattice is defined by two primitive vectors:

a = (edge_length, 0)

b = (edge_length / 2, sqrt(3) / 2 * edge_length * anisotropy_ratio)

For each lattice node p, two triangles are created:

  • lower/right triangle: (p, p + a, p + b)

  • upper/left triangle: (p + a, p + a + b, p + b)

If alignment_point is provided, the lattice is shifted so that the centroid of one triangle lies exactly on this point. More precisely, the centroid of the triangle (p, p + a, p + b) is aligned with alignment_point.

Parameters:

  • surface_to_cover (Union[shapely.Polygon, shapely.MultiPolygon]) – Surface to cover with triangular tiles. Only triangles intersecting this surface are kept in the returned tiling.

  • edge_length (float) – Edge length of the triangles before anisotropic vertical scaling.

  • anisotropy_ratio (float, optional) – Vertical anisotropy ratio applied to the triangle height, by default 1.0. A value larger than 1 stretches the triangular lattice vertically.

  • alignment_point (Optional[ArrayLike], optional) – World-space coordinate (x, y) used to align the tiling. If provided, one triangle centroid is guaranteed to coincide exactly with this point. If None, the lower-left corner of the surface bounding box is used as the default aligned triangle centroid.

Returns:

A tuple containing:

  • A shapely.MultiPolygon with all triangles intersecting surface_to_cover.

  • An adjacency dictionary mapping each kept triangle index to the list of neighbouring kept triangle indices sharing at least one rounded vertex.

Return type:

Tuple[shapely.MultiPolygon, Dict[int, List[int]]]

Raises:

  • ValueError – If edge_length is not strictly positive.

  • ValueError – If anisotropy_ratio is not strictly positive.

Notes

This implementation intentionally uses a vertex lattice instead of a centre lattice. This is usually the most stable construction for triangular tilings because all shared edges and vertices are generated from the same coordinates.