Recomposed
Canvas

PathMeasure : Position et Direction à N'importe Quelle Distance le Long d'un Chemin

Oct 17, 2026 · 8 min read

PathMeasure : Position et Direction à N'importe Quelle Distance le Long d'un Chemin

L'intuition

Un Path est construit à partir d'appels moveTo/quadraticTo/cubicTo, donc il est tentant de supposer que « 50% du chemin parcouru » signifie t = 0.5 dans l'appel de courbe qui l'a tracé. Ce n'est pas le cas.

  • Le t d'une courbe est un poids d'interpolation injecté dans ses calculs mathématiques, pas une mesure en pixels. Partout où un point de contrôle tire le plus fort, la courbe couvre plus de terrain par pas de t ; partout où il tire le moins, le même pas de t ne couvre presque rien.
  • t = 0.5 atterrit là où cette interpolation dit qu'il atterrit. Rien dans le chiffre 0.5 ne le relie à « la moitié des pixels » de la courbe.
  • Ce que vous voulez réellement, pour un point en mouvement, une révélation de trait en tracé progressif, ou du texte qui suit une courbe, c'est la distance : « donne-moi le point à 150 pixels le long de ce chemin », indépendamment de la façon dont le t propre à la courbe se trouve être distribué.

Le travail de PathMeasure se résume à deux étapes : parcourir un Path une fois pour trouver sa longueur réelle, puis vous permettre d'interroger la position et la direction à n'importe quelle distance dans cette longueur, t n'entrant jamais en jeu.

Le problème : t est un poids d'interpolation, pas une distance

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

Le point de contrôle à (260, 20) se trouve loin sur le côté de la corde entre le début et la fin, donc il tire fort sur la première moitié de la courbe et presque pas sur sa deuxième moitié.

Faites glisser le curseur ci-dessous et observez l'écart entre les deux points s'ouvrir : le point au t brut fonce en avant tôt, tandis que le point à longueur d'arc garde un rythme régulier et ne rattrape que lorsque la courbe s'aplatit vers la fin :

raw tarc length (real)
50%

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

Personne n'écrit à la main l'interpolation derrière ce point au t brut, quadraticTo l'exécute déjà en interne, donc vous ne l'appelez jamais vous-même. L'erreur qu'il représente est une erreur que vous, vous écrivez : injecter une simple progression 0f..1f, venant d'un animateFloat, d'un geste de glissement, d'une SeekBar, directement dans quelque chose qui parcourt l'espace de paramètre propre à la courbe plutôt que la distance réelle. Un échantillonneur « points de passage espacés uniformément » écrit à la main, un calcul de phase de tirets, une rotation indexée directement sur progress, tous supposent que progress = 0.5 signifie déjà « la moitié des pixels ». Ce n'est pas le cas :

// 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 atterrit à (200, 35), qui se révèle être déjà à 69% du parcours réel de 262px de la courbe, pas 50%, parce que la courbe couvre la plupart de sa distance tôt (là où le point de contrôle tire le plus fort) et avance péniblement sur le reste.

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 signifie maintenant (150, 26), le véritable point à mi- chemin des 262px de la courbe, à chaque fois, peu importe où le point de contrôle tire. Un point piloté par getPosition se déplace à une vitesse visuelle constante d'un bout à l'autre, t n'entrant jamais en jeu.

Ce que getPosition et getTangent renvoient réellement

  • getPosition(distance): Offset est le point sur le chemin à cette distance depuis le début. Compose limite silencieusement distance à l'intervalle 0..length, donc une distance avant le début ou après la fin ne lève pas d'exception, elle se cale simplement sur l'extrémité la plus proche.
  • getTangent(distance): Offset est un vecteur de direction à ce même point, pas un angle. Il pointe dans la direction que prend le chemin à cet endroit précis, ce qui est exactement ce dont vous avez besoin pour faire pivoter quelque chose afin qu'il fasse face à sa direction de déplacement (une icône de voiture virant le long d'un circuit de course, un glyphe s'inclinant pour suivre un texte courbé).

Transformer ce vecteur de direction en une rotation Float pour graphicsLayer { rotationZ = ... } ne nécessite qu'un appel à atan2 :

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

Le fondamental

Ceci est la paramétrisation par longueur d'arc : réindexer une courbe pour que son entrée soit la distance réelle parcourue plutôt que le paramètre qui se trouvait définir les mathématiques (le t propre à une courbe, un angle, un indice de nœud). Des pas égaux dans la nouvelle entrée signifient toujours des pas égaux en pixels, propriété que le t brut n'a justement pas. PathMeasure construit cela en parcourant le chemin une fois, en accumulant la longueur au fur et à mesure, si bien que les requêtes de distance ultérieures sont des recherches dans ce parcours plutôt que de la géométrie fraîche.

