openwisp · cestercian · Mar 1, 2025 · Mar 5, 2025 · Mar 12, 2025 · Mar 12, 2025
diff --git a/README.md b/README.md
@@ -372,23 +372,13 @@ For map, you need to configure `mapOptions`. The [`mapOptions`](https://leafletj
 
 You can also customize some global properties with [`echartsOption`](https://echarts.apache.org/en/option.html) in echarts.
 
-### API Introduction
+## Automatic Cluster Overlap Prevention
 
-#### Core
+When multiple clusters of different categories share identical coordinates, NetJSONGraph now **automatically** offsets them in a circular pattern (pixel-space repulsion). No extra utilities or configuration flags are required—simply enable clustering with a `clusteringAttribute`, and the library handles overlap for you.
 
-- `setConfig`
+See the [Cluster Overlap Example](./examples/netjson-clustering.html) to view the result.
 
-  Method to set the configuration of the graph. You can use this function to add, update or modify the configuration of the graph.
-
-- `setUtils`
-
-  Method to set the utils of the graph. You can use this function to add, update the utils.
-
-- `render`
-
-  Method to render the graph.
-
-#### Realtime Update
+## Realtime Update
 
 We use [socket.io](https://socket.io/) to monitor data changes which supports WebSockets and Polling. You can call `JSONDataUpdate` when the data change event occurs and pass the data to update the view.
 
@@ -795,7 +785,7 @@ Using array files to append data step by step at start.
 Similiar to the first method, but easier.  
 [ Append data using arrays demo](https://openwisp.github.io/netjsongraph.js/examples/netjsonmap-appendData2.html)
 
-The demo shows the clustering of nodes.  
+The demo shows how to handle overlapping clusters with different statuses.
 [ Clustering demo](https://openwisp.github.io/netjsongraph.js/examples/netjson-clustering.html)
 
 ### Upgrading from 0.1.x versions to 0.2.x

diff --git a/public/example_templates/netjson-clustering.html b/public/example_templates/netjson-clustering.html
@@ -1,7 +1,7 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
   <head>
-    <title>netjsongraph.js: basic example</title>
+    <title>NetJSON Cluster Overlap Example</title>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link
@@ -14,6 +14,11 @@
     <link href="../lib/css/netjsongraph-theme.css" rel="stylesheet" />
     <link href="../lib/css/netjsongraph.css" rel="stylesheet" />
     <style type="text/css">
+      body {
+        margin: 0;
+        padding: 0;
+        font-family: Arial, sans-serif;
+      }
       #legend h4 {
         margin: 10px 0;
         text-align: center;
@@ -30,7 +35,6 @@
         border-radius: 8px;
         color: #000;
         font-family: Arial, sans-serif;
-        font-family: sans-serif;
         font-size: 14px;
         z-index: 1000;
         user-select: text;
@@ -44,101 +48,188 @@
         width: 16px;
         margin-right: 5px;
       }
-      #legend .link-up,
-      #legend .link-down {
+      .status-ok,
+      .status-problem,
+      .status-critical {
         display: inline-block;
-        height: 5px;
-        border-bottom-width: 6px;
-        border-bottom-style: solid;
+        width: 15px;
+        height: 15px;
+        margin-right: 5px;
+        border-radius: 50%;
       }
-      #legend .link-up {
-        color: #3acc38;
-        margin-right: 10px;
+      .status-ok {
+        background-color: #1ba619;
       }
-      #legend .link-down {
-        color: red;
-        margin-right: 10px;
+      .status-problem {
+        background-color: #ffa500;
       }
-
-      @media only screen and (max-width: 850px) {
-        #legend {
-          right: 15px;
-        }
+      .status-critical {
+        background-color: #c92517;
       }
     </style>
   </head>
   <body>
-    <script type="text/javascript">
-      const map = new NetJSONGraph("../assets/data/netjsonmap.json", {
+    <script type="text/javascript" src="/netjsongraph.min.js"></script>
+    <script type="module">
+      function generateNodesForStatus(
+        status,
+        baseLat,
+        baseLng,
+        minNodes,
+        maxNodes,
+        startId,
+      ) {
+        const nodes = [];
+        const numNodes =
+          Math.floor(Math.random() * (maxNodes - minNodes + 1)) + minNodes;
+        let currentId = startId;
+
+        for (let i = 0; i < numNodes; i++) {
+          nodes.push({
+            id: `${currentId++}`,
+            name: `${status.charAt(0).toUpperCase() + status.slice(1)} Node ${i + 1}`,
+            // Slightly offset location for each node within the group
+            location: {
+              lat: baseLat + (Math.random() - 0.5) * 0.001,
+              lng: baseLng + (Math.random() - 0.5) * 0.001,
+            },
+            properties: {status: status},
+          });
+        }
+        return {nodes, nextId: currentId};
+      }
+
+      let nextNodeId = 1;
+      const criticalNodesResult = generateNodesForStatus(
+        "critical",
+        45.4642,
+        9.19,
+        7,
+        15,
+        nextNodeId,
+      );
+      nextNodeId = criticalNodesResult.nextId;
+      const okNodesResult = generateNodesForStatus(
+        "ok",
+        45.4742,
+        9.18,
+        12,
+        22,
+        nextNodeId,
+      );
+      nextNodeId = okNodesResult.nextId;
+      const problemNodesResult = generateNodesForStatus(
+        "problem",
+        45.4842,
+        9.17,
+        5,
+        10,
+        nextNodeId,
+      );
+
+      const allNodes = [
+        ...criticalNodesResult.nodes,
+        ...okNodesResult.nodes,
+        ...problemNodesResult.nodes,
+      ];
+
+      const testData = {
+        type: "NetworkGraph",
+        label: "Cluster Overlap Test with Variable Nodes",
+        nodes: allNodes,
+        links: [], // Keep links empty for this example
+      };
+
+      const map = new NetJSONGraph(testData, {
         render: "map",
         clustering: true,
-        clusteringThreshold: 50,
-        // set map initial state.
+        clusteringThreshold: 2,
+        clusterRadius: 80,
+        disableClusteringAtLevel: 18,
+        clusteringAttribute: "status",
+        clusterSeparation: 20,
         mapOptions: {
-          center: [46.86764405052012, 19.675998687744144],
-          zoom: 4,
+          center: [45.4642, 9.19],
+          zoom: 12,
+          minZoom: 3,
+          maxZoom: 18,
           nodeConfig: {
             label: {
               offset: [0, -10],
             },
           },
         },
-        linkCategories: [
+        nodeCategories: [
           {
-            name: "down",
-            linkStyle: {
-              color: "#c92517",
-              width: 5,
+            name: "ok",
+            nodeStyle: {
+              color: "#1ba619",
+            },
+          },
+          {
+            name: "problem",
+            nodeStyle: {
+              color: "#ffa500",
             },
-            emphasis: {
-              linkStyle: {
-                color: "#FD0101",
-                opacity: 1,
-              },
+          },
+          {
+            name: "critical",
+            nodeStyle: {
+              color: "#c92517",
             },
           },
         ],
-        // Convert to internal json format
         prepareData: (data) => {
-          data.nodes.map((node) => {
+          data.nodes.forEach((node) => {
             node.label = node.name;
-            node.properties = Object.assign(node.properties || {}, {
+            node.properties = {
+              ...node.properties,
               location: node.location,
-            });
-          });
-
-          data.links.map((link) => {
-            link.properties = link.properties || {};
-            if (link.properties.status) {
-              link.category = link.properties.status;
+            };
+
+            if (node.properties && node.properties.status) {
+              const status = node.properties.status.toLowerCase();
+              // Map known statuses to categories
+              if (status === 'ok' || status === 'problem' || status === 'critical') {
+                node.category = status;
+              } else {
+                // Default others to unknown (though this example only generates known ones)
+                node.category = "unknown";
+              }
+            } else {
+              // Default nodes without status to unknown
+              node.category = "unknown";
             }
           });
         },
       });
 
-      const createLegend = (key, name) => {
+      const createLegend = (key, className) => {
         const legendItem = document.createElement("p");
         const legendIcon = document.createElement("span");
-
-        legendIcon.setAttribute("class", name);
-
+        legendIcon.setAttribute("class", className);
         legends.appendChild(legendItem);
         legendItem.appendChild(legendIcon);
-
         legendItem.innerHTML += key;
         return legendItem;
       };
+
       const legends = document.createElement("div");
       const legendsHeader = document.createElement("h4");
       legends.setAttribute("id", "legend");
-      legendsHeader.innerHTML = "Legend";
+      legendsHeader.innerHTML = "Node Status";
       legends.appendChild(legendsHeader);
-      legends.appendChild(createLegend("Up", "link-up"));
-      legends.appendChild(createLegend("Down", "link-down"));
-
+      legends.appendChild(createLegend("OK", "status-ok"));
+      legends.appendChild(createLegend("Problem", "status-problem"));
+      legends.appendChild(createLegend("Critical", "status-critical"));
       document.body.appendChild(legends);
 
-      map.render();
+      try {
+        map.render();
+        const leafletMap = map.map;
+      } catch (e) {
+        console.error("Error initializing NetJSONGraph:", e);
+      }
     </script>
   </body>
 </html>
diff --git a/src/js/cluster-utils.js b/src/js/cluster-utils.js
diff --git a/src/js/netjsongraph.config.js b/src/js/netjsongraph.config.js
@@ -38,6 +38,7 @@ const NetJSONGraphDefaultConfig = {
   clusteringThreshold: 100,
   disableClusteringAtLevel: 8,
   clusterRadius: 80,
+  clusterSeparation: 20,
   showMetaOnNarrowScreens: false,
   showLabelsAtZoomLevel: 7,
   echartsOption: {
@@ -252,7 +253,26 @@ const NetJSONGraphDefaultConfig = {
       radius: 8,
     },
   },
-  nodeCategories: [],
+  nodeCategories: [
+    {
+      name: "ok",
+      nodeStyle: {
+        color: "#28a745",
+      },
+    },
+    {
+      name: "problem",
+      nodeStyle: {
+        color: "#ffc107",
+      },
+    },
+    {
+      name: "critical",
+      nodeStyle: {
+        color: "#dc3545",
+      },
+    },
+  ],
   linkCategories: [],
 
   /**
@@ -265,8 +285,26 @@ const NetJSONGraphDefaultConfig = {
    * @this  {object}        The instantiated object of NetJSONGraph
    *
    */
-  // eslint-disable-next-line no-unused-vars
-  prepareData(JSONData) {},
+  prepareData(JSONData) {
+    if (JSONData && JSONData.nodes) {
+      JSONData.nodes.forEach((node) => {
+        if (node.properties && node.properties.status) {
+          const status = node.properties.status.toLowerCase();
+          if (
+            status === "ok" ||
+            status === "problem" ||
+            status === "critical"
+          ) {
+            node.category = status;
+          } else {
+            node.category = "unknown";
+          }
+        } else {
+          node.category = "unknown";
+        }
+      });
+    }
+  },
 
   /**
    * @function
@@ -283,16 +321,16 @@ const NetJSONGraphDefaultConfig = {
     let nodeLinkData;
     if (this.type === "netjson") {
       if (type === "node") {
-        nodeLinkData = this.utils.nodeInfo(data);
+        ({nodeLinkData} = {nodeLinkData: this.utils.nodeInfo(data)});
       } else {
-        nodeLinkData = this.utils.linkInfo(data);
+        ({nodeLinkData} = {nodeLinkData: this.utils.linkInfo(data)});
       }
 
       if (this.config.showMetaOnNarrowScreens || this.el.clientWidth > 850) {
         this.gui.metaInfoContainer.style.display = "flex";
       }
     } else {
-      nodeLinkData = data;
+      ({nodeLinkData} = {nodeLinkData: data});
     }
 
     this.gui.getNodeLinkInfo(type, nodeLinkData);
@@ -311,4 +349,5 @@ const NetJSONGraphDefaultConfig = {
   onReady() {},
 };
 
+export const {prepareData} = NetJSONGraphDefaultConfig;
 export default {...NetJSONGraphDefaultConfig};