@tscircuit/rectdiff 0.0.4 → 0.0.5

package/lib/solvers/rectdiff/gapfill/engine/initGapFillState.ts

@@ -0,0 +1,57 @@
+// lib/solvers/rectdiff/gapfill/engine/initGapFillState.ts
+import type { Placed3D } from "../../types"
+import type { GapFillState, GapFillOptions, LayerContext } from "../types"
+
+const DEFAULT_OPTIONS: GapFillOptions = {
+  minWidth: 0.1,
+  minHeight: 0.1,
+  maxIterations: 10,
+  targetCoverage: 0.999,
+  scanResolution: 0.5,
+}
+
+/**
+ * Initialize the gap fill state from existing rectdiff state.
+ */
+export function initGapFillState(
+  {
+    placed,
+    options,
+  }: {
+    placed: Placed3D[]
+    options?: Partial<GapFillOptions>
+  },
+  ctx: LayerContext,
+): GapFillState {
+  const opts = { ...DEFAULT_OPTIONS, ...options }
+
+  // Deep copy placed arrays to avoid mutation issues
+  const placedCopy = placed.map((p) => ({
+    rect: { ...p.rect },
+    zLayers: [...p.zLayers],
+  }))
+
+  const placedByLayerCopy = ctx.placedByLayer.map((layer) =>
+    layer.map((r) => ({ ...r })),
+  )
+
+  return {
+    bounds: { ...ctx.bounds },
+    layerCount: ctx.layerCount,
+    obstaclesByLayer: ctx.obstaclesByLayer,
+    placed: placedCopy,
+    placedByLayer: placedByLayerCopy,
+    options: opts,
+    iteration: 0,
+    gapsFound: [],
+    gapIndex: 0,
+    done: false,
+    initialGapCount: 0,
+    filledCount: 0,
+    // Four-stage visualization state
+    stage: "scan",
+    currentGap: null,
+    currentSeed: null,
+    expandedRect: null,
+  }
+}

package/lib/solvers/rectdiff/gapfill/engine/stepGapFill.ts

@@ -0,0 +1,128 @@
+// lib/solvers/rectdiff/gapfill/engine/stepGapFill.ts
+import type { GapFillState } from "../types"
+import { findAllGaps } from "../detection"
+import { tryExpandGap } from "./tryExpandGap"
+import { addPlacement } from "./addPlacement"
+
+/**
+ * Perform one step of gap filling with four-stage visualization.
+ * Stages: scan → select → expand → place
+ * Returns true if still working, false if done.
+ */
+export function stepGapFill(state: GapFillState): boolean {
+  if (state.done) return false
+
+  switch (state.stage) {
+    case "scan": {
+      // Stage 1: Gap detection/scanning
+
+      // Check if we need to find new gaps
+      if (
+        state.gapsFound.length === 0 ||
+        state.gapIndex >= state.gapsFound.length
+      ) {
+        // Check if we've hit max iterations
+        if (state.iteration >= state.options.maxIterations) {
+          state.done = true
+          return false
+        }
+
+        // Find new gaps
+        state.gapsFound = findAllGaps(
+          {
+            scanResolution: state.options.scanResolution,
+            minWidth: state.options.minWidth,
+            minHeight: state.options.minHeight,
+          },
+          {
+            bounds: state.bounds,
+            layerCount: state.layerCount,
+            obstaclesByLayer: state.obstaclesByLayer,
+            placedByLayer: state.placedByLayer,
+          },
+        )
+
+        if (state.iteration === 0) {
+          state.initialGapCount = state.gapsFound.length
+        }
+
+        state.gapIndex = 0
+        state.iteration++
+
+        // If no gaps found, we're done
+        if (state.gapsFound.length === 0) {
+          state.done = true
+          return false
+        }
+      }
+
+      // Move to select stage
+      state.stage = "select"
+      return true
+    }
+
+    case "select": {
+      // Stage 2: Show the gap being targeted
+      if (state.gapIndex >= state.gapsFound.length) {
+        // No more gaps in this iteration, go back to scan
+        state.stage = "scan"
+        return true
+      }
+
+      state.currentGap = state.gapsFound[state.gapIndex]!
+      state.currentSeed = {
+        x: state.currentGap.centerX,
+        y: state.currentGap.centerY,
+      }
+      state.expandedRect = null
+
+      // Move to expand stage
+      state.stage = "expand"
+      return true
+    }
+
+    case "expand": {
+      // Stage 3: Show expansion attempt
+      if (!state.currentGap) {
+        // Shouldn't happen, but handle gracefully
+        state.stage = "select"
+        return true
+      }
+
+      // Try to expand from the current seed
+      const expandedRect = tryExpandGap(state, {
+        gap: state.currentGap,
+        seed: state.currentSeed!,
+      })
+      state.expandedRect = expandedRect
+
+      // Move to place stage
+      state.stage = "place"
+      return true
+    }
+
+    case "place": {
+      // Stage 4: Show the placed result
+      if (state.expandedRect && state.currentGap) {
+        // Actually place the rectangle
+        addPlacement(state, {
+          rect: state.expandedRect,
+          zLayers: state.currentGap.zLayers,
+        })
+        state.filledCount++
+      }
+
+      // Move to next gap and reset to select stage
+      state.gapIndex++
+      state.currentGap = null
+      state.currentSeed = null
+      state.expandedRect = null
+      state.stage = "select"
+      return true
+    }
+
+    default:
+      state.stage = "scan"
+      return true
+  }
+}

