Voir la source de G rect - A Matlab toolbox for georectifying digital images

== Introduction ==

This toolbox contains a series of Matlab functions for georectifying highly oblique digital images. This is useful in oceanography for obtaining quantitative
information on sea-surface patterns such as those induced by internal waves, fronts or sea-ice. 

Although this toobox was initially developed to georectify geophysical images it can be used just as well for rectifying laboratory images. The following images show examples of such image rectifications.
{|
|[[File:Massif1.png|thumb|left|Example of a geophysical photo showing sea-ice distribution in the St. Lawrence Estuary.]] 
|[[File:Massif2.png|thumb|left|Same as previous photo once georectified.]] 
|[[File:Lab1.png|thumb|left|Example of a laboratory basin photo. ]] 
|[[File:Lab2.png|thumb|left|Same as previous once georectified.]] 
|}

== How to get the package ==
Click on this link to download the package: [[Media:g_rect_package_1.0.zip|g_rect_package_1.0]].

Once expanded the <tt>g_rect</tt> package is organized as follow:
<tt>
* g_rect_package
** src (the source codes)
*** g_rect (contains the main georectification functions)
*** g_calib (contains camera calibration functions)
*** g_stabilize (contains image stabilization functions)
** Examples
*** Field (a field example)
*** Lab (a lab example)
</tt>
The main georectification functions are found within the <tt>g_rect</tt> directory. The other two directories are for more
advanced processing if the camera needs to be calibrated (<tt>g_calib</tt>) or if you need to stabilize (i.e. removing small movements 
between successive images) a series of images (<tt>g_stabilize</tt>). You may not need to play at all with these.

== g_rect: Quick Start ==

For a quick start let's only play with the main function called <tt>g_rect.m</tt> found under the <tt>g_rect</tt> directory. First you should set this directory into your Matlab path (File -> Set Path). 

Then go with Matlab into the directory Examples/Field. You will find there an image (IMG_6614.JPG) and a file named <tt>parameters.dat</tt>.
This is the main input parameter file that you need to edit for a given image or for a given series of images. 

This input parameter file looks like this:

=== Input file: parameters.dat ===
<tt>
 % I/O information
 imgFname      =  'IMG_6614.JPG';   % This is the reference image
 firstImgFname =  'IMG_6614.JPG';  % This is just to indicate the first image of a sequence 
 lastImgFname  =  'IMG_6614.JPG'; % This is just to indicate the last image of a sequence 
 outputFname   =  'g_rect.mat';      % This is the output filename where the new coordinates will be stored.
 
 % Field or lab case situation.
 % Set field = true for field situation and field = false for lab situation.
 % Lab situation does not expect to work with latitude and longitude but simply with meters.
 field = true; 
  
 % Camera position
 % lat/lon for field situation
 % meter for lab situation
 LON0 = -70.6010167;
 LAT0 =  47.2713000; 
  
 % Offset from center of the principal point (generally zero)
 ic = 0;
 jc = 0;
 
 % Parameters
 hfov =      45.0;     % Field of view of the camera
 lambda =    2;        % Dip angle above vertical (e.g. straight down = 90, horizontal = 0)
 phi =       0.0;      % Tilt angle (generally close to 0)
 H =         720;      % Camera altitude
 theta =     70.0;     % View angle clockwise from North (e.g. straight East = 90)
 
 % Uncertainty in parameters. Set the uncertainty to 0.0 for fixed parameters.
 dhfov =     20.0; 
 dlambda =   10.0;
 dphi =      5.0;
 dH =        0.0; 
 dtheta =    20.0; 
 
 % Order of the polynomial correction (0, 1 or 2) 
 polyOrder = 1;
 
 % To save memory calculation can be done in single precision.
 % For higher precision set the variable 'precision' to 'double'.
 precision = 'double';
 
 % Ground Control Points (GCP). 
 % The data must come right after the gcpData = true 
 gcpData = true;
 360  829  -70.561367  47.303783
  54  719  -70.54500   47.335
  99  661  -70.505     47.375
 452  641  -70.435     47.389
 429  633  -70.418     47.408
 816  644  -70.393     47.368
