Merge pull request #340 from jeffeb3/feature/flow-tiles

Flow tiles

Author: jeffeb3

src/features/shapes/flow_tile/FlowTile.js

@@ -0,0 +1,154 @@
+import FlowTile from "./FlowTile"
+import { tileRenderers } from "./tileRenderers"
+import { tileBounds, getEdgePoints, getEdgeMidpoints } from "./geometry"
+
+describe("FlowTile", () => {
+  let shape
+
+  beforeEach(() => {
+    shape = new FlowTile()
+  })
+
+  describe("drawOuterBorder", () => {
+    it("creates segments for tile perimeter", () => {
+      const segments = shape.drawOuterBorder(3, 3)
+
+      // Each edge has 2 segments per tile (split at midpoint)
+      // 3 tiles per edge * 2 segments * 4 edges = 24 segments
+      expect(segments.length).toBe(24)
+    })
+
+    it("segments connect at tile midpoints", () => {
+      const segments = shape.drawOuterBorder(2, 2)
+      const topSegments = segments.slice(0, 4) // First 4 are top edge
+
+      // Check midpoint connections
+      expect(topSegments[0][1].x).toBe(topSegments[1][0].x)
+      expect(topSegments[0][1].y).toBe(topSegments[1][0].y)
+    })
+  })
+})
+
+describe("tileRenderers", () => {
+  const bounds = tileBounds(0, 0, 2)
+
+  describe("Arc", () => {
+    it("produces 2 arc paths without stroke", () => {
+      const paths = tileRenderers.Arc(bounds, 0, 0, false)
+
+      expect(paths.length).toBe(2)
+    })
+
+    it("produces 4 paths with stroke (inner/outer for each arc)", () => {
+      const paths = tileRenderers.Arc(bounds, 0, 0.25, false)
+
+      expect(paths.length).toBe(4)
+    })
+
+    it("produces 6 paths with border (2 arcs + 4 border segments)", () => {
+      const paths = tileRenderers.Arc(bounds, 0, 0, true)
+
+      expect(paths.length).toBe(6)
+    })
+
+    it("produces different paths for different orientations", () => {
+      const paths0 = tileRenderers.Arc(bounds, 0, 0, false)
+      const paths1 = tileRenderers.Arc(bounds, 1, 0, false)
+
+      // Arc endpoints should differ between orientations
+      const start0 = paths0[0][0]
+      const start1 = paths1[0][0]
+
+      expect(start0.x === start1.x && start0.y === start1.y).toBe(false)
+    })
+  })
+
+  describe("Diagonal", () => {
+    it("produces 2 line paths without stroke", () => {
+      const paths = tileRenderers.Diagonal(bounds, 0, 0, false)
+
+      expect(paths.length).toBe(2)
+    })
+
+    it("produces 4 paths with stroke", () => {
+      const paths = tileRenderers.Diagonal(bounds, 0, 0.3, false)
+
+      expect(paths.length).toBe(4)
+    })
+
+    it("produces 6 paths with border", () => {
+      const paths = tileRenderers.Diagonal(bounds, 0, 0, true)
+
+      expect(paths.length).toBe(6)
+    })
+
+    it("line paths have 2 points each", () => {
+      const paths = tileRenderers.Diagonal(bounds, 0, 0, false)
+
+      expect(paths[0].length).toBe(2)
+      expect(paths[1].length).toBe(2)
+    })
+  })
+})
+
+describe("geometry", () => {
+  describe("tileBounds", () => {
+    it("computes bounds centered on given point", () => {
+      const bounds = tileBounds(4, 6, 2)
+
+      expect(bounds.cx).toBe(4)
+      expect(bounds.cy).toBe(6)
+      expect(bounds.left).toBe(3)
+      expect(bounds.right).toBe(5)
+      expect(bounds.top).toBe(5)
+      expect(bounds.bottom).toBe(7)
+    })
+
+    it("defaults to size 2", () => {
+      const bounds = tileBounds(0, 0)
+
+      expect(bounds.size).toBe(2)
+      expect(bounds.right - bounds.left).toBe(2)
+    })
+  })
+
+  describe("getEdgePoints", () => {
+    it("returns midpoints for fraction 0.5", () => {
+      const bounds = tileBounds(0, 0, 2)
+      const points = getEdgePoints(bounds, [0.5])
+
+      expect(points.left[0].x).toBe(-1)
+      expect(points.left[0].y).toBe(0)
+      expect(points.right[0].x).toBe(1)
+      expect(points.right[0].y).toBe(0)
+      expect(points.top[0].x).toBe(0)
+      expect(points.top[0].y).toBe(-1)
+      expect(points.bottom[0].x).toBe(0)
+      expect(points.bottom[0].y).toBe(1)
+    })
+
+    it("returns multiple points for multiple fractions", () => {
+      const bounds = tileBounds(0, 0, 3)
+      const points = getEdgePoints(bounds, [1 / 3, 2 / 3])
+
+      expect(points.left.length).toBe(2)
+      expect(points.top.length).toBe(2)
+    })
+  })
+
+  describe("getEdgeMidpoints", () => {
+    it("returns named midpoint properties", () => {
+      const bounds = tileBounds(0, 0, 2)
+      const { midLeft, midRight, midTop, midBottom } = getEdgeMidpoints(bounds)
+
+      expect(midLeft.x).toBe(-1)
+      expect(midLeft.y).toBe(0)
+      expect(midRight.x).toBe(1)
+      expect(midRight.y).toBe(0)
+      expect(midTop.x).toBe(0)
+      expect(midTop.y).toBe(-1)
+      expect(midBottom.x).toBe(0)
+      expect(midBottom.y).toBe(1)
+    })
+  })
+})

