improved documentation

README.md

@@ -1,2 +1,67 @@
 # bjorn
-Bjorn's Image comparison tool
+
+## Image comparison tool for Bjorn
+
+**bjorn allow the users (like Bjorn) to compare images that are provided as a list in a csv file**
+
+## Installation
+### [LATEST RELEASE](https://github.com/ganeshmannamal/bjorn/releases/latest)
+Download the appropriate release package as per you operating system. Supported operating systems are:
+ * MacOS (Darwin)
+ * Windows
+ * Linux
+
+Unpack the downloaded archive in you local directory to install the `bjorn` cli tool.
+
+## Usage
+```
+Usage:
+  bjorn [command]
+
+Available Commands:
+  diff        compare images listed in a csv file
+  help        Help about any command
+```
+
+### bjorn diff
+
+compare images listed in a csv file.
+
+```
+bjorn diff [flags]
+```
+
+### Options
+
+```
+  -f, --file string   CSV file to read image list
+  -h, --help          help for diff
+  -o, --out string    Output file location
+      --alsologtostderr                  log to standard error as well as files
+      --config string                    config file (default is $HOME/.bjorn.yaml)
+  -h, --help                             help for bjorn
+      --log_backtrace_at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
+      --log_dir string                   If non-empty, write log files in this directory
+      --logtostderr                      log to standard error instead of files
+      --stderrthreshold severity         logs at or above this threshold go to stderr (default 2)
+  -v, --v Level                          log level for V logs
+      --vmodule moduleSpec               comma-separated list of pattern=N settings for file-filtered logging
+```
+
+## Development
+
+### Image Comparison
+Bjorn uses a simple pixel based approach to image comparison. Each pixel of the 2 images being compared using the RGB values of each pixel.
+The Score is calculated by [summing up the difference in RGB values for each pixel](https://github.com/ganeshmannamal/bjorn/blob/master/pkg/pair/pair.go#L48) and using this value to get the ratio of different pixels to total pixels in the images.
+
+Limitations of current approach:
+ * It assumes the images are of the same size. Scaled versions of the same image will be considered different.
+ * Comparing same images in different formats (png, jpg, gif) can produce a score of ~0.01-0.02. The comparison algorithm uses a threshold of 0.01, below which images are considered similar
+
+### Further Development
+The comparison algorithm is defined as the `Compare()` function in the [pair](https://github.com/ganeshmannamal/bjorn/blob/master/pkg/pair/pair.go) package. This function may be extended to improve the comparison algorithm.
+Possible improvements include:
+ * Improve comparison algorithm to consider scaled images.
+ * Add ability to define multiple comparison algorithm and flags to select each.
+ * Add command to compare 2 images separately (eg `bjorn diff images img1 img2`).
+

pkg/cmd/diff.go

@@ -16,6 +16,10 @@ type Opts struct {
 	outFile string
 }
 
+// NewDiffCommand generates a cobra command for executing the diff command.
+// This command accepts the flags --file (-f path to csv file) and
+// --out (-o path for output file). --out is optional, if not provided,
+// out put file is created in same directory as input csv
 func NewDiffCommand() *cobra.Command {
 	opts := &Opts{}
 	diffCmd := &cobra.Command{
@@ -41,6 +45,9 @@ func NewDiffCommand() *cobra.Command {
 	return diffCmd
 }
 
+// Run reads the csv file and parses each line for image pairs for comparison.
+// After comparison it writes the to output csv, with each line containing -
+// "image1,image2,score,time taken
 func (opts *Opts) Run() error {
 	csvRootPath, err := filepath.Abs(filepath.Dir(opts.csvFile))
 	if err != nil {

pkg/cmd/root.go

@@ -16,7 +16,7 @@ var cfgFile string
 
 var rootCmd = &cobra.Command{
 	Use:   "bjorn",
-	Short: "image comparison tool for Bjorn",
+	Short: "Image comparison tool for Bjorn",
 	Long: `bjorn allow the users (like Bjorn) to compare images that are
 		provided as a list in a csv file`,
 	PersistentPreRun: func(cmd *cobra.Command, args []string) {
@@ -25,6 +25,10 @@ var rootCmd = &cobra.Command{
 	},
 }
 
+func NewRootCmd() *cobra.Command {
+	return rootCmd
+}
+
 func init() {
 	cobra.OnInitialize(initConfig)
 	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.bjorn.yaml)")

pkg/pair/pair.go

@@ -9,6 +9,9 @@ import (
 	"time"
 )
 
+// Pair is a construct of 2 images to be compared, along with Score and time taken for comparison
+// Score is a value between 0 to 1 indicating similarity of images.
+// 0 indicates the images are identical, 1 indicates images are of different sizes
 type Pair struct {
 	Image1 image.Image
 	Image2 image.Image
@@ -36,6 +39,10 @@ func NewImagePair(image1Path, image2Path string) (*Pair, error) {
 	return p, nil
 }
 
+// Compare uses simple pixel based comparison to determine similarity between images.
+// If the images are of different sizes, they are considered different with a Score of 1.
+// Red, Green and Blue values of each pixel is compared to calculate the difference in pixel.
+// Ratio of the sum of all pixel differences and Total no of pixels is user to determine the Score
 func (p *Pair) Compare() {
 	defer p.elapsed()() // deferred call to get execution time of Compare func
 	if p.Image1.Bounds() != p.Image2.Bounds() {
@@ -64,6 +71,8 @@ func (p *Pair) Compare() {
 	}
 }
 
+// Elapsed helps calculate the time taken for each comparison
+// A deferred call at the start of Compare() helps calculate the time taken
 func (p *Pair) elapsed() func() {
 	start := time.Now()
 	return func() {