@tscircuit/rectdiff 0.0.38 → 0.0.39

package/.github/workflows/bun-test.yml

@@ -28,4 +28,4 @@ jobs:
         run: bun install
 
       - name: Run tests
-        run: bun test --timeout 9999
+        run: bun test --timeout 999999

package/lib/RectDiffPipeline.ts

@@ -16,17 +16,20 @@ import { computeInverseRects } from "./solvers/RectDiffSeedingSolver/computeInve
 import { buildZIndexMap } from "./solvers/RectDiffSeedingSolver/layers"
 import { buildObstacleClearanceGraphics } from "./utils/renderObstacleClearance"
 import { mergeGraphics } from "graphics-debug"
+import { SparseMultilayerPromotionSolver } from "./solvers/SparseMultilayerPromotionSolver/SparseMultilayerPromotionSolver"
 
 export interface RectDiffPipelineInput {
   simpleRouteJson: SimpleRouteJson
   gridOptions?: Partial<GridFill3DOptions>
   obstacleClearance?: number
+  sparseMultilayerPromotionTargetShare?: number
 }
 
 export class RectDiffPipeline extends BasePipelineSolver<RectDiffPipelineInput> {
   rectDiffGridSolverPipeline?: RectDiffGridSolverPipeline
   gapFillSolver?: GapFillSolverPipeline
   outerLayerContainmentMergeSolver?: OuterLayerContainmentMergeSolver
+  sparseMultilayerPromotionSolver?: SparseMultilayerPromotionSolver
   boardVoidRects: XYRect[] | undefined
   zIndexByName?: Map<string, number>
   layerNames?: string[]
@@ -87,6 +90,25 @@ export class RectDiffPipeline extends BasePipelineSolver<RectDiffPipelineInput>
         },
       ],
     ),
