For those considering doing some future assignments in C/C++ see the last question. Even if you prefer to work in C/C++, it is highly recommended that you know. If you expect that you might join/collaborate with the vision group, doing some of the assignments in C/C++ and using the software mentioned below is highly recommended.

Matlab is installed on the UA CS linux machines (the path is /usr/local/bin). Normally, to begin, you just type "Matlab" at the shell prompt. For example, you may want to use the machines gr01 through gr08 in GS 930, either on-site, or remotely. If your DISPLAY environment is properly set, the default behavior is the GUI interface. Otherwise, you will get the command line interface. This GUI is required for much of this assignment. You may find that the GUI is slow to start up, and painfully slow to use over a slow connection. For a faster startup (but without some of the features needed for some parts of this assignment), you can try

        matlab -nodisplay -nojvm

Matlab is available for personal use to UA faculty, staff and students. It can be downloaded from http://sitelicense.arizona.edu/matlab/ by any University of Arizona faculty, staff or student with a netid. The site-license includes MATLAB, Simulink, plus 48 toolboxes.

IMPORTANT NOTE. Even if you develop programs on some other machine, they must work on our reference machines, gr01 through gr08.

Deliverables

The parts of the assignment that imply a deliverable are indicated as such with (+). Note that each deliverable figure created should be a new one. If you do not use the "figure" command as explained below, a new figure overwrites the previous one.

1. Become familiar with Matlab (no deliverables).

   Read this short Matlab tutorial and be aware of this longer Matlab primer . The complete documentation for Matlab is also available on the web. All Matlab commands are well documented with Matlab's help system. For example, if you want to know how the svd function works, type help svd. You can also get help on all the built in operators and even the language itself. Typing help gives a list of help topics.

   Tip: You may want to turn on paging (more on) for reading help pages.

   In addition, the GUI has a "function browser" that you may find useful.

2. Reading and Displaying Images

   Place a JPEG color image in your working directory with the name 1-1.jpg. When the instructor runs your program, they will use this image:

    1-1.jpg  

   If you want to use a different image, you should consider testing with that image as well before handing in your assignment.

   Load the image (1-1.jpg) into a variable using imread. Type help imread to find out how to do this. Create a new figure using figure and display the image in it using imshow(+).

   Tip: Make sure you put a semicolon at the end of your imread command! The semicolon at the end of a line prevents Matlab from displaying the result of an expression. Most of the time, you want the semicolon.

   Make sure you understand the data structure being used to represent the image. Type whos to get a list of active variables along with their types and sizes. You can see that your image is a 3D array of bytes. This is row by column by "channel" where the channels are red, green, and blue intensity values.

   What is the range of values contained in the image array? Use the min and max functions to output this information (+).

   Hint: These commands by default operate on only one dimension of their argument. Convert your image into a 1D array (a vector) using the (:) notation when you pass it to min and max.

   Hint for the hint: help colon.

   Convert the image to grayscale using rgb2gray. Check the representation of the image now. Use size or whos to find this out. You will see that we now have a 2D array, or a matrix. Create a new figure and display the black and white image (+).

3. Files and Paths

   The interactivity of Matlab is great for debugging and experimenting, but usually one wants to type code into a file. Create a file hw1.m and put the commands in it to provide the deliverables from the previous part. Now type hw1 at the Matlab prompt to execute the commands in the file. A file of this sort is known as a script. As you work through the exercises, update hw1.m with debugged code that creates the required output.

   Tip: Matlab has pwd, ls, and cd commands that do what you expect.

   Tip: If your script is in some other directory than pwd, then you can add that other directory to Matlab's search path with the addpath command. The current directory is in Matlab's search path by default.

4. Image channels

   Create three grayscale images based on our color image by extracting the red, green, and blue pixels, respectively, into an array. Display the three images (+,+,+). Are they what you expect? Can you explain why some areas that are bright in the color image are dark in some of the grayscale "slices"?

   Tip: While Matlab has C style loops, you should avoid doing this sort of thing with low level loops. Instead, use the colon notion (help colon).

   Create a new color image that has the green channel from the original image as its red channel, the blue channel from the original as its green, and the red channel from the original as its blue. Create a new figure and display the result (+).

   Hint: Again, you might find the colon notation helpful (help colon).

