MP4: 2D

As we have learned previously, computers are frequently used to transform and analyze data. And an increasing amount of that data is multi-dimensional: including both photo and video data. People are taking a huge amount of photos and video, and processing that data is almost entirely done on or by computers.

For MP4 you’ll be working with two-dimensional photo pixel data as you complete the server part of a simple photo editing application. It is due Friday, October 20th, 2017 @ 5PM. To receive full credit, you must submit by this deadline. In addition, 10% of your grade on MP4 is for committing code that earns at least 50 points by Friday, October 13th, 2017 @ 5PM.

1. Learning Objectives

The purpose of MP4 is to continue introducing you to data transformation. You’ll begin to learn how to:

  1. implement various image transformations by performing transformations on 2D arrays

  2. avoid writing repetitive code by identifying similarities between various transformations

  3. working with bits and bytes to get and set pixel color channel information

We’ll also continue to reinforce the learning objectives from previous MPs (1, 2, and 3).

2. Assignment Structure

MP4 consists of a simple client-server system. The HTML, CSS, and JavaScript for the client are provided for you. But it relies on your backend to work properly.

Your job is to complete the required transformations in Transform.java. These functions are called by the web server that is set up using WebServer.java.

As always, you may find our official MP4 online documentation helpful in understanding what each function is supposed to do.

2.1. Obtaining MP4

Please follow the instructions from MP1. You’ll find MP4 in an MP4 folder in your Subversion home directory. Unless you want to learn a lot more about Subversion, do not delete your MP4 folder once you have it.

2.2. Your Goal

At this point you should be familiar with the requirements from previous MPs. MP4 is similar, and retains (but strengthens) the starting the assignment on time grading component from MP3. See the grading description below.

2.3. Running MP4

To experiment with the web interface, do the following:

  1. Run WebServer.java as a Java application. You may need to correct errors with Transform.java before this will work.

  2. Open your web browser and navigate to http://localhost:8125.

At first, nothing will work because you have not implemented any of the required transformations yet. Note that our web interface uses some new-ish browser features, and of course Internet Explorer hasn’t implemented all of them yet. We have confirmed that Chrome, Firefox, and Safari work on both Mac and Windows 1.

2.3.1. Fixing port conflict problems

A common problem with using Eclipse to complete MP4 are so-called port collisions. This will happen if you try to start a new web server running your latest completed transformations without shutting down the one that is currently running.

Here’s how to do this properly. This problem is also covered by the video above.

  1. Stop your program using the Eclipse red stop button.

  2. Restart your server with your latest changes.

If you encounter the problem described above, here is how to fix it:

  1. Stop the failed web server using the stop button.

  2. Close that console using the Eclipse close cross icon.

  3. This should show you the console that is running the old web server that is causing the problem. Shut that down using the stop button, and then you can restart the web server with your changes.

3. Approaching MP4

All of our previous advice about how to approach the CS 125 MPs still applies. But MP4 has some unique features that are designed to continue your development as computer scientists and software developers.

3.1. Don’t Repeat Yourself (DRY)

Whenever you write software, you should try to adhere to the DRY principle: don’t repeat yourself.

What does this mean? It means that you should try to avoid writing duplicative code—multiple functions (or parts of the same function) that perform identical tasks.

Consider the fact that any computer program could be written as one giant function and with no subroutines at all 2. But the result would be awful, since any time the program needed to repeat a task it would have to repeat the code needed to accomplish that task. And any time you fixed a bug in one part of the code, you’d have to find every other identical part and fix the bug there as well. Code like this quickly becomes impossible to understand, test, debug, and improve—and will also make it hard to keep a job.

At first glance, MP4 may seem daunting. You have 22 functions to write! And yes, you can complete MP4 by writing 22 separate independent functions.

But there is a much smarter way to approach MP4. As a hint, the solution set consists of only six real functions—with the rest just calling into this much smaller set of helper functions. The reason is that many of the transformations perform similar operations. For example, a shift down is similar to a shift up, as well as a shift left and a shift right. So rather than writing four separate extremely-similar functions, I can write a slightly more complicate generic shift function and have it called by all of the others.

There is a balance here that requires practice to get right. Trying to reduce the needs of 22 different functions to one single method produces overly-complicate and brittle code. But writing them all separately misses opportunities to harness common subroutines. You’ll get better at this with practice, and MP4 is a good chance to get some. So do not implement 22 separate transformation functions, but also do not attempt to implement one function that does everything. There are some natural groupings that you will probably be able to identify.

3.2. Manipulating Binary Data

MP4 requires you to manipulate binary pixel data stored in Java int primitive types. The int values in the 2D array passed to your functions contain 4 bytes in RGBA order:

  1. The first (lowest) byte in the int stores the red value, which goes from 0 (no red)–255 (maximum red).

  2. The second byte in the int stores the green value, which goes from 0 (no green)–255 (maximum green).

  3. The third byte in the int stores the blue value, which goes from 0 (no blue)–255 (maximum blue).

  4. The fourth (highest) byte in the int stores the alpha value, which goes from 0–255. The alpha channel sets the transparency of the pixel, which affects how it blends with pixels below it in the image. A value of 0 makes the pixel fully transparent, while a value of 255 makes it fully opaque (completely non transparent).

