@pascal-app/editor 1.0.1 → 1.0.4

package/src/lib/floorplan/site-plan/front-edge.ts

@@ -0,0 +1,156 @@
+/**
+ * The street-facing lot edge from the mapped roads. Pure: no store, no
+ * network.
+ *
+ * For every lot edge, score how well a road fronts it:
+ *   1. PARALLELISM — the edge direction must be within `FRONT_EDGE_PARALLEL_DEG`
+ *      of the nearest road segment (streets run ALONG a frontage; a road
+ *      perpendicular to an edge is rejected).
+ *   2. OUTSIDE — the nearest road point must sit on the OUTWARD side of the
+ *      edge: the street is off the lot, not a driveway cutting through it.
+ *   3. DISTANCE — among edges that pass, the smallest edge-midpoint-to-road
+ *      distance wins (the closest fronting street); edges within
+ *      `FRONT_EDGE_DISTANCE_TIE_M` of each other are a tie, and the LONGER
+ *      edge takes it — a sliver left by a curb return or a split frontage
+ *      never beats the frontage it sits beside.
+ * CORNER AND THROUGH LOTS: when the address's street matches a road, edges
+ * fronting THAT road are preferred over a merely-closer other street — the
+ * addressed street is the true front. The match keeps the street type and
+ * the directional (street-name.ts, USPS Pub. 28): "NW 34th St" is not
+ * "NW 34th Terrace".
+ *
+ * Coordinates are the site plan frame (metres, x east, y south), the frame
+ * the lot polygon and the OSM roads share.
+ */
+import { edgeLength, outwardNormal, type Pt } from './geometry'
+import { parseStreetName, sameStreet } from './street-name'
+
+export interface RoadCenterline {
+  name?: string
+  centerline: readonly Pt[]
+}
+
+export interface FrontEdgeMatch {
+  /** Lot edge index: the edge runs from `points[index]` to `points[index + 1]`. */
+  index: number
+  /** Edge midpoint to the road centerline, metres. */
+  distance: number
+  /** The fronting road's name ('' when OSM has none). */
+  name: string
+  /** True when the road is the address's street — name, type and directional (corner / through-lot rule). */
+  named: boolean
+  /** Every lot edge a street runs along (parallel, outside, within 25 m): a corner lot lists two or more. */
+  streetEdges?: number[]
+  /** The street each of those edges runs along (the nearest road's name), by edge index; unnamed roads are left out. */
+  streetNames?: Record<string, string>
+}
+
+export const FRONT_EDGE_PARALLEL_DEG = 30
+export const FRONT_EDGE_DISTANCE_TIE_M = 1.5
+
+/** `next` beats `best` when it is clearly nearer, or as near and longer. */
+function better(
+  next: FrontEdgeMatch & { length: number },
+  best: (FrontEdgeMatch & { length: number }) | null,
+): boolean {
+  if (!best) return true
+  if (next.distance < best.distance - FRONT_EDGE_DISTANCE_TIE_M) return true
+  if (next.distance > best.distance + FRONT_EDGE_DISTANCE_TIE_M) return false
+  return next.length > best.length
+}
+
+/**
+ * Core street name: the house number, the directionals and the street type
+ * dropped — "2600 Castro Way" ↔ OSM "Castro Way" ↔ "S Castro"; OSM spells
+ * the quadrant out ("Northeast 109th Street" ↔ "NE 109th St"). The core
+ * alone does not say two lines are one street: `sameStreet` also compares
+ * the type and the directional.
+ */
+export function streetCore(s: string | null | undefined): string {
+  return parseStreetName(s).name
+}
+
+/** The winning lot-edge index with its road, or null (keep the current / fallback edge). */
+export function detectFrontEdgeFromRoads(
+  lot: readonly Pt[],
+  roads: readonly RoadCenterline[],
+  addressStreet?: string | null,
+): FrontEdgeMatch | null {
+  const n = lot.length
+  if (n < 3 || roads.length === 0) return null
+  const sinLimit = Math.sin((FRONT_EDGE_PARALLEL_DEG * Math.PI) / 180)
+  const want = parseStreetName(addressStreet)
+  let best: (FrontEdgeMatch & { length: number }) | null = null
+  let bestNamed: (FrontEdgeMatch & { length: number }) | null = null
+  const streetEdges: number[] = []
+  const streetNames: Record<string, string> = {}
+
+  for (let i = 0; i < n; i++) {
+    const a = lot[i] as Pt
+    const b = lot[(i + 1) % n] as Pt
+    const len = edgeLength(lot, i)
+    if (len < 0.05) continue
+    const mid: Pt = [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2]
+    const ex = (b[0] - a[0]) / len
+    const ey = (b[1] - a[1]) / len
+    const [nx, ny] = outwardNormal(lot, i)
+
+    // nearest road segment to this edge's midpoint, across every centerline
+    let near = Number.POSITIVE_INFINITY
+    let nearPt: Pt | null = null
+    let nearDir: Pt | null = null
+    let nearName = ''
+    for (const road of roads) {
+      const cl = road.centerline
+      for (let k = 0; k + 1 < cl.length; k++) {
+        const s0 = cl[k] as Pt
+        const s1 = cl[k + 1] as Pt
+        const dx = s1[0] - s0[0]
+        const dy = s1[1] - s0[1]
+        const dd = dx * dx + dy * dy
+        if (dd < 1e-12) continue
+        const t = Math.max(0, Math.min(1, ((mid[0] - s0[0]) * dx + (mid[1] - s0[1]) * dy) / dd))
+        const foot: Pt = [s0[0] + dx * t, s0[1] + dy * t]
+        const d = Math.hypot(mid[0] - foot[0], mid[1] - foot[1])
+        if (d < near) {
+          near = d
+          nearPt = foot
+          const sl = Math.sqrt(dd)
+          nearDir = [dx / sl, dy / sl]
+          nearName = road.name ?? ''
+        }
+      }
+    }
+    if (!nearPt || !nearDir) continue
+    // (1) parallel: |sin(angle between the edge and the road)| small
+    const sinAng = Math.abs(ex * nearDir[1] - ey * nearDir[0])
+    if (sinAng > sinLimit) continue
+    // (2) outside: the road lies on the outward side of the edge
+    if ((nearPt[0] - mid[0]) * nx + (nearPt[1] - mid[1]) * ny <= 0) continue
+
+    // a street runs along this edge (a corner lot collects two or more)
+    if (near <= 25 && len >= 3) {
+      streetEdges.push(i)
+      if (nearName) streetNames[String(i)] = nearName
+    }
+    const match = { index: i, distance: near, name: nearName, named: false, length: len }
+    if (better(match, best)) best = match
+    if (sameStreet(want, nearName) && better(match, bestNamed)) {
+      bestNamed = { ...match, named: true }
+    }
+  }
+  const pick = bestNamed ?? best
+  return pick
+    ? {
+        index: pick.index,
+        distance: pick.distance,
+        name: pick.name,
+        named: pick.named,
+        streetEdges: streetEdges.includes(pick.index) ? streetEdges : [pick.index, ...streetEdges],
+        streetNames:
+          pick.name && !streetNames[String(pick.index)]
+            ? { ...streetNames, [String(pick.index)]: pick.name }
+            : streetNames,
+      }
+    : null
+}

