Easy grouping plus notes

CONTRIBUTING.md

@@ -104,3 +104,45 @@ def __hello_module():
 
 We only want to expose the absolute bare minimum number of functions to the consumers of
 our modules.
+
+## Overview of Function
+
+In order to understand how things are drawn and maintained there are some classes you need to know.
+
+### Modes
+
+Lambas, partially applied functions, and function passing are used throughout the application to not only improve
+readability but also improve modularity of the code. You can see modes in `clusterview/mode.py`. These modes are used
+to put the application in a global state for adding, editing, moving, and deleting things.
+
+In order to improve readability `main_window.py`, the main application class module, uses some neat function passing
+tricks to determine which modes to use in `clusterview/mode_handlers.py`. The `mode_handlers.py` module is fairly
+complicated but defines basically all of the mode handling code used for each mode in the application.
+
+### Point
+
+The `Point` class is the base class for all drawn points. It contains important details for calculating location
+in space such as it's containing viewport, it's x and y coordinates in the viewport, it's drawn size, it's color,
+and a list of optional attributes.
+
+### PointSet
+
+A `PointSet` is a convenient holder for all points on a screen. It contains methods that simplify adding to, removing,
+moving, and deleting points from the canvas. It maintains a constant viewport state, point size, and other useful
+attributes so that you do not need to concern yourself with them during use.
+
+### PointManager
+
+The `PointManager` is a global singleton that is shared across the entire application. You can think of the
+`PointManager` as the absolute source of truth for the state of points in the application. In addition to maintaining
+a global `PointSet`, it also maintains the `save` and `load` configuration features so that they are consistent
+each time they are used.
+
+### Grouping Points
+
+Each point can be grouped by color, defined in `clusterview/colors.py` in the global `PointSet`. This way you
+do not need to explicitly maintain sets of points representing groups, and can instead call the `groups` function
+on the `PointSet` to return to you a dictionary from `color.Color` to `Point` representing each group and their
+member points.
+
+

README.md

@@ -40,3 +40,4 @@ python3 clusterview.py
 ```
 
 To start the software.
+

clusterview/points.py

@@ -341,3 +341,20 @@ class PointSet:
         for p in self.__points:
             if p.hit(x, y):
                 self.__points.remove(p)
+
+    def groups(self):
+        """
+        Returns a map from color to point representing each point's group
+        membership based on color.
+        """
+        g = {}
+
+        for p in self.__points:
+            if p.color not in g:
+                # Create the key for the group color since it does
+                # not exist.
+                g[p.color] = []
+
+            g[p.color].append(p)
+
+        return g

tests/test_point_set.py

@@ -90,3 +90,25 @@ def test_clear_all_selected_points():
             unselected += 1
 
     assert unselected == 2
+
+
+def test_groups():
+    point_set = PointSet(8, 100, 100)
+    point_set.add_point(4, 4, Color.GREY)
+    point_set.add_point(5, 5, Color.GREY)
+    point_set.add_point(10, 4, Color.BLUE)
+    point_set.add_point(30, 5, Color.BLUE)
+
+    p1 = Point(4, 4, Color.GREY, 8, 100, 100)
+    p2 = Point(5, 5, Color.GREY, 8, 100, 100)
+    p3 = Point(10, 4, Color.BLUE, 8, 100, 100)
+    p4 = Point(30, 5, Color.BLUE, 8, 100, 100)
+
+    expected = {
+        Color.GREY: [p1, p2],
+        Color.BLUE: [p3, p4]
+    }
+
+    groups = point_set.groups()
+
+    assert groups == expected