goodmap 1.1.3__py3-none-any.whl → 1.1.6__py3-none-any.whl

goodmap/clustering.py

@@ -0,0 +1,75 @@
+import logging
+import uuid
+
+from scipy.spatial import KDTree
+
+# Maximum distance to consider a point-cluster match (accounts for floating point errors)
+DISTANCE_THRESHOLD = 1e-8
+
+logger = logging.getLogger(__name__)
+
+
+def map_clustering_data_to_proper_lazy_loading_object(input_array):
+    response_array = []
+    for item in input_array:
+        if item["count"] == 1:
+            response_object = {
+                "position": [item["longitude"], item["latitude"]],
+                "uuid": item["uuid"],
+                "cluster_uuid": None,
+                "cluster_count": None,
+                "type": "point",
+            }
+            response_array.append(response_object)
+            continue
+        response_object = {
+            "position": [item["longitude"], item["latitude"]],
+            "uuid": None,
+            "cluster_uuid": str(uuid.uuid4()),
+            "cluster_count": item["count"],
+            "type": "cluster",
+        }
+        response_array.append(response_object)
+    return response_array
+
+
+# Since there can be some floating point errors
+# we need to check if the distance is close enough to 0
+def match_clusters_uuids(points, clusters):
+    """
+    Match single-point clusters to their original point UUIDs.
+
+    For clusters containing exactly one point, this function attempts to match the cluster
+    coordinates back to the original point to retrieve its UUID. The 'uuid' key is optional
+    and will only be present in single-point clusters where a matching point is found.
+
+    Args:
+        points: List of point dicts with 'position' and 'uuid' keys
+        clusters: List of cluster dicts with 'longitude', 'latitude', and 'count' keys.
+                 For single-point clusters (count=1), a 'uuid' key will be added if a
+                 matching point is found (modified in place)
+
+    Returns:
+        The modified clusters list with 'uuid' keys added to matched single-point clusters
+    """
+    points_coords = [(point["position"][0], point["position"][1]) for point in points]
+    tree = KDTree(points_coords)
+    for cluster in clusters:
+        if cluster["count"] == 1:
+            cluster_coords = (cluster["longitude"], cluster["latitude"])
+            dist, idx = tree.query(cluster_coords)
+            if dist < DISTANCE_THRESHOLD:
+                closest_point = points[idx]
+                cluster["uuid"] = closest_point["uuid"]
+            else:
+                # Log warning when no match is found - indicates data inconsistency
+                logger.warning(
+                    "No matching UUID found for cluster at coordinates (%f, %f). "
+                    "Distance to nearest point: %f (threshold: %f)",
+                    cluster["longitude"],
+                    cluster["latitude"],
+                    dist,
+                    DISTANCE_THRESHOLD,
+                )
+                cluster["uuid"] = None
+    return clusters

goodmap/core_api.py

@@ -1,13 +1,28 @@
 import importlib.metadata
+import logging
 import uuid
 
+import numpy
+import pysupercluster
 from flask import Blueprint, jsonify, make_response, request
 from flask_babel import gettext
 from flask_restx import Api, Resource, fields
 from platzky.config import LanguagesMapping
 
+from goodmap.clustering import (
+    map_clustering_data_to_proper_lazy_loading_object,
+    match_clusters_uuids,
+)
 from goodmap.formatter import prepare_pin
 
+# SuperCluster configuration constants
+MIN_ZOOM = 0
+MAX_ZOOM = 16
+CLUSTER_RADIUS = 200
+CLUSTER_EXTENT = 512
+
+logger = logging.getLogger(__name__)
+
 
 def make_tuple_translation(keys_to_translate):
     return [(x, gettext(x)) for x in keys_to_translate]
@@ -22,6 +37,27 @@ def get_or_none(data, *keys):
     return data
 
 
