Recomposed
Canvas

PathMeasure: Position und Richtung an jedem beliebigen Punkt entlang eines Pfads

Oct 17, 2026 · 7 min read

PathMeasure: Position und Richtung an jedem beliebigen Punkt entlang eines Pfads

Die Intuition

Ein Path wird aus moveTo/quadraticTo/cubicTo-Aufrufen aufgebaut, daher liegt es nahe anzunehmen, "50 % des Wegs entlang des Pfads" bedeute t = 0.5 in dem jeweiligen Kurvenaufruf, der ihn gezeichnet hat. Das stimmt nicht.

  • Das t einer Kurve ist ein Mischgewicht, das in ihre Interpolationsmathematik einfließt, keine Pixel-Messung. Wo immer ein Kontrollpunkt am stärksten zieht, legt die Kurve pro Schritt von t mehr Strecke zurück; wo er am wenigsten zieht, deckt derselbe Schritt von t fast nichts ab.
  • t = 0.5 landet dort, wo die Interpolation es eben hinlegt. Nichts an der Zahl 0.5 verknüpft sie mit "der Hälfte der Pixel" der Kurve.
  • Was man für einen bewegten Punkt, ein Draw-on-Stroke-Reveal oder einen Text, der einer Kurve folgt, tatsächlich braucht, ist Distanz: "gib mir den Punkt 150 Pixel entlang dieses Pfads", unabhängig davon, wie das t der Kurve selbst verteilt ist.

PathMeasure hat genau eine Aufgabe in zwei Schritten: einmal einen Path durchlaufen, um seine tatsächliche Länge zu ermitteln, und dann Position und Richtung an jeder beliebigen Distanz innerhalb dieser Länge abfragen lassen – t kommt dabei nie ins Spiel.

Das Problem: t ist ein Mischgewicht, keine Distanz

val path = Path().apply {
    moveTo(20f, 20f)
    quadraticTo(x1 = 260f, y1 = 20f, x2 = 260f, y2 = 80f)
}

Der Kontrollpunkt bei (260, 20) sitzt weit seitlich der Sehne zwischen Start und Ende, daher zieht er stark an der frühen Hälfte der Kurve und kaum an der späteren Hälfte.

Ziehe den Schieberegler unten und beobachte, wie sich die Lücke zwischen den beiden Punkten öffnet: Der Punkt mit rohem t schießt früh voraus, während der Punkt mit Bogenlänge ein gleichmäßiges Tempo hält und erst gegen Ende, wenn die Kurve flacher wird, wieder aufholt:

raw tarc length (real)
50%

drag the slider — progress 50%, raw-t dot is 180.6px away from the real arc-length position

Niemand programmiert die Interpolation hinter diesem Punkt mit rohem t von Hand – quadraticTo führt sie bereits intern aus, man ruft sie also nie selbst auf. Der Fehler, für den sie steht, ist aber einer, den man tatsächlich schreibt: einen einfachen 0f..1f-Fortschritt, von animateFloat, einer Drag-Geste, einer SeekBar, direkt in irgendetwas zu füttern, das den eigenen Parameterraum der Kurve durchläuft statt echter Distanz. Ein handgeschriebener Sampler für "gleichmäßig verteilte Wegpunkte", eine Dash-Phase-Berechnung, eine Rotation, die direkt an progress gekoppelt ist – sie alle gehen davon aus, dass progress = 0.5 bereits "die Hälfte der Pixel" bedeutet. Das tut es nicht:

// the math behind the raw-t dot above, for reference, not something
// you'd write yourself: t fed straight into quadraticTo's own interpolation
fun quadraticAt(p0: Offset, p1: Offset, p2: Offset, t: Float): Offset {
    val mt = 1 - t
    return Offset(
        x = mt * mt * p0.x + 2 * mt * t * p1.x + t * t * p2.x,
        y = mt * mt * p0.y + 2 * mt * t * p1.y + t * t * p2.y,
    )
}
val raw = quadraticAt(Offset(20f, 20f), Offset(260f, 20f), Offset(260f, 80f), t = 0.5f)
// raw == Offset(200f, 35f)

t = 0.5 landet bei (200, 35), was sich als bereits 69 % des Wegs entlang der tatsächlichen 262px-Länge der Kurve herausstellt, nicht 50 %, weil die Kurve die meiste Distanz früh zurücklegt (wo der Kontrollpunkt am stärksten zieht) und sich durch den Rest schleppt.

val measure = PathMeasure()
measure.setPath(path, forceClosed = false)
 
val totalLength = measure.length // real pixel length of the curve
val point = measure.getPosition(distance = totalLength * progress)
val direction = measure.getTangent(distance = totalLength * progress)

