diy-layout-creator/diylc/docs/plans/orthogonal-connector.md

# Orthogonal Connector

A wire that runs only horizontally and vertically, turning at rounded 90-degree
corners.

## 1. Goal

`HookupWire` draws a free Bezier curve between two sticky endpoints;
`Line` draws a single straight segment. Neither can express the routing style
used in schematics and block diagrams, where a connection leaves a terminal on
an axis, turns at right angles, and arrives on an axis. This document designs
that third kind of connector.

The shapes that must be reachable are, at minimum, horizontal-vertical-horizontal
and vertical-horizontal-vertical. Simple L bends and longer staircases should
fall out of the same mechanism rather than needing a separate component.

## 2. How many handles does the route actually need

An orthogonal route is a polyline whose segments alternate between horizontal
and vertical. Both endpoints are pinned, so counting the free numbers is easy:
a route of `s` segments has `s - 1` corners and `s - 2` continuous degrees of
freedom, plus **one discrete bit** saying whether the first segment leaves the
start point horizontally or vertically.

| Segments | Shape | Corners | Continuous DOF | Bit |
| --- | --- | --- | --- | --- |
| 2 | `HV` / `VH` (an L) | 1 | 0 | yes |
| 3 | `HVH` / `VHV` | 2 | 1 | yes |
| 4 | `HVHV` / `VHVH` | 3 | 2 | yes |
| 6 | `HVHVHV` / … | 5 | 4 | yes |

This is the crux of the problem stated in the request. A single interior control
point carries two numbers, but the `HVH` / `VHV` case needs *one* number and
*one bit*. One point is simultaneously one coordinate too many and one bit too
few, so no scheme that reads only that point's position can resolve the
arrangement without a heuristic that flips as the user drags across a diagonal.

The line in the table that is exactly parameterised is the four-segment one: three
corners, two degrees of freedom, and a middle corner that is a genuine free point
in the plane. That observation drives the whole design.

## 3. The chosen parameterisation

**Each interior control point is a real bend vertex, and the route between
consecutive vertices is a fixed `H` then `V` pair.** For one interior point `h`
the route is

```
    A ────────────┐                    A = start          (sticky)
                  │                    c1 = (h.x, A.y)    (derived)
                  h ─────────┐         h  = the handle    (draggable)
                             │         c2 = (B.x, h.y)    (derived)
                             B         B = end            (sticky)
```

that is `A → (h.x, A.y) → h → (B.x, h.y) → B`: four segments, alternating,
starting horizontal and ending vertical. Both of the handle's coordinates are
used, nothing is discarded, and there is no hidden state.

The requested arrangements are reached by letting segments collapse to zero
length, which is what snap-to-grid makes trivial:

| Handle placed at | Route degenerates to |
| --- | --- |
| anywhere | `HVHV`, three visible bends |
| `h.y == B.y` | `HVH`, two bends, vertical leg at `h.x` |
| `h.x == A.x` | `VHV`, two bends, horizontal leg at `h.y` |
| `h == (A.x, B.y)` | `VH`, one bend |
| `h == (B.x, A.y)` | `HV`, one bend |

The handle may sit outside the box spanned by the endpoints, which gives routes
that detour around obstacles. Nothing special is needed for that case.

### Generalising

`k` interior points chain the same template:

```
A → (h1.x, A.y) → h1 → (h2.x, h1.y) → h2 → … → (B.x, hk.y) → B
```

This is `2k + 2` segments and `2k` degrees of freedom, matching the `s - 2` rule
exactly. Every additional handle buys two more bends, every stored number is
meaningful, and the normalisation code is the same loop regardless of `k`. The
number of handles is an enum property, mirroring `AbstractCurvedComponent`'s
`Point Count`.

### The bit does not need a property

The template above always leaves the start horizontally, so in principle there is
a bit to expose. In practice there is not, because the collapses in the table
already cover every way a route can meet its endpoints:

| Leaves the start | Arrives at the end | Reached by |
| --- | --- | --- |
| horizontally | vertically | bend point anywhere |
| horizontally | horizontally | bend point on the end row |
| vertically | vertically | bend point on the start column |
| vertically | horizontally | bend point on the opposite corner of the box |

A `Start Direction` property would therefore be a second, less discoverable way
of doing what dragging already does, so it is not offered. The single shape it
would add is the mirror-image staircase through a given bend point, which one
more bend point reaches anyway.

The bit does survive as a plain field, because a quarter-turn rotation swaps the
two axes and an `H V H V` route becomes a `V H V H` one, which the fixed template
cannot express. `OrthogonalComponentTransformer` records the swap there so that
rotating a component yields exactly the rotated route. Nothing else reads or
writes it, and it never appears in the property editor.

### Why not the alternatives

| Scheme | Verdict |
| --- | --- |
| One handle, only one coordinate honoured, arrangement from an enum | Half of the handle's motion is visibly inert with no explanation, and it does not generalise past two bends without a second property. |
| One handle, arrangement inferred from which side of the diagonal it is on | The route snaps between `HVH` and `VHV` mid-drag. Predictable to implement, unpleasant to use. |
| Store corners raw and project them onto a legal path on every read | Over-parameterised: `2k` stored numbers for `k - 1` degrees of freedom, so the projection needs to know which point moved last, and a whole-component drag rewrites the raw values and loses the arrangement. |

## 4. Class layout

