feat(library): add flexible polyline encoding and decoding

Adds FlexiblePolylineUtil to the library module, alongside the existing
PolyUtil codec. The format supports configurable precision, a header that
carries the precision with the data, and an optional third value per point.

Also adds a demo activity exercising the decoder, registered under the
Geometry category.

Author: kikoso

demo/src/main/AndroidManifest.xml

@@ -65,6 +65,9 @@
         <activity
             android:name=".PolyDecodeDemoActivity"
             android:exported="true" />
+        <activity
+            android:name=".FlexiblePolylineDemoActivity"
+            android:exported="true" />
         <activity
             android:name=".PolySimplifyDemoActivity"
             android:exported="true" />

demo/src/main/java/com/google/maps/android/utils/demo/FlexiblePolylineDemoActivity.kt

@@ -0,0 +1,111 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.maps.android.utils.demo
+
+import android.widget.Toast
+import com.google.android.gms.maps.CameraUpdateFactory
+import com.google.android.gms.maps.model.BitmapDescriptorFactory
+import com.google.android.gms.maps.model.LatLng
+import com.google.android.gms.maps.model.MarkerOptions
+import com.google.android.gms.maps.model.PolylineOptions
+import com.google.maps.android.FlexiblePolylineUtil
+
+/**
+ * Demonstrates [FlexiblePolylineUtil] by decoding a HERE Flexible Polyline and drawing it.
+ *
+ * The sample string encodes the Sydney Harbour Bridge walkway with an altitude for every
+ * point, at seven decimal places of coordinate precision. The demo makes two points:
+ *
+ * - the geometry draws exactly like any other path, because once decoded it is just a list of
+ *   [LatLng] values;
+ * - the altitude cannot be drawn. A [com.google.android.gms.maps.model.Polyline] has no height,
+ *   so the third dimension is surfaced here as marker text instead, which is the honest
+ *   treatment for data the renderer cannot express.
+ */
+class FlexiblePolylineDemoActivity : BaseDemoActivity() {
+    override fun startDemo(isRestore: Boolean) {
+        val map = map ?: return
+        val polyline = FlexiblePolylineUtil.decode(ENCODED_WALKWAY)
+        val path = polyline.toLatLngs()
+
+        map.addPolyline(
+            PolylineOptions()
+                .addAll(path)
+                .width(POLYLINE_WIDTH)
+                .color(POLYLINE_COLOR),
+        )
+
+        // The third dimension is metadata, not geometry: label the end points with it so the
+        // altitude profile is visible without pretending the map can render height.
+        val withAltitude = polyline.points.filter { it.thirdDimensionValue != null }
+        val labelled =
+            listOfNotNull(
+                withAltitude.firstOrNull()?.let { R.string.flexible_polyline_start to it },
+                withAltitude.maxByOrNull { point -> point.thirdDimensionValue!! }
+                    ?.let { R.string.flexible_polyline_highest to it },
+                withAltitude.lastOrNull()?.let { R.string.flexible_polyline_end to it },
+            )
+        for ((titleResId, point) in labelled) {
+            map.addMarker(
+                MarkerOptions()
+                    .position(point.toLatLng())
+                    .title(getString(titleResId))
+                    .snippet(
+                        getString(
+                            R.string.flexible_polyline_altitude,
+                            point.thirdDimensionValue!!,
+                        ),
+                    )
+                    .icon(
+                        BitmapDescriptorFactory.defaultMarker(
+                            BitmapDescriptorFactory.HUE_AZURE,
+                        ),
+                    ),
+            )
+        }
+
+        Toast.makeText(
+            this,
+            getString(
+                R.string.flexible_polyline_summary,
+                polyline.points.size,
+                polyline.precision,
+                polyline.thirdDimension.name.lowercase(),
+            ),
+            Toast.LENGTH_LONG,
+        ).show()
+
+        if (!isRestore) {
+            map.moveCamera(CameraUpdateFactory.newLatLngZoom(CAMERA_TARGET, CAMERA_ZOOM))
+        }
+    }
+
+    private companion object {
+        /**
+         * The Sydney Harbour Bridge walkway, encoded at precision 7 with an altitude in metres
+         * at one decimal place. Note that the string needs no escaping to sit in source, a URL
+         * or a JSON field, unlike the Google format sample in [PolyDecodeDemoActivity].
+         */
+        const val ENCODED_WALKWAY =
+            "BnF__k0lU4kokk6CgFnzQnqDyGnzQvwD6HnzQvwDmHnzQvwDiEnzQvwDyBnzQvwDnBnzQvwDpFnzQvwDtIn" +
+                "zQvwDtI"
+
+        val CAMERA_TARGET = LatLng(-33.85343, 151.21083)
+        const val CAMERA_ZOOM = 15f
+        const val POLYLINE_WIDTH = 12f
+        const val POLYLINE_COLOR = 0xFF1A73E8.toInt()
+    }
+}

demo/src/main/java/com/google/maps/android/utils/demo/MainActivity.kt

@@ -121,6 +121,7 @@ class MainActivity : ComponentActivity() {
                 R.string.category_geometry,
                 listOf(
                     Demo(R.string.demo_title_poly_decode, PolyDecodeDemoActivity::class.java),
+                    Demo(R.string.demo_title_flexible_polyline, FlexiblePolylineDemoActivity::class.java),
                     Demo(R.string.demo_title_poly_simplify, PolySimplifyDemoActivity::class.java),
                     Demo(R.string.demo_title_polyline_progress, PolylineProgressDemoActivity::class.java),
                     Demo(R.string.demo_title_spherical_distance, DistanceDemoActivity::class.java),

demo/src/main/res/values/strings.xml

@@ -69,6 +69,7 @@
     <string name="demo_title_poly_decode">PolyUtil.decode</string>
     <string name="demo_title_poly_simplify">PolyUtil.simplify</string>
     <string name="demo_title_polyline_progress">Polyline Progress</string>
+    <string name="demo_title_flexible_polyline">FlexiblePolylineUtil.decode</string>
     <string name="demo_title_spherical_distance">SphericalUtil.computeDistanceBetween</string>
 
     <!-- Demo Titles: Utilities -->
@@ -143,4 +144,11 @@ Demonstrates how to dynamically control the visual layering (stacking order) of
 <b>Tie Resolution:</b><br/>
 • When two shapes of the same type share identical z-index values, the Google Maps SDK resolves their stacking order based on <b>insertion (creation) order</b>.
 ]]></string>
+
+    <!-- Flexible Polyline demo -->
+    <string name="flexible_polyline_summary">Points: %1$d · precision: %2$d · third dimension: %3$s</string>
+    <string name="flexible_polyline_altitude">Altitude %1$.1f m (not rendered as height)</string>
+    <string name="flexible_polyline_start">Start</string>
+    <string name="flexible_polyline_highest">Highest point</string>
+    <string name="flexible_polyline_end">End</string>
 </resources>