User:Rsiddharth/pd3dpr documentation

this text is a draft for the documentation for pd3dpr. = Performance Analysis = Jive is lightweight and it is written in a way that its CPU footprint is minimal. The code-base was predominantly developed and tested on a Pentium 4 machine.

Jive was monitored for its CPU footprint while it crunched a directory full of TIFF real time images to detect and reciprocate about the possible obstacles found in the real time images.



The red rectangle shows the instant of time when jive was executed. As it can be seen the CPU footprint is not as heavy as was expected and the peak level was found to be 46.8%

In the following sections, the performance issues and optimization in jive are discussed briefly.

Disk writes
One of the expensive operations done by is writing to the disk whenever it has to process a Standard Image Path.

As can be seen from the code, everytime standard image is processed by jive two disk writes take place -- one for writing the Standard Horizontal Pixel Difference Map & other for the Standard Vertical Pixel Differenc Map.

Disk writes are by default expensive, but given the computers today, two disk writes for a single session of running jive is not performance issue.

Disk reads
The number of disk reads, in jive, are for more than the number of writes that happens during the course of pattern analysis and recognition.

When a real time image has to be processed. The image should be read from the disk. We achieve this by using the TiffToMatrix class.

The ImagePlus class reads the TIFF image from disk. This type of read happens everytime a real time image is processed and it is inevitable.

Next, for the same real time image, when processing the Anomaly Maps, the  AnomalyProcessor uses the StandardPDM object.

The StandardPDM object, everytime it is created, reads two files which contains the Standard Horizontal and Vertical Pixel Maps.

From above, it can be inferred that for every real time image processed, we have three mandatory reads from the disk.

When Jive is used by the blind user, a real time image is processed every two seconds, therefore for a minute, Jive needs to process thirty images. So, in a minute, we have  30 x 3 = 90  disk reads. If a user is continuously using the device for one hour, then the disk reads will tend to  90 x 60 = 5400 .

Optimization
As was seen from from the previous section, the number of reads seems to be apparently high, but it would have been more than this, if not for an important optimization:

Read the TIFF image into an Integer matrix and perform pattern & magnitude analysis with the matrix instead of the image.

If we hadn't decide to put the image's pixel values into a matrix. If would have had to use TIFF image every time we were in need of the pixel values for pattern and magnitude analysis -- this would have lead to more disk reads and consequently lead to performance issues.

This important optimization is done by the TiffToMatrix class.

As can be seen, the class simply reads all the pixels from the image and puts them into a matrix.


 * Why Integer matrix: we made this decision, because matrix operations are cheap and pattern and magnitude analysis is more straightforward with matrices than with raw images.

Conclusion
The implementation is meant to be run on phone with a <tt>500MHz </tt> CPU. Jive was written with this constraint in mind. As as evident from the Optimization section, the program greatly reduces the complexity and thus the CPU footprint, by doing pattern and magnitude analysis on an Integer matrix. This and its modular design makes Jive, perfectly viable solution for the Perspective Dependent Three-Dimensional Path Recognizer.

= Appendix =

Miscellaneous content for knowing more about the Jive code base and how to use git.

Important Classes in Jive
Here is a bunch of classes that do interesting work and which, according to the authors, has been programmed cleverly.

The ImagePlus class
The ImagePlus class is part of the ImageJ library, which is a image processing library, released under the public domain.

The  class is used to read pixel values from a TIFF image.

To use the ImagePlus class, we have to create an object of it:

As can be seen, the destination of the image should be given to the ImagePlus constructor when we create the object.

Now we are ready to read pixels from the image. We do that by:

Where  are coordinates that point to a particular location in the image.

To read all the pixels from the image, we simply use a  construct:

So, that's how we use the  class to read pixels from the TIFF image and copy it into a  matrix.

FileToArray class
Part of the IO package, this class is used to read a of pixel map, stored in a plain text file, to a Integer matrix.

We use Regular Expression to detect integers or null values (marked as '-') from the plain text file:

For regex, the  &   classes are used.

The pixel reading from the plain text file is done by first putting the whole file into a  object (fileContent) and giving it to the Matcher object

After this, the Matcher's  method is used to detect integer values and if an integer value is found, it is put in the corresponding position in the Integer matrix:

After the whole pixel map is put into the Integer matrix, The matrix can fetched using the  method part of the same class.

PatternRecognizer interface
One of the best design decisions that was made through the developement of jive was with the interface.

It is a generic interface that all classes which do recognition should implement. By virtue of this, we make the jive Eco-system extremely modular -- new recognizers can be added to the code-base just by implementing this interface!

All recognizers that implement this class must be added to the in the PatternRecognizers class, which is part of the  package.

Using Git
Git, the fast version control system is used to maintain the jive code base.

We can do interesting things with git:


 * 1) Skim through the project's history
 * 2) Do work on multiple branches -- this is touted to be the kill feature in git.
 * 3) Push the code-base to remote repos -- a back-up solution
 * 4) etc

Browsing History
The Jive code-base is publicly hosted and can be cloned from:

To browse the jive's history, do:

and you'll get:

For a more interesting output, you can do:

and get this:

As it can be observed, the log says who has done the work, when that work was done, its hash and finally a condensed version of the commit message attached to the respective commit.

Checkout out Branches
For Jive, at present, we maintain three different branches.


 * 1) <tt>master</tt> branch - contains stable working-tree
 * 2) <tt>dev</tt> branch - all development is done here and later merged into master
 * 3) <tt>doc</tt> branch - all work related to documentation is done in this branch.

To see, in which branch you're in, do:

The `*' beside the `doc' implies that, we you're in the `doc' branch at present.

To move to a different branch, do:

To learn more about git, go to http://git-scm.com

rsiddharth (talk) 15:33, 24 April 2013 (UTC)