Recomposed
Canvas

PathMeasure: パス上の任意の距離における位置と方向

Oct 17, 2026 · 9 min read

PathMeasure: パス上の任意の距離における位置と方向

直感的な理解

PathはmoveTo/quadraticTo/cubicToの呼び出しから組み立てられるため、「パスの50%地点」とはそれを描いたカーブ呼び出しのt = 0.5のことだと思い込みたくなります。しかし、それは違います。

  • カーブのtは補間計算に与えられるブレンド重みであり、ピクセルの測定値ではありません。制御点が最も強く引く場所では、tの1ステップあたりカーブはより多くの距離を進みます。制御点が最も弱く引く場所では、同じtの1ステップでもほとんど距離が進みません。
  • t = 0.5は、その補間が示す場所に着地するだけです。0.5という数字自体が「カーブのピクセル数の半分」を意味する理由はどこにもありません。
  • 動く点、ドローオンによるストロークの表示、カーブに沿うテキストにとって実際に必要なのは距離です。つまり「このパスに沿って150ピクセル進んだ地点の点をくれ」という話であり、カーブ自身のtがどのように分布しているかとは無関係です。

PathMeasureの仕事は本質的に2段階です。まずPathを一度歩いて実際の長さを求め、その後その長さの中の任意の距離における位置と方向を問い合わせられるようにします。tはまったく関係してきません。

問題: tはブレンド重みであり、距離ではない

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

(260, 20)にある制御点は、始点と終点を結ぶ弦から大きく外れた場所にあります。そのため、カーブの前半には強く引き寄せられますが、後半にはほとんど影響しません。

下のスライダーをドラッグして、2つの点の間に生まれるギャップを観察してください。生のtに基づく点は序盤で先に進みすぎてしまい、弧長に基づく点は一定のペースを保ち、カーブが終盤で平坦になってようやく追いつきます。

raw tarc length (real)
50%

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

上記の生のtによる点の背後にある補間を誰も自分で書くことはありません。quadraticToが内部でそれを実行してくれるので、自分で呼び出すことは決してないのです。しかしそれが象徴する間違いは、あなたが実際に書くコードにも現れます。animateFloatやドラッグジェスチャー、SeekBarから得られる単純な0f..1fの進行値を、距離ではなくカーブ自身のパラメータ空間を歩くものにそのまま渡してしまうことです。自作の「等間隔なウェイポイント」サンプラーや、破線のフェーズ計算、progressを直接使った回転、これらはすべてprogress = 0.5が「ピクセルの半分」を意味すると思い込んでいます。実際はそうではありません。

// 参考までに、上の生のtによる点の裏にある計算。自分で書くものではなく
// tをそのまま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は(200, 35)に着地しますが、これはカーブの実際の262pxの長さのうち、50%ではなく、実は69%の地点です。制御点が最も強く引く序盤でカーブがほとんどの距離を進み、残りはじわじわと進むためです。

val measure = PathMeasure()
measure.setPath(path, forceClosed = false)
 
val totalLength = measure.length // カーブの実際のピクセル長
val point = measure.getPosition(distance = totalLength * progress)
val direction = measure.getTangent(distance = totalLength * progress)

これでprogress = 0.5は常に(150, 26)を意味するようになります。これはカーブの262pxの実際の中間地点であり、制御点がどこで強く引いていようと関係ありません。getPositionによって駆動される点は、一端からもう一端まで一定の視覚的な速度で移動します。tはまったく関係してきません。

getPositionとgetTangentが実際に返すもの

  • getPosition(distance): Offsetは、始点からその距離にあるパス上の点です。Composeはdistanceを静かに0..lengthの範囲にクランプするため、始点より前や終点より後の距離を渡してもエラーにはならず、単に近い方の端にスナップします。
  • getTangent(distance): Offsetは、同じ点における方向ベクトルであり、角度ではありません。パスがその場所でどちらに向かっているかを示すもので、物体を進行方向に向けて回転させたいとき(レーストラックのパスをコーナリングする車のアイコン、曲線テキストに沿って傾くグリフ)にまさに必要なものです。

この方向ベクトルをgraphicsLayer { rotationZ = ... }向けの回転Floatに変換するには、atan2を1回呼ぶだけです。

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

The fundamental

これは**弧長パラメータ化(arc-length parameterization)**です。カーブの入力を、カーブの計算を定義していた何らかのパラメータ(カーブ自身のt、角度、ノットのインデックスなど)から、実際に移動した距離へと再インデックス化することを指します。新しい入力における等しいステップは常にピクセル上の等しいステップを意味します。これは生のtには存在しない性質です。PathMeasureはパスを一度歩いて長さを積算していくことでこれを構築するため、以後の距離の問い合わせは新たな幾何計算ではなく、その歩行結果に対するルックアップになります。

