Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-12-04T23:23:22Z

Aagrawa5: /* Setup of Development Environment */

This wiki page contains design details for the project on [https://github.com/servo/servo/wiki/Replace-C-libraries-student-project Evaluate replacing C libraries with modern Rust equivalents] for the Mozilla research project [http://github.com/servo/servo/wiki/Design Servo].

== Background Information <ref>http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa</ref> ==

===Rust===
[http://www.rust-lang.org/ Rust] is a new programming language for developing reliable and efficient systems. It is designed to support concurrency and parallelism in building platforms that take full advantage of modern hardware. Its static type system is safe and expressive and it provides strong guarantees about isolation, concurrency execution and memory safety.
Rust combines powerful and flexible modern programming constructs with a clear performance model to make program efficiency predictable and manageable. One important way it achieves this is by allowing fine-grained control over memory allocation through contiguous records and stack allocation. This control is balanced with the absolute requirement of safety: Rust’s type system and runtime guarantee the absence of data races, buffer overflow, stack overflow or access to uninitialized or deallocated memory.

===Servo===
[http://en.wikipedia.org/wiki/Servo_%28layout_engine%29 Servo] is an experimental project to build a Web browser engine for a new generation of hardware: mobile devices, multi-core processors and high-performance GPUs.
Servo builds on top of Rust to provide a secure and reliable foundation. Rust’s lightweight task mechanism promises to allow fine-grained isolation between browser components, such as tabs and extensions, without the need for expensive runtime protection schemes, like operating system process isolation. Servo is not designed to create a full browser but is rather focused on creating a reliable and fast browser engine.

== Introduction ==
Servo currently depends on a lot of C libraries for image decoding. We wish to evaluate switching some of these to new Rust libraries. This project involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.

====Setup of Development Environment====
Servo is currently developed on 64bit OS X and 64bit Linux.

The steps needed to build on a Debian based 64 bit Linux machine are included below. The instructions for other platforms are available [https://github.com/servo/servo#prerequisites here].

* Install the prerequisite dependencies
<pre>
sudo apt-get install curl freeglut3-dev \
libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \
msttcorefonts gperf g++ cmake python-virtualenv \
libssl-dev libglfw-dev
</pre>

* Clone servo repository
<pre>
git clone https://www.github.com/ankit3005/servo
cd servo
</pre>

Ensure that modified dependencies point to right sources
<pre>
./mach update-cargo -p freetype-rs
./mach update-cargo -p image
./mach update-cargo -p freetype-rs --precise 753496406098651c83cdaf63db9f75dc42da17c7
./mach update-cargo -p image --precise 3a398831adb22f1200cb68682e446ede187d23b9
</pre>

Build and run basic tests to ensure build success.
<pre>
./mach build
./mach run tests/html/about-mozilla.html
</pre>

== Architecture of system <ref>https://github.com/servo/servo/wiki/Design#task-supervision-diagram</ref> ==

=== Task Supervision Diagram ===

[[File:TaskSupervision.png]]

=== Task Communication Diagram ===

[[File:TaskCommunication.png]]

The above diagrams gives us an overview of the Servo's architecture.
*Each box represents a Rust task.
*Primary tasks are the ones which are represented by blue boxes.
*Gray boxes are for auxiliary tasks.
*White boxes are for worker tasks. Each such box represents several tasks, the precise number of which are decided by the workload.
*Supervisor relationships are shown by dashed lines.
*Communication channels are shown by solid lines.

The scope of our project is limited to changing the libraries used in the image decoding task shown above.

== Requirement analysis ==

Servo currently depends on a lot of C libraries, because Rust equivalents for these libraries did not exist when the project started. Our project is to evaluate switching some of these to new Rust libraries that have since been created. It involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.<ref>https://github.com/servo/servo/wiki/Replace-C-libraries-student-project</ref>

Initial step

Our [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step], implemented for the OSS project involved:
# Building Servo.
# Adding [http://doc.servo.org/util/time/fn.time.html timing code] to the image decoding implementation in the net crate.
# Rebuilding Servo.
# Reporting numbers for different kinds of images (i.e. PNG, JPEG, GIF).

Final Requirements

Our final project requirements are to:
* Build Servo and add code that reports (via the println! macro) the time required to decode images into displayable pixels.
* Add image decoding timing to the profiler.
* Import the [https://github.com/PistonDevelopers/freetype-rs freetype-rs] library to replace [https://github.com/servo/rust-freetype rust-freetype] in Servo, rewriting necessary code.<ref>https://github.com/servo/servo/issues/3369</ref> For this, we are to use [http://doc.crates.io/ Cargo], the dependency manager for Servo.
* Import the [https://github.com/PistonDevelopers/image rust-image] library to replace the [https://github.com/servo/rust-stb-image rust-stb-image] and [https://github.com/nothings/stb stb-image] libraries and rewrite the <code>load_from_memory</code> function which uses these libraries.<ref>https://github.com/servo/servo/issues/3368</ref>
* Report the timing differences for loading PNGs and non-PNGs on the same benchmarks. For this step, we are to consider profiling the result and optimizing the hotspots in rust-image.

== Implementation of the Final Requirements ==

1. Add Image Decoding time to the Profiler
To profile the time required by the load_from_memory to decode an image, we make a call to the profiler which outputs the time taken to decode on the console. To enable the profiler to do so, the following files were changed:
*image_cache_task.rs
*lib.rs
*time.rs
To invoke the profiler, we added a category under which to group the timings and passed a TimeProfilerChan (ie. a channel for communicating with the profiler task) to the ImageCacheTask::new method. On successfully building and running servo, we get the following image timings by profiler on the console:
<pre> ./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html </pre>
[[File:Profiler.png]]

2. Imported the freetype-rs library to replace rust-freetype in Servo.
We replaced the currently used rust-freetype library with the freetype-rs library. To enable proper functioning of servo after importing the new library, following files were modified in the repository [https://github.com/PistonDevelopers/freetype-rs PistonDevelopers/freetype-rs]:
*Cargo.toml
*src/ffi.rs
*src/lib.rs
*src/lib.rs
*src/library.rs
*src/tt_os2.rs
These changes were committed and have been pulled by PistonDevelopers. Check the changes on [https://github.com/PistonDevelopers/freetype-rs/pull/70 pull request] for more info.

3. Imported the rust-image library to replace the rust-stb-image and stb-image libraries and rewrite the load_from_memory function which uses these libraries.
In order to import the new library we modified the following files files in the repository [https://github.com/ankit3005/servo]:
*Cargo.toml
*components/net/lib.rs
*components/net/image_cache_task.rs
*components/net/image/base.rs
*components/net/image/holder.rs
*components/gfx/render_context.rs
*components/gfx/lib.rs
*components/gfx/Cargo.toml
*components/gfx/display_list/mod.rs
*components/layout/display_list_builder.rs
*components/layout/lib.rs

4. Reported the timing differences for loading PNGs and non-PNGs on the same benchmarks.
Once the new image library was imported , passed in several test images to record the decoding timing for different images.
The timing was compared with the decoding time for images by passing in the same images to the servo build containing the C image library. The results can be seen in the Test-Cases section below.

== Data and component design <ref>http://www.rust-ci.org/PistonDevelopers/piston/doc/image/index.html</ref>==

===Data Design===
The system entities that the project deals with is present in the image crate.

The structs and enums used to represent images are as below :

Structures
{| class = "wikitable"
|-
|ImageBuf
|An Image whose pixels are contained within a vector
|-
|Luma
|A type to hold a grayscale pixel
|-
|LumaA
|A type to hold a grayscale pixel with an alpha channel
|-
|MutPixels
|Mutable pixel iterator
|-
|Pixels
|Immutable pixel iterator
|-
|Rgb
|A type to hold an RGB pixel
|-
|Rgba
|A type to hold an RGB pixel with an alpha channel
|-
|SubImage
|A View into another image
|}

Enums
{| class="wikitable"
|-
|ColorType
|An enumeration over supported color types and their bit depths
|-
|DynamicImage
|A Dynamic Image
|-
|FilterType
|Available Sampling Filters
|-
|ImageError
|An enumeration of Image Errors
|-
|ImageFormat
|An enumeration of supported image formats. Not all formats support both encoding and decoding.
|}

===Component Design===

Rust image : It is an image processing library. This crate provides basic imaging processing functions and methods for converting to and from image formats.
All image processing functions provided operate on types that implement the GenericImage trait and return an ImageBuf. The details of other modules and traits included are :

Modules<ref>http://doc.rust-lang.org/guide.html#crates-and-modules</ref>
{| class="wikitable"
|-
|gif
|Decoding of GIF Images
|-
|imageops
|Image Processing Functions
|-
|jpeg
|Decoding and Encoding of JPEG Images
|-
|png
|Decoding and Encoding of PNG Images
|-
|ppm
|Encoding of portable pixmap Images
|-
|webp
|Decoding of Webp Images
|}

Traits<ref>http://rustbyexample.com/trait.html</ref>
{| class="wikitable"
|-
|GenericImage
|A trait for manipulating images.
|-
|ImageDecoder
|The trait that all decoders implement
|-
|MutableRefImage
|A trait for images that allow providing mutable references to pixels.
|-
|Pixel
|A trait that all pixels implement.
|}

Functions
{| class="wikitable"
|-
|load
|Create a new image from a Reader
|-
|load_from_memory
|Create a new image from a byte slice
|-
|open
|Open the image located at the path specified. The image's format is determined from the path's file extension
|}

== Design Principles ==

We are adhering to the following design principles for our implementation:

'''Open-Closed Principle'''<ref>http://en.wikipedia.org/wiki/Open/closed_principle</ref>

Although our task is to evaluate replacing C libraries with Rust libraries, we won't actually be modifying any existing functionality.

'''Interface Segregation Principle'''<ref>http://en.wikipedia.org/wiki/Interface_segregation_principle</ref>

The existing code is currently using the ''rust-freetype'' library for rendering fonts on the browser. We will be replacing this with the ''freetype-rs'' library, which divides the functionality offered by the former into smaller libraries which can be individually implemented instead of calling the entire library.

== Design Pattern==

We have implemented the Adapter Pattern in our Project:

When we updated the image library, the function load_from_memory() in base.rs had to be updated since the return from the updated function accepts a different set of parameters.
We implemented the Adapter pattern as a wrapper function over the new load_from_memory() function which performs the below functions:
1. Based on the file extension generate the ImageFormat Enum.
2. The return of the new function is a Result<DynamicImage>. This needs to be converted into a DynamicImage struct.
<pre>
pub fn load_from_memory(buffer: &[u8],ext: &str) -> Option<DynamicImage> {
if buffer.len() == 0 {
return None;
}
else {
//Retrieve the ImageFormat enum to be passed into the updated function
let image_type: Option< servo_image::ImageFormat > = get_format(ext);
if image_type == None
{
panic!("Image format not supported!");
}
else{
let new_image_type: servo_image::ImageFormat = image_type.unwrap();

//The updated function returns a Result<DynamicImage>
//below code resolves it to be returned by the wrapper function
let result = servo_image::load_from_memory(buffer,new_image_type);
if result.is_ok() {
let v = result.unwrap();
return Some(v);
}
else {
return None;
}
}
}
}

</pre>

==Flowchart describing Project Implementation==
[[File:Flowchart_final_M1455.JPG]]

== UML diagrams ==

===Class Diagram===
[[File:Class_diagram_M1455.JPG]]

== Test Cases ==

The project does not plan to add new functionality.
The test-cases we propose to run are will ensure that tasks that could be performed with the older C libraries can be executed.

The following test cases are proposed.

1. The initial step test case includes printing the decoding time for various image formates and has been included in the wiki: [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step]

2. The profiler is meant to capture the image decoding time take by the load_from_memory function. The profiler is run using the following command which gives the decoding time for the image passed as an argument:
<pre>./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html</pre>

3. After replacing the rust-freetype library by the freetype-rs library, we have tested that it works as expected by passing a webpage url and checking that the text renders correctly.
<pre>./mach run http://simple.wikipedia.org/wiki/Main_Page</pre>

4. After replacing the rust-stb-image and stb-image libraries with rust-image library and rewriting the load_from_memory function, we tested the the imports worked as expected by passing in different formats of images as urls and rendering them.
<pre> ./mach run https://www.http://optipng.sourceforge.net/pngtech/img/lena.png</pre>
Below you can see the image being rendered after importing the new rust image library: 
<center>[[File:lenaRenderedCorrectly.png]]</center>

As you can see the image is being rendered as intended.
Note: This was previously broken due to a bug in our code. We had used the wrong enum type while decoding images that resulted in distorted images. This was fixed by the following [https://github.com/ankit3005/servo/commit/dfa0b92b21144c01223db78d8570aa5ac890922c commit].

5. Our test cases include reporting the timing differences for loading PNGs and non-PNG images. The following report has been made with respect to the same:
{| class="wikitable sortable mw-collapsible"
|-
!Image Source
!Resolution
!New library decode timing (in ms)
!Old library decode timing (in ms)
|-
|http://meesoft.logicnet.dk/Analyzer/help/Lenna.jpg
|256X256
|40.3814
|45.002006
|-
|http://peps.redprince.net/peps/tiger-Q300.png
|290X300
|78.0789
|29.636256
|-
|http://www.codeproject.com/KB/GDI-plus/ImageProcessing2/grayscale.jpg
|332X300
|106.7289
|64.298119
|-
|http://www.ampsoft.net/webdesign-l/img/JPEG-sample-landscape-standard.jpg
|300X200
|88.852
|42.395043
|-
|http://andreas.com/pixs/ping-sample.gif
|682X310
|106.9462
|124.54975
|-
|http://www.cs.cmu.edu/~chuck/lennapg/len_top.jpg
|400X225
|118.0558
|62.443986
|-
|http://www.roman10.net/wp-content/uploads/2011/08/sample_thumb.jpg
|484X316
|175.0287
|99.462362
|-
|http://www.kksou.com/php-gtk2/gif/sample6.png
|480X240
|223.9521
|44.864687
|-
|http://imagej.nih.gov/ij/images/lena.jpg
|512X512
|257.5638
|165.242363
|-
|http://people.sc.fsu.edu/~jburkardt/data/png/lena.png
|512X512
|397.7005
|88.834362
|-
|http://24.media.tumblr.com/tumblr_m97zes5x3k1rezf8ro1_500.jpg
|500X375
|312.1556
|129.003554
|-
|http://urlnextdoor.com/ai/design-layout/images/sample-png.png
|200X200
|152.053
|20.885724
|-
|https://cdn2.iconfinder.com/data/icons/free-3d-printer-icon-set/512/3d_objects.png
|512X512
|550.5805
|78.025999
|-
|http://www.samontab.com/web/wp-content/uploads/2012/06/lena3.png
|512X512
|811.8095
|97.916758
|-
|http://www.math.uga.edu/~mjlai/images/LenaRecovered.jpg
|1200X900
|909.2834
|662.842394
|-
|https://chadaphone.files.wordpress.com/2013/10/face_detection.png
|640X480
|942.4558
|113.816885
|-
|https://www.drupal.org/files/issues/sample_7.png
|800X600
|708.9273
|157.806566
|-
|http://optipng.sourceforge.net/pngtech/img/lena.png
|512X512
|924.4648
|95.02457
|-
|http://www.ultrasync.net/dee/warehouse_the_odd_stage/lena2_before_1024.png
|1024X1024
|1507.7304
|326.962991
|-
|http://menehune.opt.wfu.edu/CSC365_665/Proj1/Gif/lena.gif
|256X256
|2466.9467
|40.845023
|-
|http://www.openbsd.org/art/puffy/ppuf1000X907.gif
|1000x907
|56338.6327
|615.134272
|}

== Video ==
A walkthrough of our entire project is available on this link: [https://www.youtube.com/watch?v=rq8MvpR1JyI Final Project Walkthrough]

== References ==
<references/>

== See Also ==
[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa Initial Step Details]

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-12-04T22:43:34Z

Aagrawa5: /* Test Cases */

This wiki page contains design details for the project on [https://github.com/servo/servo/wiki/Replace-C-libraries-student-project Evaluate replacing C libraries with modern Rust equivalents] for the Mozilla research project [http://github.com/servo/servo/wiki/Design Servo].

== Background Information <ref>http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa</ref> ==

===Rust===
[http://www.rust-lang.org/ Rust] is a new programming language for developing reliable and efficient systems. It is designed to support concurrency and parallelism in building platforms that take full advantage of modern hardware. Its static type system is safe and expressive and it provides strong guarantees about isolation, concurrency execution and memory safety.
Rust combines powerful and flexible modern programming constructs with a clear performance model to make program efficiency predictable and manageable. One important way it achieves this is by allowing fine-grained control over memory allocation through contiguous records and stack allocation. This control is balanced with the absolute requirement of safety: Rust’s type system and runtime guarantee the absence of data races, buffer overflow, stack overflow or access to uninitialized or deallocated memory.

===Servo===
[http://en.wikipedia.org/wiki/Servo_%28layout_engine%29 Servo] is an experimental project to build a Web browser engine for a new generation of hardware: mobile devices, multi-core processors and high-performance GPUs.
Servo builds on top of Rust to provide a secure and reliable foundation. Rust’s lightweight task mechanism promises to allow fine-grained isolation between browser components, such as tabs and extensions, without the need for expensive runtime protection schemes, like operating system process isolation. Servo is not designed to create a full browser but is rather focused on creating a reliable and fast browser engine.

== Introduction ==
Servo currently depends on a lot of C libraries for image decoding. We wish to evaluate switching some of these to new Rust libraries. This project involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.

====Setup of Development Environment====
Servo is currently developed on 64bit OS X and 64bit Linux.

The steps needed to build on a Debian based 64 bit Linux machine are included below. The instructions for other platforms are available [https://github.com/servo/servo#prerequisites here].

* Install the prerequisite dependencies
<pre>
sudo apt-get install curl freeglut3-dev \
libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \
msttcorefonts gperf g++ cmake python-virtualenv \
libssl-dev libglfw-dev
</pre>

* Clone servo repository
<pre>
git clone https://www.github.com/servo/servo
cd servo
</pre>

Ensure that modified dependencies point to right sources
<pre>
./mach update-cargo -p freetype-rs
./mach update-cargo -p image
./mach update-cargo -p freetype-rs --precise 753496406098651c83cdaf63db9f75dc42da17c7
./mach update-cargo -p image --precise 3a398831adb22f1200cb68682e446ede187d23b9
</pre>

Build and run basic tests to ensure build success.
<pre>
./mach build
./mach run tests/html/about-mozilla.html
</pre>

== Architecture of system <ref>https://github.com/servo/servo/wiki/Design#task-supervision-diagram</ref> ==

=== Task Supervision Diagram ===

[[File:TaskSupervision.png]]

=== Task Communication Diagram ===

[[File:TaskCommunication.png]]

The above diagrams gives us an overview of the Servo's architecture.
*Each box represents a Rust task.
*Primary tasks are the ones which are represented by blue boxes.
*Gray boxes are for auxiliary tasks.
*White boxes are for worker tasks. Each such box represents several tasks, the precise number of which are decided by the workload.
*Supervisor relationships are shown by dashed lines.
*Communication channels are shown by solid lines.

The scope of our project is limited to changing the libraries used in the image decoding task shown above.

== Requirement analysis ==

Servo currently depends on a lot of C libraries, because Rust equivalents for these libraries did not exist when the project started. Our project is to evaluate switching some of these to new Rust libraries that have since been created. It involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.<ref>https://github.com/servo/servo/wiki/Replace-C-libraries-student-project</ref>

Initial step

Our [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step], implemented for the OSS project involved:
# Building Servo.
# Adding [http://doc.servo.org/util/time/fn.time.html timing code] to the image decoding implementation in the net crate.
# Rebuilding Servo.
# Reporting numbers for different kinds of images (i.e. PNG, JPEG, GIF).

Final Requirements

Our final project requirements are to:
* Build Servo and add code that reports (via the println! macro) the time required to decode images into displayable pixels.
* Add image decoding timing to the profiler.
* Import the [https://github.com/PistonDevelopers/freetype-rs freetype-rs] library to replace [https://github.com/servo/rust-freetype rust-freetype] in Servo, rewriting necessary code.<ref>https://github.com/servo/servo/issues/3369</ref> For this, we are to use [http://doc.crates.io/ Cargo], the dependency manager for Servo.
* Import the [https://github.com/PistonDevelopers/image rust-image] library to replace the [https://github.com/servo/rust-stb-image rust-stb-image] and [https://github.com/nothings/stb stb-image] libraries and rewrite the <code>load_from_memory</code> function which uses these libraries.<ref>https://github.com/servo/servo/issues/3368</ref>
* Report the timing differences for loading PNGs and non-PNGs on the same benchmarks. For this step, we are to consider profiling the result and optimizing the hotspots in rust-image.

== Implementation of the Final Requirements ==

1. Add Image Decoding time to the Profiler
To profile the time required by the load_from_memory to decode an image, we make a call to the profiler which outputs the time taken to decode on the console. To enable the profiler to do so, the following files were changed:
*image_cache_task.rs
*lib.rs
*time.rs
To invoke the profiler, we added a category under which to group the timings and passed a TimeProfilerChan (ie. a channel for communicating with the profiler task) to the ImageCacheTask::new method. On successfully building and running servo, we get the following image timings by profiler on the console:
<pre> ./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html </pre>
[[File:Profiler.png]]

2. Imported the freetype-rs library to replace rust-freetype in Servo.
We replaced the currently used rust-freetype library with the freetype-rs library. To enable proper functioning of servo after importing the new library, following files were modified in the repository [https://github.com/PistonDevelopers/freetype-rs PistonDevelopers/freetype-rs]:
*Cargo.toml
*src/ffi.rs
*src/lib.rs
*src/lib.rs
*src/library.rs
*src/tt_os2.rs
These changes were committed and have been pulled by PistonDevelopers. Check the changes on [https://github.com/PistonDevelopers/freetype-rs/pull/70 pull request] for more info.

3. Imported the rust-image library to replace the rust-stb-image and stb-image libraries and rewrite the load_from_memory function which uses these libraries.
In order to import the new library we modified the following files files in the repository [https://github.com/ankit3005/servo]:
*Cargo.toml
*components/net/lib.rs
*components/net/image_cache_task.rs
*components/net/image/base.rs
*components/net/image/holder.rs
*components/gfx/render_context.rs
*components/gfx/lib.rs
*components/gfx/Cargo.toml
*components/gfx/display_list/mod.rs
*components/layout/display_list_builder.rs
*components/layout/lib.rs

4. Reported the timing differences for loading PNGs and non-PNGs on the same benchmarks.
Once the new image library was imported , passed in several test images to record the decoding timing for different images.
The timing was compared with the decoding time for images by passing in the same images to the servo build containing the C image library. The results can be seen in the Test-Cases section below.

== Data and component design <ref>http://www.rust-ci.org/PistonDevelopers/piston/doc/image/index.html</ref>==

===Data Design===
The system entities that the project deals with is present in the image crate.

The structs and enums used to represent images are as below :

Structures
{| class = "wikitable"
|-
|ImageBuf
|An Image whose pixels are contained within a vector
|-
|Luma
|A type to hold a grayscale pixel
|-
|LumaA
|A type to hold a grayscale pixel with an alpha channel
|-
|MutPixels
|Mutable pixel iterator
|-
|Pixels
|Immutable pixel iterator
|-
|Rgb
|A type to hold an RGB pixel
|-
|Rgba
|A type to hold an RGB pixel with an alpha channel
|-
|SubImage
|A View into another image
|}

Enums
{| class="wikitable"
|-
|ColorType
|An enumeration over supported color types and their bit depths
|-
|DynamicImage
|A Dynamic Image
|-
|FilterType
|Available Sampling Filters
|-
|ImageError
|An enumeration of Image Errors
|-
|ImageFormat
|An enumeration of supported image formats. Not all formats support both encoding and decoding.
|}

===Component Design===

Rust image : It is an image processing library. This crate provides basic imaging processing functions and methods for converting to and from image formats.
All image processing functions provided operate on types that implement the GenericImage trait and return an ImageBuf. The details of other modules and traits included are :

Modules<ref>http://doc.rust-lang.org/guide.html#crates-and-modules</ref>
{| class="wikitable"
|-
|gif
|Decoding of GIF Images
|-
|imageops
|Image Processing Functions
|-
|jpeg
|Decoding and Encoding of JPEG Images
|-
|png
|Decoding and Encoding of PNG Images
|-
|ppm
|Encoding of portable pixmap Images
|-
|webp
|Decoding of Webp Images
|}

Traits<ref>http://rustbyexample.com/trait.html</ref>
{| class="wikitable"
|-
|GenericImage
|A trait for manipulating images.
|-
|ImageDecoder
|The trait that all decoders implement
|-
|MutableRefImage
|A trait for images that allow providing mutable references to pixels.
|-
|Pixel
|A trait that all pixels implement.
|}

Functions
{| class="wikitable"
|-
|load
|Create a new image from a Reader
|-
|load_from_memory
|Create a new image from a byte slice
|-
|open
|Open the image located at the path specified. The image's format is determined from the path's file extension
|}

== Design Principles ==

We are adhering to the following design principles for our implementation:

'''Open-Closed Principle'''<ref>http://en.wikipedia.org/wiki/Open/closed_principle</ref>

Although our task is to evaluate replacing C libraries with Rust libraries, we won't actually be modifying any existing functionality.

'''Interface Segregation Principle'''<ref>http://en.wikipedia.org/wiki/Interface_segregation_principle</ref>

The existing code is currently using the ''rust-freetype'' library for rendering fonts on the browser. We will be replacing this with the ''freetype-rs'' library, which divides the functionality offered by the former into smaller libraries which can be individually implemented instead of calling the entire library.

== Design Pattern==

We have implemented the Adapter Pattern in our Project:

When we updated the image library, the function load_from_memory() in base.rs had to be updated since the return from the updated function accepts a different set of parameters.
We implemented the Adapter pattern as a wrapper function over the new load_from_memory() function which performs the below functions:
1. Based on the file extension generate the ImageFormat Enum.
2. The return of the new function is a Result<DynamicImage>. This needs to be converted into a DynamicImage struct.
<pre>
pub fn load_from_memory(buffer: &[u8],ext: &str) -> Option<DynamicImage> {
if buffer.len() == 0 {
return None;
}
else {
//Retrieve the ImageFormat enum to be passed into the updated function
let image_type: Option< servo_image::ImageFormat > = get_format(ext);
if image_type == None
{
panic!("Image format not supported!");
}
else{
let new_image_type: servo_image::ImageFormat = image_type.unwrap();

//The updated function returns a Result<DynamicImage>
//below code resolves it to be returned by the wrapper function
let result = servo_image::load_from_memory(buffer,new_image_type);
if result.is_ok() {
let v = result.unwrap();
return Some(v);
}
else {
return None;
}
}
}
}

</pre>

==Flowchart describing Project Implementation==
[[File:Flowchart_final_M1455.JPG]]

== UML diagrams ==

===Class Diagram===
[[File:Class_diagram_M1455.JPG]]

== Test Cases ==

The project does not plan to add new functionality.
The test-cases we propose to run are will ensure that tasks that could be performed with the older C libraries can be executed.

The following test cases are proposed.

1. The initial step test case includes printing the decoding time for various image formates and has been included in the wiki: [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step]

2. The profiler is meant to capture the image decoding time take by the load_from_memory function. The profiler is run using the following command which gives the decoding time for the image passed as an argument:
<pre>./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html</pre>

3. After replacing the rust-freetype library by the freetype-rs library, we have tested that it works as expected by passing a webpage url and checking that the text renders correctly.
<pre>./mach run http://simple.wikipedia.org/wiki/Main_Page</pre>

4. After replacing the rust-stb-image and stb-image libraries with rust-image library and rewriting the load_from_memory function, we tested the the imports worked as expected by passing in different formats of images as urls and rendering them.
<pre> ./mach run https://www.http://optipng.sourceforge.net/pngtech/img/lena.png</pre>
Below you can see the image being rendered after importing the new rust image library: 
<center>[[File:lenaRenderedCorrectly.png]]</center>

As you can see the image is being rendered as intended.
Note: This was previously broken due to a bug in our code. We had used the wrong enum type while decoding images that resulted in distorted images. This was fixed by the following [https://github.com/ankit3005/servo/commit/dfa0b92b21144c01223db78d8570aa5ac890922c commit].

5. Our test cases include reporting the timing differences for loading PNGs and non-PNG images. The following report has been made with respect to the same:
{| class="wikitable sortable mw-collapsible"
|-
!Image Source
!Resolution
!New library decode timing (in ms)
!Old library decode timing (in ms)
|-
|http://meesoft.logicnet.dk/Analyzer/help/Lenna.jpg
|256X256
|40.3814
|45.002006
|-
|http://peps.redprince.net/peps/tiger-Q300.png
|290X300
|78.0789
|29.636256
|-
|http://www.codeproject.com/KB/GDI-plus/ImageProcessing2/grayscale.jpg
|332X300
|106.7289
|64.298119
|-
|http://www.ampsoft.net/webdesign-l/img/JPEG-sample-landscape-standard.jpg
|300X200
|88.852
|42.395043
|-
|http://andreas.com/pixs/ping-sample.gif
|682X310
|106.9462
|124.54975
|-
|http://www.cs.cmu.edu/~chuck/lennapg/len_top.jpg
|400X225
|118.0558
|62.443986
|-
|http://www.roman10.net/wp-content/uploads/2011/08/sample_thumb.jpg
|484X316
|175.0287
|99.462362
|-
|http://www.kksou.com/php-gtk2/gif/sample6.png
|480X240
|223.9521
|44.864687
|-
|http://imagej.nih.gov/ij/images/lena.jpg
|512X512
|257.5638
|165.242363
|-
|http://people.sc.fsu.edu/~jburkardt/data/png/lena.png
|512X512
|397.7005
|88.834362
|-
|http://24.media.tumblr.com/tumblr_m97zes5x3k1rezf8ro1_500.jpg
|500X375
|312.1556
|129.003554
|-
|http://urlnextdoor.com/ai/design-layout/images/sample-png.png
|200X200
|152.053
|20.885724
|-
|https://cdn2.iconfinder.com/data/icons/free-3d-printer-icon-set/512/3d_objects.png
|512X512
|550.5805
|78.025999
|-
|http://www.samontab.com/web/wp-content/uploads/2012/06/lena3.png
|512X512
|811.8095
|97.916758
|-
|http://www.math.uga.edu/~mjlai/images/LenaRecovered.jpg
|1200X900
|909.2834
|662.842394
|-
|https://chadaphone.files.wordpress.com/2013/10/face_detection.png
|640X480
|942.4558
|113.816885
|-
|https://www.drupal.org/files/issues/sample_7.png
|800X600
|708.9273
|157.806566
|-
|http://optipng.sourceforge.net/pngtech/img/lena.png
|512X512
|924.4648
|95.02457
|-
|http://www.ultrasync.net/dee/warehouse_the_odd_stage/lena2_before_1024.png
|1024X1024
|1507.7304
|326.962991
|-
|http://menehune.opt.wfu.edu/CSC365_665/Proj1/Gif/lena.gif
|256X256
|2466.9467
|40.845023
|-
|http://www.openbsd.org/art/puffy/ppuf1000X907.gif
|1000x907
|56338.6327
|615.134272
|}

== Video ==
A walkthrough of our entire project is available on this link: [https://www.youtube.com/watch?v=rq8MvpR1JyI Final Project Walkthrough]

== References ==
<references/>

== See Also ==
[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa Initial Step Details]

File:LenaRenderedCorrectly.png

2014-12-04T22:42:27Z

Aagrawa5: uploaded a new version of "File:LenaRenderedCorrectly.png"

File:LenaRenderedCorrectly.png

2014-12-04T22:41:56Z

Aagrawa5: uploaded a new version of "File:LenaRenderedCorrectly.png"

File:LenaRenderedCorrectly.png

2014-12-04T22:41:31Z

Aagrawa5: uploaded a new version of "File:LenaRenderedCorrectly.png"

File:LenaRenderedCorrectly.png

2014-12-04T22:40:45Z

Aagrawa5:

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-12-04T22:40:30Z

Aagrawa5: /* Test Cases */

This wiki page contains design details for the project on [https://github.com/servo/servo/wiki/Replace-C-libraries-student-project Evaluate replacing C libraries with modern Rust equivalents] for the Mozilla research project [http://github.com/servo/servo/wiki/Design Servo].

== Background Information <ref>http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa</ref> ==

===Rust===
[http://www.rust-lang.org/ Rust] is a new programming language for developing reliable and efficient systems. It is designed to support concurrency and parallelism in building platforms that take full advantage of modern hardware. Its static type system is safe and expressive and it provides strong guarantees about isolation, concurrency execution and memory safety.
Rust combines powerful and flexible modern programming constructs with a clear performance model to make program efficiency predictable and manageable. One important way it achieves this is by allowing fine-grained control over memory allocation through contiguous records and stack allocation. This control is balanced with the absolute requirement of safety: Rust’s type system and runtime guarantee the absence of data races, buffer overflow, stack overflow or access to uninitialized or deallocated memory.

===Servo===
[http://en.wikipedia.org/wiki/Servo_%28layout_engine%29 Servo] is an experimental project to build a Web browser engine for a new generation of hardware: mobile devices, multi-core processors and high-performance GPUs.
Servo builds on top of Rust to provide a secure and reliable foundation. Rust’s lightweight task mechanism promises to allow fine-grained isolation between browser components, such as tabs and extensions, without the need for expensive runtime protection schemes, like operating system process isolation. Servo is not designed to create a full browser but is rather focused on creating a reliable and fast browser engine.

== Introduction ==
Servo currently depends on a lot of C libraries for image decoding. We wish to evaluate switching some of these to new Rust libraries. This project involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.

====Setup of Development Environment====
Servo is currently developed on 64bit OS X and 64bit Linux.

The steps needed to build on a Debian based 64 bit Linux machine are included below. The instructions for other platforms are available [https://github.com/servo/servo#prerequisites here].

* Install the prerequisite dependencies
<pre>
sudo apt-get install curl freeglut3-dev \
libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \
msttcorefonts gperf g++ cmake python-virtualenv \
libssl-dev libglfw-dev
</pre>

* Clone servo repository
<pre>
git clone https://www.github.com/servo/servo
cd servo
</pre>

Ensure that modified dependencies point to right sources
<pre>
./mach update-cargo -p freetype-rs
./mach update-cargo -p image
./mach update-cargo -p freetype-rs --precise 753496406098651c83cdaf63db9f75dc42da17c7
./mach update-cargo -p image --precise 3a398831adb22f1200cb68682e446ede187d23b9
</pre>

Build and run basic tests to ensure build success.
<pre>
./mach build
./mach run tests/html/about-mozilla.html
</pre>

== Architecture of system <ref>https://github.com/servo/servo/wiki/Design#task-supervision-diagram</ref> ==

=== Task Supervision Diagram ===

[[File:TaskSupervision.png]]

=== Task Communication Diagram ===

[[File:TaskCommunication.png]]

The above diagrams gives us an overview of the Servo's architecture.
*Each box represents a Rust task.
*Primary tasks are the ones which are represented by blue boxes.
*Gray boxes are for auxiliary tasks.
*White boxes are for worker tasks. Each such box represents several tasks, the precise number of which are decided by the workload.
*Supervisor relationships are shown by dashed lines.
*Communication channels are shown by solid lines.

The scope of our project is limited to changing the libraries used in the image decoding task shown above.

== Requirement analysis ==

Servo currently depends on a lot of C libraries, because Rust equivalents for these libraries did not exist when the project started. Our project is to evaluate switching some of these to new Rust libraries that have since been created. It involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.<ref>https://github.com/servo/servo/wiki/Replace-C-libraries-student-project</ref>

Initial step

Our [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step], implemented for the OSS project involved:
# Building Servo.
# Adding [http://doc.servo.org/util/time/fn.time.html timing code] to the image decoding implementation in the net crate.
# Rebuilding Servo.
# Reporting numbers for different kinds of images (i.e. PNG, JPEG, GIF).

Final Requirements

Our final project requirements are to:
* Build Servo and add code that reports (via the println! macro) the time required to decode images into displayable pixels.
* Add image decoding timing to the profiler.
* Import the [https://github.com/PistonDevelopers/freetype-rs freetype-rs] library to replace [https://github.com/servo/rust-freetype rust-freetype] in Servo, rewriting necessary code.<ref>https://github.com/servo/servo/issues/3369</ref> For this, we are to use [http://doc.crates.io/ Cargo], the dependency manager for Servo.
* Import the [https://github.com/PistonDevelopers/image rust-image] library to replace the [https://github.com/servo/rust-stb-image rust-stb-image] and [https://github.com/nothings/stb stb-image] libraries and rewrite the <code>load_from_memory</code> function which uses these libraries.<ref>https://github.com/servo/servo/issues/3368</ref>
* Report the timing differences for loading PNGs and non-PNGs on the same benchmarks. For this step, we are to consider profiling the result and optimizing the hotspots in rust-image.

== Implementation of the Final Requirements ==

1. Add Image Decoding time to the Profiler
To profile the time required by the load_from_memory to decode an image, we make a call to the profiler which outputs the time taken to decode on the console. To enable the profiler to do so, the following files were changed:
*image_cache_task.rs
*lib.rs
*time.rs
To invoke the profiler, we added a category under which to group the timings and passed a TimeProfilerChan (ie. a channel for communicating with the profiler task) to the ImageCacheTask::new method. On successfully building and running servo, we get the following image timings by profiler on the console:
<pre> ./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html </pre>
[[File:Profiler.png]]

2. Imported the freetype-rs library to replace rust-freetype in Servo.
We replaced the currently used rust-freetype library with the freetype-rs library. To enable proper functioning of servo after importing the new library, following files were modified in the repository [https://github.com/PistonDevelopers/freetype-rs PistonDevelopers/freetype-rs]:
*Cargo.toml
*src/ffi.rs
*src/lib.rs
*src/lib.rs
*src/library.rs
*src/tt_os2.rs
These changes were committed and have been pulled by PistonDevelopers. Check the changes on [https://github.com/PistonDevelopers/freetype-rs/pull/70 pull request] for more info.

3. Imported the rust-image library to replace the rust-stb-image and stb-image libraries and rewrite the load_from_memory function which uses these libraries.
In order to import the new library we modified the following files files in the repository [https://github.com/ankit3005/servo]:
*Cargo.toml
*components/net/lib.rs
*components/net/image_cache_task.rs
*components/net/image/base.rs
*components/net/image/holder.rs
*components/gfx/render_context.rs
*components/gfx/lib.rs
*components/gfx/Cargo.toml
*components/gfx/display_list/mod.rs
*components/layout/display_list_builder.rs
*components/layout/lib.rs

4. Reported the timing differences for loading PNGs and non-PNGs on the same benchmarks.
Once the new image library was imported , passed in several test images to record the decoding timing for different images.
The timing was compared with the decoding time for images by passing in the same images to the servo build containing the C image library. The results can be seen in the Test-Cases section below.

== Data and component design <ref>http://www.rust-ci.org/PistonDevelopers/piston/doc/image/index.html</ref>==

===Data Design===
The system entities that the project deals with is present in the image crate.

The structs and enums used to represent images are as below :

Structures
{| class = "wikitable"
|-
|ImageBuf
|An Image whose pixels are contained within a vector
|-
|Luma
|A type to hold a grayscale pixel
|-
|LumaA
|A type to hold a grayscale pixel with an alpha channel
|-
|MutPixels
|Mutable pixel iterator
|-
|Pixels
|Immutable pixel iterator
|-
|Rgb
|A type to hold an RGB pixel
|-
|Rgba
|A type to hold an RGB pixel with an alpha channel
|-
|SubImage
|A View into another image
|}

Enums
{| class="wikitable"
|-
|ColorType
|An enumeration over supported color types and their bit depths
|-
|DynamicImage
|A Dynamic Image
|-
|FilterType
|Available Sampling Filters
|-
|ImageError
|An enumeration of Image Errors
|-
|ImageFormat
|An enumeration of supported image formats. Not all formats support both encoding and decoding.
|}

===Component Design===

Rust image : It is an image processing library. This crate provides basic imaging processing functions and methods for converting to and from image formats.
All image processing functions provided operate on types that implement the GenericImage trait and return an ImageBuf. The details of other modules and traits included are :

Modules<ref>http://doc.rust-lang.org/guide.html#crates-and-modules</ref>
{| class="wikitable"
|-
|gif
|Decoding of GIF Images
|-
|imageops
|Image Processing Functions
|-
|jpeg
|Decoding and Encoding of JPEG Images
|-
|png
|Decoding and Encoding of PNG Images
|-
|ppm
|Encoding of portable pixmap Images
|-
|webp
|Decoding of Webp Images
|}

Traits<ref>http://rustbyexample.com/trait.html</ref>
{| class="wikitable"
|-
|GenericImage
|A trait for manipulating images.
|-
|ImageDecoder
|The trait that all decoders implement
|-
|MutableRefImage
|A trait for images that allow providing mutable references to pixels.
|-
|Pixel
|A trait that all pixels implement.
|}

Functions
{| class="wikitable"
|-
|load
|Create a new image from a Reader
|-
|load_from_memory
|Create a new image from a byte slice
|-
|open
|Open the image located at the path specified. The image's format is determined from the path's file extension
|}

== Design Principles ==

We are adhering to the following design principles for our implementation:

'''Open-Closed Principle'''<ref>http://en.wikipedia.org/wiki/Open/closed_principle</ref>

Although our task is to evaluate replacing C libraries with Rust libraries, we won't actually be modifying any existing functionality.

'''Interface Segregation Principle'''<ref>http://en.wikipedia.org/wiki/Interface_segregation_principle</ref>

The existing code is currently using the ''rust-freetype'' library for rendering fonts on the browser. We will be replacing this with the ''freetype-rs'' library, which divides the functionality offered by the former into smaller libraries which can be individually implemented instead of calling the entire library.

== Design Pattern==

We have implemented the Adapter Pattern in our Project:

When we updated the image library, the function load_from_memory() in base.rs had to be updated since the return from the updated function accepts a different set of parameters.
We implemented the Adapter pattern as a wrapper function over the new load_from_memory() function which performs the below functions:
1. Based on the file extension generate the ImageFormat Enum.
2. The return of the new function is a Result<DynamicImage>. This needs to be converted into a DynamicImage struct.
<pre>
pub fn load_from_memory(buffer: &[u8],ext: &str) -> Option<DynamicImage> {
if buffer.len() == 0 {
return None;
}
else {
//Retrieve the ImageFormat enum to be passed into the updated function
let image_type: Option< servo_image::ImageFormat > = get_format(ext);
if image_type == None
{
panic!("Image format not supported!");
}
else{
let new_image_type: servo_image::ImageFormat = image_type.unwrap();

//The updated function returns a Result<DynamicImage>
//below code resolves it to be returned by the wrapper function
let result = servo_image::load_from_memory(buffer,new_image_type);
if result.is_ok() {
let v = result.unwrap();
return Some(v);
}
else {
return None;
}
}
}
}

</pre>

==Flowchart describing Project Implementation==
[[File:Flowchart_final_M1455.JPG]]

== UML diagrams ==

===Class Diagram===
[[File:Class_diagram_M1455.JPG]]

== Test Cases ==

The project does not plan to add new functionality.
The test-cases we propose to run are will ensure that tasks that could be performed with the older C libraries can be executed.

The following test cases are proposed.

1. The initial step test case includes printing the decoding time for various image formates and has been included in the wiki: [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step]

2. The profiler is meant to capture the image decoding time take by the load_from_memory function. The profiler is run using the following command which gives the decoding time for the image passed as an argument:
<pre>./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html</pre>

3. After replacing the rust-freetype library by the freetype-rs library, we have tested that it works as expected by passing a webpage url and checking that the text renders correctly.
<pre>./mach run http://simple.wikipedia.org/wiki/Main_Page</pre>

4. After replacing the rust-stb-image and stb-image libraries with rust-image library and rewriting the load_from_memory function, we tested the the imports worked as expected by passing in different formats of images as urls and rendering them.
<pre> ./mach run https://www.http://optipng.sourceforge.net/pngtech/img/lena.png</pre>
Below you can see the image being rendered after importing the new rust image library: 
<center>[[File:lenaRenderedCorrectly.png]]</center>

As you can see the image is being rendered as intended.
Note: This was previously broken due to a bug in our code. We had used the wrong enum type while decoding images that resulted in distorted images. This was fixed by the following [commit https://github.com/ankit3005/servo/commit/dfa0b92b21144c01223db78d8570aa5ac890922c].

5. Our test cases include reporting the timing differences for loading PNGs and non-PNG images. The following report has been made with respect to the same:
{| class="wikitable sortable mw-collapsible"
|-
!Image Source
!Resolution
!New library decode timing (in ms)
!Old library decode timing (in ms)
|-
|http://meesoft.logicnet.dk/Analyzer/help/Lenna.jpg
|256X256
|40.3814
|45.002006
|-
|http://peps.redprince.net/peps/tiger-Q300.png
|290X300
|78.0789
|29.636256
|-
|http://www.codeproject.com/KB/GDI-plus/ImageProcessing2/grayscale.jpg
|332X300
|106.7289
|64.298119
|-
|http://www.ampsoft.net/webdesign-l/img/JPEG-sample-landscape-standard.jpg
|300X200
|88.852
|42.395043
|-
|http://andreas.com/pixs/ping-sample.gif
|682X310
|106.9462
|124.54975
|-
|http://www.cs.cmu.edu/~chuck/lennapg/len_top.jpg
|400X225
|118.0558
|62.443986
|-
|http://www.roman10.net/wp-content/uploads/2011/08/sample_thumb.jpg
|484X316
|175.0287
|99.462362
|-
|http://www.kksou.com/php-gtk2/gif/sample6.png
|480X240
|223.9521
|44.864687
|-
|http://imagej.nih.gov/ij/images/lena.jpg
|512X512
|257.5638
|165.242363
|-
|http://people.sc.fsu.edu/~jburkardt/data/png/lena.png
|512X512
|397.7005
|88.834362
|-
|http://24.media.tumblr.com/tumblr_m97zes5x3k1rezf8ro1_500.jpg
|500X375
|312.1556
|129.003554
|-
|http://urlnextdoor.com/ai/design-layout/images/sample-png.png
|200X200
|152.053
|20.885724
|-
|https://cdn2.iconfinder.com/data/icons/free-3d-printer-icon-set/512/3d_objects.png
|512X512
|550.5805
|78.025999
|-
|http://www.samontab.com/web/wp-content/uploads/2012/06/lena3.png
|512X512
|811.8095
|97.916758
|-
|http://www.math.uga.edu/~mjlai/images/LenaRecovered.jpg
|1200X900
|909.2834
|662.842394
|-
|https://chadaphone.files.wordpress.com/2013/10/face_detection.png
|640X480
|942.4558
|113.816885
|-
|https://www.drupal.org/files/issues/sample_7.png
|800X600
|708.9273
|157.806566
|-
|http://optipng.sourceforge.net/pngtech/img/lena.png
|512X512
|924.4648
|95.02457
|-
|http://www.ultrasync.net/dee/warehouse_the_odd_stage/lena2_before_1024.png
|1024X1024
|1507.7304
|326.962991
|-
|http://menehune.opt.wfu.edu/CSC365_665/Proj1/Gif/lena.gif
|256X256
|2466.9467
|40.845023
|-
|http://www.openbsd.org/art/puffy/ppuf1000X907.gif
|1000x907
|56338.6327
|615.134272
|}

== Video ==
A walkthrough of our entire project is available on this link: [https://www.youtube.com/watch?v=rq8MvpR1JyI Final Project Walkthrough]

== References ==
<references/>

== See Also ==
[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa Initial Step Details]

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-12-04T22:35:26Z

Aagrawa5: /* Test Cases */

This wiki page contains design details for the project on [https://github.com/servo/servo/wiki/Replace-C-libraries-student-project Evaluate replacing C libraries with modern Rust equivalents] for the Mozilla research project [http://github.com/servo/servo/wiki/Design Servo].

== Background Information <ref>http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa</ref> ==

===Rust===
[http://www.rust-lang.org/ Rust] is a new programming language for developing reliable and efficient systems. It is designed to support concurrency and parallelism in building platforms that take full advantage of modern hardware. Its static type system is safe and expressive and it provides strong guarantees about isolation, concurrency execution and memory safety.
Rust combines powerful and flexible modern programming constructs with a clear performance model to make program efficiency predictable and manageable. One important way it achieves this is by allowing fine-grained control over memory allocation through contiguous records and stack allocation. This control is balanced with the absolute requirement of safety: Rust’s type system and runtime guarantee the absence of data races, buffer overflow, stack overflow or access to uninitialized or deallocated memory.

===Servo===
[http://en.wikipedia.org/wiki/Servo_%28layout_engine%29 Servo] is an experimental project to build a Web browser engine for a new generation of hardware: mobile devices, multi-core processors and high-performance GPUs.
Servo builds on top of Rust to provide a secure and reliable foundation. Rust’s lightweight task mechanism promises to allow fine-grained isolation between browser components, such as tabs and extensions, without the need for expensive runtime protection schemes, like operating system process isolation. Servo is not designed to create a full browser but is rather focused on creating a reliable and fast browser engine.

== Introduction ==
Servo currently depends on a lot of C libraries for image decoding. We wish to evaluate switching some of these to new Rust libraries. This project involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.

====Setup of Development Environment====
Servo is currently developed on 64bit OS X and 64bit Linux.

The steps needed to build on a Debian based 64 bit Linux machine are included below. The instructions for other platforms are available [https://github.com/servo/servo#prerequisites here].

* Install the prerequisite dependencies
<pre>
sudo apt-get install curl freeglut3-dev \
libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \
msttcorefonts gperf g++ cmake python-virtualenv \
libssl-dev libglfw-dev
</pre>

* Clone servo repository
<pre>
git clone https://www.github.com/servo/servo
cd servo
</pre>

Ensure that modified dependencies point to right sources
<pre>
./mach update-cargo -p freetype-rs
./mach update-cargo -p image
./mach update-cargo -p freetype-rs --precise 753496406098651c83cdaf63db9f75dc42da17c7
./mach update-cargo -p image --precise 3a398831adb22f1200cb68682e446ede187d23b9
</pre>

Build and run basic tests to ensure build success.
<pre>
./mach build
./mach run tests/html/about-mozilla.html
</pre>

== Architecture of system <ref>https://github.com/servo/servo/wiki/Design#task-supervision-diagram</ref> ==

=== Task Supervision Diagram ===

[[File:TaskSupervision.png]]

=== Task Communication Diagram ===

[[File:TaskCommunication.png]]

The above diagrams gives us an overview of the Servo's architecture.
*Each box represents a Rust task.
*Primary tasks are the ones which are represented by blue boxes.
*Gray boxes are for auxiliary tasks.
*White boxes are for worker tasks. Each such box represents several tasks, the precise number of which are decided by the workload.
*Supervisor relationships are shown by dashed lines.
*Communication channels are shown by solid lines.

The scope of our project is limited to changing the libraries used in the image decoding task shown above.

== Requirement analysis ==

Servo currently depends on a lot of C libraries, because Rust equivalents for these libraries did not exist when the project started. Our project is to evaluate switching some of these to new Rust libraries that have since been created. It involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.<ref>https://github.com/servo/servo/wiki/Replace-C-libraries-student-project</ref>

Initial step

Our [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step], implemented for the OSS project involved:
# Building Servo.
# Adding [http://doc.servo.org/util/time/fn.time.html timing code] to the image decoding implementation in the net crate.
# Rebuilding Servo.
# Reporting numbers for different kinds of images (i.e. PNG, JPEG, GIF).

Final Requirements

Our final project requirements are to:
* Build Servo and add code that reports (via the println! macro) the time required to decode images into displayable pixels.
* Add image decoding timing to the profiler.
* Import the [https://github.com/PistonDevelopers/freetype-rs freetype-rs] library to replace [https://github.com/servo/rust-freetype rust-freetype] in Servo, rewriting necessary code.<ref>https://github.com/servo/servo/issues/3369</ref> For this, we are to use [http://doc.crates.io/ Cargo], the dependency manager for Servo.
* Import the [https://github.com/PistonDevelopers/image rust-image] library to replace the [https://github.com/servo/rust-stb-image rust-stb-image] and [https://github.com/nothings/stb stb-image] libraries and rewrite the <code>load_from_memory</code> function which uses these libraries.<ref>https://github.com/servo/servo/issues/3368</ref>
* Report the timing differences for loading PNGs and non-PNGs on the same benchmarks. For this step, we are to consider profiling the result and optimizing the hotspots in rust-image.

== Implementation of the Final Requirements ==

1. Add Image Decoding time to the Profiler
To profile the time required by the load_from_memory to decode an image, we make a call to the profiler which outputs the time taken to decode on the console. To enable the profiler to do so, the following files were changed:
*image_cache_task.rs
*lib.rs
*time.rs
To invoke the profiler, we added a category under which to group the timings and passed a TimeProfilerChan (ie. a channel for communicating with the profiler task) to the ImageCacheTask::new method. On successfully building and running servo, we get the following image timings by profiler on the console:
<pre> ./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html </pre>
[[File:Profiler.png]]

2. Imported the freetype-rs library to replace rust-freetype in Servo.
We replaced the currently used rust-freetype library with the freetype-rs library. To enable proper functioning of servo after importing the new library, following files were modified in the repository [https://github.com/PistonDevelopers/freetype-rs PistonDevelopers/freetype-rs]:
*Cargo.toml
*src/ffi.rs
*src/lib.rs
*src/lib.rs
*src/library.rs
*src/tt_os2.rs
These changes were committed and have been pulled by PistonDevelopers. Check the changes on [https://github.com/PistonDevelopers/freetype-rs/pull/70 pull request] for more info.

3. Imported the rust-image library to replace the rust-stb-image and stb-image libraries and rewrite the load_from_memory function which uses these libraries.
In order to import the new library we modified the following files files in the repository [https://github.com/ankit3005/servo]:
*Cargo.toml
*components/net/lib.rs
*components/net/image_cache_task.rs
*components/net/image/base.rs
*components/net/image/holder.rs
*components/gfx/render_context.rs
*components/gfx/lib.rs
*components/gfx/Cargo.toml
*components/gfx/display_list/mod.rs
*components/layout/display_list_builder.rs
*components/layout/lib.rs

4. Reported the timing differences for loading PNGs and non-PNGs on the same benchmarks.
Once the new image library was imported , passed in several test images to record the decoding timing for different images.
The timing was compared with the decoding time for images by passing in the same images to the servo build containing the C image library. The results can be seen in the Test-Cases section below.

== Data and component design <ref>http://www.rust-ci.org/PistonDevelopers/piston/doc/image/index.html</ref>==

===Data Design===
The system entities that the project deals with is present in the image crate.

The structs and enums used to represent images are as below :

Structures
{| class = "wikitable"
|-
|ImageBuf
|An Image whose pixels are contained within a vector
|-
|Luma
|A type to hold a grayscale pixel
|-
|LumaA
|A type to hold a grayscale pixel with an alpha channel
|-
|MutPixels
|Mutable pixel iterator
|-
|Pixels
|Immutable pixel iterator
|-
|Rgb
|A type to hold an RGB pixel
|-
|Rgba
|A type to hold an RGB pixel with an alpha channel
|-
|SubImage
|A View into another image
|}

Enums
{| class="wikitable"
|-
|ColorType
|An enumeration over supported color types and their bit depths
|-
|DynamicImage
|A Dynamic Image
|-
|FilterType
|Available Sampling Filters
|-
|ImageError
|An enumeration of Image Errors
|-
|ImageFormat
|An enumeration of supported image formats. Not all formats support both encoding and decoding.
|}

===Component Design===

Rust image : It is an image processing library. This crate provides basic imaging processing functions and methods for converting to and from image formats.
All image processing functions provided operate on types that implement the GenericImage trait and return an ImageBuf. The details of other modules and traits included are :

Modules<ref>http://doc.rust-lang.org/guide.html#crates-and-modules</ref>
{| class="wikitable"
|-
|gif
|Decoding of GIF Images
|-
|imageops
|Image Processing Functions
|-
|jpeg
|Decoding and Encoding of JPEG Images
|-
|png
|Decoding and Encoding of PNG Images
|-
|ppm
|Encoding of portable pixmap Images
|-
|webp
|Decoding of Webp Images
|}

Traits<ref>http://rustbyexample.com/trait.html</ref>
{| class="wikitable"
|-
|GenericImage
|A trait for manipulating images.
|-
|ImageDecoder
|The trait that all decoders implement
|-
|MutableRefImage
|A trait for images that allow providing mutable references to pixels.
|-
|Pixel
|A trait that all pixels implement.
|}

Functions
{| class="wikitable"
|-
|load
|Create a new image from a Reader
|-
|load_from_memory
|Create a new image from a byte slice
|-
|open
|Open the image located at the path specified. The image's format is determined from the path's file extension
|}

== Design Principles ==

We are adhering to the following design principles for our implementation:

'''Open-Closed Principle'''<ref>http://en.wikipedia.org/wiki/Open/closed_principle</ref>

Although our task is to evaluate replacing C libraries with Rust libraries, we won't actually be modifying any existing functionality.

'''Interface Segregation Principle'''<ref>http://en.wikipedia.org/wiki/Interface_segregation_principle</ref>

The existing code is currently using the ''rust-freetype'' library for rendering fonts on the browser. We will be replacing this with the ''freetype-rs'' library, which divides the functionality offered by the former into smaller libraries which can be individually implemented instead of calling the entire library.

== Design Pattern==

We have implemented the Adapter Pattern in our Project:

When we updated the image library, the function load_from_memory() in base.rs had to be updated since the return from the updated function accepts a different set of parameters.
We implemented the Adapter pattern as a wrapper function over the new load_from_memory() function which performs the below functions:
1. Based on the file extension generate the ImageFormat Enum.
2. The return of the new function is a Result<DynamicImage>. This needs to be converted into a DynamicImage struct.
<pre>
pub fn load_from_memory(buffer: &[u8],ext: &str) -> Option<DynamicImage> {
if buffer.len() == 0 {
return None;
}
else {
//Retrieve the ImageFormat enum to be passed into the updated function
let image_type: Option< servo_image::ImageFormat > = get_format(ext);
if image_type == None
{
panic!("Image format not supported!");
}
else{
let new_image_type: servo_image::ImageFormat = image_type.unwrap();

//The updated function returns a Result<DynamicImage>
//below code resolves it to be returned by the wrapper function
let result = servo_image::load_from_memory(buffer,new_image_type);
if result.is_ok() {
let v = result.unwrap();
return Some(v);
}
else {
return None;
}
}
}
}

</pre>

==Flowchart describing Project Implementation==
[[File:Flowchart_final_M1455.JPG]]

== UML diagrams ==

===Class Diagram===
[[File:Class_diagram_M1455.JPG]]

== Test Cases ==

The project does not plan to add new functionality.
The test-cases we propose to run are will ensure that tasks that could be performed with the older C libraries can be executed.

The following test cases are proposed.

1. The initial step test case includes printing the decoding time for various image formates and has been included in the wiki: [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step]

2. The profiler is meant to capture the image decoding time take by the load_from_memory function. The profiler is run using the following command which gives the decoding time for the image passed as an argument:
<pre>./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html</pre>

3. After replacing the rust-freetype library by the freetype-rs library, we have tested that it works as expected by passing a webpage url and checking that the text renders correctly.
<pre>./mach run http://simple.wikipedia.org/wiki/Main_Page</pre>

4. After replacing the rust-stb-image and stb-image libraries with rust-image library and rewriting the load_from_memory function, we tested the the imports worked as expected by passing in different formats of images as urls and rendering them.
<pre> ./mach run https://www.http://optipng.sourceforge.net/pngtech/img/lena.png</pre>
Below you can see the image being rendered after importing the new rust image library: 
<center>[[File:M1455newcrop.png]]</center>

As you can see the image is not being rendered as intended. It is suspected to be a bud in the rust image library developed by the PistonDevelopers. We have been asked by servo representatives to raise an issue with the developers of the rust image library.

5. Our test cases include reporting the timing differences for loading PNGs and non-PNG images. The following report has been made with respect to the same:
{| class="wikitable sortable mw-collapsible"
|-
!Image Source
!Resolution
!New library decode timing (in ms)
!Old library decode timing (in ms)
|-
|http://meesoft.logicnet.dk/Analyzer/help/Lenna.jpg
|256X256
|40.3814
|45.002006
|-
|http://peps.redprince.net/peps/tiger-Q300.png
|290X300
|78.0789
|29.636256
|-
|http://www.codeproject.com/KB/GDI-plus/ImageProcessing2/grayscale.jpg
|332X300
|106.7289
|64.298119
|-
|http://www.ampsoft.net/webdesign-l/img/JPEG-sample-landscape-standard.jpg
|300X200
|88.852
|42.395043
|-
|http://andreas.com/pixs/ping-sample.gif
|682X310
|106.9462
|124.54975
|-
|http://www.cs.cmu.edu/~chuck/lennapg/len_top.jpg
|400X225
|118.0558
|62.443986
|-
|http://www.roman10.net/wp-content/uploads/2011/08/sample_thumb.jpg
|484X316
|175.0287
|99.462362
|-
|http://www.kksou.com/php-gtk2/gif/sample6.png
|480X240
|223.9521
|44.864687
|-
|http://imagej.nih.gov/ij/images/lena.jpg
|512X512
|257.5638
|165.242363
|-
|http://people.sc.fsu.edu/~jburkardt/data/png/lena.png
|512X512
|397.7005
|88.834362
|-
|http://24.media.tumblr.com/tumblr_m97zes5x3k1rezf8ro1_500.jpg
|500X375
|312.1556
|129.003554
|-
|http://urlnextdoor.com/ai/design-layout/images/sample-png.png
|200X200
|152.053
|20.885724
|-
|https://cdn2.iconfinder.com/data/icons/free-3d-printer-icon-set/512/3d_objects.png
|512X512
|550.5805
|78.025999
|-
|http://www.samontab.com/web/wp-content/uploads/2012/06/lena3.png
|512X512
|811.8095
|97.916758
|-
|http://www.math.uga.edu/~mjlai/images/LenaRecovered.jpg
|1200X900
|909.2834
|662.842394
|-
|https://chadaphone.files.wordpress.com/2013/10/face_detection.png
|640X480
|942.4558
|113.816885
|-
|https://www.drupal.org/files/issues/sample_7.png
|800X600
|708.9273
|157.806566
|-
|http://optipng.sourceforge.net/pngtech/img/lena.png
|512X512
|924.4648
|95.02457
|-
|http://www.ultrasync.net/dee/warehouse_the_odd_stage/lena2_before_1024.png
|1024X1024
|1507.7304
|326.962991
|-
|http://menehune.opt.wfu.edu/CSC365_665/Proj1/Gif/lena.gif
|256X256
|2466.9467
|40.845023
|-
|http://www.openbsd.org/art/puffy/ppuf1000X907.gif
|1000x907
|56338.6327
|615.134272
|}

== Video ==
A walkthrough of our entire project is available on this link: [https://www.youtube.com/watch?v=rq8MvpR1JyI Final Project Walkthrough]

== References ==
<references/>

== See Also ==
[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa Initial Step Details]

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-12-04T16:45:56Z

Aagrawa5: /* Setup of Development Environment */

This wiki page contains design details for the project on [https://github.com/servo/servo/wiki/Replace-C-libraries-student-project Evaluate replacing C libraries with modern Rust equivalents] for the Mozilla research project [http://github.com/servo/servo/wiki/Design Servo].

== Background Information <ref>http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa</ref> ==

===Rust===
[http://www.rust-lang.org/ Rust] is a new programming language for developing reliable and efficient systems. It is designed to support concurrency and parallelism in building platforms that take full advantage of modern hardware. Its static type system is safe and expressive and it provides strong guarantees about isolation, concurrency execution and memory safety.
Rust combines powerful and flexible modern programming constructs with a clear performance model to make program efficiency predictable and manageable. One important way it achieves this is by allowing fine-grained control over memory allocation through contiguous records and stack allocation. This control is balanced with the absolute requirement of safety: Rust’s type system and runtime guarantee the absence of data races, buffer overflow, stack overflow or access to uninitialized or deallocated memory.

===Servo===
[http://en.wikipedia.org/wiki/Servo_%28layout_engine%29 Servo] is an experimental project to build a Web browser engine for a new generation of hardware: mobile devices, multi-core processors and high-performance GPUs.
Servo builds on top of Rust to provide a secure and reliable foundation. Rust’s lightweight task mechanism promises to allow fine-grained isolation between browser components, such as tabs and extensions, without the need for expensive runtime protection schemes, like operating system process isolation. Servo is not designed to create a full browser but is rather focused on creating a reliable and fast browser engine.

== Introduction ==
Servo currently depends on a lot of C libraries for image decoding. We wish to evaluate switching some of these to new Rust libraries. This project involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.

====Setup of Development Environment====
Servo is currently developed on 64bit OS X and 64bit Linux.

The steps needed to build on a Debian based 64 bit Linux machine are included below. The instructions for other platforms are available [https://github.com/servo/servo#prerequisites here].

* Install the prerequisite dependencies
<pre>
sudo apt-get install curl freeglut3-dev \
libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \
msttcorefonts gperf g++ cmake python-virtualenv \
libssl-dev libglfw-dev
</pre>

* Clone servo repository
<pre>
git clone https://www.github.com/servo/servo
cd servo
</pre>

Ensure that modified dependencies point to right sources
<pre>
./mach update-cargo -p freetype-rs
./mach update-cargo -p image
./mach update-cargo -p freetype-rs --precise 753496406098651c83cdaf63db9f75dc42da17c7
./mach update-cargo -p image --precise 3a398831adb22f1200cb68682e446ede187d23b9
</pre>

Build and run basic tests to ensure build success.
<pre>
./mach build
./mach run tests/html/about-mozilla.html
</pre>

== Architecture of system <ref>https://github.com/servo/servo/wiki/Design#task-supervision-diagram</ref> ==

=== Task Supervision Diagram ===

[[File:TaskSupervision.png]]

=== Task Communication Diagram ===

[[File:TaskCommunication.png]]

The above diagrams gives us an overview of the Servo's architecture.
*Each box represents a Rust task.
*Primary tasks are the ones which are represented by blue boxes.
*Gray boxes are for auxiliary tasks.
*White boxes are for worker tasks. Each such box represents several tasks, the precise number of which are decided by the workload.
*Supervisor relationships are shown by dashed lines.
*Communication channels are shown by solid lines.

The scope of our project is limited to changing the libraries used in the image decoding task shown above.

== Requirement analysis ==

Servo currently depends on a lot of C libraries, because Rust equivalents for these libraries did not exist when the project started. Our project is to evaluate switching some of these to new Rust libraries that have since been created. It involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.<ref>https://github.com/servo/servo/wiki/Replace-C-libraries-student-project</ref>

Initial step

Our [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step], implemented for the OSS project involved:
# Building Servo.
# Adding [http://doc.servo.org/util/time/fn.time.html timing code] to the image decoding implementation in the net crate.
# Rebuilding Servo.
# Reporting numbers for different kinds of images (i.e. PNG, JPEG, GIF).

Final Requirements

Our final project requirements are to:
* Build Servo and add code that reports (via the println! macro) the time required to decode images into displayable pixels.
* Add image decoding timing to the profiler.
* Import the [https://github.com/PistonDevelopers/freetype-rs freetype-rs] library to replace [https://github.com/servo/rust-freetype rust-freetype] in Servo, rewriting necessary code.<ref>https://github.com/servo/servo/issues/3369</ref> For this, we are to use [http://doc.crates.io/ Cargo], the dependency manager for Servo.
* Import the [https://github.com/PistonDevelopers/image rust-image] library to replace the [https://github.com/servo/rust-stb-image rust-stb-image] and [https://github.com/nothings/stb stb-image] libraries and rewrite the <code>load_from_memory</code> function which uses these libraries.<ref>https://github.com/servo/servo/issues/3368</ref>
* Report the timing differences for loading PNGs and non-PNGs on the same benchmarks. For this step, we are to consider profiling the result and optimizing the hotspots in rust-image.

== Implementation of the Final Requirements ==

1. Add Image Decoding time to the Profiler
To profile the time required by the load_from_memory to decode an image, we make a call to the profiler which outputs the time taken to decode on the console. To enable the profiler to do so, the following files were changed:
*image_cache_task.rs
*lib.rs
*time.rs
To invoke the profiler, we added a category under which to group the timings and passed a TimeProfilerChan (ie. a channel for communicating with the profiler task) to the ImageCacheTask::new method. On successfully building and running servo, we get the following image timings by profiler on the console:
<pre> ./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html </pre>
[[File:Profiler.png]]

2. Imported the freetype-rs library to replace rust-freetype in Servo.
We replaced the currently used rust-freetype library with the freetype-rs library. To enable proper functioning of servo after importing the new library, following files were modified in the repository [https://github.com/PistonDevelopers/freetype-rs PistonDevelopers/freetype-rs]:
*Cargo.toml
*src/ffi.rs
*src/lib.rs
*src/lib.rs
*src/library.rs
*src/tt_os2.rs
These changes were committed and have been pulled by PistonDevelopers. Check the changes on [https://github.com/PistonDevelopers/freetype-rs/pull/70 pull request] for more info.

3. Imported the rust-image library to replace the rust-stb-image and stb-image libraries and rewrite the load_from_memory function which uses these libraries.
In order to import the new library we modified the following files files in the repository [https://github.com/ankit3005/servo]:
*Cargo.toml
*components/net/lib.rs
*components/net/image_cache_task.rs
*components/net/image/base.rs
*components/net/image/holder.rs
*components/gfx/render_context.rs
*components/gfx/lib.rs
*components/gfx/Cargo.toml
*components/gfx/display_list/mod.rs
*components/layout/display_list_builder.rs
*components/layout/lib.rs

4. Reported the timing differences for loading PNGs and non-PNGs on the same benchmarks.
Once the new image library was imported , passed in several test images to record the decoding timing for different images.
The timing was compared with the decoding time for images by passing in the same images to the servo build containing the C image library. The results can be seen in the Test-Cases section below.

== Data and component design <ref>http://www.rust-ci.org/PistonDevelopers/piston/doc/image/index.html</ref>==

===Data Design===
The system entities that the project deals with is present in the image crate.

The structs and enums used to represent images are as below :

Structures
{| class = "wikitable"
|-
|ImageBuf
|An Image whose pixels are contained within a vector
|-
|Luma
|A type to hold a grayscale pixel
|-
|LumaA
|A type to hold a grayscale pixel with an alpha channel
|-
|MutPixels
|Mutable pixel iterator
|-
|Pixels
|Immutable pixel iterator
|-
|Rgb
|A type to hold an RGB pixel
|-
|Rgba
|A type to hold an RGB pixel with an alpha channel
|-
|SubImage
|A View into another image
|}

Enums
{| class="wikitable"
|-
|ColorType
|An enumeration over supported color types and their bit depths
|-
|DynamicImage
|A Dynamic Image
|-
|FilterType
|Available Sampling Filters
|-
|ImageError
|An enumeration of Image Errors
|-
|ImageFormat
|An enumeration of supported image formats. Not all formats support both encoding and decoding.
|}

===Component Design===

Rust image : It is an image processing library. This crate provides basic imaging processing functions and methods for converting to and from image formats.
All image processing functions provided operate on types that implement the GenericImage trait and return an ImageBuf. The details of other modules and traits included are :

Modules<ref>http://doc.rust-lang.org/guide.html#crates-and-modules</ref>
{| class="wikitable"
|-
|gif
|Decoding of GIF Images
|-
|imageops
|Image Processing Functions
|-
|jpeg
|Decoding and Encoding of JPEG Images
|-
|png
|Decoding and Encoding of PNG Images
|-
|ppm
|Encoding of portable pixmap Images
|-
|webp
|Decoding of Webp Images
|}

Traits<ref>http://rustbyexample.com/trait.html</ref>
{| class="wikitable"
|-
|GenericImage
|A trait for manipulating images.
|-
|ImageDecoder
|The trait that all decoders implement
|-
|MutableRefImage
|A trait for images that allow providing mutable references to pixels.
|-
|Pixel
|A trait that all pixels implement.
|}

Functions
{| class="wikitable"
|-
|load
|Create a new image from a Reader
|-
|load_from_memory
|Create a new image from a byte slice
|-
|open
|Open the image located at the path specified. The image's format is determined from the path's file extension
|}

== Design Principles ==

We are adhering to the following design principles for our implementation:

'''Open-Closed Principle'''<ref>http://en.wikipedia.org/wiki/Open/closed_principle</ref>

Although our task is to evaluate replacing C libraries with Rust libraries, we won't actually be modifying any existing functionality.

'''Interface Segregation Principle'''<ref>http://en.wikipedia.org/wiki/Interface_segregation_principle</ref>

The existing code is currently using the ''rust-freetype'' library for rendering fonts on the browser. We will be replacing this with the ''freetype-rs'' library, which divides the functionality offered by the former into smaller libraries which can be individually implemented instead of calling the entire library.

== Design Pattern==

We have implemented the Adapter Pattern in our Project:

When we updated the image library, the function load_from_memory() in base.rs had to be updated since the return from the updated function accepts a different set of parameters.
We implemented the Adapter pattern as a wrapper function over the new load_from_memory() function which performs the below functions:
1. Based on the file extension generate the ImageFormat Enum.
2. The return of the new function is a Result<DynamicImage>. This needs to be converted into a DynamicImage struct.
<pre>
pub fn load_from_memory(buffer: &[u8],ext: &str) -> Option<DynamicImage> {
if buffer.len() == 0 {
return None;
}
else {
//Retrieve the ImageFormat enum to be passed into the updated function
let image_type: Option< servo_image::ImageFormat > = get_format(ext);
if image_type == None
{
panic!("Image format not supported!");
}
else{
let new_image_type: servo_image::ImageFormat = image_type.unwrap();

//The updated function returns a Result<DynamicImage>
//below code resolves it to be returned by the wrapper function
let result = servo_image::load_from_memory(buffer,new_image_type);
if result.is_ok() {
let v = result.unwrap();
return Some(v);
}
else {
return None;
}
}
}
}

</pre>

==Flowchart describing Project Implementation==
[[File:Flowchart_final_M1455.JPG]]

== UML diagrams ==

===Class Diagram===
[[File:Class_diagram_M1455.JPG]]

== Test Cases ==

The project does not plan to add new functionality.
The test-cases we propose to run are will ensure that tasks that could be performed with the older C libraries can be executed.

The following test cases are proposed.

1. The initial step test case includes printing the decoding time for various image formates and has been included in the wiki: [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step]

2. The profiler is meant to capture the image decoding time take by the load_from_memory function. The profiler is run using the following command which gives the decoding time for the image passed as an argument:
<pre>./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html</pre>

3. After replacing the rust-freetype library by the freetype-rs library, we have tested that it works as expected by passing a webpage url and checking that the text renders correctly.
<pre>./mach run http://simple.wikipedia.org/wiki/Main_Page</pre>

4. After replacing the rust-stb-image and stb-image libraries with rust-image library and rewriting the load_from_memory function, we tested the the imports worked as expected by passing in different formats of images as urls and rendering them.
<pre> ./mach run https://www.http://optipng.sourceforge.net/pngtech/img/lena.png</pre>
Below you can see the image being rendered after importing the new rust image library: 
<center>[[File:M1455newcrop.png]]</center>

As you can see the image is not being rendered as intended. It is suspected to be a bud in the rust image library developed by the PistonDevelopers. We have been asked by servo representatives to raise an issue with the developers of the rust image library.

5. Our test cases include reporting the timing differences for loading PNGs and non-PNG images. The following report has been made with respect to the same:

<center>[[File:Report001.PNG]]</center>

== Video ==
A walkthrough of our entire project is available on this link: [https://www.youtube.com/watch?v=rq8MvpR1JyI Final Project Walkthrough]

== References ==
<references/>

== See Also ==
[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa Initial Step Details]

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-12-04T16:44:06Z

Aagrawa5: /* Setup of Development Environment */

This wiki page contains design details for the project on [https://github.com/servo/servo/wiki/Replace-C-libraries-student-project Evaluate replacing C libraries with modern Rust equivalents] for the Mozilla research project [http://github.com/servo/servo/wiki/Design Servo].

== Background Information <ref>http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa</ref> ==

===Rust===
[http://www.rust-lang.org/ Rust] is a new programming language for developing reliable and efficient systems. It is designed to support concurrency and parallelism in building platforms that take full advantage of modern hardware. Its static type system is safe and expressive and it provides strong guarantees about isolation, concurrency execution and memory safety.
Rust combines powerful and flexible modern programming constructs with a clear performance model to make program efficiency predictable and manageable. One important way it achieves this is by allowing fine-grained control over memory allocation through contiguous records and stack allocation. This control is balanced with the absolute requirement of safety: Rust’s type system and runtime guarantee the absence of data races, buffer overflow, stack overflow or access to uninitialized or deallocated memory.

===Servo===
[http://en.wikipedia.org/wiki/Servo_%28layout_engine%29 Servo] is an experimental project to build a Web browser engine for a new generation of hardware: mobile devices, multi-core processors and high-performance GPUs.
Servo builds on top of Rust to provide a secure and reliable foundation. Rust’s lightweight task mechanism promises to allow fine-grained isolation between browser components, such as tabs and extensions, without the need for expensive runtime protection schemes, like operating system process isolation. Servo is not designed to create a full browser but is rather focused on creating a reliable and fast browser engine.

== Introduction ==
Servo currently depends on a lot of C libraries for image decoding. We wish to evaluate switching some of these to new Rust libraries. This project involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.

====Setup of Development Environment====
Servo is currently developed on 64bit OS X and 64bit Linux.

The steps needed to build on a Debian based 64 bit Linux machine are included below. The instructions for other platforms are available [https://github.com/servo/servo#prerequisites here].

* Install the prerequisite dependencies
<pre>
sudo apt-get install curl freeglut3-dev \
libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \
msttcorefonts gperf g++ cmake python-virtualenv \
libssl-dev libglfw-dev
</pre>

* Clone servo repository
<pre>
git clone https://www.github.com/servo/servo
cd servo
</pre>

Ensure that modified dependencies point to right sources
<pre>
./mach update-cargo -p freetype-rs --precise 753496406098651c83cdaf63db9f75dc42da17c7
./mach update-cargo -p image --precise 3a398831adb22f1200cb68682e446ede187d23b9
</pre>

Build and run basic tests to ensure build success.
<pre>
./mach build
./mach run tests/html/about-mozilla.html
</pre>

== Architecture of system <ref>https://github.com/servo/servo/wiki/Design#task-supervision-diagram</ref> ==

=== Task Supervision Diagram ===

[[File:TaskSupervision.png]]

=== Task Communication Diagram ===

[[File:TaskCommunication.png]]

The above diagrams gives us an overview of the Servo's architecture.
*Each box represents a Rust task.
*Primary tasks are the ones which are represented by blue boxes.
*Gray boxes are for auxiliary tasks.
*White boxes are for worker tasks. Each such box represents several tasks, the precise number of which are decided by the workload.
*Supervisor relationships are shown by dashed lines.
*Communication channels are shown by solid lines.

The scope of our project is limited to changing the libraries used in the image decoding task shown above.

== Requirement analysis ==

Servo currently depends on a lot of C libraries, because Rust equivalents for these libraries did not exist when the project started. Our project is to evaluate switching some of these to new Rust libraries that have since been created. It involves rewriting the code that uses these libraries as well as taking measurements before and after to determine the costs involved.<ref>https://github.com/servo/servo/wiki/Replace-C-libraries-student-project</ref>

Initial step

Our [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step], implemented for the OSS project involved:
# Building Servo.
# Adding [http://doc.servo.org/util/time/fn.time.html timing code] to the image decoding implementation in the net crate.
# Rebuilding Servo.
# Reporting numbers for different kinds of images (i.e. PNG, JPEG, GIF).

Final Requirements

Our final project requirements are to:
* Build Servo and add code that reports (via the println! macro) the time required to decode images into displayable pixels.
* Add image decoding timing to the profiler.
* Import the [https://github.com/PistonDevelopers/freetype-rs freetype-rs] library to replace [https://github.com/servo/rust-freetype rust-freetype] in Servo, rewriting necessary code.<ref>https://github.com/servo/servo/issues/3369</ref> For this, we are to use [http://doc.crates.io/ Cargo], the dependency manager for Servo.
* Import the [https://github.com/PistonDevelopers/image rust-image] library to replace the [https://github.com/servo/rust-stb-image rust-stb-image] and [https://github.com/nothings/stb stb-image] libraries and rewrite the <code>load_from_memory</code> function which uses these libraries.<ref>https://github.com/servo/servo/issues/3368</ref>
* Report the timing differences for loading PNGs and non-PNGs on the same benchmarks. For this step, we are to consider profiling the result and optimizing the hotspots in rust-image.

== Implementation of the Final Requirements ==

1. Add Image Decoding time to the Profiler
To profile the time required by the load_from_memory to decode an image, we make a call to the profiler which outputs the time taken to decode on the console. To enable the profiler to do so, the following files were changed:
*image_cache_task.rs
*lib.rs
*time.rs
To invoke the profiler, we added a category under which to group the timings and passed a TimeProfilerChan (ie. a channel for communicating with the profiler task) to the ImageCacheTask::new method. On successfully building and running servo, we get the following image timings by profiler on the console:
<pre> ./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html </pre>
[[File:Profiler.png]]

2. Imported the freetype-rs library to replace rust-freetype in Servo.
We replaced the currently used rust-freetype library with the freetype-rs library. To enable proper functioning of servo after importing the new library, following files were modified in the repository [https://github.com/PistonDevelopers/freetype-rs PistonDevelopers/freetype-rs]:
*Cargo.toml
*src/ffi.rs
*src/lib.rs
*src/lib.rs
*src/library.rs
*src/tt_os2.rs
These changes were committed and have been pulled by PistonDevelopers. Check the changes on [https://github.com/PistonDevelopers/freetype-rs/pull/70 pull request] for more info.

3. Imported the rust-image library to replace the rust-stb-image and stb-image libraries and rewrite the load_from_memory function which uses these libraries.
In order to import the new library we modified the following files files in the repository [https://github.com/ankit3005/servo]:
*Cargo.toml
*components/net/lib.rs
*components/net/image_cache_task.rs
*components/net/image/base.rs
*components/net/image/holder.rs
*components/gfx/render_context.rs
*components/gfx/lib.rs
*components/gfx/Cargo.toml
*components/gfx/display_list/mod.rs
*components/layout/display_list_builder.rs
*components/layout/lib.rs

4. Reported the timing differences for loading PNGs and non-PNGs on the same benchmarks.
Once the new image library was imported , passed in several test images to record the decoding timing for different images.
The timing was compared with the decoding time for images by passing in the same images to the servo build containing the C image library. The results can be seen in the Test-Cases section below.

== Data and component design <ref>http://www.rust-ci.org/PistonDevelopers/piston/doc/image/index.html</ref>==

===Data Design===
The system entities that the project deals with is present in the image crate.

The structs and enums used to represent images are as below :

Structures
{| class = "wikitable"
|-
|ImageBuf
|An Image whose pixels are contained within a vector
|-
|Luma
|A type to hold a grayscale pixel
|-
|LumaA
|A type to hold a grayscale pixel with an alpha channel
|-
|MutPixels
|Mutable pixel iterator
|-
|Pixels
|Immutable pixel iterator
|-
|Rgb
|A type to hold an RGB pixel
|-
|Rgba
|A type to hold an RGB pixel with an alpha channel
|-
|SubImage
|A View into another image
|}

Enums
{| class="wikitable"
|-
|ColorType
|An enumeration over supported color types and their bit depths
|-
|DynamicImage
|A Dynamic Image
|-
|FilterType
|Available Sampling Filters
|-
|ImageError
|An enumeration of Image Errors
|-
|ImageFormat
|An enumeration of supported image formats. Not all formats support both encoding and decoding.
|}

===Component Design===

Rust image : It is an image processing library. This crate provides basic imaging processing functions and methods for converting to and from image formats.
All image processing functions provided operate on types that implement the GenericImage trait and return an ImageBuf. The details of other modules and traits included are :

Modules<ref>http://doc.rust-lang.org/guide.html#crates-and-modules</ref>
{| class="wikitable"
|-
|gif
|Decoding of GIF Images
|-
|imageops
|Image Processing Functions
|-
|jpeg
|Decoding and Encoding of JPEG Images
|-
|png
|Decoding and Encoding of PNG Images
|-
|ppm
|Encoding of portable pixmap Images
|-
|webp
|Decoding of Webp Images
|}

Traits<ref>http://rustbyexample.com/trait.html</ref>
{| class="wikitable"
|-
|GenericImage
|A trait for manipulating images.
|-
|ImageDecoder
|The trait that all decoders implement
|-
|MutableRefImage
|A trait for images that allow providing mutable references to pixels.
|-
|Pixel
|A trait that all pixels implement.
|}

Functions
{| class="wikitable"
|-
|load
|Create a new image from a Reader
|-
|load_from_memory
|Create a new image from a byte slice
|-
|open
|Open the image located at the path specified. The image's format is determined from the path's file extension
|}

== Design Principles ==

We are adhering to the following design principles for our implementation:

'''Open-Closed Principle'''<ref>http://en.wikipedia.org/wiki/Open/closed_principle</ref>

Although our task is to evaluate replacing C libraries with Rust libraries, we won't actually be modifying any existing functionality.

'''Interface Segregation Principle'''<ref>http://en.wikipedia.org/wiki/Interface_segregation_principle</ref>

The existing code is currently using the ''rust-freetype'' library for rendering fonts on the browser. We will be replacing this with the ''freetype-rs'' library, which divides the functionality offered by the former into smaller libraries which can be individually implemented instead of calling the entire library.

== Design Pattern==

We have implemented the Adapter Pattern in our Project:

When we updated the image library, the function load_from_memory() in base.rs had to be updated since the return from the updated function accepts a different set of parameters.
We implemented the Adapter pattern as a wrapper function over the new load_from_memory() function which performs the below functions:
1. Based on the file extension generate the ImageFormat Enum.
2. The return of the new function is a Result<DynamicImage>. This needs to be converted into a DynamicImage struct.
<pre>
pub fn load_from_memory(buffer: &[u8],ext: &str) -> Option<DynamicImage> {
if buffer.len() == 0 {
return None;
}
else {
//Retrieve the ImageFormat enum to be passed into the updated function
let image_type: Option< servo_image::ImageFormat > = get_format(ext);
if image_type == None
{
panic!("Image format not supported!");
}
else{
let new_image_type: servo_image::ImageFormat = image_type.unwrap();

//The updated function returns a Result<DynamicImage>
//below code resolves it to be returned by the wrapper function
let result = servo_image::load_from_memory(buffer,new_image_type);
if result.is_ok() {
let v = result.unwrap();
return Some(v);
}
else {
return None;
}
}
}
}

</pre>

==Flowchart describing Project Implementation==
[[File:Flowchart_final_M1455.JPG]]

== UML diagrams ==

===Class Diagram===
[[File:Class_diagram_M1455.JPG]]

== Test Cases ==

The project does not plan to add new functionality.
The test-cases we propose to run are will ensure that tasks that could be performed with the older C libraries can be executed.

The following test cases are proposed.

1. The initial step test case includes printing the decoding time for various image formates and has been included in the wiki: [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa initial step]

2. The profiler is meant to capture the image decoding time take by the load_from_memory function. The profiler is run using the following command which gives the decoding time for the image passed as an argument:
<pre>./mach run -p 1 https://optipng.sourceforge.net/pngtech/img/lena.html</pre>

3. After replacing the rust-freetype library by the freetype-rs library, we have tested that it works as expected by passing a webpage url and checking that the text renders correctly.
<pre>./mach run http://simple.wikipedia.org/wiki/Main_Page</pre>

4. After replacing the rust-stb-image and stb-image libraries with rust-image library and rewriting the load_from_memory function, we tested the the imports worked as expected by passing in different formats of images as urls and rendering them.
<pre> ./mach run https://www.http://optipng.sourceforge.net/pngtech/img/lena.png</pre>
Below you can see the image being rendered after importing the new rust image library: 
<center>[[File:M1455newcrop.png]]</center>

As you can see the image is not being rendered as intended. It is suspected to be a bud in the rust image library developed by the PistonDevelopers. We have been asked by servo representatives to raise an issue with the developers of the rust image library.

5. Our test cases include reporting the timing differences for loading PNGs and non-PNG images. The following report has been made with respect to the same:

<center>[[File:Report001.PNG]]</center>

== Video ==
A walkthrough of our entire project is available on this link: [https://www.youtube.com/watch?v=rq8MvpR1JyI Final Project Walkthrough]

== References ==
<references/>

== See Also ==
[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2014/oss_M1455_asa Initial Step Details]

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-13T19:12:47Z

Aagrawa5: /* Requirement analysis */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-13T19:11:28Z

Aagrawa5: /* Design Principles */

CSC/ECE 517 Fall 2014

2014-11-11T23:47:20Z

Aagrawa5:

*[[CSC/ECE_517_Fall_2014/sample_page]]
*[[CSC/ECE_517_Fall_2014/ch1a 22 as]]
*[[CSC/ECE 517 Fall 2014/ch1a 19 mx]]
*[[CSC/ECE 517 Fall 2014/ch1a 3 zq]]
*[[CSC/ECE 517 Fall 2014/ch1a 4 lf]]
*[[CSC/ECE 517 Fall 2014/ch1a 4 wl]]
*[[CSC/ECE 517 Fall 2014/ch1a a7 ch]]
*[[CSC/ECE 517 Fall 2014/ch1a 25 rs]]
*[[CSC/ECE 517 Fall 2014/ch1a 25 jf]]
*[[CSC/ECE 517 Fall 2014/ch1a 8 os]]
*[[CSC/ECE 517 Fall 2014/ch1a 8 sn]]
*[[CSC/ECE 517 Fall 2014/ch1a 15 gs]]
*[[CSC/ECE 517 Fall 2014/ch1a 10 hu]]
*[[CSC/ECE 517 Fall 2014/ch1a 20 kv]]
*[[CSC/ECE 517 Fall 2014/ch1a 21 as]]
*[[CSC/ECE 517 Fall 2014/ch1a 24 sa]]
*[[CSC/ECE 517 Fall 2014/ch1a 26 sn]]
*[[CSC/ECE 517 Fall 2014/ch1a 6 rl]]
*[[CSC/ECE 517 Fall 2014/ch1a 2 ss]]
*[[CSC/ECE 517 Fall 2014/ch1a 16 av]]
*[[CSC/ECE 517 Fall 2014/ch1a 1 rm]]
*[[CSC/ECE 517 Fall 2014/ch1a 1 sj]]
*[[CSC/ECE 517 Fall 2014/ch1a 23 ss]]
*[[CSC/ECE 517 Fall 2014/ch1a 20 rn]]
*[[CSC/ECE 517 Fall 2014/ch1a 22 sp]]
*[[CSC/ECE 517 Fall 2014/oss M1454 rss]]

*[[CSC/ECE 517 Fall 2014/ch1a 26 gn]]

*[[CSC/ECE 517 Fall 2014/ch1a 13 va]]
*[[CSC/ECE 517 Fall 2014/ch1a 9 aa]]
*[[CSC/ECE 517 Fall 2014/ch1a 9 kn]]
*[[CSC/ECE 517 Fall 2014/ch1a 11 ap]]
*[[CSC/ECE 517 Fall 2014/ch1a 25 ks]]
*[[CSC/ECE 517 Fall 2014/ch1a 7 kz]]
*[[CSC/ECE_517_Fall_2014/ch1a_6_bn]]
*[[CSC/ECE_517_Fall_2014/ch1a 10 zz]]
*[[CSC/ECE_517_Fall_2014/ch1a 16 va]]
*[[CSC/ECE_517_Fall_2014/ch1a F1415 rv]]
*[[CSC/ECE_517_Fall_2014/ch1a_3_cp]]
*[[CSC/ECE 517 Fall 2014/ch1b 26 sa]]
*[[CSC/ECE_517_Fall_2014/ch1b_28_cg]]
*[[CSC/ECE_517_Fall_2014/ch1b 29 ry]]
*[[CSC/ECE_517_Fall_2014/ch1b 30 cs]]
*[[CSC/ECE_517_Fall_2014/ch1b_33_jy]]
*[[CSC/ECE_517_Fall_2014/ch1b_27_js]]
*[[CSC/ECE 517 Fall 2014/oss E1453 syy]]
*[[CSC/ECE 517 Fall 2014/oss E1463 vpd]]
*[[CSC/ECE 517 Fall 2014/oss E1465 oak]]
*[[CSC/ECE 517 Fall 2014/oss_M1456_kdv]]
*[[CSC/ECE 517 Fall 2014/oss_M1453_sst]]
*[[CSC/ECE 517 Fall 2014/oss_E1456_akk]]
*[[CSC/ECE_517_Fall_2014/oss_M1455_asa]]
*[[CSC/ECE_517_Fall_2014/oss_E1458_sst]]
*[[CSC/ECE_517_Fall_2014/oss_E1457_ags]]
*[[CSC/ECE_517_Fall_2014/OSS_E1466_gjf]]
*[[CSC/ECE_517_Fall_2014/oss_M1452_jns]]
*[[CSC/ECE_517_Fall_2014/oss_E1462_nms]]
*[[CSC/ECE_517_Fall_2014/OSS_S1455_ajp]]
*[[CSC/ECE_517_Fall_2014/OSS_S1454_ccc]]
*[[CSC/ECE_517_Fall_2014/OSS_E1450_cxm]]
*[[CSC/ECE_517_Fall_2014/OSS_E1455_skn]]
*[[CSC/ECE_517_Fall_2014/OSS_M1450_vda]]
*[[CSC/ECE_517_Fall_2014/OSS_E1467_rsv]]
*[[CSC/ECE_517_Fall_2014/OSS_E1464_vnn]]
*[[CSC/ECE 517 Fall 2014/OSS_M1451_ahs]]
*[[CSC/ECE 517 Fall 2014/OSS_E1451_las]]
*[[CSC/ECE 517 Fall 2014/OSS_E1461_knn]]
*[[CSC/ECE_517_Fall_2014/oss_E1460_aua]]
*[[CSC/ECE_517_Fall_2014/oss_E1459_jjr]]
*[[CSC/ECE_517_Fall_2014/final_E1472_gjfz]]
*[[CSC/ECE_517_Fall_2014/final_design_doc_M1451_hsss]]
*[[CSC/ECE_517_Fall_2014/final_E1471_asuv]]
*[[CSC/ECE_517_Fall_2014/final_E1475_nrnn]]
*[[CSC/ECE_517_Fall_2014/final_design_doc_M1450_navr]]
*[[CSC/ECE_517_Fall_2014/final_M1455_yaaa]]

CSC/ECE 517 Fall 2014/final M1455 ayaa

2014-11-11T23:46:56Z

Aagrawa5: moved CSC/ECE 517 Fall 2014/final M1455 ayaa to CSC/ECE 517 Fall 2014/final M1455 yaaa

#REDIRECT [[CSC/ECE 517 Fall 2014/final M1455 yaaa]]

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:46:56Z

Aagrawa5: moved CSC/ECE 517 Fall 2014/final M1455 ayaa to CSC/ECE 517 Fall 2014/final M1455 yaaa

CSC/ECE 517 Fall 2014/final M1455 aya

2014-11-11T23:46:22Z

Aagrawa5: moved CSC/ECE 517 Fall 2014/final M1455 aya to CSC/ECE 517 Fall 2014/final M1455 ayaa

#REDIRECT [[CSC/ECE 517 Fall 2014/final M1455 ayaa]]

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:46:22Z

Aagrawa5: moved CSC/ECE 517 Fall 2014/final M1455 aya to CSC/ECE 517 Fall 2014/final M1455 ayaa

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:39:27Z

Aagrawa5: /* UML diagrams */

File:Class diagram M1455.JPG

2014-11-11T23:37:59Z

Aagrawa5: Class diagram for M1455

Class diagram for M1455

CSC/ECE 517 Fall 2014

2014-11-11T23:36:27Z

Aagrawa5:

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:35:08Z

Aagrawa5: /* Requirement analysis */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:34:51Z

Aagrawa5: /* Requirement analysis */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:24:19Z

Aagrawa5: /* Proposed Test Cases */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:19:46Z

Aagrawa5: /* Proposed Test Cases */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:12:39Z

Aagrawa5: /* UML diagrams */

File:Flowchart final M1455.JPG

2014-11-11T23:11:55Z

Aagrawa5:

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:10:03Z

Aagrawa5: /* Requirement analysis */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:09:21Z

Aagrawa5: /* Data Design */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T23:00:06Z

Aagrawa5: /* Class Diagram */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T22:59:52Z

Aagrawa5: /* UML diagrams */

File:Flowchart final M1455.png

2014-11-11T22:59:18Z

Aagrawa5: Flowchart describing steps required in M1465 semester project

Flowchart describing steps required in M1465 semester project

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T22:33:38Z

Aagrawa5: /* Component Design */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T22:30:23Z

Aagrawa5: /* Data Design */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T22:30:04Z

Aagrawa5: /* Data and component design */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T22:29:37Z

Aagrawa5: /* Data and component design */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T22:28:09Z

Aagrawa5: /* Data and component design */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T22:22:40Z

Aagrawa5: /* Requirement analysishttps://github.com/servo/servo/wiki/Replace-C-libraries-student-project */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T22:19:42Z

Aagrawa5: /* Proposed Test Cases */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T21:55:09Z

Aagrawa5: /* Architecture of system https://github.com/servo/servo/wiki/Design#task-supervision-diagram */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T21:51:41Z

Aagrawa5: /* Development Environment */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T21:51:20Z

Aagrawa5: /* Architecture of system https://github.com/servo/servo/wiki/Design#task-supervision-diagram */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T21:39:55Z

Aagrawa5: /* Preface */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T21:39:19Z

Aagrawa5:

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T21:37:33Z

Aagrawa5: /* Requirement analysishttps://github.com/servo/servo/wiki/Replace-C-libraries-student-project */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T21:36:32Z

Aagrawa5: /* Development Environment */

CSC/ECE 517 Fall 2014/final M1455 yaaa

2014-11-11T21:35:59Z

Aagrawa5: Created page with "This wiki page contains design details for the project on [https://github.com/servo/servo/wiki/Replace-C-libraries-student-project Evaluate replacing C libraries with modern Rust..."

CSC/ECE 517 Fall 2014/oss E1460 aua

2014-10-30T00:29:55Z

Aagrawa5: /* Elimination of Boolean Zen */

==Expertiza - Refactoring StudentQuizController==
Expertiza is a web application developed using Ruby on Rails that serves as a peer-review system. The application allows students to submit and peer-review learning objects (articles, code, web sites, etc)<ref>[https://github.com/expertiza/expertiza Expertiza on GitHub]</ref><ref>[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki Page]</ref>. It is an open source project and it's codebase is maintained in GitHub. We are contributing to Expertiza as a part of our Object-Oriented Design and Development's Open-Source Software (OSS) Project. Our goal in this project is to refactor the StudentQuiz controller. In this Wiki Page, we would be explaining the changes that we have made for the same.
__TOC__

==Project Description==
The StudentQuiz controller consists of methods involved in creating, scoring & recording responses of the quizzes taken by reviewers or students of the other teams with the same topic.
 The changes that are needed to be done are described as follows:<ref>[https://docs.google.com/a/ncsu.edu/document/d/1FZCL9KWSdVNsX9BowuZ3gxbCOJoiWX-GVLctSZei3No/edit# GoogleDoc for our project requirements]</ref>
<ol>
<li>Pluralize the class. (StudentQuizzesController)</li>
<li>Rename methods to conform to RESTful style. (e.g. :- Rename the list method to index.)</li>
<li>Reduce the number of instance variables per controller action.</li>
<li>Review Method graded? for boolean zen.</li>
<li>Perform Code cleanup by removing unused code.</li>
<li>Use good Ruby style guidelines in the code.</li>
<li>Split a method performing multiple tasks, into seperate methods.</li>
<li>Fix logical errors in the code.</li>
</ol>

==Modifications made to the Existing Code==

===Pluralized the class name StudentQuizController===
----
As per the Rails convention the controller class names are suggested to be plural.
This helps in generating RESTful routing URI helpers. Also, naming the classes as plural seems intuitive.<ref>[http://stackoverflow.com/questions/646951/singular-or-plural-controller-and-helper-names-in-rails Using the Singular or Plural controller and helper names in Rails]</ref>.
We used the refactor functionality in RubyMine to rename the StudentQuiz controller class to StudentQuizzes.

The following files were modified and/or renamed.
<pre>
app/controllers/review_mapping_controller.rb
app/controllers/{student_quiz_controller.rb → student_quizzes_controller.rb}
app/helpers/student_quiz_helper.rb
app/helpers/student_quizzes_helper.rb
app/views/questionnaires/view.html.erb
app/views/{student_quiz → student_quizzes}/_quiz_form.html.erb
app/views/{student_quiz → student_quizzes}/_responses.html.erb
app/views/{student_quiz → student_quizzes}/_set_dynamic_quiz.html.erb
app/views/{student_quiz → student_quizzes}/_set_self_quiz.html.erb
app/views/{student_quiz → student_quizzes}/finished_quiz.html.erb
app/views/{student_quiz → student_quizzes}/grade_essays.html.erb
app/views/{student_quiz → student_quizzes}/list.html.erb
app/views/{student_quiz → student_quizzes}/take_quiz.html.erb
app/views/student_task/view.html.erb
app/views/tree_display/actions/_assignments_actions.html.erb
test/functional/{student_quiz_controller_test.rb → student_quizzes_controller_test.rb}
test/test_helper.rb
test/unit/helpers/student_quiz_helper_test.rb
test/unit/helpers/student_quizzes_helper_test.rb
</pre>

The detailed change-set for this refactor can be seen [https://github.com/ankit3005/expertiza/commit/20981333a14a3f468f76cd6d414b3088975b71bd here].

===RESTful style implementation===
----
The purpose of the list method in the StudentQuizzes controller is to list all the quizzes that are available to a particular user for a particular assignment. RESTful guidelines state that a method that returns a list of all available objects, in this case the quizzes, should be named as index. Therefore, we renamed the list method to the index method in the controller and in all the files that had references to the list method of the student_quizzes_controller (For e.g. :- The view finished_quiz.html.erb of the Student Quiz controller, the review_mapping controller.rb etc.).

Before Refactoring :
 Method : list
<pre>
def list
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@assignment = Assignment.find(@participant.parent_id)

# Find the current phase that the assignment is in.
@quiz_phase = @assignment.get_current_stage(AssignmentParticipant.find(params[:id]).topic_id)

@quiz_mappings = QuizResponseMap.where(reviewer_id: @participant.id)

# Calculate the number of quizzes that the user has completed so far.
@num_quizzes_total = @quiz_mappings.size

@num_quizzes_completed = 0
@quiz_mappings.each do |map|
@num_quizzes_completed += 1 if map.response
end

if @assignment.staggered_deadline?
@quiz_mappings.each { |quiz_mapping|
if @assignment.team_assignment?
participant = AssignmentTeam.get_first_member(quiz_mapping.reviewee_id)
else
participant = quiz_mapping.reviewee
end

if !participant.nil? and !participant.topic_id.nil?
quiz_due_date = TopicDeadline.where(topic_id: participant.topic_id, deadline_type_id: 1).first
end
}
deadline_type_id = DeadlineType.find_by_name('quiz').id
end
end
}
</pre>

After Refactoring :
 Method : index
<pre>
def index
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)
@assignment = Assignment.find(participant.parent_id)
@quiz_mappings = QuizResponseMap.get_mappings_for_reviewer(participant.id)
end
</pre>

===Instance Variable Reductions===
----
In Rails, the data is shared between the controllers and views through the instance variables. The instance variabIes that are set during the execution a particular controller method are accessible to the view. Excessive usage of this standard method of data sharing between the controller and the view results in increased coupling between them <ref>[http://blog.remarkablelabs.com/2013/01/how-to-decrease-coupling-in-your-controllers-views-with-decent_exposure-for-better-maintainability Decreasing Controller-View Coupling in Rails]</ref>. Increased coupling results in several problems, including less maintainability of code, difficulty in code reuse etc. <ref>[http://en.wikipedia.org/wiki/Coupling_(computer_programming)#Disadvantages Disadvantages of Tight Coupling - Wikipedia]</ref> Thus, we need to reduce coupling as much as possible and in this case it can be achieved by reducing as many instance variables as possible in the controller. Therefore, we have refactored our code in order to eliminate unnecessary instance variables and to convert all the instance variables to local variables that are not used in the views.

In the take_quiz method, the following instance variables were removed:
 
* Changed the quizzes instance variable to a local variable.
* Eliminated the instance variable assignment which was not being used anywhere.
* Eliminated the local variable teams which was not being used any where

Before Refactoring
<pre>
def self.take_quiz assignment_id , reviewer_id
@quizzes = Array.new
reviewer = Participant.where(user_id: reviewer_id, parent_id: assignment_id).first
@assignment = Assignment.find(assignment_id)
teams = TeamsUser.where(user_id: reviewer_id)
Team.where(parent_id: assignment_id).each do |quiz_creator|
unless TeamsUser.find_by_team_id(quiz_creator.id).user_id == reviewer_id
Questionnaire.where(instructor_id: quiz_creator.id).each do |questionnaire|
if !@assignment.team_assignment?
unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer.id).first
@quizzes.push(questionnaire)
end
else unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer_id).first
@quizzes.push(questionnaire)
end
end
end
end
end
return @quizzes
end
</pre>

After Refactoring
<pre>
def self.take_quiz assignment_id , reviewer_id
quizzes = Array.new
reviewer = Participant.where(user_id: reviewer_id, parent_id: assignment_id).first
Team.where(parent_id: assignment_id).each do |quiz_creator|
unless TeamsUser.find_by_team_id(quiz_creator.id).user_id == reviewer_id
Questionnaire.where(instructor_id: quiz_creator.id).each do |questionnaire|
unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer.id).first
quizzes.push(questionnaire)
end
end
end
end
return quizzes
end
</pre>

===Follow principle of Boolean Zen===
----
In cases where a method only returns a boolean value by evaluating an expression (using the if..else construct), the if..else statement is redundant and can be eliminated. We have a method graded? that does this thing. Thus, we eliminated the if..else construct in the graded? method as it was redundant.<ref>[https://www.cs.utexas.edu/~scottm/cs312/handouts/slides/topic16_boolean_logic.pdf About Boolean Zen]</ref>

 Before Refactoring 
 
Method : graded?
<pre>
def graded?(response, question)
if Score.where(question_id: question.id, response_id: response.id).first
return true
else
return false
end
end
</pre>

 After Refactoring 
 Method : graded?
<pre>
def graded?(response, question)
return (Score.where(question_id: question.id, response_id: response.id).first)
end
</pre>

===Code Cleanup===
----
At some places, we found certain statements and variable assignments that were not being used later on in the method or code. We have eliminated such unused statements, so that methods contain only code that is being used later on. This would improve the readability and the maintainability of the code. For example in the code below we eliminated the @quiz_phase and the @num_quizzes_total variables because they were not being used anywhere in the code. Also, since the local variables quiz_due_date, deadline_type_id, participant were not being used anywhere, we could eliminate the entire if block from the code below. We then converted the instance variable participant to a local variable because it was not being used in the corresponding view.
 
 
Before Refactoring
 
Method : list
 
<pre>
def list
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@assignment = Assignment.find(@participant.parent_id)

# Find the current phase that the assignment is in.
@quiz_phase = @assignment.get_current_stage(AssignmentParticipant.find(params[:id]).topic_id)

@quiz_mappings = QuizResponseMap.where(reviewer_id: @participant.id)

# Calculate the number of quizzes that the user has completed so far.
@num_quizzes_total = @quiz_mappings.size

@num_quizzes_completed = 0
@quiz_mappings.each do |map|
@num_quizzes_completed += 1 if map.response
end

if @assignment.staggered_deadline?
@quiz_mappings.each { |quiz_mapping|
if @assignment.team_assignment?
participant = AssignmentTeam.get_first_member(quiz_mapping.reviewee_id)
else
participant = quiz_mapping.reviewee
end

if !participant.nil? and !participant.topic_id.nil?
quiz_due_date = TopicDeadline.where(topic_id: participant.topic_id, deadline_type_id: 1).first
end
}
deadline_type_id = DeadlineType.find_by_name('quiz').id
end
end
}
</pre>

After Refactoring
 Method : index
<pre>
def index
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)
@assignment = Assignment.find(participant.parent_id)
@quiz_mappings = QuizResponseMap.get_mappings_for_reviewer(participant.id)
end
</pre>

===Following Ruby Style Guidelines (Global Rules)===
----
At many places in the code we found that the Ruby Style Guidelines were not followed. We have refactored the code so that it uses the good code style guidelines. The following are some of the refactorings the we have done:-
 
==== Used .eql? instead of "==" ====
----
Before Refactoring
 Method : finished_quiz

<pre> if score.score == -1 </pre>

After Refactoring

<pre> if score.score.eql? -1 </pre>

==== Eliminated the "== true/false" check ====
----
Before Refactoring
 Method : finished_quiz

<pre> if essay_not_graded == true </pre>

After Refactoring

<pre> if essay_not_graded </pre>

==== Use `&&` and `||` rather than `and` and `or` to keep boolean precedence ====
----
Before Refactoring
 Method: record_response
<pre> elsif correct_answer and params["#{question.id}"] == correct_answer.txt </pre>

After Refactoring
 Method: calculate_score
<pre> elsif correct_answer && params["#{question.id}"]== correct_answer.txt </pre>

==== Use key: ‘value’, not :key => ‘value’ ====
----
Before Refactoring
 Method: record_response
<pre>new_score = Score.new :comments => choice, :question_id => question.id, :response_id => @response.id</pre>

After Refactoring
 Method: calculate_score
<pre>new_score = Score.new comments: choice, question_id: question.id, response_id: response.id</pre>

==== Replace find_by_... with a where command ====
----
 Before Refactoring 
 Method: record_response
<pre> if (QuestionType.find_by_question_id question.id).q_type == 'MCC' </pre>

 After Refactoring 
 Method: calculate_score
<pre>ques_type = (QuestionType.where( question_id: question.id)).q_type
if ques_type.eql? 'MCC'
</pre>

====Used .nil? instead of "== nil" ====
----
Before Refactoring
 Method: record_response
<pre>
if params["#{question.id}"] == nil
</pre>

After Refactoring
 Method: calculate_score
<pre>
if params["#{question.id}"].nil?
</pre>

==== Used a Boolean variable when that is sufficient====
----
Before Refactoring
 Method: record_response
<pre>
valid = 1
if valid == 0
</pre>

After Refactoring
 Method: calculate_score
<pre>
valid = false
if valid
</pre>

====Use good conditional statements====
----
Using unless is a good practice. But it is not a good practice to use unless and ! within the condition. Instead we could use an if condition itself.

Before Refactoring
 Method: record_response
<pre>
unless new_score.comments != "" && new_score.comments
valid = false
</pre>

After Refactoring
 Method: calculate_score
<pre>
if new_score.comments.empty? || new_score.comments.nil?
valid = false
</pre>

====Use of Routing Helpers====
----
Routing helpers are a simpler alternative to the otherwise complex hard coded URLs which reduce the readability of the code. Routing helpers allow us to declare possible common routes for a given controller. Routing helpers have been implemented since they maintain consistency even if changes are made to the routing paths.

Before Refactoring:
 config.rb does not contain a student_quizzes resource
 review_mapping_controller.rb
<pre>
redirect_to :controller => 'student_quizzes', :action => 'index', :id => params[:participant_id]
</pre>

After Refactoring
 config.rb
<pre>
resources :student_quizzes, :only => [:index]
</pre>
review_mapping_controller.rb
<pre>
redirect_to student_quizzes_path(:id => params[:participant_id])
</pre>

===Replace controller method with a model method ===
----
Rails 4 conventions dictate the use of a fat model and skinny controller.
It is better to place the search function in the model rather than placing it in the controller.
The search code belonged to the quiz_response_map model, since it queries that particular table in the database.
The code was extracted into the get_mappings_for_reviewer method and placed in the file quiz_response_map.rb. This method was then called from the StudentQuizzes controller.
<ref name = "stackoverflow">[http://stackoverflow.com/questions/14044681/fat-models-and-skinny-controllers-sounds-like-creating-god-models Fat Models and Skinny Controllers.]</ref>

Before Refactoring
 student_quizzes_controller.rb
 Method : index
<pre>
@quiz_mappings = QuizResponseMap.where(reviewer_id: participant.id)
</pre>

After Refactoring
 student_quizzes_controller.rb
 Method : index
<pre>
@quiz_mappings = QuizResponseMap.get_mappings_for_reviewer(participant.id)
</pre>
 quiz_response_map.rb
<pre>
def self.get_mappings_for_reviewer(participant_id)
return QuizResponseMap.where(reviewer_id: participant_id)
end
</pre>

===Changes made in method logic===
----
We have made certain changes in the logic of the methods calculate_score and record_response (previously the code of both these methods was only in record_response) primarily to improve the existing logic and eliminate redundant code. These changes are described as follows:

* The score variable was already being set to 0 on the loop entry, therefore it was redundant to reset score to zero again. Thus, we eliminated this line of code inside the if statement.
Before Refactoring
<pre>
questions.each do |question|
score = 0
if (QuestionType.find_by_question_id question.id).q_type == 'MCC'
score = 0
</pre>

After Refactoring
<pre>
questions.each do |question|
score = 0
if ques_type.eql? 'MCC'
# Eliminated score = 0 over here
</pre>

----
* The variable correct_answer stored multiple values as the where condition to which it was assigned was returning multiple values. Therefore it seemed more intuitive to rename correct_answer to correct_answers so that it is apparent that it contains multiple values.

Before Refactoring
<pre>
correct_answer = QuizQuestionChoice.where(question_id: question.id, iscorrect: 1)
</pre>

After Refactoring
<pre>
correct_answers = QuizQuestionChoice.where(question_id: question.id, iscorrect: true)
</pre>

----
* The below piece of code found out the question type twice in the same loop. Therefore we extracted it and assigned it to a local variable so that the query is executed only once.
Before Refactoring
<pre>
# First Query
if (QuestionType.find_by_question_id question.id).q_type == 'MCC'
# Repetition of the query in the same loop
if (QuestionType.find_by_question_id question.id).q_type == 'Essay'
</pre>

After Refactoring
<pre>
# Querying only once and assigning it to a local variable ques_type
ques_type = (QuestionType.where( question_id: question.id)).q_type
# Usage 1 of ques_type
if ques_type.eql? 'MCC'
# Usage 2 of ques_type
if ques_type.eql? 'Essay'
</pre>

----
* The new_scores and scores array stored almost the similar values. The scores array contained a copy of the value that the new_scores array contained. Therefore we eliminated the new_scores array and are performing all the operations only on the scores array.
Before Refactoring
<pre>
# Part 1
new_score = Score.new :comments => choice, :question_id => question.id, :response_id => @response.id

unless new_score.valid?
valid = 1
end
new_scores.push(new_score)

# Part 2
new_scores.each do |score_update|
score_update.score = score
scores.push(score_update)
end
</pre>
After Refactoring
<pre>
# Part 1
new_score = Score.new comments: choice, question_id: question.id, response_id: response.id

unless new_score.valid?
valid = false
end
scores.push(new_score)

# Part 2
scores.each do |score_update|
score_update.score = score
end
</pre>

----
* The logic to compute the final score for a multiple-choice, multiple-correct type of question seemed to be incorrect and therefore we fixed it.
Before Refactoring
<pre>
# Part 1 of the Scoring Logic
questions.each do |question|
score = 0
if (QuestionType.find_by_question_id question.id).q_type == 'MCC'
score = 0
if params["#{question.id}"] == nil
valid = 1
else
correct_answer = QuizQuestionChoice.where(question_id: question.id, iscorrect: 1)
params["#{question.id}"].each do |choice|
correct_answer.each do |correct|
if choice == correct.txt
score += 1
end

# Part 2 of the scoring logic which seems to award full points even if you marked some extra options apart from marking all correct answers
unless score == correct_answer.count
score = 0
else
score = 1
end
</pre>
After Refactoring
<pre>
# Part 1 of the Scoring Logic
questions.each do |question|
score = 0
correct_answers = QuizQuestionChoice.where(question_id: question.id, iscorrect: true)
ques_type = (QuestionType.where( question_id: question.id)).q_type
if ques_type.eql? 'MCC'
if params["#{question.id}"].nil?
valid = false
else
params["#{question.id}"].each do |choice|
correct_answers.each do |correct|
if choice.eql? correct.txt
score += 1
end

# Part 2 of the scoring logic - We have also compared the number of options the user selected to the total number of correct answers
if score.eql? correct_answers.count && score == params["#{question.id}"].count
score = 1
else
score = 0
end
</pre>

----
* The record_response function was performing two distinct operations : One operation was saving the response to the database and the other was to calculate the score for the questions. We created a new function calculate_score that would calculate the score for the questions and record_response now only performs the task of saving responses to the database.
Before Refactoring
<pre>
def record_response
@map = ResponseMap.find(params[:map_id])
@response = Response.new()
@response.map_id = params[:map_id]
@response.created_at = DateTime.current
@response.updated_at = DateTime.current
@response.save

@questionnaire = Questionnaire.find(@map.reviewed_object_id)
scores = Array.new
new_scores = Array.new
valid = 0
questions = Question.where(questionnaire_id: @questionnaire.id)
questions.each do |question|
score = 0
if (QuestionType.find_by_question_id question.id).q_type == 'MCC'
score = 0
if params["#{question.id}"] == nil
valid = 1
else
correct_answer = QuizQuestionChoice.where(question_id: question.id, iscorrect: 1)
params["#{question.id}"].each do |choice|

correct_answer.each do |correct|
if choice == correct.txt
score += 1
end

end
new_score = Score.new :comments => choice, :question_id => question.id, :response_id => @response.id

unless new_score.valid?
valid = 1
end
new_scores.push(new_score)

end
unless score == correct_answer.count
score = 0
else
score = 1
end
new_scores.each do |score_update|
score_update.score = score
scores.push(score_update)
end
end
else
score = 0
correct_answer = QuizQuestionChoice.where(question_id: question.id, iscorrect: 1).first
if (QuestionType.find_by_question_id question.id).q_type == 'Essay'
score = -1
elsif correct_answer and params["#{question.id}"] == correct_answer.txt
score = 1
end
new_score = Score.new :comments => params["#{question.id}"], :question_id => question.id, :response_id => @response.id, :score => score
unless new_score.comments != "" && new_score.comments
valid = 1
end
scores.push(new_score)
end
end
if valid == 0
scores.each do |score|
score.save
end
redirect_to :controller => 'student_quizzes', :action => 'finished_quiz', :map_id => @map.id
else
flash[:error] = "Please answer every question."
redirect_to :action => :take_quiz, :assignment_id => params[:assignment_id], :questionnaire_id => @questionnaire.id
end

end
</pre>

After Refactoring
<pre>
# New record_response method
def record_response
map = ResponseMap.find(params[:map_id])
response = Response.new
response.map_id = params[:map_id]
response.created_at = DateTime.current
response.updated_at = DateTime.current
response.save

calculate_score map,response

end

# New calculate_score
def calculate_score map, response
questionnaire = Questionnaire.find(map.reviewed_object_id)
scores = Array.new
valid = true
questions = Question.where(questionnaire_id: questionnaire.id)
questions.each do |question|
score = 0
correct_answers = QuizQuestionChoice.where(question_id: question.id, iscorrect: true)
ques_type = (QuestionType.where( question_id: question.id)).q_type
if ques_type.eql? 'MCC'
if params["#{question.id}"].nil?
valid = false
else
params["#{question.id}"].each do |choice|

correct_answers.each do |correct|
if choice.eql? correct.txt
score += 1
end

end
new_score = Score.new comments: choice, question_id: question.id, response_id: response.id

unless new_score.valid?
valid = false
end
scores.push(new_score)

end
if score.eql? correct_answers.count && score == params["#{question.id}"].count
score = 1
else
score = 0
end
scores.each do |score_update|
score_update.score = score
end
end
else
correct_answer = correct_answers.first
if ques_type.eql? 'Essay'
score = -1
elsif correct_answer && params["#{question.id}"]== correct_answer.txt
score = 1
end
new_score = Score.new :comments => params["#{question.id}"], :question_id => question.id, :response_id => response.id, :score => score
if new_score.comments.empty? || new_score.comments.nil?
valid = false
end
scores.push(new_score)
end
end
if valid
scores.each do |score|
score.save
end
redirect_to :controller => 'student_quizzes', :action => 'finished_quiz', :map_id => map.id
else
flash[:error] = "Please answer every question."
redirect_to :action => :take_quiz, :assignment_id => params[:assignment_id], :questionnaire_id => questionnaire.id
end
end
</pre>

==References==
<references/>

CSC/ECE 517 Fall 2014

2014-10-29T23:56:24Z

Aagrawa5:

CSC/ECE 517 Fall 2014/oss E1460 aua

2014-10-27T16:22:19Z

Aagrawa5: /* Use of Routing Helpers */

=Expertiza - Refactoring StudentQuizController=

__TOC__

==Introduction==
Expertiza<ref name="expertiza>''Expertiza'' http://wikis.lib.ncsu.edu/index.php/Expertiza</ref> is a web application available to both students and professors. The Expertiza project is a system to create reusable learning objects through peer review. Expertiza supports team projects, and the submission of almost any document type, including URLs and wiki pages. Students can keep a track of their assignments, teammates and can conduct peer reviews on diverse topics and projects. It is an open source project developed on Ruby on Rails platform. More information on Expertiza can be found [https://github.com/expertiza/expertiza here]. The source code can be forked and cloned for making modifications.
ertiza with main focus of Refactoring the Users Controller.

==Project Description==

Classes : student_quiz_controller.rb 
What it does : This class records the quizzes that the student has attempted and its progress and also submits grades for the essays in the quizzes attempted by the student. 
What has to be changed : 
*change list to index (and others in the RESTful style)
* Pluralize the class (StudentQuizzesController)
* graded? - review boolean zen
* Reduce the number of instance variables per controller action.
* Change the instance variables to local variables if they are not being used in the view.
* Modify methods to conform to RESTful style
* Code cleanup by using string interpolation instead of concatenation, replacing '==' with eql? and :key =>'value' with key: 'value', modifying declarations of Arrays and Hashes,removing commented out code
* Replace find_by with where to follow Rails 4.0 conventions

==Modification to Existing Code==

===Pluralized the class name StudentQuizController===
As per Rails convention the controller class names are sugested to be plural.
This helps in generating RESTful routing URI helpers. Also, naming the classes as plural seems more natural and helps in understanding<ref>http://stackoverflow.com/questions/646951/singular-or-plural-controller-and-helper-names-in-rails</ref>.
We used the refactor functionality in RubyMineto rename StudentQuiz controller class to StudentQuizzes.

The following files were modified and/or renamed.
<pre>
app/controllers/review_mapping_controller.rb
app/controllers/{student_quiz_controller.rb → student_quizzes_controller.rb}
app/helpers/student_quiz_helper.rb
app/helpers/student_quizzes_helper.rb
app/views/questionnaires/view.html.erb
app/views/{student_quiz → student_quizzes}/_quiz_form.html.erb
app/views/{student_quiz → student_quizzes}/_responses.html.erb
app/views/{student_quiz → student_quizzes}/_set_dynamic_quiz.html.erb
app/views/{student_quiz → student_quizzes}/_set_self_quiz.html.erb
app/views/{student_quiz → student_quizzes}/finished_quiz.html.erb
app/views/{student_quiz → student_quizzes}/grade_essays.html.erb
app/views/{student_quiz → student_quizzes}/list.html.erb
app/views/{student_quiz → student_quizzes}/take_quiz.html.erb
app/views/student_task/view.html.erb
app/views/tree_display/actions/_assignments_actions.html.erb
test/functional/{student_quiz_controller_test.rb → student_quizzes_controller_test.rb}
test/test_helper.rb
test/unit/helpers/student_quiz_helper_test.rb
test/unit/helpers/student_quizzes_helper_test.rb
</pre>

The detailed changeset for this refactor can be seen [https://github.com/ankit3005/expertiza/commit/20981333a14a3f468f76cd6d414b3088975b71bd here].

===RESTful style implementation===
* Modifications to student_quiz_controller.rb :
The purpose of the list method in the Student Quizzes controller is to list all the quizzes that are available to this user for a particular assignment. RESTful guidelines state that a method that returns a list of all available objects, in this case the quizzes, should be named as index. Therefore, we renamed the list method to the index method in the controller and in all the files that had references to the list method of the student_quiz_controller (For e.g. :- The view finished_quiz.html.erb of the Student Quiz controller, the review_mapping controller.rb etc.).

Before Refactoring :
<pre>
def list
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@assignment = Assignment.find(@participant.parent_id)

# Find the current phase that the assignment is in.
@quiz_phase = @assignment.get_current_stage(AssignmentParticipant.find(params[:id]).topic_id)

@quiz_mappings = QuizResponseMap.where(reviewer_id: @participant.id)

# Calculate the number of quizzes that the user has completed so far.
@num_quizzes_total = @quiz_mappings.size

@num_quizzes_completed = 0
@quiz_mappings.each do |map|
@num_quizzes_completed += 1 if map.response
end

if @assignment.staggered_deadline?
@quiz_mappings.each { |quiz_mapping|
if @assignment.team_assignment?
participant = AssignmentTeam.get_first_member(quiz_mapping.reviewee_id)
else
participant = quiz_mapping.reviewee
end

if !participant.nil? and !participant.topic_id.nil?
quiz_due_date = TopicDeadline.where(topic_id: participant.topic_id, deadline_type_id: 1).first
end
}
deadline_type_id = DeadlineType.find_by_name('quiz').id
end
end
}
</pre>

After Refactoring :

<pre>
def index
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)
@assignment = Assignment.find(participant.parent_id)
@quiz_mappings = QuizResponseMap.get_mappings_for_reviewer(participant.id)
end
</pre>

===Instance Variable Reductions===
In Rails, data is shared between the controllers and views through the instance variables. The instance variabIes that are set during the execution a particular controller method are accessible to the view. Excessive usage of this standard method of data sharing between the controller and the view results in increased coupling between them. <ref>http://blog.remarkablelabs.com/2013/01/how-to-decrease-coupling-in-your-controllers-views-with-decent_exposure-for-better-maintainability</ref> Increased coupling results in several problems, including less maintainability of code, difficulty in code reuse etc. <ref>http://en.wikipedia.org/wiki/Coupling_(computer_programming)#Disadvantages</ref> Thus, we need to reduce coupling to the maximum possible extent and in this case it can be achieved by reducing as many instance variables as possible. Therefore, we have refactored our code in order to eliminate unused and unneccessary instance variables.

Before Refactoring

student_quizzes_controller.rb

In the take_quiz method, the following instance variables were removed
Changed the quizzes instance variable to a local variable.
Eliminated instance variable assignment which was not used anywhere.
Eliminated local variable teams which was not used any where
The unified diff of the changes made is shown below
<pre>
def self.take_quiz assignment_id , reviewer_id
- @quizzes = Array.new
+ quizzes = Array.new
reviewer = Participant.where(user_id: reviewer_id, parent_id: assignment_id).first
- @assignment = Assignment.find(assignment_id)
- teams = TeamsUser.where(user_id: reviewer_id)
Team.where(parent_id: assignment_id).each do |quiz_creator|
unless TeamsUser.find_by_team_id(quiz_creator.id).user_id == reviewer_id
Questionnaire.where(instructor_id: quiz_creator.id).each do |questionnaire|
- if !@assignment.team_assignment?
- unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer.id).first
- @quizzes.push(questionnaire)
- end
- else unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer_id).first
- @quizzes.push(questionnaire)
+ unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer.id).first
+ quizzes.push(questionnaire)
end
end
end
end
+ return quizzes
end
- return @quizzes
-end
</pre>

===Code Cleanup===
Code cleanup in the controller so that the code conforms closely to Rails conventions and enhanced readability of code.
* Replaced String concats with #{} in paginate_list
Before Refactoring :

<pre>

</pre>

After Refactoring :

<pre>

</pre>

* Replaced '==' with eql?
Before Refactoring :
<pre>

</pre>

After Refactoring :
<pre>

</pre>

* Replaced :key =>'value' with key: 'value'

Before Refactoring :
<pre>

</pre>

*Modified declarations of Arrays and Hashes
Before Refactoring :
<pre>

</pre>

After Refactoring :
<pre>

</pre>

*Removed unused methods like self.participants_in and commented out code.

===Use of Routing Helpers===
Routing helpers are a simpler alternative to the otherwise complex hard coded URLs which reduce the readability of the code.Routing helpers allow us to declare possible common routes for a given controller. Routing helpers have been implemented since they maintain consistency even if changes are made to the routing paths.

Before Refactoring:
 
<pre>

</pre>
 
After Refactoring
 
<pre>

</pre>
 

===Replace find_by_.. with where in querying===
Rails 4 conventions dictate the use of 'where()' over the use of 'find_by_...' methods while querying ActiveRecords. The code has been refactored to replace the usages of find_by.. with where().

Before Refactoring
<pre>

</pre>

After Refactoring
<pre>

</pre>

===Replace controller method with a model method ===
Rails 4 conventions dictate the use of 'where()' over the use of 'find_by_...' methods while querying ActiveRecords. The code has been refactored to replace the usages of find_by.. with where().

Before Refactoring
<pre>
@quiz_mappings = QuizResponseMap.where(reviewer_id: participant.id)
</pre>

After Refactoring
<pre>
@quiz_mappings = QuizResponseMap.get_mappings_for_reviewer(participant.id)
</pre>

==References==
<references/>

CSC/ECE 517 Fall 2014/oss E1460 aua

2014-10-27T16:22:07Z

Aagrawa5: /* Code Cleanup */

=Expertiza - Refactoring StudentQuizController=

__TOC__

==Introduction==
Expertiza<ref name="expertiza>''Expertiza'' http://wikis.lib.ncsu.edu/index.php/Expertiza</ref> is a web application available to both students and professors. The Expertiza project is a system to create reusable learning objects through peer review. Expertiza supports team projects, and the submission of almost any document type, including URLs and wiki pages. Students can keep a track of their assignments, teammates and can conduct peer reviews on diverse topics and projects. It is an open source project developed on Ruby on Rails platform. More information on Expertiza can be found [https://github.com/expertiza/expertiza here]. The source code can be forked and cloned for making modifications.
ertiza with main focus of Refactoring the Users Controller.

==Project Description==

Classes : student_quiz_controller.rb 
What it does : This class records the quizzes that the student has attempted and its progress and also submits grades for the essays in the quizzes attempted by the student. 
What has to be changed : 
*change list to index (and others in the RESTful style)
* Pluralize the class (StudentQuizzesController)
* graded? - review boolean zen
* Reduce the number of instance variables per controller action.
* Change the instance variables to local variables if they are not being used in the view.
* Modify methods to conform to RESTful style
* Code cleanup by using string interpolation instead of concatenation, replacing '==' with eql? and :key =>'value' with key: 'value', modifying declarations of Arrays and Hashes,removing commented out code
* Replace find_by with where to follow Rails 4.0 conventions

==Modification to Existing Code==

===Pluralized the class name StudentQuizController===
As per Rails convention the controller class names are sugested to be plural.
This helps in generating RESTful routing URI helpers. Also, naming the classes as plural seems more natural and helps in understanding<ref>http://stackoverflow.com/questions/646951/singular-or-plural-controller-and-helper-names-in-rails</ref>.
We used the refactor functionality in RubyMineto rename StudentQuiz controller class to StudentQuizzes.

The following files were modified and/or renamed.
<pre>
app/controllers/review_mapping_controller.rb
app/controllers/{student_quiz_controller.rb → student_quizzes_controller.rb}
app/helpers/student_quiz_helper.rb
app/helpers/student_quizzes_helper.rb
app/views/questionnaires/view.html.erb
app/views/{student_quiz → student_quizzes}/_quiz_form.html.erb
app/views/{student_quiz → student_quizzes}/_responses.html.erb
app/views/{student_quiz → student_quizzes}/_set_dynamic_quiz.html.erb
app/views/{student_quiz → student_quizzes}/_set_self_quiz.html.erb
app/views/{student_quiz → student_quizzes}/finished_quiz.html.erb
app/views/{student_quiz → student_quizzes}/grade_essays.html.erb
app/views/{student_quiz → student_quizzes}/list.html.erb
app/views/{student_quiz → student_quizzes}/take_quiz.html.erb
app/views/student_task/view.html.erb
app/views/tree_display/actions/_assignments_actions.html.erb
test/functional/{student_quiz_controller_test.rb → student_quizzes_controller_test.rb}
test/test_helper.rb
test/unit/helpers/student_quiz_helper_test.rb
test/unit/helpers/student_quizzes_helper_test.rb
</pre>

The detailed changeset for this refactor can be seen [https://github.com/ankit3005/expertiza/commit/20981333a14a3f468f76cd6d414b3088975b71bd here].

===RESTful style implementation===
* Modifications to student_quiz_controller.rb :
The purpose of the list method in the Student Quizzes controller is to list all the quizzes that are available to this user for a particular assignment. RESTful guidelines state that a method that returns a list of all available objects, in this case the quizzes, should be named as index. Therefore, we renamed the list method to the index method in the controller and in all the files that had references to the list method of the student_quiz_controller (For e.g. :- The view finished_quiz.html.erb of the Student Quiz controller, the review_mapping controller.rb etc.).

Before Refactoring :
<pre>
def list
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@assignment = Assignment.find(@participant.parent_id)

# Find the current phase that the assignment is in.
@quiz_phase = @assignment.get_current_stage(AssignmentParticipant.find(params[:id]).topic_id)

@quiz_mappings = QuizResponseMap.where(reviewer_id: @participant.id)

# Calculate the number of quizzes that the user has completed so far.
@num_quizzes_total = @quiz_mappings.size

@num_quizzes_completed = 0
@quiz_mappings.each do |map|
@num_quizzes_completed += 1 if map.response
end

if @assignment.staggered_deadline?
@quiz_mappings.each { |quiz_mapping|
if @assignment.team_assignment?
participant = AssignmentTeam.get_first_member(quiz_mapping.reviewee_id)
else
participant = quiz_mapping.reviewee
end

if !participant.nil? and !participant.topic_id.nil?
quiz_due_date = TopicDeadline.where(topic_id: participant.topic_id, deadline_type_id: 1).first
end
}
deadline_type_id = DeadlineType.find_by_name('quiz').id
end
end
}
</pre>

After Refactoring :

<pre>
def index
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)
@assignment = Assignment.find(participant.parent_id)
@quiz_mappings = QuizResponseMap.get_mappings_for_reviewer(participant.id)
end
</pre>

===Instance Variable Reductions===
In Rails, data is shared between the controllers and views through the instance variables. The instance variabIes that are set during the execution a particular controller method are accessible to the view. Excessive usage of this standard method of data sharing between the controller and the view results in increased coupling between them. <ref>http://blog.remarkablelabs.com/2013/01/how-to-decrease-coupling-in-your-controllers-views-with-decent_exposure-for-better-maintainability</ref> Increased coupling results in several problems, including less maintainability of code, difficulty in code reuse etc. <ref>http://en.wikipedia.org/wiki/Coupling_(computer_programming)#Disadvantages</ref> Thus, we need to reduce coupling to the maximum possible extent and in this case it can be achieved by reducing as many instance variables as possible. Therefore, we have refactored our code in order to eliminate unused and unneccessary instance variables.

Before Refactoring

student_quizzes_controller.rb

In the take_quiz method, the following instance variables were removed
Changed the quizzes instance variable to a local variable.
Eliminated instance variable assignment which was not used anywhere.
Eliminated local variable teams which was not used any where
The unified diff of the changes made is shown below
<pre>
def self.take_quiz assignment_id , reviewer_id
- @quizzes = Array.new
+ quizzes = Array.new
reviewer = Participant.where(user_id: reviewer_id, parent_id: assignment_id).first
- @assignment = Assignment.find(assignment_id)
- teams = TeamsUser.where(user_id: reviewer_id)
Team.where(parent_id: assignment_id).each do |quiz_creator|
unless TeamsUser.find_by_team_id(quiz_creator.id).user_id == reviewer_id
Questionnaire.where(instructor_id: quiz_creator.id).each do |questionnaire|
- if !@assignment.team_assignment?
- unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer.id).first
- @quizzes.push(questionnaire)
- end
- else unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer_id).first
- @quizzes.push(questionnaire)
+ unless QuizResponseMap.where(reviewed_object_id: questionnaire.id, reviewer_id: reviewer.id).first
+ quizzes.push(questionnaire)
end
end
end
end
+ return quizzes
end
- return @quizzes
-end
</pre>

===Code Cleanup===
Code cleanup in the controller so that the code conforms closely to Rails conventions and enhanced readability of code.
* Replaced String concats with #{} in paginate_list
Before Refactoring :

<pre>

</pre>

After Refactoring :

<pre>

</pre>

* Replaced '==' with eql?
Before Refactoring :
<pre>

</pre>

After Refactoring :
<pre>

</pre>

* Replaced :key =>'value' with key: 'value'

Before Refactoring :
<pre>

</pre>

*Modified declarations of Arrays and Hashes
Before Refactoring :
<pre>

</pre>

After Refactoring :
<pre>

</pre>

*Removed unused methods like self.participants_in and commented out code.

===Use of Routing Helpers===
Routing helpers are a simpler alternative to the otherwise complex hard coded URLs which reduce the readability of the code.Routing helpers allow us to declare possible common routes for a given controller. Routing helpers have been implemented since they maintain consistency even if changes are made to the routing paths.

Before Refactoring:
 
<pre>

</pre>
 
After Refactoring
 
<pre>
def show_selection
@user = User.where(name: params[:user][:name]).take
if @user != nil
role=get_role
if role.parent_id.eql? nil || role.parent_id < (session[:user]).role_id || @user.id.eql?(session[:user]).id
render action: 'show'
else
flash[:note] = 'The specified user is not available for editing.'
redirect_to users_path #Replaced URL with routing helper
end
else
flash[:note] = params[:user][:name]+' does not exist.'
redirect_to users_path #Replaced URL with routing helper
end
end
</pre>
 

===Replace find_by_.. with where in querying===
Rails 4 conventions dictate the use of 'where()' over the use of 'find_by_...' methods while querying ActiveRecords. The code has been refactored to replace the usages of find_by.. with where().

Before Refactoring
<pre>

</pre>

After Refactoring
<pre>

</pre>

===Replace controller method with a model method ===
Rails 4 conventions dictate the use of 'where()' over the use of 'find_by_...' methods while querying ActiveRecords. The code has been refactored to replace the usages of find_by.. with where().

Before Refactoring
<pre>
@quiz_mappings = QuizResponseMap.where(reviewer_id: participant.id)
</pre>

After Refactoring
<pre>
@quiz_mappings = QuizResponseMap.get_mappings_for_reviewer(participant.id)
</pre>

==References==
<references/>