package/lib/solvers/rectdiff/gapfill/engine/tryExpandGap.ts

@@ -0,0 +1,78 @@
+// lib/solvers/rectdiff/gapfill/engine/tryExpandGap.ts
+import type { XYRect } from "../../types"
+import type { GapFillState, GapRegion } from "../types"
+import { expandRectFromSeed } from "../../geometry"
+
+/**
+ * Try to expand a rectangle from a seed point within the gap.
+ * Returns the expanded rectangle or null if expansion fails.
+ */
+export function tryExpandGap(
+  state: GapFillState,
+  {
+    gap,
+    seed,
+  }: {
+    gap: GapRegion
+    seed: { x: number; y: number }
+  },
+): XYRect | null {
+  // Build blockers for the gap's z-layers
+  const blockers: XYRect[] = []
+  for (const z of gap.zLayers) {
+    blockers.push(...(state.obstaclesByLayer[z] ?? []))
+    blockers.push(...(state.placedByLayer[z] ?? []))
+  }
+
+  // Try to expand from the seed point
+  const rect = expandRectFromSeed({
+    startX: seed.x,
+    startY: seed.y,
+    gridSize: Math.min(gap.rect.width, gap.rect.height),
+    bounds: state.bounds,
+    blockers,
+    initialCellRatio: 0,
+    maxAspectRatio: null,
+    minReq: { width: state.options.minWidth, height: state.options.minHeight },
+  })
+
+  if (!rect) {
+    // Try additional seed points within the gap
+    const seeds = [
+      { x: gap.rect.x + state.options.minWidth / 2, y: gap.centerY },
+      {
+        x: gap.rect.x + gap.rect.width - state.options.minWidth / 2,
+        y: gap.centerY,
+      },
+      { x: gap.centerX, y: gap.rect.y + state.options.minHeight / 2 },
+      {
+        x: gap.centerX,
+        y: gap.rect.y + gap.rect.height - state.options.minHeight / 2,
+      },
+    ]
+
+    for (const altSeed of seeds) {
+      const altRect = expandRectFromSeed({
+        startX: altSeed.x,
+        startY: altSeed.y,
+        gridSize: Math.min(gap.rect.width, gap.rect.height),
+        bounds: state.bounds,
+        blockers,
+        initialCellRatio: 0,
+        maxAspectRatio: null,
+        minReq: {
+          width: state.options.minWidth,
+          height: state.options.minHeight,
+        },
+      })
+
+      if (altRect) {
+        return altRect
+      }
+    }
+
+    return null
+  }
+
+  return rect
+}

package/lib/solvers/rectdiff/gapfill/engine.ts

@@ -0,0 +1,7 @@
+// lib/solvers/rectdiff/gapfill/engine.ts
+export * from "./engine/calculateCoverage"
+export * from "./engine/findUncoveredPoints"
+export * from "./engine/getGapFillProgress"
+export * from "./engine/initGapFillState"
+
+export * from "./engine/stepGapFill"

package/lib/solvers/rectdiff/gapfill/types.ts

