====== Homework 01 - Image Coordinate System, Affine Transformation ======

==== Input Data ====

The input data can be downloaded from submission system BRUTE: the image ''daliborka_01.jpg'' and the set of seven 2D points ''u2''.

==== Task overview ====

  - Load ''daliborka_01.jpg'' bitmap image into a 3D matrix/array (rows x cols x 3).
  - Display the array as image.
  - Manually acquire coordinates of the set of seven points in the image corresponding to the tops of the five chimneys and the two towers. The points must be ordered **from left to right**. Store the point coordinates in a 2x7 matrix, i.e. the point coordinates are **column** vectors.
  - In the bitmap image, colorize the pixels that are nearest to the acquired points (use rounding, not flooring/ceiling). Use the following colors in the following order: **<fc #FF0000>red = [255, 0, 0]</fc>, <fc #00FF00>green = [0, 255, 0]</fc>, <fc #0000FF>blue = [0, 0, 255]</fc>, <fc #FF00FF>magenta = [255, 0, 255]</fc>, <fc #00FFFF>cyan = [0, 255, 255]</fc>, <fc #FFDD00>yellow = [255, 255, 0]</fc>, white = [255, 255, 255]** to colorize the respective seven points. The colors are defined by their R, G, B values: **color = [R, G, B]**. The order of colors must correspond to the order of points ''u''. Store the modified bitmap image as a file ''01_daliborka_points.png''.
  - Create function ''A = estimate_A( u2, u )'' for estimation of the affine transformation ''A'' (2×3 matrix) **from** n given points ''u2'' **to** image points ''u''. The inputs ''u2'', and ''u'' are 2xn  matrices, i.e., point coordinates are columns. 
    - Perform all possible selections of 3 point correspondences from all n correspondences.
    - For each triple compute the affine transformation ''Ai'' (exactly).
    - Compute transfer errors of the particular transformation for every correspondence, i.e., the euclidean distances between points ''u'' and ''ux''; the points ''ux'' are the points ''u2'' transformed by ''A''. Find the maximum error over the correspondences.
    - From the all computed transformations ''Ai'' select the one ''A'' that has the maximum transfer error minimal.
    - Assume general number of points, though we have only 7 points and 35 different triplets.
  - Display the image, the set of points ''u'' using the same colors as above, and 100× magnified transfer errors for the best ''A'' as red lines.
  - Export the graph as a pdf file ''01_daliborka_errs.pdf''.
  - Store the points ''u'' and the matrix ''A'' in the file ''01_points.mat'' (Matlab format).

^  Example of a points and transfer errors  ^
|  {{:courses:gvg:labs:01_daliborka_errs.png?400|}}  |


==== Python implementation details ====

Please note when there is a matrix required as an output data, we mean matrix implemented as ''np.array'', not as ''np.matrix'' or any other types. If you are using different type than ''np.array'', convert your result. 

Implement the solution in a single file ''hw01.py''. The file must contain the ''estimate_A'' function, such that it can be imported (by automatic evaluation) as

<code>import hw01
A = hw01.estimate_A( u2, u )
</code>

In addition, when run as main python script, it should do the task described above. Use the ''if %%__name__ ==  "__main__"%%'' test for separating code that should not run during import.

=== Upload summary ===

Upload an archive containing the following files:
  - ''01_points.mat''
  - ''01_daliborka_points.png''
  - ''01_daliborka_errs.pdf''
  - ''hw01.py'' - your implementation

Note: <fc #FF0000>All files must be in the same directory. Do not use any subdirectories.</fc>

=== Implementation hints ===

The following packages should be used:

<code>
import numpy as np                # for matrix computation and linear algebra
import matplotlib.pyplot as plt   # for drawing and image I/O
import scipy.io as sio            # for matlab file format output
import itertools                  # for generating all combinations
</code>

Image reading/writing as numpy array:

<code>
img = plt.imread( 'daliborka_01.jpg' )
# note that img is read-only, so a copy must be made to allow pixel modifications
img = img.copy()
img[0,0] = [ 255, 255, 255 ] # put white to upper left corner
plt.imsave( 'out.png', img )
</code>

Showing the image:

<code>
plt.imshow( img )
plt.show()
</code>

Manual input of 7 points:

<code>
u = plt.ginput( 7 )
</code>
    
Draw errors, export graph as pdf:

<code>
# ux ... points u2 transformed by A
e = 100 * ( ux - u ) # error displacements magnified by 100

fig = plt.figure() # figure handle to be used later
fig.clf()
plt.imshow( img )

# draw all points (in proper color) and errors
    
...
plt.plot( u[3,0], u[3,1], 'o', color=[1,0,1], fillstyle='none' ) # the 4-th point in magenta color
plt.plot( (u[3,0 ],u[3,0]+e[3,0]), (u[3,1],u[3,1]+e[3,1]), 'r-') # the 4-th displacement
...
    
plt.show()
    
fig.savefig( '01_daliborka_errs.pdf' )
</code>

Generator of all triplets:

<code>

n = u.shape[1]
iter = itertools.combinations( range( 0, n ), 3 ) # three of n

# iterate all combinations
for inx in iter:
  u_i = u[ :, inx]
  u_2i = u_2[ :, inx ]

  # do the processing for a single triplet ...   
</code>

Save results in MATLAB format:
<code>
sio.savemat('01_points.mat', {'u': u, 'A': A})
</code>

==== Matlab implementation details ====

Implement your solution in a main script ''hw01.m'', in the file ''estimate_A.m'' containing the function, and optionally in additional files for needed functions.

=== Upload summary ===

Upload an archive containing the following files:
  - ''01_points.mat''
  - ''01_daliborka_points.png''
  - ''01_daliborka_errs.pdf''
  - ''estimate_A.m''
  - ''hw01.m'' - your Matlab implementation. It makes all required figures, output files and prints. 
  - any other files required by hw01.m, such that the task is fully runnable

Note: <fc #FF0000>All files must be in the same directory. Do not use any subdirectories.</fc>

=== Implementation hints ===

Image read, display, write:

<code>img = imread( 'daliborka_01.jpg' ); % load the image
figure; % create a new figure
image( img ); % display the image, keep axes visible
axis image % display it with square pixels
img(1,1,:) = [255, 255, 255]; % put white to the upper left corner
imwrite( img, 'out.png' ); % write the image to a file
</code>

Manual input of 7 points:

<code>[x,y] = ginput(7);</code>

Draw errors, export graph as pdf:

<code>% ux .. points u2 transformed by A
e = 100 * ( ux - u ); % magnified error displacements
...
hold on % to plot over the image
...
plot( u(1,4), u(2,4), 'o', 'linewidth', 2, 'color', 'magenta' ) % the 4-th point 
plot( [ u(1,4) u(1,4)+e(1,4) ], [ u(2,4) u(2,4)+e(2,4) ], 'r-', 'linewidth', 2 ); % the 4-th error
...
hold off

fig2pdf( gcf, '01_daliborka_errs.pdf' ) % function provided in 'tools'</code>

Save results in MAT file:

<code>save( '01_points.mat', 'u', 'A' )</code>