[Map] Add Clustering Algorithms

Author: smnandre

src/Map/CHANGELOG.md

@@ -3,11 +3,11 @@
 ## 2.29.0
 
 -  Add Symfony 8 support
+-  Add `Cluster` class and `ClusteringAlgorithmInterface` with two implementations `GridClusteringAlgorithm` and `MortonClusteringAlgorithm`
 
 ## 2.28
 
 -  Add `minZoom` and `maxZoom` options to `Map` to set the minimum and maximum zoom levels
--  The package is not experimental anymore
 
 ## 2.27
 

src/Map/doc/index.rst

@@ -727,7 +727,7 @@ property available in ``Map``, ``Marker``, ``InfoWindow``, ``Polygon``, ``Polyli
     ));
 
 On the JavaScript side, you can access these extra data by listening to ``ux:map:pre-connect``,
-``ux:map:connect``, ``ux:map:*:before-create``, ``ux:map:*:after-create`` events::
+``ux:map:connect``, ``ux:map:*:before-create``, ``ux:map:*:after-create`` events:
 
 .. code-block:: javascript
 
@@ -842,6 +842,45 @@ You can retrieve the map instance using the ``getMap()`` method, and change the
         </button>
     </div>
 
+Advanced: Clusters
+------------------
+
+.. versionadded:: 2.29
+
+    Clusters were added in UX Map 2.29.
+
+A cluster is a group of points that are close to each other on a map.
+
+Clustering reduces clutter and improves performance when displaying many points.
+This makes maps easier to read and faster to render.
+
+UX Map supports two algorithms:
+
+- **Grid**: Fast, divides map into cells.
+- **Morton**: Uses Z-order curves for spatial locality.
+
+Create a clustering algorithm, cluster your points, and add cluster markers::
+
+    use Symfony\UX\Map\Cluster\GridClusteringAlgorithm;
+    use Symfony\UX\Map\Cluster\MortonClusteringAlgorithm;
+    use Symfony\UX\Map\Point;
+
+    // Initialize clustering algorithm
+    $clusteringAlgorithm = new GridClusteringAlgorithm();
+    // or
+    // $clusteringAlgorithm = new MortonClusteringAlgorithm();
+
+    // Create clusters of points
+    $points = [new Point(48.8566, 2.3522), new Point(45.7640, 4.8357), /* ... */];
+    $clusters = $clusteringAlgorithm->cluster($points, zoom: 5.0);
+
+    // Iterate over each cluster
+    foreach ($clusters as $cluster) {
+        $cluster->getCenter(); // A Point, representing the cluster center
+        $cluster->getPoints(); // A list of Point
+        $cluster->count(); // The number of points in the cluster
+    }
+
 Backward Compatibility promise
 ------------------------------
 

src/Map/src/Cluster/Cluster.php

@@ -0,0 +1,81 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map\Cluster;
+
+use Symfony\UX\Map\Point;
+
+/**
+ * Cluster representation.
+ *
+ * @implements \IteratorAggregate<int, Point>
+ *
+ * @author Simon André <smn.andre@gmail.com>
+ */
+final class Cluster implements \Countable, \IteratorAggregate
+{
+    /**
+     * @var Point[]
+     */
+    private array $points = [];
+
+    private float $sumLat = 0.0;
+    private float $sumLng = 0.0;
+    private int $count = 0;
+
+    /**
+     * Initializes the cluster with an initial point.
+     */
+    public function __construct(Point $initialPoint)
+    {
+        $this->addPoint($initialPoint);
+    }
+
+    public function addPoint(Point $point): void
+    {
+        $this->points[] = $point;
+        $this->sumLat += $point->getLatitude();
+        $this->sumLng += $point->getLongitude();
+        ++$this->count;
+    }
+
+    /**
+     * Returns the center of the cluster as a Point.
+     */
+    public function getCenter(): Point
+    {
+        return new Point($this->sumLat / $this->count, $this->sumLng / $this->count);
+    }
+
+    /**
+     * @return non-empty-list<Point>
+     */
+    public function getPoints(): array
+    {
+        return $this->points;
+    }
+
+    /**
+     * Returns the number of points in the cluster.
+     */
+    public function count(): int
+    {
+        return $this->count;
+    }
+
+    /**
+     * @return \Traversable<int, Point>
+     */
+    public function getIterator(): \Traversable
+    {
+        return new \ArrayIterator($this->points);
+    }
+}

src/Map/src/Cluster/ClusteringAlgorithmInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map\Cluster;
+
+use Symfony\UX\Map\Point;
+
+/**
+ * Interface for various Clustering implementations.
+ */
+interface ClusteringAlgorithmInterface
+{
+    /**
+     * Clusters a set of points.
+     *
+     * @param Point[] $points List of points to be clustered
+     * @param float   $zoom   The zoom level, determining grid resolution
+     *
+     * @return Cluster[] An array of clusters, each containing grouped points
+     */
+    public function cluster(array $points, float $zoom): array;
+}