@@ -0,0 +1,60 @@
+// lib/solvers/rectdiff/gapfill/types.ts
+import type { XYRect, Placed3D } from "../types"
+
+export interface GapFillOptions {
+  /** Minimum width for gap-fill rectangles (can be smaller than main solver) */
+  minWidth: number
+  /** Minimum height for gap-fill rectangles */
+  minHeight: number
+  /** Maximum iterations to prevent infinite loops */
+  maxIterations: number
+  /** Target coverage percentage (0-1) to stop early */
+  targetCoverage: number
+  /** Grid resolution for gap detection */
+  scanResolution: number
+}
+
+export interface GapRegion {
+  /** Bounding box of the gap */
+  rect: XYRect
+  /** Z-layers where this gap exists */
+  zLayers: number[]
+  /** Center point for seeding */
+  centerX: number
+  centerY: number
+  /** Approximate area of the gap */
+  area: number
+}
+
+export interface GapFillState {
+  bounds: XYRect
+  layerCount: number
+  obstaclesByLayer: XYRect[][]
+  placed: Placed3D[]
+  placedByLayer: XYRect[][]
+  options: GapFillOptions
+
+  // Progress tracking
+  iteration: number
+  gapsFound: GapRegion[]
+  gapIndex: number
+  done: boolean
+
+  // Stats
+  initialGapCount: number
+  filledCount: number
+
+  // Four-stage visualization state
+  stage: "scan" | "select" | "expand" | "place"
+  currentGap: GapRegion | null
+  currentSeed: { x: number; y: number } | null
+  expandedRect: XYRect | null
+}
+
+/** Context for layer-based operations shared across gap fill functions */
+export interface LayerContext {
+  bounds: XYRect
+  layerCount: number
+  obstaclesByLayer: XYRect[][]
+  placedByLayer: XYRect[][]
+}

package/lib/solvers/rectdiff/geometry.ts

@@ -209,17 +209,28 @@ function maxExpandUp(
   return Math.max(0, e)
 }
 
