ECE 638 HW8 README for In/Out-gamut mask and difference image generation code

Before running the scripts, please check and make sure the following files are located in: 

1. The original input image 		in the input folder
2. The gamut-mapped image 		in the output folder
3. IndigoGamut.mat 			in the data folder
4. rgb2ycxcz4Visual.m			in the GamutMapping folder
5. ycxcz2rgb4Visual.m			in the GamutMapping folder

The computational complexity is O(MN)=O(# of pixels), and the mask generation code takes roughly 20mins for an image of size 3264 by 2448. Therefore I do not recommend using a very large image for this assignment.

To generate the in/out-gamut mask, run the following line on the command window :

generateGamutMask(img_name,mask_name)

img_name : The name of the input image including the single-quotes, e.g., 'church.tif'.
mask_name : The name of the output mask image to be written including the single-quotes, e.g., 'church_mask.tif'. Do NOT use lossy compression (e.g., JPEG) for the mask image.

You can add an optional third argument display_gamut, which is Boolean and by default set to be false. If this argument is set to be true, MATLAB will display a 3-D plot of the convex hull of the printer gamut.

The gamut mask image will have a white pixel if the corresponding pixel's color in the original image is inside the printer gamut; otherwise the pixel in the mask image will be black. For more details about how the code for generating the gamut mask is written, refer to the last part of the readme file or the comments in the script.

To generate the difference image, run the following line on the command window : 

diffImage(orig_img_name, gm_img_name, diff_img_name)

orig_img_name : The name of the original image before gamut mapping is performed, including the single-quotes, e.g., 'church.tif'.
gm_img_name : The name of the gamut-mapped image, including the single-quotes, e.g., 'church_gm.tif'.
diff_img_name : The name of the output difference image to be written including the single-quotes, e.g., 'church_diff.tif'.

The difference image is defined as 'gamut-mapped image - original image' in YyCxCz color space. Assuming the gamut mapping is properly performed, the difference between the original and the gamut-mapped image should not be too large; this results in the difference image not showing much information if no scaling is applied. By default, the difference image is scaled by 3 along each axis. By adding an optional fourth argument scale, you can choose a different amount of scaling to be used.
Also, because the Yy component should be in a specific range, Yy offset of 50 is added as well. The offset is added after scaling the difference image.

** How the generation of the mask image is done **
First we find the 3-D convex hull of the printer gamut. We assume that the convex hull represents the printer gamut reasonably. It is safe to assume that the mid-point of the Yy axis is inside the printer and the sRGB gamut; thus we shift all points by -58 in Yy direction so that the mid-point is aligned with the origin.
The convex hull consists of multiple planes; to find the planes, let us denote the three points of the printer gamut on the plane as P1, P2 and P3. The points should be written in homogeneous coordinates, thus each is written as a 4-vector. Transposing each vector and stacking them gives us a 3 by 4 matrix, and the null vector of the matrix gives us the homogeneous coordinate representation of the plane.
Next, we use the non-homogeneous representation of the three points, thus each point is written back to 3-vectors. Stacking them for each column gives us a 3 by 3 invertible matrix (if the matrix is not invertible, the points do not form a plane). All points on the plane can be written as a linear combination of the three points, and if the point is inside the triangle created by the three points, all coefficients of the linear combination should be between [0,1]. Otherwise at least one of the coefficient should be negative.
For each color point, we know that if we elongate the vector from the origin to the point infinitely, it will meet with the convex hull of the printer gamut at one of the planes. We can find the plane by looking at the linear combination and finding the one plane that gives us all positive coefficients. Then, by comparing the distance from the origin to the point where the elongated vector meets the plane with the distance from the origin to the original color point, we can determine whether that color is inside or outside the printer gamut.