src/features/shapes/flow_tile/FlowTile.spec.js

@@ -0,0 +1,48 @@
+# Flow Tile (Truchet)
+
+Generates Truchet tiling patterns - square tiles with two orientations that connect to form continuous flowing paths.
+
+## Architecture
+
+Tiles are drawn independently, then unified into a single continuous path:
+
+1. **Draw tiles**: Each tile generates arc/line paths based on its orientation (determined by seed + noise).
+
+2. **Draw outer border**: Perimeter segments connect tile edges to form a closed boundary.
+
+3. **Build graph**: Path endpoints become nodes; paths become edges with stored vertex data.
+
+4. **Connect components**: Disconnected subgraphs are bridged via MST.
+
+5. **Eulerize**: Duplicate edges added for odd-degree vertices (Chinese Postman).
+
+6. **Traverse**: Eulerian trail visits every edge exactly once, expanding stored paths.
+
+This produces a single continuous drawing path.
+
+## Tile Styles
+
+| Style | Connection Points | Description |
+|-------|-------------------|-------------|
+| Arc | Edge midpoints (1/2) | Quarter-circle arcs at opposite corners. Classic Smith Truchet. |
+| Diagonal | Edge midpoints (1/2) | Straight lines connecting opposite edges. Maze-like patterns. |
+
+## Potential Enhancements
+
+**Tile Styles**
+- **Multiscale Truchet**: [Carlson's multi-scale patterns](https://christophercarlson.com/portfolio/multi-scale-truchet-patterns/) - recursive subdivision where any tile can be replaced by four smaller tiles.
+- **Maze tiles**: 4-gate connections (straight, corner, T, cross) for true maze generation.
+- **Weave tiles**: Over/under crossings with alternating pattern.
+
+**Grid Variations** (would require new shape or significant refactor - tile geometry, borders, and stroke width are grid-specific; path connection logic is reusable)
+- **Hexagonal**: 3 arc variations per tile, weave-like patterns. See [SciPython](https://scipython.com/blog/hexagonal-truchet-tiling/).
+- **Triangle**: 2 points per edge, 3 tile types. See [Bridges 2020](https://www.archive.bridgesmathart.org/2020/bridges2020-191.pdf).
+
+**Other**
+- **Orientation bias**: Slider to control probability of orientation 0 vs 1.
+
+## References
+
+- [Wikipedia: Truchet tiles](https://en.wikipedia.org/wiki/Truchet_tiles)
+- [Carlson: Multi-Scale Truchet Patterns](https://christophercarlson.com/portfolio/multi-scale-truchet-patterns/)
+- [Bridges 2018 Paper](https://archive.bridgesmathart.org/2018/bridges2018-39.html) - Carlson's original paper on multi-scale patterns

src/features/shapes/flow_tile/README.md

@@ -0,0 +1,42 @@
+import Victor from "victor"
+
+// Compute bounding box for a tile centered at (cx, cy)
+export function tileBounds(cx, cy, size = 2) {
+  const half = size / 2
+
+  return {
+    left: cx - half,
+    right: cx + half,
+    top: cy - half,
+    bottom: cy + half,
+    cx,
+    cy,
+    size,
+  }
+}
+
+// Get connection points along tile edges at specified fractions
+export function getEdgePoints(bounds, fractions = [0.5]) {
+  const { left, right, top, bottom } = bounds
+  const width = right - left
+  const height = bottom - top
+
+  return {
+    left: fractions.map((f) => new Victor(left, top + height * f)),
+    right: fractions.map((f) => new Victor(right, top + height * f)),
+    top: fractions.map((f) => new Victor(left + width * f, top)),
+    bottom: fractions.map((f) => new Victor(left + width * f, bottom)),
+  }
+}
+
+// Get edge midpoints as named properties
+export function getEdgeMidpoints(bounds) {
+  const edgePoints = getEdgePoints(bounds, [0.5])
+
+  return {
+    midLeft: edgePoints.left[0],
+    midRight: edgePoints.right[0],
+    midTop: edgePoints.top[0],
+    midBottom: edgePoints.bottom[0],
+  }
+}