他のフレームワークでも: 同じ基本原理、異なる実装

  • SVG: 任意の<path>に対するSVGGeometryElement.getPointAtLength(length)とgetTotalLength()は、まさにこれを名前の通り行います。メソッド名の「Length」は、PathMeasure.lengthが報告するのと同じ弧長距離です。
  • CSS motion path: offset-pathとoffset-distanceを組み合わせると、要素を実際の距離でSVGパスに沿って移動させることができ、ブラウザがそのペース調整をしてくれます。JSを一切使わずに、PathMeasure一式が2つのCSSプロパティに組み込まれているようなものです。
  • WPF: PathGeometry.GetPointAtFractionLength(progress, out point, out tangent)は生の距離ではなく0から1の割合を受け取りますが、同じ問い合わせであり、位置と接線をまとめて返す点も、内部が弧長ベースである点も同じです。
  • Flutter: Path.computeMetrics()はPathMetricオブジェクトのシーケンスを返し、各オブジェクトには.lengthと、位置と角度をまとめて返す.getTangentForOffset(distance)があります。これはgetPosition/getTangentが別々の呼び出しに分けている同じ2つの値です。
  • SwiftUI: Path.trimmedPath(from:to:)(およびそれを基にしたShape.trim(from:to:)モディファイア)は、パス自身のカーブパラメータではなく、実際の弧長でトリミングします。この記事と同じカーブをto: 0.5でトリミングすると、生のt = 0.5が着地する場所ではなく、実際の弧長の中間点に着地します。これこそがこの記事全体で扱っている区別そのものです。

エッジケース

ComposeのPathMeasureは与えられた単一の しか測定せず、次のコンターに移動するためのnextContour()は存在しません。これは、モデルとなった古い android.graphics.PathMeasure とは異なる点です。

複数の分離したピースから構築されたPath(たとえば2つの別々の図形をaddPathした場合など)にsetPathを呼ぶと、length/getPositionは見つかった最初のコンターのみを、何も警告せずに対象とします。複数の独立したピースをすべて歩く必要がある場合は、結合したパスを1つのインスタンスに渡してすべてをカバーしてくれると期待するのではなく、それぞれを自分自身のサブPathから構築した自分自身のPathMeasureで測定してください。

forceClosedが変えるのは測定における「終点」の意味であり、描画されるものではありません。 setPathにforceClosed = trueを渡すと、Path自身がclose()を呼んでいなくても、始点に戻る合成的なクロージングセグメントが追加されます。そしてこのセグメントは、それ以降のlengthやすべての位置の問い合わせに反映されます。一方、画面上のストロークはどちらの場合でも変わりません。forceClosedが影響するのはPathMeasureが計算するものだけであり、drawPathが描画するものには影響しないからです。

下のパスは2回のlineTo呼び出しだけで構成されているため、最後の点と始点の間のギャップは実際には描画されず、forceClosedを切り替えてもそこは閉じません。変化するのは終点の点、つまりgetPosition(length)です。forceClosedがオフのときはストロークが実際に到達する最後の点に、オンのときは始点にスナップされ、length自体もギャップの距離分だけぴったりジャンプします。

forceClosed
length: 0

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

PathMeasureを使うべき場面

  • ドローオン/ストローク表示アニメーション: 署名が自分のストロークを再生する、配達マップのルート線が動くピンの後ろに描かれていく、チェックリストのチェックマークが自分自身をトレースする、など。
  • カーブに沿った一定速度の移動: マップアプリの青い点がウェイポイントごとに飛ぶのではなくルートに沿って滑らかに移動する、配達トラッカーのアイコンが道路をたどる、アバターがゲームのレベル選択パスに沿って跳ねる、など。
  • カーブの位置だけでなく方向にも追従する必要があるテキストやアイコン: 円形バッジに沿って弧を描くワードマーク、フォトコラージュの端に沿って曲がるキャプション、チャートのスライスの周りで曲がるラベル、など。

getPosition/getTangentは「今、点はどこにあり、どちらを向いているか」に答えます。getSegmentは「これらの2つの距離の間のすべてを、実際に描画可能なPathとしてくれ」に答えます。これはドローオンが必要とするものです。クリップやマスクではなく、実際に短くなったパスが必要なのです。

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はパスの実際の長さの最初の30%だけを保持します。これはドローオン表示のスタイルであり、背後のカーブのtがどのように分布していようと関係ありません。これは、進行度リングを確定的なパーセンテージにトリミングするのと同じ仕組みです。

destinationは返されるのではなく、その場所で変更されます。そしてgetSegmentは、ゼロ長のセグメントの場合やstartDistanceがstopDistance未満でない場合にはfalseを返し(destinationはそのまま変更されません)。4番目のパラメータであるstartWithMoveTo(デフォルトはtrue)は、書き込まれるセグメントが自分自身のmoveToで始まるかどうかを制御します。複数のセグメントを同じdestinationに追加していく場合は、毎回新しいサブパスを始めるのではなく1つのサブパスとして連結させるために、これをfalseに設定してください。

一定速度の移動については、この記事の前半のデモで使われていたのと同じanimateFloatの進行値が、自作のサンプラーではなくgetPositionを駆動するようになります。これこそ、マップアプリの点が必要とする均一なペースをもたらすものです。

カーブの方向に追従するテキストやアイコンについては、各グリフやアイコンをカーブに合わせて傾けるように回転させることは、getTangentとatan2を組み合わせ、パスに沿った各位置で1回ずつサンプリングすることに相当します。これは、曲線のワードマークやチャートのラベルがその弧に対して接線を保つために必要な計算と同じものです。

実際に使うべきメンタルモデル

Pathは描画命令であり、PathMeasureは同じパスを実際の距離で再インデックス化したものです。 「進行度」がカーブ自身のtがどこに着地するかではなく、移動したピクセル数を意味する必要がある場面では、いつでもこれに頼ってください。

Keep reading

Related reads

新しい記事をメールで受け取る