5. Visualizing Matrices

   Convert the grayscale image into a double-precision type, and scale the values so that they lie in the range [0,1].

   Hint: Use the double function to do the type conversion, and then divide by the maximum allowable value for a byte, which is 255.

   Create a new figure using figure, and use imagesc to display the grayscale image in it. Why does it look so strange?! Type colorbar to find out. You can see that 0 maps to blue, 0.5 to green, and 1 to red. This is the default jet colormap that is useful for data visualization. For this example, we might prefer the grayscale colormap. Type colormap(gray) to do this.

   Tip: Type help gray to see what default colormaps are available. Note that you can also make your own colormaps.

   Tip: The imagesc command takes a second argument that lets you specify the range of values. By default, imagesc scales the data to use the full colormap, but this is not always what you want. In this example, we could add the argument [0 1] to the imagesc command would be a nop because that is the range we already scaled it it.

   The image is probably distorted, i.e. the pixels aren't square. Use the axis command to fix this, and display a new figure (+).

   Tip: When you display matrices as images, you usually want the axes to be scaled so that the pixels are square and the image not distorted. See help axis to determine how to do this. The axis image command is a useful one. You can also turn the display of the axes on and off with the axis command.

6. Histograms A histogram divides up your data space into boxes, and puts counts of occurrences into them. They are visualizations of the empirical probability distribution of your data. (EG, how likely do very red pixels occur?). If you are not familiar with histograms, you should read the Wikipedia article and/or some other resource about them as we will assume that you know what they are.

   Convert each of the three color channel "slice" images into 1D vectors and provide histograms for them with 20 bins for each of them (+,+,+) using the hist command.

7. Manipulating Matrices

   In this section, we will work with the converted grayscale image with double values in the range [0,1].

   Tip: Array indices in Matlab start at 1, not at 0 like C.

   Tip: As in standard mathematical notation, the first index of a matrix is the row, and the second index the column. When viewing a matrix as an image, this means that the first index is the y direction going down, and the second the x direction going to the right. As is common with image manipulation tools, the origin is at the top left corner, the positive x axis points right, and the positive y axis points down.

   Get the width and height of the image using size. The size function, as is common in Matlab, can return multiple arguments.

   Hint: To store both the width and height into variables in one go, try [h,w]=size(im). You could alternately do h=size(im,1) and w=size(im,2).

   Write a couple of nested for loops to set every 5th pixel, horizontally and vertically, to 1. This should set 1/25th of the pixels to white in a square lattice pattern. Create another figure and display this result in it (+).

   Hint: Use the colon operator to define the limits of the for loops. See help colon and help for to see how to do this. Specifically, you want the minval:interval:maxval form.

   Set all the same pixels to 0, making the ones that you just set to white become black. Do it this time without using any for loops. Create yet another figure and display this result in it (+).

   Hint: You can index arrays in Matlab with vectors as well as with scalars, so im(Y,X)=0 will set multiple entries of im to zero when either X or Y are vectors, such as the vectors returned by the colon operator.

   Hint on hint: What is described in the hint might take some getting used to. Like many things in Matlab, it is easiest to combine reading of the documentation with experimentation. It is helpful to try simple things on random matrices. To get a random square matrix of size 10x10 use rand(10), and to get one of size 4x12 use rand(4,12). Vectors can be created as follows:
   v=[2 4 6 8];>
   Given such tools in an interactive environment makes it easy to create vectors with integer values and see what happens when you use them as matrix indices in assignment statements.

   Set all the pixels whose values are greater than 0.9 to zero. The command to do this is im(find(im>0.9))=0. Check that this works, create a new figure and display the result )+). You should understand why this works.

   Hint: The (im>0.9) expression evaluates to a boolean matrix, which is true where the condition holds. The find function returns a vector containing the indices of the true values. This vector is then used to index the image and set all the values to zero. Why does this last step work when the matrix is 2D and the indexing is 1D? Matlab lets you treat matrices as 1D vectors too, linearizing the matrix in column-major order.

   More on column-major order. Think for a moment how 2D arrays are stored in memory. There are a number of options. One options is that the array is stored as a linear sequence of numbers, i.e., a 1D vector. This still leaves two alternatives. One is that the first row is followed by the second row (row-major), which is how C/C++ handle fixed arrays. The second is that the first column is stored in order, followed by the second column, and so on. This is column-majororder which is used by Fortran and inherited by Matlab. This is an important issue to understand for those that might want to call Fortran routines form C which is a useful skill!

   More tricks (no deliverables)

   Matlab makes it easy to write "vectorized" expressions without having to write for loops or if statements. For example, this will add all the values of the image:

   sum(im(:))

   The following will count the number of values greater than 0.9:

   numel(find(im>0.9))

   So will this:

   sum(sum(im>0.9))

   This will halve only those values greater than 0.9 (note the use of the .* operator to do element-size multiplication of matrices):

   im = im - 0.5*im.*(im>0.9);

   And so will this:

   mask = (im>0.9);
im = im.*~mask + im.*mask*0.5;

   This will set 100 unique random pixels to zero:

   p = randperm(numel(im));
