[Map] Add Clustering Algorithms

src/Map/CHANGELOG.md

@@ -1,4 +1,17 @@
 # CHANGELOG
+
+## 2.24
+
+-  Add `Cluster` class, interface for clustering algorithm and two implementations:
+   `GridClusteringAlgorithm` and `MortonClusteringAlgorithm`.
+
+## 2.23
+
+-  Add `DistanceUnit` to represent distance units (`m`, `km`, `miles`, `nmi`) and
+   ease conversion between units.
+-  Add `DistanceCalculatorInterface` interface and three implementations:
+   `HaversineDistanceCalculator`, `SphericalCosineDistanceCalculator` and `VincentyDistanceCalculator`.
+-  Add `CoordinateUtils` helper, to convert decimal coordinates (`43.2109`) in DMS (`56° 78' 90"`)
 
 ## 2.22
 

src/Map/src/Cluster/Cluster.php

@@ -0,0 +1,62 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * 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.
+ *
+ * @author Simon André <[email protected]>
+ */
+final class Cluster
+{
+    /**
+     * @var Point[]
+     */
+    private array $points = [];
+
+    private float $sumLat = 0.0;
+    private float $sumLng = 0.0;
+    private int $count = 0;
+
+    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;
+    }
+
+    public function getCenterLat(): float
+    {
+        return $this->count > 0 ? $this->sumLat / $this->count : 0.0;
+    }
+
+    public function getCenterLng(): float
+    {
+        return $this->count > 0 ? $this->sumLng / $this->count : 0.0;
+    }
+
+    /**
+     * @return Point[]
+     */
+    public function getPoints(): array
+    {
+        return $this->points;
+    }
+}

src/Map/src/Cluster/ClusteringAlgorithmInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * 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 <[email protected]>
+ *
+ * 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é <[email protected]>
+ */
+final readonly 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 <[email protected]>
+ *
+ * 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é <[email protected]>
+ */
+final readonly 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);
+    }
+}

src/Map/src/Point.php

@@ -33,6 +33,16 @@ public function __construct(
         }
     }
 
+    public function getLatitude(): float
+    {
+        return $this->latitude;
+    }
+
+    public function getLongitude(): float
+    {
+        return $this->longitude;
+    }
+
     /**
      * @return array{lat: float, lng: float}
      */

src/Map/tests/Cluster/ClusterTest.php

@@ -0,0 +1,57 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map\Tests\Cluster;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\UX\Map\Cluster\Cluster;
+use Symfony\UX\Map\Point;
+
+class ClusterTest extends TestCase
+{
+    public function testAddPointAndGetCenter(): void
+    {
+        $point1 = new Point(10.0, 20.0);
+        $cluster = new Cluster($point1);
+
+        $this->assertEquals(10.0, $cluster->getCenterLat());
+        $this->assertEquals(20.0, $cluster->getCenterLng());
+
+        $point2 = new Point(12.0, 22.0);
+        $cluster->addPoint($point2);
+
+        $this->assertEquals(11.0, $cluster->getCenterLat());
+        $this->assertEquals(21.0, $cluster->getCenterLng());
+    }
+
+    public function testGetPoints(): void
+    {
+        $point1 = new Point(10.0, 20.0);
+        $point2 = new Point(12.0, 22.0);
+        $cluster = new Cluster($point1);
+        $cluster->addPoint($point2);
+
+        $points = $cluster->getPoints();
+        $this->assertCount(2, $points);
+        $this->assertSame($point1, $points[0]);
+        $this->assertSame($point2, $points[1]);
+    }
+
+    public function testEmptyCluster(): void
+    {
+        $point1 = new Point(10.0, 20.0);
+        $cluster = new Cluster($point1); // Start an empty cluster
+        $points = $cluster->getPoints();
+        $this->assertCount(1, $points);
+        $this->assertEquals(10.0, $cluster->getCenterLat());
+        $this->assertEquals(20.0, $cluster->getCenterLng());
+    }
+}