</tt>
----

This file contains all parameters required to perform a georectification. You can add spaces and comments as you wish within this file. 
One specify format needs however to be respected. The ground control points (gcp) must appear right after the variable <tt>gcpData = true</tt>;
These ground control points represent the lon-lat position associated with some image coordinates. 

If you know perfectly some of the camera parameters (e.g. the field of view) you simply have to set the uncertainty of this parameter to zero (e.g. dfov = 0).
Otherwise, for other parameters with some uncertainty the minimization algorithm will search within the given uncertainty to find the best parameters 
values that gives a best fit between the image control points once georectified and the ground control points (see Bourgault, 2008, for details). 

To run the georectification, all you have to do in principle is to edit this file and to type in Matlab <tt>g_rect</tt> at the command line. 
You will then be prompted for the name of the input parameter file (it does not have to be called <tt>parameters.in</tt>). You image will appear
with the GCPs as well as a table re-listing all of your parameters. If you're ok with this type <tt>enter</tt>. 

You will then see the algorithm searching the parameter space and will eventually return the result for the set of parameters found. A file will be created, named
accoring to the name given in the variable <tt>outputFname</tt>.
This is the main result file that contain all important variables. The most important matrices created are named <tt>LAT</tt> and <tt>LON</tt>.
These two matrices have the same size as your original image and provides the latitude and longitude of every associated pixel. You can then
make a figure using for example the command <tt>pcolor</tt> (or <tt>m_pcolor</tt> if you use the <tt>m_map</tt> package) with <tt>LON</tt> and <tt>LAT</tt>
as the arguments for the position and a third argument for the pixel intensity which could simply be the mean of the RGB channel if you want to reduce
a color image to a grayscale image. Fancier color representation could also be done but this is up to you. 
 
The <tt>g_rect</tt> package works best with the <tt>m_map</tt> package installed.

== g_calib ==
Camera calibration could be done if required. All files needed are found in the <tt>g_calib</tt> folder. 
The package comes from this site that you should consult for information on how to perform a camera calibration: http://www.vision.caltech.edu/bouguetj/calib_doc/

Essentially, a camera calibration removes distortion associated with a lens as shown by comparing the images below.
{|
|[[File:sample_original.jpg|thumb|left|Example of an original image showing obvious distortion. The checkboard should be flat but curvature is seen.]] 
|[[File:sample_calibrated.png|thumb|left|The same image once calibrated.]] 
|}

Note that this step is not always required for two main reasons. Firstly, it could be that the camera and lens you use has little acceptable distortion.
Secondly, the algorithm in <tt>g_rect</tt> provides a polynomial  correction (of order 1 or 2) to the image if you have enough ground control points (it is the variable
name <tt>polyOrder</tt> in the input parameter file). This is an indirect way of correcting for lens distortion that is often acceptable.

== g_stablilize ==
Generally, sequences of images are collected from a fixed tripod. For example, you may want to observe the movement of sea-ice over a semi-diurnal cycle at a sample rate
of 1 image per minute (roughly 750 images). If the tripod does not move during the collection then the georectification 
procedure described above with <tt>g_rect</tt> only needs to be applied to one image. The coordinate matrices <tt>LAT</tt> and <tt>LON</tt> can then be applied to all 
images of the sequence.  

In practice, the camera moves for many reasons. It may be because you need to replace the batteries, because you touched the camera by mistake, because you need to change 
a camera setting half-way through the experiment or, if you're outside, because wind gusts induce small but perceptible camera movements. If you don't correct for these 
movements, the sequence will be jumpy if you make a movie with it. This may lead to inaccurate measurements if you need to compare two frames, say for calculating ice drift velocities.

To fix this problem you could apply a new georectification to every images that has moved. This is however not practical if, for example, camera movements were randomly induced by wind 
gusts. In some windy situations, just about every image show small but perceptible camera movements. You don't want to apply the georectification 750 times.   