im(p(1:100)) = 0;

   See help elmat for a list of interesting matrix manipulation and creation routines.

8. Writing Images (no deliverables)

   Write the image to a file called out.jpg using the imwrite function. Use some independent image viewer like display, xv or a web browser to verify that this worked. I recommend learning about the ImageMagick suite of tools for converting, and displaying images (do "man convert", and a "man display" to find out more). Also the program import can be used to get a screen-shot in linux.

9. Plotting

   Explore the plot command. Plot the sin function over the domain -pi:pi. Use the linspace command to define the domain x and then do plot(x,sin(x)). Use the hold on command to plot another function on the same graph. Do this to add cos. Use a different color, e.g. plot(x,cos(x),'r'). The running of hw1.m should produce a plot along these lines (+).

10. Playing with Linear Algebra

    Matlab is a great tool to for experimenting with linear algebra.

    Use the fact that inv() inverts a matrix to solve for X=(x,y,z):

       3*x + 4*y +   z = 9
       2*x -   y + 2*z = 8
         x +   y -   z = 0 
    

    Verify that your "solution" works. Make sure that your program outputs the answer, and also the "proof" that it is correct (+).

    If there are more equations than unknowns, then, in the general case, "classically" the problem is over constrained and there is no solution. However, in this course, we will often be assuming that such equations are approximations and have errors due to noise or other reasons, and that an exact solution cannot be found regardless. Thus we will want to find the "best" solution. This is known as solving the equations in the least squares sense. The solution for AX=b, where A has more rows than columns, is given by X=inv(A'*A)A'b, where inv(A'A)A' is known as the Moore-Penrose inverse of A. Use this to solve for X=(x,y,z) in:

       3.0*x + 4.0*y +  1.0*z = 9
       3.1*x + 2.9*y +  0.9*z = 9
       2.0*x - 1.0*y +  2.0*z = 8
       2.1*x - 1.1*y +  2.0*z = 8
       1.0*x + 1.0*y -  1.0*z = 0 
       1.1*x + 1.0*y -  0.9*z = 0 
    

    Your program should output the solution and the magnitude of the error vector (+).

    Recall that an eigenvector of a matrix A is a vector v, so that Av=kv, for some scalar constant k. If A is real and symmetric, then A has real eigenvalues and eigenvectors. Note that for a random matrix, R, R*R' is symmetric. (Try it!). The the matlab function eig() gives you eigenvectors and eigenvalues. Use these hints to create a 4x4 matrix A, and a corresponding vector v, that satisfies the eigenvector equation above. Show that your A and v have this relation by printing out the value of A*v./v (+).

11. Documenting Functions

    When you create a new function, it should always be documented so that help returns something informative. The convention in Matlab is to place the help message in comments after the function declaration (the comment character is "%").

    For example, you can look at some of the code in the Matlab library. Some of it is implemented as .m files, and some of it is "builtin". Regardless, there should be a .m file for at least the documentation. Using the "which" command, see if you can find the .m file for your favorite function so far. On my mac, the path provided was not exact, but gave me a good idea where to look.

    If you look at some of these examples, you will see that the first line of the comment contains a one-line description of the command. All subsequent contiguous comment lines are included in the help message. Document your hw1.mfunction in this style. For the purposes of this assignment, no need to be overly detailed. A short paragraph or two about the main teaching points will suffice. (+).

12. Using C/C++ instead (optional). Doing the assignments in C/C++ is relatively straightforward with appropriate library support. There are many options for this that you can use, including the UA CS vision group library. (If you expect that you might join/collaborate with the vision group, you will want to get comfortable with this software.) If you want to experiment with this software, then have a look at this example program (information about the library is in comments). To run the program you will also need a matrix input file called matrix.txt and a file named image.tiff. .

    A good warm-up project is to implement the least squares computation above. In increasingly simplicity, but decreasing enlightenment, you could: 1) Use basic matrix operations, including get_matrix_inverse(); 2) Shorten things using get_MP_inverse(); 3) Shorten things even further with least_squares(). Doing all three might be a good way to play with the library.

    To view the documentation pointed to by the above links, you many need:

        login: me
        pw:    doc4fun
    

    More and better information about compiling, linking, and using the library to come very soon.

What to Hand In

In general the README.txt file will tell the instructor which language you used for which parts, which machine available ot the grader (e.g. gr01) you tested it on, and whether you did any extra questions (otherwise the instructor might not notice).

Specification summary: The instructor will change directory to where your assignment is, and then enter "help hw1" to see if you learned how to document matlab files. They will then invoke your program with the command hw1, and check if the figures and results requested appear. You can scan for "+" to double check that you have it all.