dcel
API
Generated with
dcel/io.github.scala_tessella.dcel

io.github.scala_tessella.dcel

package io.github.scala_tessella.dcel

Members list

Packages

package io.github.scala_tessella.dcel.conversion
package io.github.scala_tessella.dcel.delaney
package io.github.scala_tessella.dcel.geometry
package io.github.scala_tessella.dcel.structure

Type members

Classlikes

enum ErrorCategory(val label: String, val build: String => TilingError)

The error category carries its own user-facing label and the factory that builds the corresponding TilingError from a message string. NotFoundError is intentionally excluded: it carries two fields and does not fit the single-string factory shape used by TilingError.combineErrors.

The error category carries its own user-facing label and the factory that builds the corresponding TilingError from a message string. NotFoundError is intentionally excluded: it carries two fields and does not fit the single-string factory shape used by TilingError.combineErrors.

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class GeometryError(message: String) extends TilingError

An interior angle is invalid (e.g. a full circle on a single edge) or an angle vector — for an inner face, for the boundary's interior view, for the boundary's exterior view, or around an interior vertex — does not close to a valid simple polygon or to 360°. Surfaced by the geometry stage of TilingValidation.validate.

An interior angle is invalid (e.g. a full circle on a single edge) or an angle vector — for an inner face, for the boundary's interior view, for the boundary's exterior view, or around an interior vertex — does not close to a valid simple polygon or to 360°. Surfaced by the geometry stage of TilingValidation.validate.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait TilingError
class Object
trait Matchable
class Any
Show all
case class IncompleteError(message: String) extends TilingError

A vertex, half-edge or face is missing required state (e.g. a vertex without a leaving edge, a half-edge without an incident face). Returned by the completeness stage of TilingValidation.validate; on failure, the later checks are not run.

A vertex, half-edge or face is missing required state (e.g. a vertex without a leaving edge, a half-edge without an incident face). Returned by the completeness stage of TilingValidation.validate; on failure, the later checks are not run.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait TilingError
class Object
trait Matchable
class Any
Show all
enum Isometry

A rigid motion of the plane, used to describe the copy added by TilingDCEL.maybeAddCopy. The four cases are the four plane isometries (distance-preserving): translation and rotation preserve orientation, reflection and glide reflection reverse it. Scaling is deliberately excluded — it would break the unit-edge invariant. See ADR-0011.

A rigid motion of the plane, used to describe the copy added by TilingDCEL.maybeAddCopy. The four cases are the four plane isometries (distance-preserving): translation and rotation preserve orientation, reflection and glide reflection reverse it. Scaling is deliberately excluded — it would break the unit-edge invariant. See ADR-0011.

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class NotFoundError(entity: String, id: String) extends TilingError

A lookup by VertexId or FaceId did not match any entity in the tiling. Carries the queried entity label (e.g. "Vertex") and the id string for structured matching.

A lookup by VertexId or FaceId did not match any entity in the tiling. Carries the queried entity label (e.g. "Vertex") and the id string for structured matching.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait TilingError
class Object
trait Matchable
class Any
Show all
case class PeriodicityError(message: String) extends TilingError

The patch has no detectable translation lattice, or its lattice quotient is inconsistent (a candidate period that is not a genuine symmetry, or a patch too small to cover a fundamental domain). Surfaced by the Delaney–Dress pipeline (TilingDelaney): exact uniformity is a property of the periodic tiling a patch samples, so a patch that cannot be recognised as periodic has no exact answer — this error is that honest outcome (ADR-0019).

The patch has no detectable translation lattice, or its lattice quotient is inconsistent (a candidate period that is not a genuine symmetry, or a patch too small to cover a fundamental domain). Surfaced by the Delaney–Dress pipeline (TilingDelaney): exact uniformity is a property of the periodic tiling a patch samples, so a patch that cannot be recognised as periodic has no exact answer — this error is that honest outcome (ADR-0019).

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait TilingError
class Object
trait Matchable
class Any
Show all
case class SpatialError(message: String) extends TilingError

Coordinate-level conflict: the boundary is not a simple polygon, two vertices share a position, an edge is not of unit length, or two edges properly intersect. Surfaced by the spatial stage of TilingValidation.validate and by SimplePolygon.fromUntrusted when the candidate fails the sweep-line simplicity check.