This is when camera stabilization becomes very useful. The idea is to choose one reference image, generally the first image of the sequence, and to geometrically transform all other
images, for translation, scale and rotation, to match the reference image as close as possible. This step is done before doing the georectification. 
However, for this to work we need to tell the algorithm which parts of the image are not supposed to have moved. 
The algorithm cannot tell by itself whether it is the camera that moved of the ice we are observing.  These portions of image are called region of interest (ROI).
Details of this procedure are described by Farid and Woodward (2007). The Matlab algorithm found in Farid and Woodward (2007) have been adapted here.

The folder <tt>g_stabilize</tt> contains a series of Matlab functions for performing the image stabilization. However, you need to be familiar with only the following two functions:
=== <tt>g_roi.m</tt> ===
This function is a utility that helps you determine region of interest. To use it you simply have to call the function with your reference image filename such as 
 <tt>g_roi('IMG_1.jpg")</tt> 
and follow the instructions. Essentially, you will be asked to make polygons around regions of interests (roi). These are regions
in your image that don't move. Try not to take moving patterns on the water or the sky that has moving clouds. 

This function only puts 1s in ROIs and 0s everywhere else. Once you're done a file names roi.mat is created. The blue and red image below shows
the ROI image corresponding to the image #1. This file is then needed by the next function that performs
the actual stabilization.

===<tt>g_stabilize.m</tt> ===
Once you have created the <tt>roi.mat</tt> file you simply type, in principle, the following command:

 <tt>g_stabilize(root_img_name,ext,id_img_ref,id_img_first,id_img_last)</tt>

where
 <tt>root_img_name</tt> is the root of the images name (e.g. <tt>IMG_</tt>;
 <tt>ext</tt> is the images extension (e.g. <tt>'png'</tt> or <tt>'jpg'</tt>; 
 <tt>id_img_ref</tt> is the number that identifies the reference image;
 <tt>id_img_first</tt> is the number of the first image of the sequence you want to stabilize;
 <tt>id_img_last</tt> is the number of the last image of the sequence you want to stabilize; 

This will recreate a series of images with the same name but with the suffix <tt>_stable</tt> added to your image filename. 
The original images are conserved. 

=== Remark ===
Because of rapidly changing light conditions outside, the stabilize algorithm may not work as you would hope. This is because region of interests
are often subject to moving cloud shadows that may fool the algorithm. In some cases it may be necessary to filter first you image and to 
apply equalizers in order to minimize as much as possible such motions. In general, the algorithm does quite a good job. You can appreciate 
the effect by downloading and comparing <tt>IMG_1.JPG</tt> with <tt>IMG_58.JPG</tt> and <tt>IMG_58_stable.JPG</tt> below. 

{|
|[[File:IMG_1.JPG|thumb|left|Example of the first image of a sequence (image #1). All subsequent images can be stabilized using this image as the reference.]] 
|[[File:IMG_58.JPG|thumb|left|Image #58 shows important differences in the view point compared to the first image. It was very windy that day and the tripod moved with wind gusts.]] 
|[[File:roi.png|thumb|left|Region of interest (ROI) needed for the stabilization algorithm. This can be done with the function <tt>g_roi.m</tt>]] 
|[[File:IMG_58_stable.JPG|thumb|left|Image #58 once stabilized relative to image #1.]] 
|}

== References ==
* Bourgault (2008), [[Media:Bourgault_2008.pdf|Shore-based photogrammetry of river ice]], ''Can. J. Civil Eng.''.
* Bourgault et al (2011), [[Media:Bourgault_et_al_2011a.pdf|Field observations of a large-amplitude internal wavetrain and its reflection off a steep slope]], ''J. Phys. Oceanogr.''
* Farid and Woodward (2007), [[Media:Farid_Woodward_2007.pdf|Video stabilization and enhancement]], Unpublished.
* Pawlowicz (2003), [[Media:Pawlowicz_2003.pdf|Quantitative visualization of geophysical flows using low-cost oblique digital time-lapse imaging]], IEEE ''J. Ocean. Eng.''