| Class | Module | Role |
| --- | --- | --- |
| `AbstractOrthogonalComponent<T>` | `diylc-core`, `org.diylc.components` | Sibling of `AbstractCurvedComponent`. Owns the control points, the point-count and start-direction properties, the corner radius, path construction, length and caching bounds. Declares `protected abstract void drawCurve(Path2D, Graphics2D, ComponentState, IDrawingObserver)`, the same hook `AbstractCurvedComponent` uses, so concrete subclasses stay thin. |
| `OrthogonalComponentTransformer` | `diylc-core`, `org.diylc.components.transform` | Delegates point rotation to `SimpleComponentTransformer`, then flips `Start Direction`. Mirroring needs no flip and passes straight through. |
| `OrthogonalWire` | `diylc-library`, `org.diylc.components.connectivity` | The layout part, shown as `Right Angle Wire` under `Connectivity`. `AWG` value, stripe support, `IContinuity`. Its body is close to a copy of `HookupWire`'s, which is the point of reusing the `drawCurve` hook. |
| `OrthogonalLine` | `diylc-library`, `org.diylc.components.connectivity` | The schematic part, shown as `Right Angle Line` under `Schematic Symbols`. Draws the same route as a plain stroke of a given thickness, one pixel by default, with the optional arrow heads `Line` offers. |

The two concrete parts differ only in `drawCurve` and in the properties each adds
on top of the base. `Right Angle Line` mirrors `Line`'s property set exactly:
thickness, colour, style, arrow size and the two arrow toggles. It also carries
`IContinuity`, which `Line` does not, because it sits in `Schematic Symbols`
rather than `Shapes` and a wire drawn between two symbols is expected to show up
in the netlist.

Its arrow heads take their direction from the first and the last route segment
rather than from the straight line between the endpoints, and they are not
trimmed out of the stroke the way `Line` trims its own. The head is filled in the
line colour with its tip on the endpoint, so whatever runs underneath it is
already hidden.

## 5. Geometry

`buildVertices()` returns the full vertex list including any zero-length
collapses, then consecutive duplicates are dropped. `buildPath()` walks the
deduplicated list and rounds each corner:

```
r_i = min(cornerRadius, len(v[i-1], v[i]) / 2, len(v[i], v[i+1]) / 2)
```

The corner is drawn as a quadratic Bezier whose control point is the corner
itself, from the point `r_i` before it to the point `r_i` after it. Clamping to
half of each adjacent segment means short segments and collapsed segments
degrade to sharp corners instead of overshooting; an arc would look marginally
better at large radii but the difference is invisible at the radii this
component is for.

`Corner Radius` is a `Size` property, default around `0.05in`, `0` giving hard
corners.

## 6. Component contract

| Member | Behaviour |
| --- | --- |
| `creationMethod` | `SINGLE_CLICK`, as `HookupWire`. `POINT_BY_POINT` only ever assigns control points `0` and `1`, so it cannot place a component whose second endpoint is not index 1. |
| `isControlPointSticky` | `true` only for the first and last index. |
| `canControlPointOverlap` | `true` for interior indices. |
| `getControlPointVisibilityPolicy` | `WHEN_SELECTED` for every index. |
| `getControlPointNodeName` | `null` for interior indices. |
| `arePointsConnected` | `true` only for the pair `{0, count - 1}`, exactly as `HookupWire`. |
| Selection guidelines | Draw the dashed guideline polyline through the derived vertices with tracking off, as `AbstractCurvedComponent.draw` does. |
| Hit area | Falls out of filling the stroked path while the drawing observer is tracking. |
| `getLength` | Exact sum of segment lengths, so `IHaveLength` is honest here in a way the Bezier approximation is not. |
| `enableCache` | `false`, matching `HookupWire`. |

## 7. Defaults

Dropped on an empty canvas the component spans `DEFAULT_SIZE` diagonally, with
the single handle at `((A.x + B.x) / 2, B.y)`, which renders as a plain `HVH`
route. That is the shape most users expect from a right-angle connector, and one
drag of the handle reaches everything else.

## 8. What was built

| File | Module |
| --- | --- |
| `org/diylc/components/AbstractOrthogonalComponent.java` | `diylc-core` |
| `org/diylc/components/transform/OrthogonalComponentTransformer.java` | `diylc-core` |
| `org/diylc/components/connectivity/OrthogonalWire.java` | `diylc-library` |
| `org/diylc/components/connectivity/OrthogonalLine.java` | `diylc-library` |
| `org/diylc/components/AbstractOrthogonalComponentTest.java` | `diylc-core`, tests |

The three open questions were settled as follows.

1. The component is called `Right Angle Wire` and sits in `Connectivity`, next to
   `Hookup Wire`, whose drawing code it shares through the `drawCurve` hook. Its
   property list differs from `Hookup Wire`'s only in carrying `Corner Radius`
   where the curved wire carries `Smooth`.
2. The handle count ships configurable from the start, as `Point Count` with
   values `Three`, `Four` and `Five`, matching `AbstractCurvedComponent`'s
   property of the same name. Changing it spreads the bend points into an even
   staircase between the two ends.
3. No snapping was added. The clean shapes are already one grid step away, and a
   snap that pulls a handle onto the start column or end row would fight
   snap-to-grid rather than complement it. This is the decision most worth
   revisiting, since with no `Start Direction` property those two alignments are
   now the only route to the two-bend shapes.

The test covers the routing template in both start directions, the degenerate
shapes, the invariant that every produced segment is axis aligned, point-count
changes, and the transformer contract that rotating the component yields exactly
the rotated route.