Coordinate-level conflict: the boundary is not a simple polygon, two vertices share a position, an edge is not of unit length, or two edges properly intersect. Surfaced by the spatial stage of TilingValidation.validate and by SimplePolygon.fromUntrusted when the candidate fails the sweep-line simplicity check.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait TilingError
class Object
trait Matchable
class Any
Show all
object Tiling

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
Tiling.type
object TilingAddition

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object TilingBuilder

Constructors for TilingDCEL instances. Two families:

Constructors for TilingDCEL instances. Two families:

All constructors validate their inputs and return Either[TilingError, Tiling] (regular polygon is the one exception: its construction cannot fail). The constructed tilings are certified Tiling values — guaranteed by construction to satisfy the full DCEL invariants (ADR-0017).

This object owns input validation and the single-polygon builds; the lattice-construction plumbing lives in the package-private TilingNetBuilder.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
final case class TilingDCEL

An edge-to-edge tessellation of unit-side polygons, modelled as a Doubly Connected Edge List (DCEL): each edge is represented by two oppositely oriented half-edges, and each half-edge knows its origin vertex, incident face, twin, predecessor and successor. The tiling has exactly one unbounded outerFace; all other faces are inner.

An edge-to-edge tessellation of unit-side polygons, modelled as a Doubly Connected Edge List (DCEL): each edge is represented by two oppositely oriented half-edges, and each half-edge knows its origin vertex, incident face, twin, predecessor and successor. The tiling has exactly one unbounded outerFace; all other faces are inner.

This is the raw, uncertified structure: queries live here, but every mutating operation lives on Tiling, the certified subtype proving its value passed TilingValidation.validate (ADR-0017). Consumers normally hold a Tiling, obtained from the companion's smart constructors (TilingDCEL.createRegularPolygon, TilingDCEL.createSimplePolygon, TilingDCEL.fromUntrusted), from TilingBuilder for lattices and rings, or by certifying a raw value with Tiling.from. The primary constructor is private to enforce validation on untrusted input.

Mutating operations on Tiling return a fresh Either[TilingError, Tiling] and operate on an internal deep copy — the original is never modified.

Value parameters

halfEdges

All half-edges in the tiling (each edge appears twice, once per direction).

innerFaces

The tiling's bounded interior faces.

outerFace

The single unbounded outer face.

vertices

All vertices in the tiling.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object TilingDCEL

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
TilingDCEL.type
object TilingDelaney

The bridge from a periodic DCEL patch to its Delaney–Dress symbol (ADR-0019): exact uniformity, gonality, symmetry and tiling identity.

The bridge from a periodic DCEL patch to its Delaney–Dress symbol (ADR-0019): exact uniformity, gonality, symmetry and tiling identity.

Pipeline: detect the translation lattice (TilingLattice.translationLattice, the one heuristic step) → quotient the patch by the lattice into a CLOSED torus map (every vertex, edge and face keyed by its position modulo the lattice) → encode its barycentric chambers (two per half-edge; σ₀ swaps the endpoint, σ₁ follows next/prev within the face, σ₂ crosses to the twin) → classify via delaney.DelaneySymbols.classifyTorusMap. The minimal symbol divides out whatever extra symmetry the chosen cell hid, so the result does not depend on which fundamental domain the lattice detector anchored.

Failures surface as PeriodicityError (ADR-0004): a patch with no detectable lattice, a candidate period that is not a genuine symmetry, or a patch too small to cover a fundamental domain has no exact answer, and says so instead of returning a number.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object TilingDeletion

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object TilingEquivalency

Structural comparison of FINITE PATCHES: deep copies, structural/reflectional traversal equivalence, and the boundary-signature grouping. These compare concrete patches as built; for the identity of the PERIODIC TILING a patch samples — equality up to isomorphism, independent of the patch cut — use the minimal-symbol canonicalKey from TilingDelaney.delaneyClassification.

Structural comparison of FINITE PATCHES: deep copies, structural/reflectional traversal equivalence, and the boundary-signature grouping. These compare concrete patches as built; for the identity of the PERIODIC TILING a patch samples — equality up to isomorphism, independent of the patch cut — use the minimal-symbol canonicalKey from TilingDelaney.delaneyClassification.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
sealed trait TilingError

Failure outcome returned in the Left of any Either[TilingError, _] produced by the library.