+    definePipelineStep(
+      "sparseMultilayerPromotionSolver",
+      SparseMultilayerPromotionSolver,
+      (rectDiffPipeline: RectDiffPipeline) => [
+        {
+          meshNodes:
+            rectDiffPipeline.outerLayerContainmentMergeSolver?.getOutput()
+              .outputNodes ??
+            rectDiffPipeline.gapFillSolver?.getOutput().outputNodes ??
+            rectDiffPipeline.rectDiffGridSolverPipeline?.getOutput()
+              .meshNodes ??
+            [],
+          promotionTargetShare:
+            rectDiffPipeline.inputProblem
+              .sparseMultilayerPromotionTargetShare ?? 0.86,
+          simpleRouteJson: rectDiffPipeline.inputProblem.simpleRouteJson,
+        },
+      ],
+    ),
   ]
 
   override _setup(): void {
@@ -120,6 +142,11 @@ export class RectDiffPipeline extends BasePipelineSolver<RectDiffPipelineInput>
   override getOutput(): { meshNodes: CapacityMeshNode[] } {
     const outerLayerMergeOutput =
       this.outerLayerContainmentMergeSolver?.getOutput()
+    const sparseMultilayerOutput =
+      this.sparseMultilayerPromotionSolver?.getOutput()
+    if (sparseMultilayerOutput) {
+      return { meshNodes: sparseMultilayerOutput.outputNodes }
+    }
     if (outerLayerMergeOutput) {
       return { meshNodes: outerLayerMergeOutput.outputNodes }
     }

package/lib/math/layers/getUnionZ.ts

@@ -0,0 +1,6 @@
+/**
+ * Combine two layer lists into one ordered list.
+ * Duplicate layers are removed.
+ */
+export const getUnionZ = ({ a, b }: { a: number[]; b: number[] }) =>
+  [...new Set([...a, ...b])].sort((x, y) => x - y)

package/lib/math/layers/getZLayerName.ts

@@ -0,0 +1,6 @@
+/**
+ * Build the display name for a layer span.
+ * This keeps layer labels consistent.
+ */
+export const getZLayerName = ({ availableZ }: { availableZ: number[] }) =>
+  `z${availableZ.join(",")}`

package/lib/math/layers/getZSpanMask.ts

@@ -0,0 +1,6 @@
+/**
+ * Turn a layer list into a numeric mask.
+ * This is used for fast grouping and comparisons.
+ */
+export const getZSpanMask = ({ availableZ }: { availableZ: number[] }) =>
+  availableZ.reduce((mask, z) => mask | (1 << z), 0)

package/lib/math/layers/hasContiguousZSpan.ts

@@ -0,0 +1,11 @@
+/**
+ * Check whether the layers form one continuous range.
+ * Gapped layer spans return false.
+ */
+export const hasContiguousZSpan = ({ zValues }: { zValues: number[] }) => {
+  for (let i = 1; i < zValues.length; i++) {
+    if (zValues[i]! - zValues[i - 1]! !== 1) return false
+  }
+
+  return true
+}

package/lib/math/rects/intersectRects.ts

@@ -0,0 +1,28 @@
+import type { XYRect } from "../../rectdiff-types"
+import { EPS } from "../../utils/rectdiff-geometry"
+
+/**
+ * Return the shared area between two rectangles.
+ * Returns null when they do not overlap.
+ */
+export const intersectRects = ({
+  a,
+  b,
+}: {
+  a: XYRect
+  b: XYRect
+}): XYRect | null => {
+  const x0 = Math.max(a.x, b.x)
+  const y0 = Math.max(a.y, b.y)
+  const x1 = Math.min(a.x + a.width, b.x + b.width)
+  const y1 = Math.min(a.y + a.height, b.y + b.height)
+
+  if (x1 <= x0 + EPS || y1 <= y0 + EPS) return null
+
+  return {
+    x: x0,
+    y: y0,
+    width: x1 - x0,
+    height: y1 - y0,
+  }
+}

package/lib/math/rects/mergeRects.ts

@@ -0,0 +1,12 @@
+import type { XYRect } from "../../rectdiff-types"
+
+/**
+ * Build one rectangle that covers both inputs.
+ * This is the outer box around the two shapes.
+ */
+export const mergeRects = ({ a, b }: { a: XYRect; b: XYRect }): XYRect => ({
+  x: Math.min(a.x, b.x),
+  y: Math.min(a.y, b.y),
+  width: Math.max(a.x + a.width, b.x + b.width) - Math.min(a.x, b.x),
+  height: Math.max(a.y + a.height, b.y + b.height) - Math.min(a.y, b.y),
+})

package/lib/math/rects/rectArea.ts

@@ -0,0 +1,7 @@
+import type { XYRect } from "../../rectdiff-types"
+
+/**
+ * Return the area of a rectangle.
+ * Width and height are multiplied directly.
+ */
+export const rectArea = ({ rect }: { rect: XYRect }) => rect.width * rect.height

package/lib/math/rects/rectContainsRect.ts

@@ -0,0 +1,18 @@
+import type { XYRect } from "../../rectdiff-types"
+import { EPS } from "../../utils/rectdiff-geometry"
+
+/**
+ * Check whether one rectangle fully contains another.
+ * A small tolerance is used for edge cases.
+ */
+export const rectContainsRect = ({
+  inner,
+  outer,
+}: {
+  inner: XYRect
+  outer: XYRect
+}) =>
+  inner.x + EPS >= outer.x &&
+  inner.y + EPS >= outer.y &&
+  inner.x + inner.width <= outer.x + outer.width + EPS &&
+  inner.y + inner.height <= outer.y + outer.height + EPS

package/lib/math/rects/rectsTouchOrOverlap.ts

@@ -0,0 +1,12 @@
+import type { XYRect } from "../../rectdiff-types"
+import { EPS } from "../../utils/rectdiff-geometry"
+
+/**
+ * Check whether two rectangles touch or overlap.
+ * Separate rectangles return false.
+ */
+export const rectsTouchOrOverlap = ({ a, b }: { a: XYRect; b: XYRect }) =>
+  a.x <= b.x + b.width + EPS &&
+  b.x <= a.x + a.width + EPS &&
+  a.y <= b.y + b.height + EPS &&
+  b.y <= a.y + a.height + EPS

package/lib/math/rects/subtractRects.ts

@@ -0,0 +1,23 @@
+import type { XYRect } from "../../rectdiff-types"
+import { subtractRect2D } from "../../utils/rectdiff-geometry"
+
+/**
+ * Remove several rectangles from one rectangle.
+ * The result is the list of remaining pieces.
+ */
+export const subtractRects = ({
+  cutters,
+  target,
+}: {
+  cutters: XYRect[]
+  target: XYRect
+}) => {
+  let remaining: XYRect[] = [target]
+
+  for (const cutter of cutters) {
+    if (remaining.length === 0) return remaining
+    remaining = remaining.flatMap((piece) => subtractRect2D(piece, cutter))
+  }
+
+  return remaining
+}

package/lib/solvers/OuterLayerContainmentMergeSolver/OuterLayerContainmentMergeSolver.ts

@@ -29,6 +29,22 @@ const nodeToRect = (node: CapacityMeshNode): XYRect => ({
 
 const rectArea = (rect: XYRect) => rect.width * rect.height
 
+const intersectRects = (a: XYRect, b: XYRect): XYRect | null => {
+  const x0 = Math.max(a.x, b.x)
+  const y0 = Math.max(a.y, b.y)
+  const x1 = Math.min(a.x + a.width, b.x + b.width)
+  const y1 = Math.min(a.y + a.height, b.y + b.height)
+
+  if (x1 <= x0 + EPS || y1 <= y0 + EPS) return null
+
+  return {
+    x: x0,
+    y: y0,
+    width: x1 - x0,
+    height: y1 - y0,
+  }
+}
+
 const cloneNode = (node: CapacityMeshNode): CapacityMeshNode => ({
   ...node,
   center: { ...node.center },
@@ -87,6 +103,7 @@ const isFullyCoveredByRects = (target: XYRect, coveringRects: XYRect[]) => {
 export class OuterLayerContainmentMergeSolver extends BaseSolver {
   private outputNodes: CapacityMeshNode[] = []
   private promotedNodeIds = new Set<string>()
+  private fullyPromotedNodeIds = new Set<string>()
   private residualNodeIds = new Set<string>()
 
   constructor(private input: OuterLayerContainmentMergeSolverInput) {
@@ -96,6 +113,7 @@ export class OuterLayerContainmentMergeSolver extends BaseSolver {
   override _setup() {
     this.outputNodes = this.input.meshNodes.map(cloneNode)
     this.promotedNodeIds.clear()
+    this.fullyPromotedNodeIds.clear()
     this.residualNodeIds.clear()
   }
 
@@ -116,6 +134,8 @@ export class OuterLayerContainmentMergeSolver extends BaseSolver {
     const viaMinSize = Math.max(srj.minViaDiameter ?? 0, srj.minTraceWidth || 0)
     const originalNodes = this.input.meshNodes.map(cloneNode)
     const obstaclesByLayer = this.buildObstaclesByLayer(layerCount)
+    const shouldAllowPartialPromotion =
+      this.getUsableMultilayerVolumeShare(originalNodes) < 0.5
     const mutableOuterNodes = originalNodes.filter(
       (node) =>
         isFreeNode(node) &&
@@ -166,23 +186,51 @@ export class OuterLayerContainmentMergeSolver extends BaseSolver {
         continue
       }
       if (!isFullyCoveredByRects(candidateRect, oppositeSupportRects)) {
+        if (!shouldAllowPartialPromotion) {
+          continue
+        }
+
+        const partialPromotionRects = this.getSupportedPromotionRects({
+          candidateRect,
+          supportRects: oppositeSupportRects,
+          minRectSize: viaMinSize,
+        })
+
+        if (partialPromotionRects.length === 0) {
+          continue
+        }
+
+        for (const partialRect of partialPromotionRects) {
+          const promotedNode = cloneNodeWithRect(
+            candidate,
+            partialRect,
+            `${candidate.capacityMeshNodeId}-outer-partial-${promotedNodes.length}`,
+          )
+          promotedNode.availableZ = [topZ, bottomZ]
+          promotedNode.layer = `z${topZ},${bottomZ}`
+          promotedNodes.push(promotedNode)
+          promotedRects.push(partialRect)
+          this.promotedNodeIds.add(promotedNode.capacityMeshNodeId)
+        }
         continue
       }
 
-      promotedNodes.push({
+      const promotedNode = {
         ...candidate,
         availableZ: [topZ, bottomZ],
         layer: `z${topZ},${bottomZ}`,
-      })
+      }
+      promotedNodes.push(promotedNode)
       promotedRects.push(candidateRect)
-      this.promotedNodeIds.add(candidate.capacityMeshNodeId)
+      this.promotedNodeIds.add(promotedNode.capacityMeshNodeId)
+      this.fullyPromotedNodeIds.add(candidate.capacityMeshNodeId)
     }
 
     let nextResidualId = 0
     const residualNodes: CapacityMeshNode[] = []
 
     for (const node of mutableOuterNodes) {
-      if (this.promotedNodeIds.has(node.capacityMeshNodeId)) {
+      if (this.fullyPromotedNodeIds.has(node.capacityMeshNodeId)) {
         continue
       }
 
@@ -211,6 +259,62 @@ export class OuterLayerContainmentMergeSolver extends BaseSolver {
     return [...immutableNodes, ...promotedNodes, ...residualNodes]
   }
 
+  private getUsableMultilayerVolumeShare(nodes: CapacityMeshNode[]) {
+    let totalVolume = 0
+    let obstacleVolume = 0
+    let multilayerVolume = 0
+
+    for (const node of nodes) {
+      const volume = node.width * node.height * node.availableZ.length
+      totalVolume += volume
+      if (node._containsObstacle) {
+        obstacleVolume += volume
+        continue
+      }
+      if (node.availableZ.length > 1) {
+        multilayerVolume += volume
+      }
+    }
+
+    const usableVolume = totalVolume - obstacleVolume
+    if (usableVolume <= EPS) return 0
+    return multilayerVolume / usableVolume
+  }
+
+  private getSupportedPromotionRects(params: {
+    candidateRect: XYRect
+    supportRects: XYRect[]
+    minRectSize: number
+  }) {
+    const { candidateRect, supportRects, minRectSize } = params
+    const promotedPieces: XYRect[] = []
+
+    for (const supportRect of supportRects) {
+      const overlapRect = intersectRects(candidateRect, supportRect)
+      if (!overlapRect) continue
+
+      let remainingPieces = [overlapRect]
+      for (const existingPiece of promotedPieces) {
+        remainingPieces = remainingPieces.flatMap((piece) =>
+          subtractRect2D(piece, existingPiece),
+        )
+        if (remainingPieces.length === 0) break
+      }
+
+      for (const piece of remainingPieces) {
+        if (
+          piece.width + EPS < minRectSize ||
+          piece.height + EPS < minRectSize
+        ) {
+          continue
+        }
+        promotedPieces.push(piece)
+      }
+    }
+
+    return promotedPieces
+  }
+
   private buildObstaclesByLayer(layerCount: number): ObstacleWithRect[][] {
     const out = Array.from(
       { length: layerCount },

package/lib/solvers/SparseMultilayerPromotionSolver/SparseMultilayerPromotionSolver.ts

@@ -0,0 +1,134 @@
+import {
+  BasePipelineSolver,
+  definePipelineStep,
+  type PipelineStep,
+} from "@tscircuit/solver-utils"
+import type { GraphicsObject } from "graphics-debug"
+import type {
+  CapacityMeshNode,
+  CapacityMeshNodeId,
+} from "../../types/capacity-mesh-types"
+import { getZLayerName } from "../../math/layers/getZLayerName"
+import { getColorForZLayer } from "../../utils/getColorForZLayer"
+import { CoalesceMultilayerTilesSolver } from "./solvers/CoalesceMultilayerTilesSolver"
+import { PromoteSparseMultilayerCoverageSolver } from "./solvers/PromoteSparseMultilayerCoverageSolver"
+import { TrimContainedSingleLayerCoverageSolver } from "./solvers/TrimContainedSingleLayerCoverageSolver"
+import type { SparseMultilayerPromotionInput } from "./types"
+
+/**
+ * This pipeline makes shared multilayer regions easier to use.
+ * It grows shared space, removes redundant leftovers, and combines small tiles.
+ */
+export class SparseMultilayerPromotionSolver extends BasePipelineSolver<SparseMultilayerPromotionInput> {
+  coalesceMultilayerTilesSolver?: CoalesceMultilayerTilesSolver
+  promoteSparseMultilayerCoverageSolver?: PromoteSparseMultilayerCoverageSolver
+  trimContainedSingleLayerCoverageSolver?: TrimContainedSingleLayerCoverageSolver
+
+  override pipelineDef: PipelineStep<any>[] = [
+    definePipelineStep(
+      "promoteSparseMultilayerCoverageSolver",
+      PromoteSparseMultilayerCoverageSolver,
+      (solver: SparseMultilayerPromotionSolver) => [
+        {
+          meshNodes: solver.inputProblem.meshNodes,
+          minRectSize: Math.max(
+            solver.inputProblem.simpleRouteJson.minViaDiameter ?? 0,
+            solver.inputProblem.simpleRouteJson.minTraceWidth ?? 0,
+          ),
+          promotionTargetShare: solver.inputProblem.promotionTargetShare,
+        },
+      ],
+    ),
+    definePipelineStep(
+      "trimContainedSingleLayerCoverageSolver",
+      TrimContainedSingleLayerCoverageSolver,
+      (solver: SparseMultilayerPromotionSolver) => [
+        {
+          meshNodes:
+            solver.promoteSparseMultilayerCoverageSolver?.getOutput()
+              .outputNodes ?? solver.inputProblem.meshNodes,
+          minRectSize: Math.max(
+            solver.inputProblem.simpleRouteJson.minViaDiameter ?? 0,
+            solver.inputProblem.simpleRouteJson.minTraceWidth ?? 0,
+          ),
+          promotionTargetShare: solver.inputProblem.promotionTargetShare,
+        },
+      ],
+    ),
+    definePipelineStep(
+      "coalesceMultilayerTilesSolver",
+      CoalesceMultilayerTilesSolver,
+      (solver: SparseMultilayerPromotionSolver) => [
+        {
+          meshNodes:
+            solver.trimContainedSingleLayerCoverageSolver?.getOutput()
+              .outputNodes ??
+            solver.promoteSparseMultilayerCoverageSolver?.getOutput()
+              .outputNodes ??
+            solver.inputProblem.meshNodes,
+        },
+      ],
+    ),
+  ]
+
+  override getConstructorParams() {
+    return [this.inputProblem]
+  }
+
+  override getOutput(): { outputNodes: CapacityMeshNode[] } {
+    return {
+      outputNodes:
+        this.coalesceMultilayerTilesSolver?.getOutput().outputNodes ??
+        this.trimContainedSingleLayerCoverageSolver?.getOutput().outputNodes ??
+        this.promoteSparseMultilayerCoverageSolver?.getOutput().outputNodes ??
+        this.inputProblem.meshNodes,
+    }
+  }
+
+  override finalVisualize(): GraphicsObject {
+    const promotedIds = new Set<CapacityMeshNodeId>([
+      ...(this.promoteSparseMultilayerCoverageSolver?.getOutput()
+        .promotedNodeIds ?? []),
+      ...(this.coalesceMultilayerTilesSolver?.getOutput().promotedNodeIds ??
+        []),
+    ])
+    const residualIds = new Set<CapacityMeshNodeId>([
+      ...(this.promoteSparseMultilayerCoverageSolver?.getOutput()
+        .residualNodeIds ?? []),
+      ...(this.trimContainedSingleLayerCoverageSolver?.getOutput()
+        .residualNodeIds ?? []),
+    ])
+
+    return {
+      title: "SparseMultilayerPromotionSolver",
+      coordinateSystem: "cartesian",
+      rects: this.getOutput().outputNodes.map((node) => {
+        const colors = getColorForZLayer(node.availableZ)
+        const isPromoted = promotedIds.has(node.capacityMeshNodeId)
+        const isResidual = residualIds.has(node.capacityMeshNodeId)
+
+        return {
+          center: node.center,
+          width: node.width,
+          height: node.height,
+          stroke: isPromoted
+            ? "rgba(168, 85, 247, 0.95)"
+            : isResidual
+              ? "rgba(14, 116, 144, 0.95)"
+              : colors.stroke,
+          fill: node._containsObstacle
+            ? "rgba(239, 68, 68, 0.35)"
+            : isPromoted
+              ? "rgba(192, 132, 252, 0.28)"
+              : isResidual
+                ? "rgba(34, 211, 238, 0.18)"
+                : colors.fill,
+          layer: getZLayerName({ availableZ: node.availableZ }),
+        }
+      }),
+      points: [],
+      lines: [],
+      texts: [],
+    }
+  }
+}

package/lib/solvers/SparseMultilayerPromotionSolver/cloneNode.ts

@@ -0,0 +1,15 @@
+import type { CapacityMeshNode } from "../../types/capacity-mesh-types"
+
+/**
+ * Make a safe copy of a node.
+ * Later steps can change the copy without touching the original.
+ */
+export const cloneNode = ({
+  node,
+}: {
+  node: CapacityMeshNode
+}): CapacityMeshNode => ({
+  ...node,
+  center: { ...node.center },
+  availableZ: [...node.availableZ],
+})

package/lib/solvers/SparseMultilayerPromotionSolver/cloneNodeWithRect.ts

@@ -0,0 +1,34 @@
+import type { XYRect } from "../../rectdiff-types"
+import type { CapacityMeshNode } from "../../types/capacity-mesh-types"
+import { getZLayerName } from "../../math/layers/getZLayerName"
+
+/**
+ * Copy a node and replace its shape.
+ * The layer span can also be replaced when needed.
+ */
+export const cloneNodeWithRect = ({
+  rect,
+  templateNode,
+  availableZ,
+  capacityMeshNodeId,
+}: {
+  availableZ?: number[]
+  capacityMeshNodeId: string
+  rect: XYRect
+  templateNode: CapacityMeshNode
+}): CapacityMeshNode => {
+  const nextAvailableZ = availableZ ?? templateNode.availableZ
+
+  return {
+    ...templateNode,
+    capacityMeshNodeId,
+    center: {
+      x: rect.x + rect.width / 2,
+      y: rect.y + rect.height / 2,
+    },
+    width: rect.width,
+    height: rect.height,
+    availableZ: [...nextAvailableZ],
+    layer: getZLayerName({ availableZ: nextAvailableZ }),
+  }
+}

package/lib/solvers/SparseMultilayerPromotionSolver/createResidualNodes.ts

@@ -0,0 +1,42 @@
+import { subtractRect2D } from "../../utils/rectdiff-geometry"
+import type {
+  CapacityMeshNode,
+  CapacityMeshNodeId,
+} from "../../types/capacity-mesh-types"
+import type { XYRect } from "../../rectdiff-types"
+import { cloneNodeWithRect } from "./cloneNodeWithRect"
+
+/**
+ * Cut one rectangle out of a node and return the remaining pieces.
+ * Each remaining piece is turned back into a node.
+ */
+export const createResidualNodes = ({
+  cutRect,
+  getNextResidualId,
+  idPrefix,
+  node,
+  onResidualNodeIdCreated,
+}: {
+  cutRect: XYRect
+  getNextResidualId: () => number
+  idPrefix: string
+  node: CapacityMeshNode
+  onResidualNodeIdCreated: (nodeId: CapacityMeshNodeId) => void
+}) =>
+  subtractRect2D(
+    {
+      x: node.center.x - node.width / 2,
+      y: node.center.y - node.height / 2,
+      width: node.width,
+      height: node.height,
+    },
+    cutRect,
+  ).map((rect) => {
+    const residualNode = cloneNodeWithRect({
+      templateNode: node,
+      rect,
+      capacityMeshNodeId: `${idPrefix}-${getNextResidualId()}`,
+    })
+    onResidualNodeIdCreated(residualNode.capacityMeshNodeId)
+    return residualNode
+  })