COS 426:
Computer Graphics
Spring 2018


COS 426 General | Assignment 1


Overview

In this assignment you will create a simple image processing program. The operations that you implement will mostly be filters that take an input image (or two), process the image(s), and produce an output image.


Getting Started

The JavaScript based image processing program has two modes: (1) an interactive mode where you can enable/disable various filters, adjust parameters to these filters, and see the result right away; and (2) a batch mode where all the filters and parameters are fixed. Each version runs in a web page, and for the batch mode the filters and parameters are specified in the URL.

Same as A0, to get started, download this zip file and unzip it on your computer. Change to the subdirectory cos426-assign1 and run the command python -m SimpleHTTPServer in the terminal. (That command is for python 2.7. In python 3 it should be python3 -m http.server. There are also many other ways to start a web server, for example using php -S localhost:8000 or by installing WAMP or MAMP or Node. Various other options are discussed here.) A web server will be launched locally on your computer, rooted at this directory. Note that our assignments will not work if you simply open the html file in the browser directly using file://... due to the same-origin security policy. Therefore we run a local web server.

Once you have started the local web server, direct your browser to http://localhost:8000 (8000 is the default port used by the python web server). You should see the web page for Assignment 1 showing a picture of a flower. On the right hand side of the web page, you can find two control menus. The left one is the feature menu which contains the features/operations you will need to implement in this assignment and the right one is the history menu which keeps track of the history operations. In the feature menu, you can expand the folders and see all the features. As an example, we provide the implementation of "Brightness" under the "Luminance" folder. By clicking "Brightness", a new operation will be pushed to the bottom of the history menu, and now you can pull the slider to adjust the brightness of the image. Note that we also provide the implementation of "Grayscale" under the "Color" folder. If you want to add another image, simply click "Push Image" and an new image will be pushed to the image stack.

Please familiarize yourself with the already-implemented features (Push Image, Brightness, Grayscale, Quantize). For those features which have not been implemented yet, a warning box will pop up if you click on them. You will need to comment out the warning box code after you implement the features. All the operations you apply will appear in sequence in the history menu and you can delete the past operations if you want. For the "Push Image" operation, by clicking "Delete Below", all the operations below it will be removed as well because those operations are associated with the image being removed. For other operations, by clicking "Delete", only the selected operation will be removed. Also note that all the history operations are encoded in the URL, so feel free to refresh the webpage and everything will still be there. This allows you to change your code and then get back to the same place. It also allows you to change the values directly in the URL rather than in the GUI. We recommend Google Chrome for development. In most cases, refreshing the webpage will make your edited scripts take effect. However, the browser sometimes caches old scripts. To disable caching, in Chrome's Developer Tools, select the "Network" tab and check "Disable cache". Note that this only works when the Developer Tools window is on.

To make debugging friendly, a "Batch Mode" button is given. Once you are satisfied with the parameters in the interactive GUI, click "Batch Mode" and the batch mode will be loaded in a new tab with all the parameters fixed. Then you can simply refresh when you make changes to your code. For some filters which are slow to process, the batch mode will say "Processing" instead of showing the result immediately. Another cool feature is "Animation". By clicking "Animation", a gif animation will show in the batch mode by varying the value of the most recent ONE-parameter operation. Typically "Animation" is designed for quick operations, so you probably don't want to try this on slow operations such as "Median".

Use your favorite text/code editor to edit the file js/student.js and fill in your name and NetID. Reload the web page in your browser, and now your information should appear above the image.



Implementing the Image Processing Filters

The assignment is worth 20 points. The following is a list of features that you may implement (listed roughly from easiest to hardest). The number in front of the feature corresponds to how many points the feature is worth for the full implementation. Partial or partially-correct solutions will receive partial credit. The features in bold face are required. The other ones are optional. Refer to the examples web page for example output images as well as some implementation hints.

Two of the features (brightness and grayscale) are already implemented for you ask examples. By implementing all the required features (in bold), you get 14 points. Full credit for this assignment is 20 points, so to complement the required features you may choose from the optional features listed above and participate in the art contest (which yields one point for participation and two for winning). It is possible to get more than 20 points for this assignment. The value of non-required features incurs diminishing returns after the first 6 points. For sums of non-required features (n>6), each point over 6 will accrue a value of 3/4 the previous point.

Your final score is based on the following factors:

Final score will be rounded to the nearest 0.5. The formula in javascript is:
Math.round((Math.min(R, r) + Math.min(N, n) + d * (1 - Math.pow(d, Math.max(n - N, 0))) / (1 - d) + a) * 2.0) / 2.0

Score Calculator:
my score on the required features
my score on the non-required features
my score on the art contest
total score


How to Program the Filters

To implement the image processing features listed above, you only need to edit the file js/filters.js. Before starting on that, we recommend you take a quick look at the file js/image.js because it has some important helper code relating to images and pixels. You are welcome to look at any of the other files, but it should not be necessary and some of them have some pretty byzantine javascript magic. In js/filters.js, two of the image processing filters are already implemented for you as examples, so you should get the idea of how it works. Some of the filters (like brightness) can work directly in the image that is passed to them; however, other filters (like gaussian) need to allocate a new image to avoid overwriting the original pixel values needed in subsequent processing.


Submitting

You should submit your solution via CS dropbox here. The submitted zip file should preserve the directory structure of the skeleton code we provided in the zip file above. CS dropbox requires that the size of a single file is below 50MB. You can put few largest files in your own web space / google drive / dropbox and include a link to that in the write-up to save space.

The writeup.html file should be an HTML document demonstrating the effects of the features you have implemented and would like scored. For the features you would like to demonstrate, make sure that you include the required results by replacing placeholder.png(s) with you results. You are encouraged to include more representative results, but extra results only affect your score when your implementation is partially correct. You don't have to show the input images for the required results.

You should start from the the example writeup.html provided. At the top of that file are a list of features that you might implement, linking to the section where you talk about them. Please remove any features that you do not implement from the list as well as the corresponding sections, but otherwise leave this header section in tact. When you include an extra result, also include a link to the batch.html command that creates that image, as illustrated in the "Brightness" example.

To save space, please submit images in png format. You may include one or a few gif files as well to show animations, but these files can be large so please try not to include lots of large gifs.

Note that you are expected to use good programming style at all times, including meaningful variable names, a comment or three describing what the code is doing, etc. Partial credit may not be assigned for code without comments. We have mostly tried to conform to the idiomatic JS style conventions.



Hints

A few hints:


FAQ

Here are some answers to frequently asked questions. Check back here occasionally, as we may add FAQs to this list: