@tscircuit/schematic-trace-solver 0.0.44 → 0.0.45

package/lib/solvers/SchematicTracePipelineSolver/SchematicTracePipelineSolver.ts

@@ -200,7 +200,6 @@ export class SchematicTracePipelineSolver extends BaseSolver {
         {
           inputProblem: instance.inputProblem,
           allTraces: traces,
-          targetTraceIds: new Set(traces.map((t) => t.mspPairId)),
           allLabelPlacements: labelMergingOutput.netLabelPlacements,
           mergedLabelNetIdMap: labelMergingOutput.mergedLabelNetIdMap,
           paddingBuffer: 0.1,

package/lib/solvers/TraceCleanupSolver/TraceCleanupSolver.ts

@@ -7,74 +7,120 @@ import type { SolvedTracePath } from "lib/solvers/SchematicTraceLinesSolver/Sche
 import { visualizeInputProblem } from "lib/solvers/SchematicTracePipelineSolver/visualizeInputProblem"
 import type { NetLabelPlacement } from "../NetLabelPlacementSolver/NetLabelPlacementSolver"
 
+/**
+ * Defines the input structure for the TraceCleanupSolver.
+ */
 interface TraceCleanupSolverInput {
   inputProblem: InputProblem
   allTraces: SolvedTracePath[]
-  targetTraceIds: Set<string>
   allLabelPlacements: NetLabelPlacement[]
   mergedLabelNetIdMap: Record<string, Set<string>>
   paddingBuffer: number
 }
 
-type PipelineStep = "minimizing_turns" | "balancing_l_shapes"
+import { UntangleTraceSubsolver } from "./sub-solver/UntangleTraceSubsolver"
+import { is4PointRectangle } from "./is4PointRectangle"
 
 /**
- * Cleans up traces by minimizing turns and balancing L-shapes to improve
- * the overall aesthetics and readability of the schematic.
+ * Represents the different stages or steps within the trace cleanup pipeline.
+ */
+type PipelineStep =
+  | "minimizing_turns"
+  | "balancing_l_shapes"
+  | "untangling_traces"
+
+/**
+ * The TraceCleanupSolver is responsible for improving the aesthetics and readability of schematic traces.
+ * It operates in a multi-step pipeline:
+ * 1. **Untangling Traces**: It first attempts to untangle any overlapping or highly convoluted traces using a sub-solver.
+ * 2. **Minimizing Turns**: After untangling, it iterates through each trace to minimize the number of turns, simplifying their paths.
+ * 3. **Balancing L-Shapes**: Finally, it balances L-shaped trace segments to create more visually appealing and consistent layouts.
+ * The solver processes traces one by one, applying these cleanup steps sequentially to refine the overall trace layout.
  */
 export class TraceCleanupSolver extends BaseSolver {
   private input: TraceCleanupSolverInput
   private outputTraces: SolvedTracePath[]
   private traceIdQueue: string[]
   private tracesMap: Map<string, SolvedTracePath>
-  private pipelineStep: PipelineStep = "minimizing_turns"
+  private pipelineStep: PipelineStep = "untangling_traces"
   private activeTraceId: string | null = null // New property
+  override activeSubSolver: BaseSolver | null = null
 
   constructor(solverInput: TraceCleanupSolverInput) {
     super()
     this.input = solverInput
     this.outputTraces = [...solverInput.allTraces]
     this.tracesMap = new Map(this.outputTraces.map((t) => [t.mspPairId, t]))
-    this.traceIdQueue = Array.from(solverInput.targetTraceIds)
+    this.traceIdQueue = Array.from(
+      solverInput.allTraces.map((e) => e.mspPairId),
+    )
   }
 
   override _step() {
-    if (
-      this.pipelineStep === "minimizing_turns" &&
-      this.traceIdQueue.length === 0
-    ) {
+    if (this.activeSubSolver) {
+      this.activeSubSolver.step()
+      if (this.activeSubSolver.solved) {
+        const output = (
+          this.activeSubSolver as UntangleTraceSubsolver
+        ).getOutput()
+        this.outputTraces = output.traces
+        this.tracesMap = new Map(this.outputTraces.map((t) => [t.mspPairId, t]))
+        this.activeSubSolver = null
+        this.pipelineStep = "minimizing_turns"
+      } else if (this.activeSubSolver.failed) {
+        this.activeSubSolver = null
+        this.pipelineStep = "minimizing_turns"
+      }
+      return
+    }
+
+    switch (this.pipelineStep) {
+      case "untangling_traces":
+        this._runUntangleTracesStep()
+        break
+      case "minimizing_turns":
+        this._runMinimizeTurnsStep()
+        break
+      case "balancing_l_shapes":
+        this._runBalanceLShapesStep()
+        break
+    }
+  }
+
+  private _runUntangleTracesStep() {
+    this.activeSubSolver = new UntangleTraceSubsolver({
+      ...this.input,
+      allTraces: Array.from(this.tracesMap.values()),
+    })
+  }
+
+  private _runMinimizeTurnsStep() {
+    if (this.traceIdQueue.length === 0) {
       this.pipelineStep = "balancing_l_shapes"
-      this.traceIdQueue = Array.from(this.input.targetTraceIds)
+      this.traceIdQueue = Array.from(
+        this.input.allTraces.map((e) => e.mspPairId),
+      )
+      return
     }
 
-    if (
-      this.pipelineStep === "balancing_l_shapes" &&
-      this.traceIdQueue.length === 0
-    ) {
+    this._processTrace("minimizing_turns")
+  }
+
+  private _runBalanceLShapesStep() {
+    if (this.traceIdQueue.length === 0) {
       this.solved = true
       return
     }
 
+    this._processTrace("balancing_l_shapes")
+  }
+
+  private _processTrace(step: "minimizing_turns" | "balancing_l_shapes") {
     const targetMspConnectionPairId = this.traceIdQueue.shift()!
-    this.activeTraceId = targetMspConnectionPairId // Set active trace ID
+    this.activeTraceId = targetMspConnectionPairId
     const originalTrace = this.tracesMap.get(targetMspConnectionPairId)!
 
-    const { tracePath } = originalTrace
-
-    // Skip if the trace is a perfect rectangle
-    const is4PointRectangle = (path: typeof tracePath): boolean => {
-      if (path.length !== 4) return false
-      const [p0, p1, p2, p3] = path
-      // H-V-H "C" shape
-      const isHVHC =
-        p0.y === p1.y && p1.x === p2.x && p2.y === p3.y && p0.x === p3.x
-      // V-H-V "C" shape
-      const isVHVC =
-        p0.x === p1.x && p1.y === p2.y && p2.x === p3.x && p0.y === p3.y
-      return isHVHC || isVHVC
-    }
-
-    if (is4PointRectangle(tracePath)) {
+    if (is4PointRectangle(originalTrace.tracePath)) {
       return
     }
 
@@ -82,7 +128,7 @@ export class TraceCleanupSolver extends BaseSolver {
 
     let updatedTrace: SolvedTracePath
 
-    if (this.pipelineStep === "minimizing_turns") {
+    if (step === "minimizing_turns") {
       updatedTrace = minimizeTurnsWithFilteredLabels({
         ...this.input,
         targetMspConnectionPairId,
@@ -96,10 +142,7 @@ export class TraceCleanupSolver extends BaseSolver {
       })
     }
 
-    // Update the state in the central map
     this.tracesMap.set(targetMspConnectionPairId, updatedTrace)
-
-    // Update the output for visualization
     this.outputTraces = Array.from(this.tracesMap.values())
   }
 
@@ -110,6 +153,10 @@ export class TraceCleanupSolver extends BaseSolver {
   }
 
   override visualize(): GraphicsObject {
+    if (this.activeSubSolver) {
+      return this.activeSubSolver.visualize()
+    }
+
     const graphics = visualizeInputProblem(this.input.inputProblem, {
       chipAlpha: 0.1,
       connectionAlpha: 0.1,

package/lib/solvers/TraceCleanupSolver/hasCollisions.ts

@@ -1,9 +1,13 @@
-import type { Point } from "graphics-debug"
-import { segmentIntersectsRect } from "lib/solvers/SchematicTraceLinesSolver/SchematicTraceSingleLineSolver2/collisions"
+import type { Point } from "@tscircuit/math-utils"
+import { segmentToBoxMinDistance } from "@tscircuit/math-utils"
 
+/**
+ * Checks if a given path (series of segments) collides with any of the provided obstacles.
+ * It iterates through each segment of the path and checks for intersection with each obstacle.
+ */
 export const hasCollisions = (
   pathSegments: Point[],
-  obstacles: any[],
+  obstacles: Array<{ minX: number; maxX: number; minY: number; maxY: number }>,
 ): boolean => {
   // Check each segment of the path
   for (let i = 0; i < pathSegments.length - 1; i++) {
@@ -12,7 +16,15 @@ export const hasCollisions = (
 
     // Check collision with each obstacle
     for (const obstacle of obstacles) {
-      if (segmentIntersectsRect(p1, p2, obstacle)) {
+      const box = {
+        center: {
+          x: obstacle.minX + (obstacle.maxX - obstacle.minX) / 2,
+          y: obstacle.minY + (obstacle.maxY - obstacle.minY) / 2,
+        },
+        width: obstacle.maxX - obstacle.minX,
+        height: obstacle.maxY - obstacle.minY,
+      }
+      if (segmentToBoxMinDistance(p1, p2, box) <= 0) {
         return true
       }
     }

package/lib/solvers/TraceCleanupSolver/is4PointRectangle.ts

@@ -0,0 +1,17 @@
+import type { Point } from "@tscircuit/math-utils"
+
+/**
+ * Checks if a given path of four points forms a rectangle with horizontal and vertical segments.
+ * It verifies if the path forms either an H-V-H "C" shape or a V-H-V "C" shape.
+ */
+export const is4PointRectangle = (path: Point[]): boolean => {
+  if (path.length !== 4) return false
+  const [p0, p1, p2, p3] = path
+  // H-V-H "C" shape
+  const isHVHC =
+    p0.y === p1.y && p1.x === p2.x && p2.y === p3.y && p0.x === p3.x
+  // V-H-V "C" shape
+  const isVHVC =
+    p0.x === p1.x && p1.y === p2.y && p2.x === p3.x && p0.y === p3.y
+  return isHVHC || isVHVC
+}

package/lib/solvers/TraceCleanupSolver/isSegmentAnEndpointSegment.ts

@@ -0,0 +1,36 @@
+import type { Point } from "graphics-debug"
+
+/**
+ * Determines if a given segment (p1-p2) is either the first or the last segment of an original path.
+ * This is useful for identifying segments that are at the extremities of a trace.
+ */
+export const isSegmentAnEndpointSegment = (
+  p1: Point,
+  p2: Point,
+  originalPath: Point[],
+): boolean => {
+  if (originalPath.length < 2) return false
+
+  const originalStart = originalPath[0]
+  const originalEnd = originalPath[originalPath.length - 1]
+
+  // Check if p1-p2 is the first segment of the original path
+  if (
+    p1.x === originalStart.x &&
+    p1.y === originalStart.y &&
+    p2.x === originalPath[1].x &&
+    p2.y === originalPath[1].y
+  ) {
+    return true
+  }
+  // Check if p1-p2 is the last segment of the original path
+  if (
+    p1.x === originalPath[originalPath.length - 2].x &&
+    p1.y === originalPath[originalPath.length - 2].y &&
+    p2.x === originalEnd.x &&
+    p2.y === originalEnd.y
+  ) {
+    return true
+  }
+  return false
+}

package/lib/solvers/TraceCleanupSolver/mergeGraphicsObjects.ts

@@ -0,0 +1,28 @@
+import type { GraphicsObject } from "graphics-debug"
+
+/**
+ * Merges multiple GraphicsObject instances into a single GraphicsObject.
+ * It combines all lines, points, rectangles, circles, and texts from the input objects.
+ */
+export const mergeGraphicsObjects = (
+  objects: (GraphicsObject | undefined)[],
+): GraphicsObject => {
+  const merged: GraphicsObject = {
+    lines: [],
+    points: [],
+    rects: [],
+    circles: [],
+    texts: [],
+  }
+
+  for (const obj of objects) {
+    if (!obj) continue
+    if (obj.lines) merged.lines!.push(...obj.lines)
+    if (obj.points) merged.points!.push(...obj.points)
+    if (obj.rects) merged.rects!.push(...obj.rects)
+    if (obj.circles) merged.circles!.push(...obj.circles)
+    if (obj.texts) merged.texts!.push(...obj.texts)
+  }
+
+  return merged
+}

package/lib/solvers/TraceCleanupSolver/minimizeTurnsWithFilteredLabels.ts

@@ -4,6 +4,13 @@ import type { SolvedTracePath } from "lib/solvers/SchematicTraceLinesSolver/Sche
 import { getObstacleRects } from "lib/solvers/SchematicTraceLinesSolver/SchematicTraceSingleLineSolver2/rect"
 import type { NetLabelPlacement } from "../NetLabelPlacementSolver/NetLabelPlacementSolver"
 
+/**
+ * Minimizes the turns of a target trace while considering other traces and labels as obstacles.
+ * This function first identifies the target trace and separates it from other traces, which are then treated as obstacles.
+ * It also filters out labels that belong to the target trace's net, so they don't act as obstacles.
+ * The function then combines static obstacles (from the input problem) with the other traces and filtered labels to create a comprehensive set of obstacles.
+ * Finally, it uses a turn minimization algorithm to find a new path for the target trace that avoids these combined obstacles.
+ */
 export const minimizeTurnsWithFilteredLabels = ({
   targetMspConnectionPairId,
   traces,
@@ -44,7 +51,16 @@ export const minimizeTurnsWithFilteredLabels = ({
     }),
   )
 
-  const staticObstacles = getObstacleRects(inputProblem)
+  const staticObstaclesRaw = getObstacleRects(inputProblem)
+  const PADDING = 0.01
+  const staticObstacles = staticObstaclesRaw.map((obs) => ({
+    ...obs,
+    minX: obs.minX - PADDING,
+    minY: obs.minY - PADDING,
+    maxX: obs.maxX + PADDING,
+    maxY: obs.maxY + PADDING,
+  }))
+
   const combinedObstacles = [...staticObstacles, ...traceObstacles]
 
   const originalPath = targetTrace.tracePath
@@ -67,6 +83,7 @@ export const minimizeTurnsWithFilteredLabels = ({
     path: originalPath,
     obstacles: combinedObstacles,
     labelBounds,
+    originalPath: originalPath,
   })
 
   return {

package/lib/solvers/TraceCleanupSolver/recognizeStairStepPattern.ts

@@ -0,0 +1,56 @@
+import type { Point } from "graphics-debug"
+
+/**
+ * Recognizes a "stair-step" pattern within a given path of points starting from a specified index.
+ * A stair-step pattern is characterized by alternating horizontal and vertical segments.
+ * The function checks for a sequence of at least three segments where the orientation (horizontal/vertical) alternates.
+ * It returns the end index of the recognized stair-step pattern if found, otherwise -1.
+ */
+export const recognizeStairStepPattern = (
+  pathToCheck: Point[],
+  startIdx: number,
+): number => {
+  if (startIdx >= pathToCheck.length - 3) return -1
+
+  let endIdx = startIdx
+  let isStairStep = true
+
+  for (let i = startIdx; i < pathToCheck.length - 2 && i < startIdx + 10; i++) {
+    if (i + 2 >= pathToCheck.length) break
+
+    const p1 = pathToCheck[i]
+    const p2 = pathToCheck[i + 1]
+    const p3 = pathToCheck[i + 2]
+
+    const seg1Vertical = p1.x === p2.x
+    const seg2Vertical = p2.x === p3.x
+
+    if (seg1Vertical === seg2Vertical) {
+      break
+    }
+
+    const seg1Direction = seg1Vertical
+      ? Math.sign(p2.y - p1.y)
+      : Math.sign(p2.x - p1.x)
+
+    if (i > startIdx) {
+      const prevP = pathToCheck[i - 1]
+      const prevSegVertical = prevP.x === p1.x
+      const prevDirection = prevSegVertical
+        ? Math.sign(p1.y - prevP.y)
+        : Math.sign(p1.x - prevP.x)
+
+      if (
+        (seg1Vertical && prevSegVertical && seg1Direction !== prevDirection) ||
+        (!seg1Vertical && !prevSegVertical && seg1Direction !== prevDirection)
+      ) {
+        isStairStep = false
+        break
+      }
+    }
+
+    endIdx = i + 2
+  }
+
+  return isStairStep && endIdx - startIdx >= 3 ? endIdx : -1
+}