ColourShape benchmark and moar docs (#11)

* Added benchmark

* Rebase

* [Server] ColouredShapePipeline Benchmarks and Documentation

* [Server] ColouredShapePipeline Benchmarks and Documentation

* Added benchmark

* Rebase

* [Server] ColouredShapePipeline Benchmarks and Documentation

* [Server] ColouredShapePipeline Benchmarks and Documentation

* [Server] ColouredShapePipeline Benchmarks and Documentation

* [CSP] Rebase off master

* [CSP] Remove unused variables

* [CSP] Make circles Mat private and final

photon-server/src/main/java/org/photonvision/vision/pipe/impl/FindCirclesPipe.java

@@ -31,12 +31,17 @@ import org.photonvision.vision.pipe.CVPipe;
 public class FindCirclesPipe
         extends CVPipe<Pair<Mat, List<Contour>>, List<CVShape>, FindCirclesPipe.FindCirclePipeParams> {
 
+    // Output vector of found circles. Each vector is encoded as 3 or 4 element floating-point vector
+    // (x,y,radius) or (x,y,radius,votes) .
     private final Mat circles = new Mat();
-
     /**
-    * Runs the process for the pipe.
+    * Runs the process for the pipe. The reason we need a separate pipe for circles is because if we
+    * were to use the FindShapes pipe, we would have to assume that any shape more than 10-20+ sides
+    * is a circle. Only issue with such approximation is that the user would no longer be able to
+    * track shapes with 10-20+ sides. And hence, in order to overcome this edge case, we can use
+    * HoughCircles which is more flexible and accurate for finding circles.
     *
-    * @param in Input for pipe processing.
+    * @param in Input for pipe processing. 8-bit, single-channel, grayscale input image.
     * @return Result of processing.
     */
     @Override
@@ -47,27 +52,40 @@ public class FindCirclesPipe
         Imgproc.HoughCircles(
                 in.getLeft(),
                 circles,
+                // Detection method, see #HoughModes. The available methods are #HOUGH_GRADIENT and
+                // #HOUGH_GRADIENT_ALT.
                 Imgproc.HOUGH_GRADIENT,
+                /*Inverse ratio of the accumulator resolution to the image resolution.
+                For example, if dp=1 , the accumulator has the same resolution as the input image.
+                If dp=2 , the accumulator has half as big width and height. For #HOUGH_GRADIENT_ALT the recommended value is dp=1.5,
+                unless some small very circles need to be detected.
+                */
                 1.0,
                 params.minDist,
                 params.maxCannyThresh,
                 params.accuracy,
                 params.minRadius,
                 params.maxRadius);
+        // Great, we now found the center point of the circle and it's radius, but we have no idea what
+        // contour it corresponds to
         for (int x = 0; x < circles.cols(); x++) {
+            // Grab the current circle we are looking at
             double[] c = circles.get(0, x);
+            // Find the center points of that circle
             double x_center = c[0];
             double y_center = c[1];
 
             for (Contour contour : in.getRight()) {
+                // Grab the moments of the current contour
                 Moments mu = contour.getMoments();
+                // Determine if the contour is within the threshold of the detected circle
                 if (Math.abs(x_center - (mu.m10 / mu.m00)) <= params.allowableThreshold
                         && Math.abs(y_center - (mu.m01 / mu.m00)) <= params.allowableThreshold) {
+                    // If it is, then add it to the output array
                     output.add(new CVShape(contour, ContourShape.Circle));
                 }
             }
         }
-
         return output;
     }
 
@@ -79,6 +97,17 @@ public class FindCirclesPipe
         private final int maxCannyThresh;
         private final int accuracy;
 
+        /*
+        * @params minDist - Minimum distance between the centers of the detected circles.
+        * If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed.
+        *
+        * @param maxCannyThresh -First method-specific parameter. In case of #HOUGH_GRADIENT and #HOUGH_GRADIENT_ALT, it is the higher threshold of the two passed to the Canny edge detector (the lower one is twice smaller).
+        * Note that #HOUGH_GRADIENT_ALT uses #Scharr algorithm to compute image derivatives, so the threshold value shough normally be higher, such as 300 or normally exposed and contrasty images.
+        *
+        *
+        * @param allowableThreshold - When finding the corresponding contour, this is used to see how close a center should be to a contour for it to be considered THAT contour.
+        * Should be increased with lower resolutions and decreased with higher resolution
+        *  */
         public FindCirclePipeParams(
                 int allowableThreshold,
                 int minRadius,

photon-server/src/main/java/org/photonvision/vision/pipe/impl/FindPolygonPipe.java

@@ -49,6 +49,11 @@ public class FindPolygonPipe
     private CVShape getShape(Contour in) {
 
         int corners = getCorners(in);
+        corners = getCorners(in);
+
+        /*The contourShape enum has predefined shapes for Circles, Triangles, and Quads
+        meaning any shape not fitting in those predefined shapes must be a custom shape.
+        */
         if (ContourShape.fromSides(corners) == null) {
             return new CVShape(in, ContourShape.Custom);
         }
@@ -65,18 +70,21 @@ public class FindPolygonPipe
     }
 
     private int getCorners(Contour contour) {
+        // Release previous approx
         approx.release();
         Imgproc.approxPolyDP(
                 contour.getMat2f(),
                 approx,
+                // Converts an accuracy percentage between 1-100 to an epsilon
                 params.accuracyPercentage / 600.0 * Imgproc.arcLength(contour.getMat2f(), true),
                 true);
+        // The height of the resultant approximation is the number of vertices
         return (int) approx.size().height;
     }
 
     public static class FindPolygonPipeParams {
         private final double accuracyPercentage;
-
+        // Should be a value between 0-100
         public FindPolygonPipeParams(double accuracyPercentage) {
             this.accuracyPercentage = accuracyPercentage;
         }

photon-server/src/main/java/org/photonvision/vision/pipeline/ColoredShapePipeline.java

@@ -61,7 +61,7 @@ public class ColoredShapePipeline
     private CVPipeResult<List<TrackedTarget>> targetList;
     private final Point[] rectPoints = new Point[4];
 
-    ColoredShapePipeline() {
+    public ColoredShapePipeline() {
         settings = new ColoredShapePipelineSettings();
     }