+def get_locations_from_request(database, request_args, as_basic_info=False):
+    """
+    Shared helper to fetch locations from database based on request arguments.
+
+    Args:
+        database: Database instance
+        request_args: Request arguments (flask.request.args)
+        as_basic_info: If True, returns list of basic_info dicts, otherwise returns Location objects
+
+    Returns:
+        List of locations (either as objects or basic_info dicts)
+    """
+    query_params = request_args.to_dict(flat=False)
+    all_locations = database.get_locations(query_params)
+
+    if as_basic_info:
+        return [x.basic_info() for x in all_locations]
+
+    return all_locations
+
+
 def core_pages(
     database,
     languages: LanguagesMapping,
@@ -106,9 +142,58 @@ def core_pages(
             """
             Shows list of locations with uuid and position
             """
-            query_params = request.args.to_dict(flat=False)
-            all_locations = database.get_locations(query_params)
-            return jsonify([x.basic_info() for x in all_locations])
+            locations = get_locations_from_request(database, request.args, as_basic_info=True)
+            return jsonify(locations)
+
+    @core_api.route("/locations-clustered")
+    class GetLocationsClustered(Resource):
+        def get(self):
+            """
+            Shows list of locations with uuid, position and clusters
+            """
+            try:
+                query_params = request.args.to_dict(flat=False)
+                zoom = int(query_params.get("zoom", [7])[0])
+
+                # Validate zoom level (aligned with SuperCluster min_zoom/max_zoom)
+                if not MIN_ZOOM <= zoom <= MAX_ZOOM:
+                    return make_response(
+                        jsonify({"message": f"Zoom must be between {MIN_ZOOM} and {MAX_ZOOM}"}),
+                        400,
+                    )
+
+                points = get_locations_from_request(database, request.args, as_basic_info=True)
+                if not points:
+                    return jsonify([])
+
+                points_numpy = numpy.array(
+                    [(point["position"][0], point["position"][1]) for point in points]
+                )
+
+                index = pysupercluster.SuperCluster(
+                    points_numpy,
+                    min_zoom=MIN_ZOOM,
+                    max_zoom=MAX_ZOOM,
+                    radius=CLUSTER_RADIUS,
+                    extent=CLUSTER_EXTENT,
+                )
+
+                clusters = index.getClusters(
+                    top_left=(-180.0, 90.0),
+                    bottom_right=(180.0, -90.0),
+                    zoom=zoom,
+                )
+                clusters = match_clusters_uuids(points, clusters)
+
+                return jsonify(map_clustering_data_to_proper_lazy_loading_object(clusters))
+            except ValueError as e:
+                logger.warning("Invalid parameter in clustering request: %s", e)
+                return make_response(jsonify({"message": "Invalid parameters provided"}), 400)
+            except Exception as e:
+                logger.error("Clustering operation failed: %s", e, exc_info=True)
+                return make_response(
+                    jsonify({"message": "An error occurred during clustering"}), 500
+                )
 
     @core_api.route("/location/<location_id>")
     class GetLocation(Resource):

goodmap/data_models/location.py

@@ -6,7 +6,6 @@ from pydantic import BaseModel, Field, create_model, field_validator
 class LocationBase(BaseModel, extra="allow"):
     position: tuple[float, float]
     uuid: str
-    remark: str = ""
 
     @field_validator("position")
     @classmethod
@@ -18,7 +17,11 @@ class LocationBase(BaseModel, extra="allow"):
         return v
 
     def basic_info(self):
-        return {"uuid": self.uuid, "position": self.position, "remark": bool(self.remark)}
+        return {
+            "uuid": self.uuid,
+            "position": self.position,
+            "remark": bool(getattr(self, "remark", False)),
+        }
 
 
 def create_location_model(obligatory_fields: list[tuple[str, Type[Any]]]) -> Type[BaseModel]:

goodmap/templates/map.html

@@ -116,6 +116,7 @@ window.PRIMARY_COLOR = "{{ primary_color }}";
 window.SHOW_SUGGEST_NEW_POINT_BUTTON = {{ feature_flags.SHOW_SUGGEST_NEW_POINT_BUTTON | default(false) | tojson }};
 window.SHOW_SEARCH_BAR = {{ feature_flags.SHOW_SEARCH_BAR | default(false) | tojson }};
 window.USE_LAZY_LOADING = {{ feature_flags.USE_LAZY_LOADING | default(false) | tojson }};
+window.USE_SERVER_SIDE_CLUSTERING = {{ feature_flags.USE_SERVER_SIDE_CLUSTERING | default(false) | tojson }};
 window.SHOW_ACCESSIBILITY_TABLE = {{ feature_flags.SHOW_ACCESSIBILITY_TABLE | default(false) | tojson }};
 window.FEATURE_FLAGS = {{ feature_flags | tojson }};
 </script>

{goodmap-1.1.3.dist-info → goodmap-1.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: goodmap
-Version: 1.1.3
+Version: 1.1.6
 Summary: Map engine to serve all the people :)
 License-File: LICENSE.md
 Author: Krzysztof Kolodzinski
@@ -26,8 +26,11 @@ Requires-Dist: gql (>=3.4.0,<4.0.0)
 Requires-Dist: gunicorn (>=20.1.0,<21.0.0)
 Requires-Dist: humanize (>=4.6.0,<5.0.0)
 Requires-Dist: myst-parser (>=4.0.0,<5.0.0) ; extra == "docs"
+Requires-Dist: numpy (>=2.2.0,<3.0.0)
 Requires-Dist: platzky (>=1.0.0,<2.0.0)
 Requires-Dist: pydantic (>=2.7.1,<3.0.0)
+Requires-Dist: pysupercluster-problematy (>=0.7.8,<0.8.0)
+Requires-Dist: scipy (>=1.15.1,<2.0.0)
 Requires-Dist: sphinx (>=8.0.0,<9.0.0) ; extra == "docs"
 Requires-Dist: sphinx-rtd-theme (>=3.0.0,<4.0.0) ; extra == "docs"
 Requires-Dist: tomli (>=2.0.0,<3.0.0) ; extra == "docs"
@@ -82,9 +85,9 @@ poetry run <command>
 
 ### TL;DR
 If you don't want to go through all the configuration, e.g. you just simply want to test if everything works,
-you can simply run app with test dataset provided in `tests/e2e_tests` directory:
+you can simply run app with test dataset provided in `examples` directory:
 
-> poetry run flask --app 'goodmap.goodmap:create_app(config_path="./tests/e2e_tests/e2e_test_config.yml")' run
+> poetry run flask --app 'goodmap.goodmap:create_app(config_path="./examples/e2e_test_config.yml")' run
 
 ### Configuration
 
@@ -102,7 +105,7 @@ Afterwards run it with:
 
 ## Database
 
-The database is stored in JSON, in the `map` section. For an example database see `tests/e2e_tests/e2e_test_data.json`. The first subsection `data` consists of the actual datapoints, representing points on a map.
+The database is stored in JSON, in the `map` section. For an example database see `examples/e2e_test_data.json`. The first subsection `data` consists of the actual datapoints, representing points on a map.
 
 Datapoints have fields. The next subsections define special types of fields:
 - `obligatory_fields` - here are explicitely stated all the fields that the application assumes are presnt in all datapoints. E.g.
@@ -130,9 +133,10 @@ You can define the fields in all these subsections. Besides these types of field
 
 ## Examples
 
-You can find examples of working configuration and database in `tests/e2e_tests` named:
-- `e2e_test_config.yml`
-- `e2e_test_data.json`
+You can find examples of working configuration and database in `examples/` directory:
+- `e2e_test_config.yml` - Basic configuration example
+- `e2e_test_data.json` - Example database with sample location data
+- `mongo_e2e_test_config.yml` - MongoDB configuration example
 
 
 

{goodmap-1.1.3.dist-info → goodmap-1.1.6.dist-info}/RECORD

@@ -1,15 +1,16 @@
 goodmap/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+goodmap/clustering.py,sha256=ULB-fPNOUDblgpBK4vzuo0o2yqIcvG84F3R6Za2X_l4,2905
 goodmap/config.py,sha256=sseE4sceFB8OBuFsrRpQJvjv0Vg5KFdkzihBX_hbE2c,1313
 goodmap/core.py,sha256=rzMhOIYnR1jxTX6uHQJKIPLYxdUm4_v2d6LrtHtJpHU,1465
-goodmap/core_api.py,sha256=RVG4X64BSXTIzmj9mPK1DcT9p6xD00NnmX8FUaoj-uE,13277
-goodmap/data_models/location.py,sha256=H3EKozc-WZvrYm6cwajl8_gaw4rQhxdlvxR1mk4mpkA,1104
+goodmap/core_api.py,sha256=BkulLV2cZvws0CEAHNu4Svyptyol5TN0uLPW2Iw10NA,16294
+goodmap/data_models/location.py,sha256=oPsxTiPSL0cABlQH2YjFGgioO-mROujtQvnkNiQQR-s,1149
 goodmap/data_validator.py,sha256=lBmVAPxvSmEOdUGeVYSjUvVVmKfPyq4CWoHfczTtEMM,4090
 goodmap/db.py,sha256=2yZIQO6KbN6y21gxwO0xmxXIcXXrk7wqd7mgSOAefJw,47491
 goodmap/formatter.py,sha256=VlUHcK1HtM_IEU0VE3S5TOkZLVheMdakvUeW2tCKdq0,783
 goodmap/goodmap.py,sha256=q6okPopWBH6jDkKJcGDegebaapHLFUVilJ3p3aKi97k,2960
 goodmap/templates/goodmap-admin.html,sha256=39PJ1drk_xdkyzXgPZZNXYq9gA9oTVeR8hsgeae6E0g,35614
-goodmap/templates/map.html,sha256=N4N0ONzEFUS4bFtOA2jgXVbMQ7cKd1cRYIVnGLUzBIE,3995
-goodmap-1.1.3.dist-info/METADATA,sha256=CstkaPb9MW6r9Pj03bVWuCfEmW-juFPr9UGe30l3Fyo,5619
-goodmap-1.1.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-goodmap-1.1.3.dist-info/licenses/LICENSE.md,sha256=nkCQOR7uheLRvHRfXmwx9LhBnMcPeBU9d4ebLojDiQU,1067
-goodmap-1.1.3.dist-info/RECORD,,
+goodmap/templates/map.html,sha256=aEIL6M7AlBZ34asV5R1syKq9IA1tBZNhiBMA9ovco7I,4105
+goodmap-1.1.6.dist-info/METADATA,sha256=keFFJTCCtpImzKzTNRwgbbuGWrHT27MFAfYSjjoLCvg,5868
+goodmap-1.1.6.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+goodmap-1.1.6.dist-info/licenses/LICENSE.md,sha256=nkCQOR7uheLRvHRfXmwx9LhBnMcPeBU9d4ebLojDiQU,1067
+goodmap-1.1.6.dist-info/RECORD,,