Failure outcome returned in the Left of any Either[TilingError, _] produced by the library.

Errors fall into a small set of categories that signal what kind of invariant was broken:

  • ValidationError — an operation precondition or argument is wrong (typical of maybeAdd* / maybeDelete* calls), or TilingValidation.validate is reporting an aggregate failure of the topology / geometry / spatial checks.
  • IncompleteError — a vertex, half-edge or face has unset or inconsistent internal state.
  • TopologyError — half-edge linkage (twin / next / prev / incident-face) or a face cycle is broken, or a deletion would partition the tiling.
  • GeometryError — interior angles are invalid or the inner-face / boundary angle vector does not close to a simple polygon.
  • SpatialError — coordinates conflict: two vertices share a position, an edge is not unit length, or two edges properly intersect.
  • PeriodicityError — the patch is not recognisably periodic, or its lattice quotient is inconsistent; the Delaney–Dress pipeline (TilingDelaney, ADR-0019) has no exact answer for it.
  • NotFoundError — a lookup by VertexId or FaceId matched no entity in the tiling.

All variants carry a human-readable message; NotFoundError additionally carries the queried entity type and id for structured matching. See TilingError.combineErrors for the helper used to fold multiple per-check messages into a single error of a chosen category.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class SpatialError
Show all
object TilingError

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
object TilingLattice

Largest parallelogon contained in a tiling (ADR-0015) and the translation-lattice detection it builds on.

Largest parallelogon contained in a tiling (ADR-0015) and the translation-lattice detection it builds on.

Public API (extensions on TilingDCEL): largestContainedParallelogon (ordered corner vertices, the headline query) and translationLattice (the reduced primitive basis). The block view (cell dimensions

  • area) behind the corners is kept package-private until a consumer needs it.

