Recomposed
Canvas

PathMeasure: Posição e Direção em Qualquer Distância ao Longo de um Path

Oct 17, 2026 · 8 min read

PathMeasure: Posição e Direção em Qualquer Distância ao Longo de um Path

A intuição

Um Path é construído a partir de chamadas moveTo/quadraticTo/cubicTo, então é tentador assumir que "50% do caminho ao longo do path" significa t = 0.5 em qualquer que seja a chamada de curva que o desenhou. Não é.

  • O t de uma curva é um peso de interpolação alimentado na matemática de interpolação dela, não uma medida em pixels. Onde um ponto de controle puxa mais forte, a curva percorre mais distância por passo de t; onde ele puxa menos, o mesmo passo de t percorre quase nada.
  • t = 0.5 cai onde quer que essa interpolação diga que cai. Nada no número 0.5 o vincula a "metade dos pixels" da curva.
  • O que você realmente quer, para um ponto em movimento, uma revelação de traço desenhando-se, ou um texto que segue uma curva, é distância: "me dê o ponto 150 pixels ao longo deste path," independentemente de como o t próprio da curva esteja distribuído.

O PathMeasure tem um trabalho inteiro em dois passos: percorrer um Path uma vez para encontrar seu comprimento real, depois permitir que você consulte posição e direção em qualquer distância dentro desse comprimento, sem o t nunca entrar em cena.

O problema: t é um peso de interpolação, não uma distância

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

O ponto de controle em (260, 20) fica bem afastado para o lado da corda entre início e fim, então ele puxa forte na primeira metade da curva e quase nada na segunda metade.

Arraste o controle deslizante abaixo e observe a diferença entre os dois pontos se abrir: o ponto do t bruto dispara na frente logo no começo, enquanto o ponto de comprimento de arco mantém um ritmo constante e só alcança o outro quando a curva se achata perto do final:

raw tarc length (real)
50%

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

Ninguém escreve manualmente a interpolação por trás desse ponto do t bruto, o próprio quadraticTo já a executa internamente, então você nunca a chama diretamente. O erro que ele representa é um que você escreve: alimentar um progresso simples de 0f..1f, vindo de animateFloat, um gesto de arrastar, uma SeekBar, direto em algo que percorre o espaço de parâmetro da própria curva em vez da distância real. Um amostrador manual de "waypoints igualmente espaçados," um cálculo de fase de traço, uma rotação baseada diretamente em progress, todos eles assumem que progress = 0.5 já significa "metade dos pixels." Não significa:

// a matemática por trás do ponto do t bruto acima, apenas como referência,
// não algo que você escreveria: t alimentado direto na interpolação do quadraticTo
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 cai em (200, 35), que na verdade já está em 69% do caminho ao longo do comprimento real de 262px da curva, não 50%, porque a curva percorre a maior parte da sua distância logo no início (onde o ponto de controle puxa mais forte) e se arrasta pelo resto.

val measure = PathMeasure()
measure.setPath(path, forceClosed = false)
 
val totalLength = measure.length // comprimento real em pixels da curva
val point = measure.getPosition(distance = totalLength * progress)
val direction = measure.getTangent(distance = totalLength * progress)

progress = 0.5 agora significa (150, 26), o ponto real do meio do caminho dos 262px da curva, sempre, independentemente de onde o ponto de controle puxa. Um ponto guiado por getPosition se move a uma velocidade visual constante de uma ponta à outra, sem o t nunca entrar em cena.

O que getPosition e getTangent realmente retornam

  • getPosition(distance): Offset é o ponto no path naquela distância a partir do início. O Compose discretamente limita distance dentro de 0..length, então uma distância antes do início ou depois do fim não lança uma exceção, apenas se ajusta para a extremidade mais próxima.
  • getTangent(distance): Offset é um vetor de direção naquele mesmo ponto, não um ângulo. Ele aponta para onde o path está indo exatamente ali, o que é exatamente o que você precisa para rotacionar algo de modo que ele fique de frente para onde está se movendo (um ícone de carro fazendo curvas ao longo de um path de pista de corrida, um glifo se inclinando para seguir um texto curvado).

Transformar esse vetor de direção em um Float de rotação para graphicsLayer { rotationZ = ... } está a uma chamada de atan2 de distância:

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

The fundamental

Isso é parametrização por comprimento de arco: reindexar uma curva para que sua entrada seja a distância real percorrida em vez de qualquer que seja o parâmetro que por acaso definiu a matemática (o t próprio de uma curva, um ângulo, um índice de nó). Passos iguais na nova entrada sempre significam passos iguais em pixels, que é exatamente a propriedade que o t bruto não tem. O PathMeasure constrói isso percorrendo o path uma vez, acumulando comprimento conforme avança, então consultas de distância posteriores são buscas contra esse percurso em vez de geometria recalculada do zero.