Ailleurs : même fondamental, framework différent

  • SVG : SVGGeometryElement.getPointAtLength(length) et getTotalLength() sur n'importe quel <path> font exactement cela, par leur nom même. « Length » dans le nom de la méthode est la même distance en longueur d'arc que rapporte PathMeasure.length.
  • CSS motion path : offset-path combiné à offset-distance déplace un élément le long d'un chemin SVG par distance réelle, et le navigateur en règle le rythme pour vous, un PathMeasure entier intégré dans deux propriétés CSS sans aucun JS.
  • WPF : PathGeometry.GetPointAtFractionLength(progress, out point, out tangent) prend une fraction entre 0 et 1 au lieu d'une distance brute, mais c'est la même requête, point et tangente ensemble, basée sur la longueur d'arc sous le capot.
  • Flutter : Path.computeMetrics() renvoie une séquence d'objets PathMetric, chacun avec un .length et un .getTangentForOffset(distance) qui rend position et angle ensemble, les deux mêmes nombres que getPosition/getTangent séparent en appels distincts.
  • SwiftUI : Path.trimmedPath(from:to:) (et le modificateur Shape.trim(from:to:) construit par-dessus) découpe par longueur d'arc réelle, pas par le paramètre de courbe propre au chemin. Découper la même courbe de ce billet à to: 0.5 atterrit sur son véritable milieu en longueur d'arc, pas là où atterrirait un t = 0.5 brut, exactement la distinction au cœur de ce billet.

Cas particuliers

Le PathMeasure de Compose ne mesure que le seul qui lui est donné, et il n'y a pas de nextContour() pour passer au suivant, contrairement à l'ancien android.graphics.PathMeasure dont il s'inspire.

Appelez setPath sur un Path construit à partir de plusieurs morceaux disjoints (addPath de deux formes distinctes, par exemple) et length/getPosition ne tiennent compte que du premier contour trouvé, silencieusement. Si un chemin a plusieurs morceaux disjoints qui doivent tous être parcourus, mesurez chacun avec son propre PathMeasure construit à partir de son propre sous-Path, plutôt que de confier le chemin combiné à une seule instance en espérant qu'elle couvre tout.

forceClosed change ce que signifie « la fin » pour la mesure, pas ce qui est dessiné. Passer forceClosed = true à setPath ajoute un segment de fermeture synthétique retournant au début, même si le Path lui-même n'a jamais appelé close(), et ce segment compte dans length et dans chaque requête de position à partir de là. Le trait à l'écran ne change jamais pour autant, puisque forceClosed n'affecte que ce que calcule PathMeasure, pas ce que rend drawPath.

Le chemin ci-dessous n'est fait que de deux appels lineTo, donc l'écart entre son dernier point et son début n'est jamais réellement dessiné, basculer forceClosed ne le ferme pas. Ce qui se déplace, c'est le point final, getPosition(length) : au dernier point que le trait atteint réellement avec forceClosed désactivé, replié vers le début quand il est activé, et length lui-même fait un saut exactement égal à la distance de l'écart :

forceClosed
length: 0

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

Quand se tourner vers PathMeasure

  • Animations de tracé / révélation de trait : une signature rejouant ses propres traits, la ligne de trajet d'une carte de livraison se traçant derrière une épingle en mouvement, une coche de liste se dessinant elle-même.
  • Mouvement à vitesse constante le long d'un chemin courbé : le point bleu d'une appli de carte glissant en douceur le long de votre itinéraire au lieu de sauter de point de passage en point de passage, l'icône d'un tracker de livraison suivant la route, un avatar sautillant le long du chemin de sélection de niveau d'un jeu.
  • Texte ou icônes qui doivent suivre la direction d'une courbe, pas seulement sa position : un logotype arqué le long d'un badge circulaire, une légende s'incurvant le long du bord d'un collage photo, une étiquette se courbant autour d'une tranche de graphique.

getPosition/getTangent répondent à « où est le point maintenant, et dans quelle direction fait-il face ». getSegment répond à « donne-moi tout ce qui se trouve entre ces deux distances, sous forme de véritable Path dessinable », ce dont a besoin le tracé progressif : un chemin réel et plus court à tracer, pas un clip ou un masque :

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))

À progress = 0.3, trimmed ne contient que les premiers 30% de la longueur réelle du chemin, dans le style révélation de trait, peu importe comment est distribué le t de la courbe sous-jacente, ce qui est le même mécanisme derrière le découpage d'un anneau de progression à un pourcentage déterminé.

destination est muté sur place plutôt que renvoyé, et getSegment renvoie false (le laissant intact) pour un segment de longueur nulle ou lorsque startDistance n'est pas inférieur à stopDistance. Un quatrième paramètre, startWithMoveTo (true par défaut), contrôle si le segment écrit s'ouvre avec son propre moveTo ; mettez-le à false lors de l'ajout de plusieurs segments dans la même destination afin qu'ils se connectent en un seul sous-chemin plutôt que de démarrer un nouveau chaque fois.

Pour un mouvement à vitesse constante, c'est la même progression animateFloat de la démo plus tôt dans ce billet, pilotant maintenant getPosition plutôt qu'un échantillonneur fait main, ce qui est exactement ce qui procure le rythme régulier dont a besoin le point d'une appli de carte.

Pour du texte ou des icônes suivant la direction d'une courbe, faire pivoter chaque glyphe ou icône pour qu'il s'incline avec la courbe, c'est getTangent plus atan2, échantillonné une fois par position le long du chemin, les mêmes mathématiques dont a besoin un logotype courbé ou une étiquette de graphique pour rester tangente à son arc.

Modèle mental à utiliser concrètement

Un Path est une instruction de dessin ; un PathMeasure est ce même chemin réindexé par distance réelle. Tournez-vous vers lui chaque fois que « progress » doit signifier des pixels parcourus, et non l'endroit où atterrit le t propre à une courbe.

Keep reading

Related reads

Recevez les nouveaux articles par e-mail