progress = 0.5 bedeutet jetzt (150, 26), den tatsächlichen Mittelpunkt der 262px-Kurve, jedes Mal, unabhängig davon, wo der Kontrollpunkt zieht. Ein Punkt, der von getPosition angetrieben wird, bewegt sich mit konstanter visueller Geschwindigkeit von einem Ende zum anderen – t kommt dabei nie ins Spiel.

Was getPosition und getTangent tatsächlich zurückgeben

  • getPosition(distance): Offset ist der Punkt auf dem Pfad in dieser Distanz vom Start. Compose begrenzt distance stillschweigend auf 0..length, sodass eine Distanz vor dem Start oder hinter dem Ende keinen Fehler auslöst, sondern einfach zu dem näheren Ende springt.
  • getTangent(distance): Offset ist ein Richtungsvektor an genau diesem Punkt, kein Winkel. Er zeigt dorthin, wohin der Pfad an dieser Stelle verläuft, was genau das ist, was man braucht, um etwas so zu rotieren, dass es in Bewegungsrichtung zeigt (ein Auto-Icon, das in eine Kurve einer Rennstrecke einbiegt, ein Glyph, das sich kippt, um gekrümmtem Text zu folgen).

Diesen Richtungsvektor in eine Rotation-Float für graphicsLayer { rotationZ = ... } umzuwandeln, ist nur einen atan2-Aufruf entfernt:

val angleDegrees = Math.toDegrees(
    atan2(direction.y.toDouble(), direction.x.toDouble())
).toFloat()

The fundamental

Das ist Bogenlängen-Parametrisierung (arc-length parameterization): das Neuindizieren einer Kurve, sodass ihr Input echte zurückgelegte Distanz ist statt irgendeines Parameters, der zufällig die Mathematik definiert hat (das eigene t einer Kurve, ein Winkel, ein Knoten-Index). Gleiche Schritte im neuen Input bedeuten immer gleiche Schritte in Pixeln, was genau die Eigenschaft ist, die rohes t nicht hat. PathMeasure baut das auf, indem es den Pfad einmal durchläuft und dabei Länge akkumuliert, sodass spätere Distanz-Abfragen Lookups gegen diesen Durchlauf sind statt neuer Geometrie.

Anderswo: dasselbe Fundament, anderes Framework

  • SVG: SVGGeometryElement.getPointAtLength(length) und getTotalLength() auf jedem <path> tun genau das, dem Namen nach. "Length" im Methodennamen ist dieselbe Bogenlängen-Distanz, die PathMeasure.length liefert.
  • CSS motion path: offset-path plus offset-distance bewegt ein Element entlang eines SVG-Pfads nach echter Distanz, und der Browser taktet das Tempo für dich – ein komplettes PathMeasure, eingebaut in zwei CSS-Eigenschaften, ganz ohne JS.
  • WPF: PathGeometry.GetPointAtFractionLength(progress, out point, out tangent) nimmt einen 0-1-Bruchteil statt einer rohen Distanz, ist aber dieselbe Abfrage, Punkt und Tangente zusammen, im Kern bogenlängenbasiert.
  • Flutter: Path.computeMetrics() gibt eine Sequenz von PathMetric- Objekten zurück, jedes mit einer .length und einer .getTangentForOffset(distance), die Position und Winkel zusammen zurückliefert, dieselben zwei Werte, die getPosition/getTangent in getrennte Aufrufe aufteilen.
  • SwiftUI: Path.trimmedPath(from:to:) (und der darauf aufbauende Shape.trim(from:to:)-Modifier) kürzt nach echter Bogenlänge, nicht nach dem eigenen Kurvenparameter des Pfads. Dieselbe Kurve aus diesem Beitrag bei to: 0.5 zu kürzen landet auf ihrem tatsächlichen Bogenlängen-Mittelpunkt, nicht dort, wo rohes t = 0.5 landen würde – genau die Unterscheidung, um die es in diesem ganzen Beitrag geht.

Grenzfälle

Das PathMeasure von Compose misst nur die einzelne , die ihm gegeben wird, und es gibt kein nextContour(), um zur nächsten zu wechseln, anders als beim älteren android.graphics.PathMeasure, dem es nachempfunden ist.

Ruft man setPath mit einem Path auf, der aus mehreren getrennten Stücken besteht (addPath von zwei separaten Formen, zum Beispiel), berücksichtigen length/getPosition nur die erste gefundene Contour, und das still und heimlich. Wenn ein Pfad mehrere disjunkte Stücke hat, die alle durchlaufen werden müssen, messe jedes mit seinem eigenen PathMeasure, aufgebaut aus seinem eigenen Sub-Path, statt den kombinierten Pfad einer einzigen Instanz zu übergeben und zu erwarten, dass sie alles abdeckt.