package/src/lib/floorplan/site-plan/geometry.test.ts

@@ -0,0 +1,275 @@
+import { describe, expect, it } from 'bun:test'
+import { sightTriangle, streetCorners } from '@pascal-app/core'
+import {
+  boundsInsidePolygon,
+  castYardDimensions,
+  classifyEdges,
+  edgeHeadingDeg,
+  formatFeetInches,
+  METRES_PER_FOOT,
+  mostNorthFacingEdge,
+  outwardNormal,
+  type Pt,
+  polygonArea,
+  rayToPolygon,
+  resolveFrontEdge,
+  setbackEnvelope,
+  setbackForRole,
+} from './geometry'
+
+/**
+ * 30 m (east-west) × 20 m (north-south) lot, origin at the north-west corner,
+ * wound clockwise in the plan frame (x east, y south).
+ *
+ *   edge 0: north side (top, faces north)
+ *   edge 1: east side
+ *   edge 2: south side
+ *   edge 3: west side
+ */
+const LOT: Pt[] = [
+  [0, 0],
+  [30, 0],
+  [30, 20],
+  [0, 20],
+]
+
+describe('outwardNormal', () => {
+  it('points out of the ring for every edge regardless of winding', () => {
+    const near = (i: number, x: number, y: number) => {
+      const n = outwardNormal(LOT, i)
+      expect(n[0]).toBeCloseTo(x, 9)
+      expect(n[1]).toBeCloseTo(y, 9)
+    }
+    near(0, 0, -1) // north edge faces north (−y)
+    near(1, 1, 0) // east
+    near(2, 0, 1) // south
+    near(3, -1, 0) // west
+
+    // Reversing the winding relabels the edges but normals still point out:
+    // reversed edge 0 runs [0,20] → [30,20], the south side.
+    const reversed = [...LOT].reverse()
+    const n0 = outwardNormal(reversed, 0)
+    expect(n0[0]).toBeCloseTo(0, 9)
+    expect(n0[1]).toBeCloseTo(1, 9)
+  })
+})
+
+describe('edge headings + front edge', () => {
+  it('reports compass headings clockwise from north', () => {
+    expect(edgeHeadingDeg(LOT, 0)).toBeCloseTo(0, 6)
+    expect(edgeHeadingDeg(LOT, 1)).toBeCloseTo(90, 6)
+    expect(edgeHeadingDeg(LOT, 2)).toBeCloseTo(180, 6)
+    expect(edgeHeadingDeg(LOT, 3)).toBeCloseTo(270, 6)
+  })
+
+  it('honours northRotation', () => {
+    // Rotate true north 90° clockwise: the plan-up edge now faces west.
+    expect(edgeHeadingDeg(LOT, 0, Math.PI / 2)).toBeCloseTo(270, 6)
+  })
+
+  it('picks the most north-facing edge as the fallback front', () => {
+    expect(mostNorthFacingEdge(LOT)).toBe(0)
+    expect(resolveFrontEdge(LOT, undefined)).toBe(0)
+    expect(resolveFrontEdge(LOT, 2)).toBe(2)
+    // Out-of-range indexes fall back rather than throw.
+    expect(resolveFrontEdge(LOT, 9)).toBe(0)
+  })
+})
+
+describe('classifyEdges', () => {
+  it('assigns front / rear and splits the remaining edges left and right', () => {
+    const roles = classifyEdges(LOT, 0)
+    expect(roles[0]).toBe('front')
+    expect(roles[2]).toBe('rear')
+    expect(new Set([roles[1], roles[3]])).toEqual(new Set(['left', 'right']))
+  })
+
+  it('resolves per-role setbacks with left/right overriding side', () => {
+    const s = { front: 7.6, side: 1.5, rear: 4.6, right: 3 }
+    expect(setbackForRole(s, 'front')).toBe(7.6)
+    expect(setbackForRole(s, 'rear')).toBe(4.6)
+    expect(setbackForRole(s, 'left')).toBe(1.5)
+    expect(setbackForRole(s, 'right')).toBe(3)
+  })
+})
+
+describe('setbackEnvelope', () => {
+  it('a corner lot: the second street side takes the street setback and the sight triangle clips the corner', () => {
+    // a 30 × 20 lot; edge 0 (north, y = 0) is the front, edge 1 (east, x = 30) the other street
+    const roles = classifyEdges(LOT, 0, [0, 1])
+    expect(roles[1]).toBe('street')
+    expect(roles[2]).toBe('rear')
+    expect(setbackForRole({ front: 7.5, side: 2, rear: 5 }, 'street')).toBe(7.5)
+    expect(setbackForRole({ front: 7.5, side: 2, rear: 5, streetSide: 4 }, 'street')).toBe(4)
+    const plain = setbackEnvelope(LOT, { front: 7.5, side: 2, rear: 5, streetSide: 4 }, 0, {
+      streetEdges: [0, 1],
+    })
+    const xs = plain.map((p) => p[0])
+    expect(Math.max(...xs)).toBeCloseTo(26, 6) // the east street side in 4, not the 2 ft side yard
+    // the 25 ft (7.62 m) sight triangle at the NE corner: its hypotenuse from (22.38, 0) to (30, 7.62) keeps the envelope out
+    const clipped = setbackEnvelope(LOT, { front: 7.5, side: 2, rear: 5, streetSide: 4 }, 0, {
+      streetEdges: [0, 1],
+      sightTriangleM: 7.62,
+    })
+    expect(clipped.length).toBeGreaterThanOrEqual(4)
+    for (const v of clipped) {
+      // outside the triangle: x + y ≥ 30 − 7.62 ... the hypotenuse is x − y = 22.38 ... points with x − y > 22.38 are inside it
+      expect(v[0] - v[1]).toBeLessThanOrEqual(22.38 + 0.05)
+    }
+    const tri = sightTriangle(LOT, 0, 1, 7.62)
+    expect(tri).not.toBeNull()
+    expect(tri!.corner[0]).toBeCloseTo(30, 6)
+    expect(tri!.corner[1]).toBeCloseTo(0, 6)
+    expect(streetCorners(LOT, [0, 1])).toEqual([[0, 1]])
+  })
+
+  it('a cul-de-sac corner (a run of short arc edges) is offset as one chord — no vertex runs away', () => {
+    const cape: [number, number][] = [
+      [-2, 0],
+      [-2, 30.1],
+      [-40, 32.7],
+      [-40, -5.6],
+      [-10.1, -7.6],
+      [-8.9, -7.6],
+      [-7.7, -7.3],
+      [-6.5, -6.9],
+      [-5.4, -6.3],
+      [-4.4, -5.5],
+      [-3.6, -4.6],
+      [-2.9, -3.6],
+      [-2.4, -2.4],
+      [-2.1, -1.2],
+    ]
+    const env = setbackEnvelope(cape, { front: 6.096, side: 1.524, rear: 4.572 }, 0)
+    expect(env.length).toBeGreaterThanOrEqual(6)
+    // every envelope vertex lies inside the lot, at least its setback from every lot line
+    const segDist = (p: readonly number[], a: readonly number[], b: readonly number[]) => {
+      const abx = b[0]! - a[0]!
+      const aby = b[1]! - a[1]!
+      const t = Math.max(
+        0,
+        Math.min(1, ((p[0]! - a[0]!) * abx + (p[1]! - a[1]!) * aby) / (abx * abx + aby * aby)),
+      )
+      return Math.hypot(p[0]! - (a[0]! + abx * t), p[1]! - (a[1]! + aby * t))
+    }
+    // the curb return (edges 4–13) is street frontage: it takes the FRONT setback, never a side yard
+    const frontLike = new Set([0, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13])
+    for (const v of env) {
+      for (let i = 0; i < cape.length; i++) {
+        const want = frontLike.has(i) ? 6.096 : 1.524
+        expect(segDist(v, cape[i]!, cape[(i + 1) % cape.length]!)).toBeGreaterThan(want - 0.06)
+      }
+    }
+    // the front line (x = −2, the east side) offset 6.1 m in: two vertices on x ≈ −8.1
+    const onFront = env.filter((v) => Math.abs(v[0] - (-2 - 6.096)) < 0.05)
+    expect(onFront.length).toBeGreaterThanOrEqual(2)
+    // the return's offset is a curve of its own (a 6.1 m buffer round the return's points), not a chord: the
+    // envelope turns through more than one vertex between the front offset and the south offset
+    const turning = env.filter((v) => v[0] < -8.2 + 0.05 && v[1] < 2 && v[1] > -6.2)
+    expect(turning.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('offsets each edge inward by its own setback', () => {
+    const env = setbackEnvelope(LOT, { front: 7.5, side: 2, rear: 5 }, 0)
+    expect(env).toHaveLength(4)
+    const xs = env.map((p) => p[0]).sort((a, b) => a - b)
+    const ys = env.map((p) => p[1]).sort((a, b) => a - b)
+    // North (front) edge in 7.5, south (rear) in 5, both sides in 2.
+    expect(xs[0]).toBeCloseTo(2, 9)
+    expect(xs[3]).toBeCloseTo(28, 9)
+    expect(ys[0]).toBeCloseTo(7.5, 9)
+    expect(ys[3]).toBeCloseTo(15, 9)
+    expect(polygonArea(env)).toBeCloseTo(26 * 7.5, 6)
+  })
+
+  it('applies left/right overrides to the correct sides', () => {
+    const env = setbackEnvelope(LOT, { front: 0, side: 0, rear: 0, left: 4, right: 1 }, 0)
+    const xs = env.map((p) => p[0]).sort((a, b) => a - b)
+    // Front edge runs [0,0] → [30,0]; "left" is behind that direction (west).
+    expect(xs[0]).toBeCloseTo(4, 9)
+    expect(xs[3]).toBeCloseTo(29, 9)
+  })
+
+  it('rejects setbacks that consume the lot instead of drawing a bow tie', () => {
+    expect(setbackEnvelope(LOT, { front: 12, side: 2, rear: 12 }, 0)).toEqual([])
+    expect(setbackEnvelope(LOT, { front: 0, side: 0, rear: 0 }, 0)).toEqual([])
+    expect(setbackEnvelope([[0, 0]], { front: 1, side: 1, rear: 1 }, 0)).toEqual([])
+  })
+  it('a frontage the county drew as two nearly straight lines takes one front yard, not an arc', () => {
+    // 1054 Rivera Dr, Sacramento as the parcel fabric draws it: the front (north, y ≈ −15.4) split
+    // at a kink of under 2° into edges 3 and 4; the street lookup failed, so only edge 4 came back
+    // as frontage
+    const rivera: Pt[] = [
+      [12.39, -15.35],
+      [12.77, 14.38],
+      [-14.32, 15.47],
+      [-14.34, -15.26],
+      [-1.53, -15.56],
+    ]
+    const env = setbackEnvelope(rivera, { front: 6.096, side: 1.524, rear: 4.572 }, 4, {
+      streetEdges: [4],
+    })
+    // straight across the whole frontage (the kink's own corner, no curve round it): five corners at most
+    expect(env.length).toBeLessThanOrEqual(5)
+    const segDist = (p: readonly number[], a: readonly number[], b: readonly number[]) => {
+      const abx = b[0]! - a[0]!
+      const aby = b[1]! - a[1]!
+      const t = Math.max(
+        0,
+        Math.min(1, ((p[0]! - a[0]!) * abx + (p[1]! - a[1]!) * aby) / (abx * abx + aby * aby)),
+      )
+      return Math.hypot(p[0]! - (a[0]! + abx * t), p[1]! - (a[1]! + aby * t))
+    }
+    // both halves of the frontage keep the front yard
+    for (const v of env)
+      for (const i of [3, 4])
+        expect(segDist(v, rivera[i]!, rivera[(i + 1) % rivera.length]!)).toBeGreaterThan(
+          6.096 - 0.06,
+        )
+  })
+})
+
+describe('rayToPolygon + castYardDimensions', () => {
+  it('finds the nearest boundary crossing along a ray', () => {
+    const hit = rayToPolygon(LOT, [15, 10], 0, -1)
+    expect(hit?.distance).toBeCloseTo(10, 9)
+    expect(hit?.point[1]).toBeCloseTo(0, 9)
+    // A ray from outside pointing away never hits.
+    expect(rayToPolygon(LOT, [15, -5], 0, -1)).toBeNull()
+  })
+
+  it('casts four yard dimensions from the footprint bbox edge midpoints', () => {
+    const yards = castYardDimensions(LOT, { minX: 10, minY: 6, maxX: 20, maxY: 14 })
+    expect(yards.map((y) => y.side).sort()).toEqual(['east', 'north', 'south', 'west'])
+    const by = Object.fromEntries(yards.map((y) => [y.side, y]))
+    expect(by.north?.distance).toBeCloseTo(6, 9)
+    expect(by.south?.distance).toBeCloseTo(6, 9)
+    expect(by.west?.distance).toBeCloseTo(10, 9)
+    expect(by.east?.distance).toBeCloseTo(10, 9)
+    // Dimensions start at the bbox midpoints, not the corners.
+    expect(by.north?.from).toEqual([15, 6])
+    expect(by.west?.from).toEqual([10, 10])
+  })
+
+  it('omits a side whose ray misses the lot rather than faking a number', () => {
+    // Footprint entirely north of (above) the lot: nothing casts north.
+    const yards = castYardDimensions(LOT, { minX: 10, minY: -30, maxX: 20, maxY: -25 })
+    expect(yards.map((y) => y.side)).not.toContain('north')
+  })
+})
+
+describe('boundsInsidePolygon', () => {
+  it('is true only when every bbox corner is inside the lot', () => {
+    expect(boundsInsidePolygon(LOT, { minX: 5, minY: 5, maxX: 25, maxY: 15 })).toBe(true)
+    expect(boundsInsidePolygon(LOT, { minX: -5, minY: 5, maxX: 25, maxY: 15 })).toBe(false)
+    expect(boundsInsidePolygon(LOT, { minX: 100, minY: 100, maxX: 110, maxY: 110 })).toBe(false)
+  })
+})
+
+describe('formatFeetInches', () => {
+  it('renders metres as feet-and-inches', () => {
+    expect(formatFeetInches(7.62)).toBe(`25'-0"`)
+    expect(formatFeetInches(METRES_PER_FOOT * 24.5)).toBe(`24'-6"`)
+    expect(formatFeetInches(0)).toBe(`0'-0"`)
+  })
+})