Em outros lugares: o mesmo fundamento, framework diferente

  • SVG: SVGGeometryElement.getPointAtLength(length) e getTotalLength() em qualquer <path> fazem exatamente isso, pelo próprio nome. "Length" no nome do método é a mesma distância de comprimento de arco que PathMeasure.length relata.
  • CSS motion path: offset-path junto com offset-distance move um elemento ao longo de um path SVG por distância real, e o navegador ritma isso para você, um PathMeasure inteiro embutido em duas propriedades CSS sem nenhum JS.
  • WPF: PathGeometry.GetPointAtFractionLength(progress, out point, out tangent) recebe uma fração de 0 a 1 em vez de uma distância bruta, mas é a mesma consulta, ponto e tangente juntos, baseada em comprimento de arco por baixo dos panos.
  • Flutter: Path.computeMetrics() retorna uma sequência de objetos PathMetric, cada um com um .length e um .getTangentForOffset(distance) que devolve posição e ângulo juntos, os mesmos dois números que getPosition/getTangent dividem em chamadas separadas.
  • SwiftUI: Path.trimmedPath(from:to:) (e o modificador Shape.trim(from:to:) construído sobre ele) recorta pelo comprimento de arco real, não pelo parâmetro de curva próprio do path. Recortar a mesma curva deste post em to: 0.5 cai no verdadeiro ponto médio de comprimento de arco, não onde quer que o t = 0.5 bruto cairia, a distinção exata sobre a qual este post inteiro trata.

Casos de borda

O PathMeasure do Compose só mede o único que recebe, e não há nextContour() para avançar para o próximo, diferente do android.graphics.PathMeasure mais antigo no qual ele é modelado.

Chame setPath em um Path construído a partir de vários pedaços desconectados (addPath de duas formas separadas, por exemplo) e length/getPosition levam em conta apenas o primeiro contorno encontrado, silenciosamente. Se um path tem vários pedaços disjuntos que todos precisam ser percorridos, meça cada um com seu próprio PathMeasure construído a partir do seu próprio sub-Path, em vez de passar o path combinado para uma única instância e esperar que ela cubra tudo.

forceClosed muda o que "o fim" significa para a medição, não o que é desenhado. Passar forceClosed = true para setPath adiciona um segmento de fechamento sintético de volta ao início, mesmo que o próprio Path nunca tenha chamado close(), e esse segmento conta para o length e toda consulta de posição a partir daí. O traço na tela nunca muda de nenhuma forma, já que forceClosed só afeta o que o PathMeasure calcula, não o que drawPath renderiza.

O path abaixo é apenas duas chamadas lineTo, então a lacuna entre seu último ponto e seu início nunca é realmente desenhada, alternar forceClosed não a fecha. O que se move é o ponto final, getPosition(length): no último ponto que o traço realmente alcança com forceClosed desligado, ajustado de volta para o início com ele ligado, e o próprio length salta exatamente pela distância da lacuna:

forceClosed
length: 0

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

Quando recorrer ao PathMeasure

  • Animações de desenho / revelação de traço: uma assinatura reproduzindo seus próprios traços, a linha de rota de um mapa de entrega se desenhando atrás de um pino em movimento, a marca de verificação de uma lista de tarefas se traçando.
  • Movimento a velocidade constante ao longo de um path curvado: o ponto azul de um app de mapas deslizando suavemente ao longo da sua rota em vez de saltar de waypoint a waypoint, o ícone de um rastreador de entrega seguindo a estrada, um avatar saltando ao longo do path de seleção de nível de um jogo.
  • Textos ou ícones que precisam seguir a direção de uma curva, não apenas sua posição: uma marca de palavra arqueada ao longo de um selo circular, uma legenda se curvando ao longo da borda de uma colagem de fotos, um rótulo se curvando em torno de uma fatia de gráfico.

getPosition/getTangent respondem "onde está o ponto agora, e para que lado ele está voltado." getSegment responde "me dê tudo entre essas duas distâncias, como um Path realmente desenhável," que é o que a revelação de traço precisa: um path real e mais curto para traçar, não um clip ou uma máscara:

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

Em progress = 0.3, trimmed contém apenas os primeiros 30% do comprimento real do path, no estilo revelação de traço, independentemente de como o t da curva subjacente está distribuído, que é o mesmo mecanismo por trás de recortar um anel de progresso para uma porcentagem determinada.

destination é alterado no local em vez de retornado, e getSegment retorna false (deixando-o intocado) para um segmento de comprimento zero ou quando startDistance não é menor que stopDistance. Um quarto parâmetro, startWithMoveTo (true por padrão), controla se o segmento escrito começa com seu próprio moveTo; defina-o como false ao anexar vários segmentos no mesmo destination para que eles se conectem em um único subpath em vez de iniciar um novo a cada vez.

Para movimento a velocidade constante, esse é o mesmo progresso de animateFloat da demonstração anterior neste post, agora guiando getPosition em vez de um amostrador manual, que é exatamente o que entrega o ritmo constante que o ponto de um app de mapas precisa.

Para textos ou ícones seguindo a direção de uma curva, rotacionar cada glifo ou ícone para que ele se incline com a curva é getTangent mais atan2, amostrado uma vez por posição ao longo do path, a mesma matemática que uma marca de palavra curvada ou um rótulo de gráfico precisa para permanecer tangente ao seu arco.

Modelo mental para realmente usar

Um Path é instruções de desenho; um PathMeasure é esse mesmo path reindexado por distância real. Recorra a ele sempre que "progresso" precisar significar pixels percorridos, não onde quer que o t próprio de uma curva aconteça de cair.

Keep reading

Related reads

Receba novos posts no seu e-mail