One way to remember this is to say that a RGBA hex value stores the values as 0xAABBGGRR.

Several of your transformation functions will need to manipulate the color data in individual image pixels. So we suggest that you set up some helper functions to manipulate color and alpha channel values.

3.3. Understand Your Coordinate System

If you are used to working with the coordinate plane in mathematics, the canvas coordinate system can take some getting used to. In particular:

  1. (0, 0) is at the top left, not the bottom left.

  2. Increasing Y values move the image down, not up—keep this in mind when implementing shiftUp and shiftDown.

  3. Increasing X values move the image to the right, which matches the mathematical coordinate system.

3.3.1. Centering

Understanding the coordinate system is also important when centering the image around (0, 0), which you need to do to implement the rotate, flip, and resize transformations. This is probably one of the trickier parts of MP4, so think it through carefully.

It is helpful to work some simple examples. For example, consider vertically flipping a 2x2 array. In our coordinate system, the coordinate values of the pixels in the array would be:

(0, 0)

(1, 0)

(0, 1)

(1, 1)

Note that these are the coordinate values, not the pixel contents. In order to flip the array properly, we need to adjust the coordinate values as follows:

(-0.5, -0.5)

(0.5, -0.5)

(-0.5, 0.5)

(0.5, 0.5)

At this point I can swap either the X or Y values and achieve either a horizontal or vertical flip around the origin. There is only one problem—Java can’t use double types as array indices. So we need to do this transformation on a pixel-by-pixel basis. Roughly, here is the approach. For each pixel in the original image:

  1. Center the pixel

  2. Determine how to transform it to a new location in the transformed image

  3. Undo the centering transformation

  4. Move data from the original image to the transformed image

Once you have a centering procedure that works, you can use it for the rotations, flips, expands, and shrinks. But this is one of the tougher parts of the assignment, so you might want to start with the parts that don’t require centering: position shifts, color shifts, green screen and the mystery function.

3.3.2. Shrinking and expanding

As a final note about coordinates, please consider carefully how to implement the shrink and expand transformations. Specifically, if I start with this 2x6 array (with pixel values shown):

0

0

1

1

0

0

0

0

1

1

0

0

and expand it horizontally by a factor of 3, this is the correct result:

1

1

1

1

1

1

1

1

1

1

1

1

But it is easy to get this instead:

1

0

1

1

0

1

1

0

1

1

0

1

You will want to think about this carefully. As a hint, instead of starting with the original array and trying to figure out where each pixel goes in the transformed array, you may want to start with the transformed array and calculate where each pixel should come from. Also keep in mind that simply casting a double to an integer does not round the value properly. So (int) doubleValue != Math.round(doubleValue).

3.4. Getting Help

The course staff is ready and willing to help you every step of the way! Please come to office hours, or post on the forum when you need help. You should also feel free to help each other, as long as you do not violate the academic integrity requirements.

3.5. How All Of MP4 Works

The video above is optional, but may interest those that are curious about how a modern web application works. It walks through most of what happens from the moment you click one of the image transformation buttons, to when transformed data returns from the server.

4. Grading

MP4 is worth 100 points total, broken down as follows:

  1. 80 points: Transform.java

    • 10 points for submitting code that compiles

    • 10 points for completing the position shift transformations

    • 20 points for completing the rotation and flip transformations

    • 20 points for completing the color shift transformations

    • 10 points for completing the shrink and expand transformations

    • 5 points for completing the green screen transformation

    • 5 points for completing a mystery transformation

  2. 10 points for no checkstyle violations

  3. 10 points for committing code that earns at least 50 points before Friday, October 13th, 2017 @ 5PM.

4.1. Test Cases

As in previous MPs, we have provided exhaustive test cases for each part of MP4. Please review the MP1 testing instructions.

4.2. Autograding

Like previous assignments, we provide you with an autograding script that you can use to estimate your current grade as often as you want. Note that, like MP3, the local autograder can only calculate 90 out of your 100 total points.

Unless you have modified the test cases or autograder configuration files, the autograding output should equal the score that you will earn when you submit. If you modify our test cases or the autograding configuration, all bets are off.

5. Submitting Your Work

Overall you should refer to our instructions for using Subversion. Commit early and often! You only earn credit for the version of your code that is committed to your repository, so ensure that we have your best submission before the deadline.

And remember, you must commit something that earns 50 points before Friday, October 13th, 2017 @ 5PM to earn 10 points on the assignment. This is a bit of a higher bar than in previous assignments, since fixing basic compiler and checkstyle errors will only get you 20 points. So you’ll need to complete a few of the image transformation functions to get past this bar.

5.1. Academic Integrity

Please review the MP1 academic integrity guidelines.

CS 125 is now CS 124

This site is no longer maintained, may contain incorrect information, and may not function properly.

Created 10/24/2021
Updated 10/24/2021
Commit a44ff35 // History // View
Built 10/24/2021 @ 21:29 EDT