Add comments

Author: Vallasc

Examples.md

@@ -2,6 +2,16 @@ package Algorithms
 
 import breeze.linalg.DenseMatrix
 
+/**
+  * Trait that define an algorithm for the processing pipeline
+  */
 trait Algorithm extends Serializable {
+    
+    /**
+    * Main run algorithm method, takes a matrix and return a matrix
+    *
+    * @param imageMatrix unprocessed image matrix
+    * @return processed image matrix
+    */
     def run (imageMatrix :DenseMatrix[Double]): DenseMatrix[Double]
 }

src/main/scala/Algorithms/Algorithm.scala

@@ -2,7 +2,20 @@ package Algorithms
 
 import breeze.linalg.DenseMatrix
 
+/**
+  * A convolution process takes a kernel matrix, which is slid across the image and multiplied with the input 
+  * such that the output is enhanced in a certain desirable manner.
+  *
+  * @param convolutionKernel kernel matrix
+  */
 class Convolution (convolutionKernel :DenseMatrix[Double]) extends Algorithm {
+
+    /**
+    * Main run algorithm method, takes a matrix and return a matrix
+    *
+    * @param imageMatrix unprocessed image matrix
+    * @return processed image matrix
+    */
     def run (imageMatrix :DenseMatrix[Double]) :DenseMatrix[Double]  = {
         assert(convolutionKernel.cols == 3)
         assert(convolutionKernel.rows == 3)

src/main/scala/Algorithms/Convolution.scala

@@ -8,9 +8,15 @@ import breeze.linalg.InjectNumericOps
 import scala.util.Random
 import java.io.File
 
-class Denoiser (MAX_BURNS :Int = 100, MAX_SAMPLES :Int = 200) extends Algorithm {
+/**
+  * Gibbs denoiser implementation
+  *
+  * @param maxBurns max number of iterations
+  */
+class Denoiser (maxBurns:Int = 100) extends Algorithm {
     val ITA = 0.9
     val BETA = 2
+    val MAX_SAMPLES :Int = 200
     val initialization = "same"
 
     private def energy (Y : DenseMatrix[Double], X: DenseMatrix[Double]) : Double = {
@@ -21,15 +27,29 @@ class Denoiser (MAX_BURNS :Int = 100, MAX_SAMPLES :Int = 200) extends Algorithm
         + sum( Y( ::, 0 until M-1 ) *:* Y( ::, 1 to -1 ) )
     }
 
+    /**
+      * Sample phase
+      *
+      * @param i pixel row
+      * @param j pixel col
+      * @param Y processed matrix
+      * @param X original matrix
+      * @return
+      */
     private def sample (i: Int, j: Int, Y: DenseMatrix[Double], X: DenseMatrix[Double]) : Int = {
         val blanket = new DenseVector[Double]( Array(Y(i-1, j), Y(i, j-1), Y(i, j+1), Y(i+1, j), X(i, j)) )
 
         val w = ITA * blanket(-1) + BETA * sum(blanket(0 until 4))
         val prob = 1 / (1 + math.exp(-2*w))
-        //val prob = exp( 2 * sum(blanket).toDouble ) / ( 1 + exp( 2 * sum(blanket).toDouble ))
         if (Random.nextDouble < prob) 1 else -1
     }
 
+    /**
+      * Main run algorithm method, takes a matrix and return a matrix
+      *
+      * @param imageMatrix unprocessed image matrix
+      * @return processed image matrix
+      */
     def run (imageMatrix :DenseMatrix[Double]): DenseMatrix[Double] = {
         println("Denoiser: working")
         println(s"Initialization : $initialization")
@@ -44,7 +64,7 @@ class Denoiser (MAX_BURNS :Int = 100, MAX_SAMPLES :Int = 200) extends Algorithm
 
 
         var ctr = 0
-        for ( _ <- 0 until MAX_BURNS) {
+        for ( _ <- 0 until maxBurns) {
             for { 
                 i <- 1 until N-1
                 j <- 1 until M-1

src/main/scala/Algorithms/Denoiser.scala

@@ -2,7 +2,17 @@ package Algorithms
 
 import breeze.linalg.DenseMatrix
 
-class Invert extends Algorithm {
+/**
+  * Invert colors of a given matrix
+  */
+object Invert extends Algorithm {
+
+    /**
+    * Main run algorithm method, takes a matrix and return a matrix
+    *
+    * @param imageMatrix unprocessed image matrix
+    * @return processed image matrix
+    */
      def run (imageMatrix :DenseMatrix[Double]) :DenseMatrix[Double]  = {
         imageMatrix.map( elem => 255 - elem)
     }

src/main/scala/Algorithms/Invert.scala

@@ -2,7 +2,18 @@ package Algorithms
 
 import breeze.linalg.DenseMatrix
 
-class MeanFilter extends Algorithm {
+/**
+  * Mean filtering is a simple, intuitive and easy to implement method of smoothing images,
+  * reducing the amount of intensity variation between one pixel and the next
+  */
+object MeanFilter extends Algorithm {
+
+    /**
+    * Main run algorithm method, takes a matrix and return a matrix
+    *
+    * @param imageMatrix unprocessed image matrix
+    * @return processed image matrix
+    */
     def run (imageMatrix :DenseMatrix[Double]): DenseMatrix[Double] = {
         val outMatrix =  DenseMatrix.zeros[Double](imageMatrix.rows, imageMatrix.cols)
         for {

…ain/scala/Algorithms/AverageFilter.scala …c/main/scala/Algorithms/MeanFilter.scalasrc/main/scala/Algorithms/AverageFilter.scala renamed to src/main/scala/Algorithms/MeanFilter.scala src/main/scala/Algorithms/AverageFilter.scala renamed to src/main/scala/Algorithms/MeanFilter.scala

@@ -2,7 +2,18 @@ package Algorithms
 
 import breeze.linalg.DenseMatrix
 
+/**
+  * Median filter works by moving through the image pixel by pixel,
+  * replacing each value with the median value of neighbouring pixels
+  */
 object MedianFilter extends Algorithm {
+
+    /**
+    * Main run algorithm method, takes a matrix and return a matrix
+    *
+    * @param imageMatrix unprocessed image matrix
+    * @return processed image matrix
+    */
     def run (imageMatrix :DenseMatrix[Double]): DenseMatrix[Double] = {
         val outMatrix =  DenseMatrix.zeros[Double](imageMatrix.rows, imageMatrix.cols)
         for {

src/main/scala/Algorithms/MedianFilter.scala

@@ -8,6 +8,12 @@ import Pipelines.{EdgeDetection, MedianDenoiser, GibbsEdgeDetection, Pipeline}
 import Algorithms.Denoiser
 import Pipelines.GibbsDenoiser
 
+/**
+  * Main entry point
+  * 
+  * sbt assembly
+  * spark-submit --driver-memory 8g --master local[*]  ./jar/binary.jar ./data/nike_noisy.png
+  */
 object Main {
 
     var inputPathImage = "./data/input.png"
@@ -48,6 +54,7 @@ object Main {
         println(s"Sub matrix size: ${subHeight}")
         println(s"Paddding: ${padding}")
 
+        // Get image as matrix
         val inputStream = FileUtils.getInputStream(inputPathImage)
         val inputImage = new Image()
         val pixelArray = inputImage.getPixelMatrix(inputStream, true)
@@ -56,6 +63,7 @@ object Main {
 
         // Define the Spark Job
         val job = new SparkJob(padding, subHeight, subWidth, denoiserRuns, debug)
+        // Match the selected pipeline
         val pipeline = inputPiepeline match {
             case "GibbsDenoise" => new GibbsDenoiser(denoiserRuns)
             case "GibbsEdgeDetection" => new GibbsEdgeDetection(denoiserRuns)
@@ -64,16 +72,19 @@ object Main {
         }
 
         println("\nStart")
+        // Runs job and gets execution time
         val result = Utils.time(job.run(pixelMatrix, pipeline))
         if(debug > 0)
             println(s"Time: ${result._2} ms")
 
+        // Saves output image as file
         val outputStream = FileUtils.getOutputStream(outputPathImage)
         val outputImage = new Image()
         outputImage.setPixelMatrix(result._1.data.map(_.toInt), result._1.rows, result._1.cols, true)
         outputImage.saveImage(outputStream)
         outputStream.close()
 
+        // Forges the output report
         val json = s"""{
                 "time": ${result._2},
                 "inputPiepeline": "${inputPiepeline}",
@@ -86,11 +97,9 @@ object Main {
                 "subWidth": ${subWidth}
             }"""
 
+        // Saves report to file
         val jsonOutputStream = FileUtils.getOutputStream(outputPathJson)
         jsonOutputStream.write(json.getBytes(Charset.forName("UTF-8")))
         jsonOutputStream.close()
     }
-}
-
-// sbt assembly
-// spark-submit --driver-memory 8g --master local[*]  ./jar/binary.jar ./data/nike_noisy.png
+}

src/main/scala/Main.scala

@@ -2,6 +2,9 @@ import java.io.File
 import scala.util.Random
 import _root_.Utils.FileUtils
 
+/**
+  * Used to make sample noise images
+  */
 object Noiser {
     val PROB = 0.3
     val inputImage = "./data/nike.png"

src/main/scala/Noiser/Noiser.scala

@@ -6,5 +6,5 @@ import breeze.linalg.DenseMatrix
 object EdgeDetection extends Pipeline (
     List(
         new Convolution( DenseMatrix((-1.0, -1.0, -1.0), (-1.0, 8.0, -1.0), (-1.0, -1.0, -1.0))),
-        new Invert()
+        Invert
     )) {}