forceClosed ändert, was "das Ende" für die Messung bedeutet, nicht was gezeichnet wird. forceClosed = true an setPath zu übergeben, fügt ein synthetisches Schlusssegment zurück zum Start hinzu, selbst wenn der Path selbst nie close() aufgerufen hat, und dieses Segment zählt von da an zu length und jeder Positionsabfrage. Der Stroke auf dem Bildschirm ändert sich in beiden Fällen nie, da forceClosed nur beeinflusst, was PathMeasure berechnet, nicht was drawPath rendert.

Der Pfad unten besteht nur aus zwei lineTo-Aufrufen, daher wird die Lücke zwischen seinem letzten Punkt und seinem Start nie tatsächlich gezeichnet; forceClosed umzuschalten schließt sie nicht. Was sich bewegt, ist der Endpunkt, getPosition(length): am letzten Punkt, den der Stroke mit forceClosed aus wirklich erreicht, zurückgesprungen zum Start, wenn es an ist, und length selbst springt um genau die Lückendistanz:

forceClosed
length: 0

toggle forceClosed — forceClosed false, length 0, end point at the last drawn point

Wann man zu PathMeasure greift

  • Draw-on-/Stroke-Reveal-Animationen: eine Signatur, die ihre eigenen Strokes nachspielt, die Routenlinie einer Lieferkarte, die sich hinter einem bewegten Pin aufzeichnet, ein Häkchen auf einer Checkliste, das sich selbst nachzieht.
  • Bewegung mit konstanter Geschwindigkeit entlang eines gekrümmten Pfads: der blaue Punkt einer Karten-App, der gleichmäßig entlang deiner Route gleitet statt von Wegpunkt zu Wegpunkt zu springen, das Icon eines Lieferverfolgers, das der Straße folgt, ein Avatar, der entlang des Level-Auswahl-Pfads eines Spiels hüpft.
  • Text oder Icons, die der Richtung einer Kurve folgen müssen, nicht nur ihrer Position: ein Wortmark, der entlang eines runden Abzeichens gebogen ist, eine Bildunterschrift, die sich entlang der Kante einer Foto-Collage biegt, ein Label, das sich um ein Tortendiagramm-Segment krümmt.

getPosition/getTangent beantworten "wo ist der Punkt gerade, und in welche Richtung zeigt er". getSegment beantwortet "gib mir alles zwischen diesen beiden Distanzen, als einen tatsächlich zeichenbaren Path", was Draw-on braucht: einen echten, kürzeren Pfad zum Stroken, keine Clip- oder Mask-Lösung:

val measure = PathMeasure()
measure.setPath(path, forceClosed = false)
 
val trimmed = Path()
measure.getSegment(
    startDistance = 0f,
    stopDistance = measure.length * progress,
    destination = trimmed,
)
drawPath(trimmed, style = Stroke(width = 4f))

Bei progress = 0.3 enthält trimmed nur die ersten 30 % der tatsächlichen Länge des Pfads, im Stroke-Reveal-Stil, unabhängig davon, wie das t der zugrunde liegenden Kurve verteilt ist, was derselbe Mechanismus ist, der hinter dem Kürzen eines Fortschrittsrings auf einen bestimmten Prozentsatz steckt.

destination wird an Ort und Stelle verändert statt zurückgegeben, und getSegment gibt false zurück (und lässt es unverändert) bei einem Segment der Länge null oder wenn startDistance nicht kleiner als stopDistance ist. Ein vierter Parameter, startWithMoveTo (standardmäßig true), steuert, ob das geschriebene Segment mit einem eigenen moveTo beginnt; setze ihn auf false, wenn mehrere Segmente an dasselbe destination angehängt werden, damit sie sich zu einem einzigen Sub-Pfad verbinden statt jedes Mal einen neuen zu beginnen.

Für Bewegung mit konstanter Geschwindigkeit ist das derselbe animateFloat-Fortschritt wie in der Demo weiter oben in diesem Beitrag, jetzt angetrieben von getPosition statt einem handgeschriebenen Sampler, was genau das gleichmäßige Tempo liefert, das der Punkt einer Karten-App braucht.

Für Text oder Icons, die der Richtung einer Kurve folgen, ist das Rotieren jedes Glyphs oder Icons, sodass es sich mit der Kurve mitkippt, getTangent plus atan2, einmal pro Position entlang des Pfads abgetastet, dieselbe Mathematik, die ein gekrümmter Wortmark oder ein Diagramm-Label braucht, um tangential zu seinem Bogen zu bleiben.

Mentales Modell zum tatsächlichen Gebrauch

Ein Path ist eine Zeichenanweisung; ein PathMeasure ist derselbe Pfad, neu indiziert nach echter Distanz. Greife jedes Mal dazu, wenn "Fortschritt" Pixel bedeuten muss, die zurückgelegt wurden, nicht dort, wo das eigene t einer Kurve zufällig landet.

Keep reading

Related reads

Neue Beiträge direkt in dein Postfach