src/Map/src/Cluster/GridClusteringAlgorithm.php

@@ -0,0 +1,67 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map\Cluster;
+
+use Symfony\UX\Map\Point;
+
+/**
+ * Grid-based clustering algorithm for spatial data.
+ *
+ * This algorithm groups points into fixed-size grid cells based on the given zoom level.
+ *
+ * Best for:
+ * - Fast, scalable clustering on large geographical datasets
+ * - Real-time clustering where performance is critical
+ * - Use cases where a simple, predictable grid structure is sufficient
+ *
+ * Slower for:
+ * - Highly dynamic data that requires adaptive cluster sizes
+ * - Scenarios where varying density should influence cluster sizes (e.g., DBSCAN-like approaches)
+ * - Irregularly shaped clusters that do not fit a strict grid pattern
+ *
+ * @author Simon André <smn.andre@gmail.com>
+ */
+final class GridClusteringAlgorithm implements ClusteringAlgorithmInterface
+{
+    /**
+     * Clusters a set of points using a fixed grid resolution based on the zoom level.
+     *
+     * @param Point[] $points List of points to be clustered
+     * @param float   $zoom   The zoom level, determining grid resolution
+     *
+     * @return Cluster[] An array of clusters, each containing grouped points
+     */
+    public function cluster(iterable $points, float $zoom): array
+    {
+        $gridResolution = 1 << (int) $zoom;
+        $gridSize = 360 / $gridResolution;
+        $invGridSize = 1 / $gridSize;
+
+        $cells = [];
+
+        foreach ($points as $point) {
+            $lng = $point->getLongitude();
+            $lat = $point->getLatitude();
+            $gridX = (int) (($lng + 180) * $invGridSize);
+            $gridY = (int) (($lat + 90) * $invGridSize);
+            $key = ($gridX << 16) | $gridY;
+
+            if (!isset($cells[$key])) {
+                $cells[$key] = new Cluster($point);
+            } else {
+                $cells[$key]->addPoint($point);
+            }
+        }
+
+        return array_values($cells);
+    }
+}

src/Map/src/Cluster/MortonClusteringAlgorithm.php

@@ -0,0 +1,76 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map\Cluster;
+
+use Symfony\UX\Map\Point;
+
+/**
+ * Clustering algorithm based on Morton codes (Z-order curves).
+ *
+ * This approach is optimized for spatial data and preserves locality efficiently.
+ *
+ * Best for:
+ * - Large-scale spatial clustering
+ * - Hierarchical clustering with fast locality-based grouping
+ * - Datasets where preserving spatial proximity is crucial
+ *
+ * Slower for:
+ * - High-dimensional data (beyond 2D/3D) due to Morton code limitations
+ * - Non-spatial or categorical data
+ * - Scenarios requiring dynamic cluster adjustments (e.g., streaming data)
+ *
+ * @author Simon André <smn.andre@gmail.com>
+ */
+final class MortonClusteringAlgorithm implements ClusteringAlgorithmInterface
+{
+    /**
+     * @param Point[] $points
+     *
+     * @return Cluster[]
+     */
+    public function cluster(iterable $points, float $zoom): array
+    {
+        $resolution = 1 << (int) $zoom;
+        $clustersMap = [];
+
+        foreach ($points as $point) {
+            $xNorm = ($point->getLatitude() + 180) / 360;
+            $yNorm = ($point->getLongitude() + 90) / 180;
+
+            $x = (int) floor($xNorm * $resolution);
+            $y = (int) floor($yNorm * $resolution);
+
+            $x &= 0xFFFF;
+            $y &= 0xFFFF;
+
+            $x = ($x | ($x << 8)) & 0x00FF00FF;
+            $x = ($x | ($x << 4)) & 0x0F0F0F0F;
+            $x = ($x | ($x << 2)) & 0x33333333;
+            $x = ($x | ($x << 1)) & 0x55555555;
+
+            $y = ($y | ($y << 8)) & 0x00FF00FF;
+            $y = ($y | ($y << 4)) & 0x0F0F0F0F;
+            $y = ($y | ($y << 2)) & 0x33333333;
+            $y = ($y | ($y << 1)) & 0x55555555;
+
+            $code = ($y << 1) | $x;
+
+            if (!isset($clustersMap[$code])) {
+                $clustersMap[$code] = new Cluster($point);
+            } else {
+                $clustersMap[$code]->addPoint($point);
+            }
+        }
+
+        return array_values($clustersMap);
+    }
+}