Detects the primitive translation lattice {v, w} of a finite periodic patch from its interior structure. Vertices are typed by an orientation-aware signature (the sorted directions to their neighbours), then the lattice is read off the single most populous signature class — one translation orbit, whose pairwise differences are exactly the period lattice. This is robust to a handful of welded foreign faces (they form minority classes and stay invisible) and naturally excludes cross-orientation vectors (e.g. between 6.6.6's two [6,6,6] sublattices). A candidate is kept only if it has enough overlap with the patch, ruling out large vectors with little genuine support.

Candidates are validated structurally over the whole interior (signature-preserving on the overlap, a few welded-face defects tolerated), and the result is Lagrange–Gauss reduced to a canonical primitive basis.

Residual assumption: a vertex is typed only by its first neighbour ring, so two distinct translation orbits that happen to share a first-ring signature would be conflated. Regular tilings (3⁶, 4⁴, 6⁶, 4.8.8, …) do not exhibit this; a deeper (second-ring) signature would generalise it.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object TilingPatchSymmetry

The isometry group of the FINITE PATCH, found geometrically, and the vertex orbits under it (ADR-0020).

The isometry group of the FINITE PATCH, found geometrically, and the vertex orbits under it (ADR-0020).

This answers a question that is well posed for every patch, periodic or not: which vertices are carried onto each other by a rigid motion of the plane that maps the patch onto itself. Contrast the two neighbouring surfaces:

  • TilingDelaney.delaneyVertexClasses — orbits under the symmetry group of the INFINITE tiling the patch samples. Exact and patch-independent, but undefined when no lattice is detectable.
  • TilingSymmetry — the rotational order and reflection axes of the patch, read off its outer boundary. Same object as here, but it reports the axes rather than the induced vertex permutations, so it cannot produce orbits.

Every isometry of a bounded figure fixes its centroid, and the group is therefore finite and either cyclic or dihedral (Leonardo's theorem) — see PatchSymmetryGroup. That bound is what makes the search cheap: a symmetry must permute the vertices at maximal distance from the centroid, so fixing one such reference vertex leaves at most one rotation and one reflection per candidate image, and each is confirmed by applying it to the whole patch.

Matching is tolerance-based, not exact: coordinates are BigDecimal-typed but produced through Double trigonometry and so carry ~1e-12 of error (ADR-0009), the same reason TilingDelaney keys its quotient on rounded coordinates.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object TilingSymmetry

Symmetries of the FINITE PATCH as a drawn shape: rotations and reflections of its outer boundary that the internal structure preserves. This is a property of the patch, not of the infinite tiling it samples — for the symmetry group of the tiling itself (orbifold, cone orders, mirrors) see TilingDelaney.delaneyClassification's orbifoldSignature.

Symmetries of the FINITE PATCH as a drawn shape: rotations and reflections of its outer boundary that the internal structure preserves. This is a property of the patch, not of the infinite tiling it samples — for the symmetry group of the tiling itself (orbifold, cone orders, mirrors) see TilingDelaney.delaneyClassification's orbifoldSignature.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object TilingUniformity

Uniformity and gonality analysis for tilings, exposed as extension methods on TilingDCEL.

Uniformity and gonality analysis for tilings, exposed as extension methods on TilingDCEL.

The headline operation is the uniformity tree (TilingDCEL.uniformityTree / uniformityTreeUncompressed here): a hierarchical grouping of the tiling's inner vertices into equivalence classes based on the local DCEL structure around each vertex, refined at increasing vertex-distance. Two vertices end up in the same leaf iff their neighbourhoods are boundary-equivalent at every distance examined.

Related views:

  • scanUniformityTree — a sequence of trees showing the progressive refinement at each depth (only depths that actually split a class are kept), useful for animation.
  • gonalitySampleInnerVertexIds — one representative vertex per gonality class.
  • TilingDCEL.gonalityTrees — the gonality slice of the uniformity tree.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object TilingValidation

Validation entry point for TilingDCEL instances. The public validate method runs the full pipeline; the per-stage helpers (validateCompleteness, validateTopologically, validateGeometrically, validateSpatially) are internal and called in sequence by validate but exposed here for library-internal reuse.

Validation entry point for TilingDCEL instances. The public validate method runs the full pipeline; the per-stage helpers (validateCompleteness, validateTopologically, validateGeometrically, validateSpatially) are internal and called in sequence by validate but exposed here for library-internal reuse.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
case class TopologyError(message: String) extends TilingError

Half-edge linkage (twin / next / prev / incident-face) or a face cycle is broken, the outer face is unreachable, an inner face contains holes, or a deletion would partition the tiling into disconnected components. Surfaced by the topology stage of TilingValidation.validate and by maybeDelete* operations that would violate a topological invariant.

Half-edge linkage (twin / next / prev / incident-face) or a face cycle is broken, the outer face is unreachable, an inner face contains holes, or a deletion would partition the tiling into disconnected components. Surfaced by the topology stage of TilingValidation.validate and by maybeDelete* operations that would violate a topological invariant.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait TilingError
class Object
trait Matchable
class Any
Show all
enum Tree[A]

Attributes

Companion
object
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object Tree

Attributes

Companion
enum
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
Tree.type
object Utils

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
Utils.type
case class ValidationError(message: String) extends TilingError

Operation precondition or argument failed, or TilingValidation.validate aggregated several underlying validation failures into a single error.

Operation precondition or argument failed, or TilingValidation.validate aggregated several underlying validation failures into a single error.

Typical sources: a maybeAdd* / maybeDelete* call where the named vertex is not on the boundary, an edge is missing its twin, or the requested action would otherwise violate a precondition. Also the category used by validate to wrap a "Multiple validation errors: …" message when more than one of the topology / geometry / spatial checks fails.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait TilingError
class Object
trait Matchable
class Any
Show all

Types

opaque type Tiling

A TilingDCEL that is known to satisfy the full invariants of TilingValidation.validate — the compiler-checked form of ADR-0003's safe/Unsafe convention (ADR-0017).

A TilingDCEL that is known to satisfy the full invariants of TilingValidation.validate — the compiler-checked form of ADR-0003's safe/Unsafe convention (ADR-0017).

Tiling is an opaque subtype of TilingDCEL: every query, export and analysis extension defined on the raw type works on a Tiling unchanged, at zero runtime cost. What the type adds is provenance — a Tiling can only be obtained from

  • the public constructors (TilingBuilder and the TilingDCEL companion re-exports),
  • the mutating operations defined on Tiling itself (each returns Either[TilingError, Tiling]), or
  • Tiling.from, which runs the full validation on an arbitrary TilingDCEL.

The guarantee is "valid at wrap time, never mutable from outside the package": the structural wiring is private[dcel] and every mutating operation works on a deep copy (ADR-0002). Inside the package, every wrap goes through Tiling.trusted so the complete trust boundary is greppable.

Attributes

Generated with