-/** Grow a rect around (startX,startY), honoring bounds/blockers/aspect/min sizes */
-export function expandRectFromSeed(
-  startX: number,
-  startY: number,
-  gridSize: number,
-  bounds: XYRect,
-  blockers: XYRect[],
-  initialCellRatio: number,
-  maxAspectRatio: number | null | undefined,
-  minReq: { width: number; height: number },
-): XYRect | null {
+/** Grow a rect around a seed point, honoring bounds/blockers/aspect/min sizes. */
+export function expandRectFromSeed(params: {
+  startX: number
+  startY: number
+  gridSize: number
+  bounds: XYRect
+  blockers: XYRect[]
+  initialCellRatio: number
+  maxAspectRatio: number | null | undefined
+  minReq: { width: number; height: number }
+}): XYRect | null {
+  const {
+    startX,
+    startY,
+    gridSize,
+    bounds,
+    blockers,
+    initialCellRatio,
+    maxAspectRatio,
+    minReq,
+  } = params
+
   const minSide = Math.max(1e-9, gridSize * initialCellRatio)
   const initialW = Math.max(minSide, minReq.width)
   const initialH = Math.max(minSide, minReq.height)
@@ -297,6 +308,7 @@ export function expandRectFromSeed(
   return best
 }
 
+/** Find the intersection of two 1D intervals, or null if they don't overlap. */
 export function intersect1D(a0: number, a1: number, b0: number, b1: number) {
   const lo = Math.max(a0, b0)
   const hi = Math.min(a1, b1)

package/lib/solvers/rectdiff/subsolvers/GapFillSubSolver.ts

@@ -0,0 +1,253 @@
+// lib/solvers/rectdiff/subsolvers/GapFillSubSolver.ts
+import { BaseSolver } from "@tscircuit/solver-utils"
+import type { GraphicsObject } from "graphics-debug"
+import type { XYRect, Placed3D } from "../types"
+import type {
+  GapFillState,
+  GapFillOptions,
+  LayerContext,
+} from "../gapfill/types"
+import {
+  initGapFillState,
+  stepGapFill,
+  getGapFillProgress,
+} from "../gapfill/engine"
+
+/**
+ * A sub-solver that fills empty spaces (gaps) left by the main grid-based
+ * placement algorithm.
+ *
+ * The preceding grid-based placement is fast but can leave irregular un-placed
+ * areas. This solver maximizes board coverage by finding and filling these
+ * gaps, which is critical for producing a high-quality capacity mesh.
+ *
+ * The core of the algorithm is its gap-detection phase. It works by first
+ * collecting all unique x and y-coordinates from the edges of existing
+ * obstacles and placed rectangles. This set of coordinates is supplemented by a
+ * uniform grid based on the `scanResolution` parameter. Together, these form a
+ * non-uniform grid of cells. The solver then tests the center of each cell for
+ * coverage. Contiguous uncovered cells are merged into larger, maximal
+ * rectangles, which become the candidate gaps to be filled.
+ *
+ * Once a prioritized list of gaps is generated (favoring larger, multi-layer
+ * gaps), the solver iteratively attempts to fill each one by expanding a new
+ * rectangle from a seed point until it collides with an existing boundary.
+ *
+ * The time complexity is dominated by the gap detection, which is approximately
+ * O((N+1/R)^2 * B), where N is the number of objects, R is the scan
+ * resolution, and B is the number of blockers. The algorithm's performance is
+ * therefore highly dependent on the `scanResolution`. It is a heuristic
+ * designed to be "fast enough" by avoiding a brute-force search, instead
+ * relying on this grid-based cell checking to find significant gaps.
+ */
+export class GapFillSubSolver extends BaseSolver {
+  private state: GapFillState
+  private layerCtx: LayerContext
+
+  constructor(params: {
+    placed: Placed3D[]
+    options?: Partial<GapFillOptions>
+    layerCtx: LayerContext
+  }) {
+    super()
+    this.layerCtx = params.layerCtx
+    this.state = initGapFillState(
+      {
+        placed: params.placed,
+        options: params.options,
+      },
+      params.layerCtx,
+    )
+  }
+
+  /**
+   * Execute one step of the gap fill algorithm.
+   * Each gap goes through four stages: scan for gaps, select a target gap,
+   * expand a rectangle from seed point, then place the final result.
+   */
+  override _step() {
+    const stillWorking = stepGapFill(this.state)
+    if (!stillWorking) {
+      this.solved = true
+    }
+  }
+
+  /**
+   * Calculate progress as a value between 0 and 1.
+   * Accounts for iterations, gaps processed, and current stage within each gap.
+   */
+  computeProgress(): number {
+    return getGapFillProgress(this.state)
+  }
+
+  /**
+   * Get all placed rectangles including original ones plus newly created gap-fill rectangles.
+   */
+  getPlaced(): Placed3D[] {
+    return this.state.placed
+  }
+
+  /**
+   * Get placed rectangles organized by Z-layer for efficient layer-based operations.
+   */
+  getPlacedByLayer(): XYRect[][] {
+    return this.state.placedByLayer
+  }
+
+  override getOutput() {
+    return {
+      placed: this.state.placed,
+      placedByLayer: this.state.placedByLayer,
+      filledCount: this.state.filledCount,
+    }
+  }
+
+  /** Zen visualization: show four-stage gap filling process. */
+  override visualize(): GraphicsObject {
+    const rects: NonNullable<GraphicsObject["rects"]> = []
+    const points: NonNullable<GraphicsObject["points"]> = []
+
+    // Board bounds (subtle)
+    rects.push({
+      center: {
+        x: this.layerCtx.bounds.x + this.layerCtx.bounds.width / 2,
+        y: this.layerCtx.bounds.y + this.layerCtx.bounds.height / 2,
+      },
+      width: this.layerCtx.bounds.width,
+      height: this.layerCtx.bounds.height,
+      fill: "none",
+      stroke: "#e5e7eb",
+      label: "",
+    })
+
+    switch (this.state.stage) {
+      case "scan": {
+        // Stage 1: Show scanning/detection phase with light blue overlay
+        rects.push({
+          center: {
+            x: this.layerCtx.bounds.x + this.layerCtx.bounds.width / 2,
+            y: this.layerCtx.bounds.y + this.layerCtx.bounds.height / 2,
+          },
+          width: this.layerCtx.bounds.width,
+          height: this.layerCtx.bounds.height,
+          fill: "#dbeafe",
+          stroke: "#3b82f6",
+          label: "scanning",
+        })
+        break
+      }
+
+      case "select": {
+        // Stage 2: Show the gap being targeted (red outline)
+        if (this.state.currentGap) {
+          rects.push({
+            center: {
+              x:
+                this.state.currentGap.rect.x +
+                this.state.currentGap.rect.width / 2,
+              y:
+                this.state.currentGap.rect.y +
+                this.state.currentGap.rect.height / 2,
+            },
+            width: this.state.currentGap.rect.width,
+            height: this.state.currentGap.rect.height,
+            fill: "#fecaca",
+            stroke: "#ef4444",
+            label: "target gap",
+          })
+
+          // Show the seed point
+          if (this.state.currentSeed) {
+            points.push({
+              x: this.state.currentSeed.x,
+              y: this.state.currentSeed.y,
+              color: "#dc2626",
+              label: "seed",
+            })
+          }
+        }
+        break
+      }
+
+      case "expand": {
+        // Stage 3: Show expansion attempt (yellow growing rectangle + seed)
+        if (this.state.currentGap) {
+          // Show gap outline (faded)
+          rects.push({
+            center: {
+              x:
+                this.state.currentGap.rect.x +
+                this.state.currentGap.rect.width / 2,
+              y:
+                this.state.currentGap.rect.y +
+                this.state.currentGap.rect.height / 2,
+            },
+            width: this.state.currentGap.rect.width,
+            height: this.state.currentGap.rect.height,
+            fill: "none",
+            stroke: "#f87171",
+            label: "",
+          })
+        }
+
+        if (this.state.currentSeed) {
+          // Show seed point
+          points.push({
+            x: this.state.currentSeed.x,
+            y: this.state.currentSeed.y,
+            color: "#f59e0b",
+            label: "expanding",
+          })
+        }
+
+        if (this.state.expandedRect) {
+          // Show expanded rectangle
+          rects.push({
+            center: {
+              x: this.state.expandedRect.x + this.state.expandedRect.width / 2,
+              y: this.state.expandedRect.y + this.state.expandedRect.height / 2,
+            },
+            width: this.state.expandedRect.width,
+            height: this.state.expandedRect.height,
+            fill: "#fef3c7",
+            stroke: "#f59e0b",
+            label: "expanding",
+          })
+        }
+        break
+      }
+
+      case "place": {
+        // Stage 4: Show final placed rectangle (green)
+        if (this.state.expandedRect) {
+          rects.push({
+            center: {
+              x: this.state.expandedRect.x + this.state.expandedRect.width / 2,
+              y: this.state.expandedRect.y + this.state.expandedRect.height / 2,
+            },
+            width: this.state.expandedRect.width,
+            height: this.state.expandedRect.height,
+            fill: "#bbf7d0",
+            stroke: "#22c55e",
+            label: "placed",
+          })
+        }
+        break
+      }
+    }
+
+    const stageNames = {
+      scan: "scanning",
+      select: "selecting",
+      expand: "expanding",
+      place: "placing",
+    }
+
+    return {
+      title: `GapFill (${stageNames[this.state.stage]}): ${this.state.filledCount} filled`,
+      coordinateSystem: "cartesian",
+      rects,
+      points,
+    }
+  }
+}

package/lib/solvers/rectdiff/types.ts

@@ -34,7 +34,7 @@ export type Candidate3D = {
 }
 export type Placed3D = { rect: XYRect; zLayers: number[] }
 
-export type Phase = "GRID" | "EXPANSION" | "DONE"
+export type Phase = "GRID" | "EXPANSION" | "GAP_FILL" | "DONE"
 
 export type RectDiffState = {
   // static

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/rectdiff",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "main": "dist/index.js",
   "scripts": {

package/tests/obstacle-extra-layers.test.ts

@@ -29,7 +29,7 @@ test("RectDiffSolver clamps extra layer names to available z indices", () => {
     ],
   }
 
-  const solver = new RectDiffSolver({ simpleRouteJson: srj, mode: "grid" })
+  const solver = new RectDiffSolver({ simpleRouteJson: srj })
   solver.setup()
 
   expect(srj.obstacles[0]?.zLayers).toEqual([1])

package/tests/obstacle-zlayers.test.ts

@@ -29,7 +29,7 @@ test("RectDiffSolver maps obstacle layers to numeric zLayers", () => {
     ],
   }
 
-  const solver = new RectDiffSolver({ simpleRouteJson: srj, mode: "grid" })
+  const solver = new RectDiffSolver({ simpleRouteJson: srj })
   solver.setup()
 
   expect(srj.obstacles[0]?.zLayers).toEqual([0])