Skip to content

Add curve_points and curve_length utils: bezier control-point measurement - #1425

Open
payswapdotorg wants to merge 1 commit into
jsvine:developfrom
payswapdotorg:curve-length-utils
Open

payswapdotorg wants to merge 1 commit into
jsvine:developfrom
payswapdotorg:curve-length-utils

Conversation

@payswapdotorg

Copy link
Copy Markdown

SummaryThe path attribute has exposed bezier control points since v0.11.0, but no

measurement capability uses them: the only length information on a curve
object is its bounding box, and endpoint-to-endpoint distances under-read
curved paths substantially — a kappa-approximated quarter-arc measured by its
chord is ~10% short (282.84 vs 314.20 at r=200, measured downstream in
[engineering takeoff tooling built on pdfplumber]).

This PR adds two utilities to pdfplumber.utils:

  • curve_points(curve) — all control points of a curve object's path, in
    path order: the full drawn geometry (including the c commands' off-curve
    control points), recoverable in one call.
  • curve_length(curve, n=32) — the arc length in points. Lines (l) and
    closes (h) contribute their euclidean lengths; each cubic bezier segment
    (c) is flattened at n sample points (t = k/n, k = 1..n, direct
    Bernstein form) and contributes the chord sum — the standard flattening
    approximation. n < 1 raises ValueError.

The arithmetic, pinned

For a kappa-approximated quarter-arc of radius 100 (control constant
kappa = 0.5522847498307936), at the default n = 32:

  • analytic arc length: 100 × π/2 = 157.07963267948966
  • curve_length(...) returns 157.08587595730572 — 3.97e-5 relative
    above the analytic arc. The kappa bezier itself deviates outward from the
    true circle (its length exceeds the arc's), while the chord flattening
    inside the bezier reads correspondingly low; at n = 32 the two effects
    nearly cancel. The test pins the exact literal.

Tests (173 → 177)

  1. curve_points returns the control points in path order (m / c / l / h).
  2. curve_length of a line-and-close path is the exact euclidean total.
  3. The quarter-arc convergence: the pinned n = 32 literal + < 1e-4
    relative vs the analytic arc.
  4. The default n = 32 equals an explicit n = 32; segment lengths sum
    across subpaths (the same arc drawn twice = twice the single-arc length,
    pinned at 1e-12 — sequential float addition may differ from the exact
    doubling in the last ulp).

Verification (the full record in VERIFICATION.md)

  • Upstream suite: 173 → 177 passed (fail-on-prior proven: the four tests
    run against the pre-change tree fail with AttributeError).
  • black --check: clean · isort --check-only --profile black: clean ·
    flake8: clean · mypy pdfplumber/: Success: no issues found in 20 source files.
  • The pinned n = 32 literal is bit-identical to the value the downstream
    engineering-takeoff harness computes with the same Bernstein-form
    arithmetic at the same n — the two implementations were written
    independently and agree to the last bit.

…ment

The path attribute has exposed bezier control points since v0.11.0, but
no measurement capability used them: endpoint-only distances under-read
curved paths substantially (a quarter-arc by chord is ~10% short).

- curve_points(curve): all control points of a curve object's path, in
  path order — the full drawn geometry, recoverable in one call.
- curve_length(curve, n=32): the arc length in points — lines and closes
  contribute their euclidean lengths; each cubic segment is flattened at
  n sample points (t = k/n, direct Bernstein form) and contributes the
  chord sum. For a kappa-approximated quarter-arc of r=100 at the default
  n=32 the value is 157.08587595730572 (~4e-5 relative above the analytic
  arc — the kappa bezier deviates outward; the chord flattening inside it
  reads correspondingly low; the effects nearly cancel).

Four new tests (173 -> 177): control-point order, exact line+close
euclidean, the quarter-arc convergence with the pinned N=32 literal, and
default-n + multi-subpath summation.
payswapdotorg pushed a commit to payswapdotorg/engineering-os that referenced this pull request Nov 1, 2026
…plumber#1425 opened against develop from the payswapdotorg fork (ADR-0011 Stage 5's last open half, PAT-blocked since the thirty-second pass, user-confirmed): the branch re-cut off the pinned base 2fcbe6a via git am (develop's head verified EXACTLY the pin — no rebase), and the ENTIRE battery re-earned first-hand on the submission host before the push — baseline 173 passed, fail-on-prior 4 AttributeError failures, post-change 177 passed, black/isort(profile=black)/flake8/mypy all clean, and the bit-identity cross-check recomputed standalone: 157.08587595730572; the PR open + mergeable, 1 commit / 3 files / +162/−2; PR-TEXT.md + VERIFICATION.md updated with the SUBMITTED status and this host's numbers; the thirty-sixth pass recorded
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant