[fix] Prevent Overlapping of Clusters in netjsongraph.js #171

[cestercian]

Checklist

• I have read the OpenWISP Contributing Guidelines.
• I have manually tested the changes proposed in this pull request.
• I have written new test cases for new code and/or updated existing tests for changes to existing code.
• I have updated the documentation.

Reference to Existing Issue

Closes #171

Description of Changes

This PR addresses issue #171 by preventing the overlapping of clusters in the netjsongraph.js visualization.

Changes Implemented:

• Introduced spatial indexing using KDBush to optimize clustering performance.
• Implemented grouping of nodes based on proximity and clustering attributes.
• Modified cluster assignment logic to prevent overlapping.
• Updated centroid calculations for accurate cluster placement.
• Ensured better handling of non-clustered nodes.

Testing

A test file (cluster_overlap_test.html) was created to visualize and verify the clustering behavior. The test file simulates overlapping nodes with different statuses and ensures they are properly clustered without overlaps.

Screenshot

[nemesifier]

This has slipped my attention, the notification for this was buried among many other notifications. That's why it's good to let us know about your work in the dev chat.

[nemesifier]

In the PR description you mention a test file called cluster_overlap_test.html, which I see you have removed. What type of problem where you having with this? I think such a test file to compare the behavior of this branch with master and verify whether the situation really improves is quite useful.

[cestercian]

Thanks for the review @nemesifier! The cluster_overlap_test.html file was initially created to visualize the issue, but I removed it since I thought it wasn't necessary after fixing the overlap problem. However, I see your point—it could be useful for verifying improvements. I can reintroduce it and ensure it effectively compares the branch behavior with master. Let me know if you'd like any specific tests included!

[cestercian]

Hi @nemesifier ,

I've made the requested changes:

✅ Moved netjson-cluster-overlap.html to /public/example_templates for consistency.
✅ Updated index.html to include a link to the new example, styled like the others.

Let me know if you need any further modifications or if you'd like me to proceed with replacing the current clustering example with this one. Thanks for your feedback!

[nemesifier]

This is what I see when I try to open the example, do you see a different situation?

Cannot GET /example_templates/netjson-cluster-overlap.html.

[cestercian]

hey @nemesifier

I’ve fixed the issue. The error occurred because the requested file was not being served correctly. I’ve updated netjson-cluster-overlap.html and changed the file location in index.html my latest commit, which should resolve it.

Let me know if you still encounter any issues!

[nemesifier]

I don't know if I am doing something wrong but this isn't working for me, here's what I see:

netjsongraphjs-clustering-pr.webm

@niteshsinha17 do you see a different situation or do you get the same result I get?

[cestercian]

It looks like the NetJSONGraph library isn't being recognized. This often happens when the project isn't started properly.

@nemesifier, are you running yarn start, or are you just opening the index.html file directly? If you're just opening the file, the dependencies might not be loading correctly. Try starting the project with yarn start and let me know if the issue persists.

[niteshsinha17]

I don't know if I am doing something wrong but this isn't working for me, here's what I see:

netjsongraphjs-clustering-pr.webm
@niteshsinha17 do you see a different situation or do you get the same result I get?

@nemesifier I am getting this result. Seems something is wrong. I will look into PR in detail.

[niteshsinha17]

I have done a very basic review for now. The graph is not rendering properly.

Check this comment, here @nemesifier
has mentioned about an example that needs to be added. #239 (review)

[cestercian]

Hey @niteshsinha17 ,
I moved overlap prevention logic from lib/js/clusterUtils.js to src/js/cluster-utils.js, updated imports, and removed the old file.
and optimized getNodeStyle() usage in netjsongraph.render.js by properly using all returned style configs.

let me know if any other changes are needed 😁

[niteshsinha17]

@cestercian It's really good you are putting efforts. But I am interested in knowing your observations and reasoning behind your changes.

[nemesifier]

I would group all the clustering docs into a single section coming just before "Example Usage". The rest looks good to me but I'm trying to spare some time to do a complete round of testing before merging.

[nemesifier]

While testing openwisp/openwisp-monitoring#668 on demo I see that there's overlapping clusters:

demo.webm

Will DM you to show you this.

[nemesifier]

denmark.webm

[cestercian]

cluster.june.2.mov

Logic Changes for Cluster Separation

Enhanced Cluster Logic:

• Implemented a mechanism to offset clusters of different attribute groups that originate from the same pixel location to prevent overlap.
• Clusters are arranged in a circular pattern using angle-based separation (360° divided by the number of clusters) around the original position using a configurable clusterSeparation distance.
• The offset is calculated in pixels and then converted back to geographical coordinates using Leaflet's containerPointToLatLng method.

[nemesifier]

Great progress @cestercian! 👍

Problem found during testing: the green cluster overlapped the non clustered point.

clustering-04-june-2025.webm

When calculating whether we should move the cluster, can you take into account also non clustered points to avoid this? I guess if there were 2 yellow points we would have got a cluster and it would have worked normally, but we won't always have clusters, some times as in this case we will have only 1 point of a specific color and we don't want to hide it below the clusters.

[cestercian]

Hey @nemesifier ,

I've updated the clustering logic to form clusters even for single nodes and added test cases to cover this change.