Help for MARSREFMESH

Marsrefmesh is a program to refine the vertices coordinates (X,Y,Z) of a
mesh which models a surface based on some photoconsistency criteria of a series 
of images of that surface.

EXECUTION:

*IMPORTANT* - See Usage before using the program.

marsrefmesh inp=ascii_listOfFiles refimage=1,2 in_mesh=file.OBJ 
out_mesh=fileOut.OBJ

where:
- ascii_listoffiles is a text file containing all the images that will be 
used in the refinement.
- refimage ids represent the index of the images in ascii_listOfFiles that will
be considered reference (see below for more information). 1-based index.
- in_mesh is the input mesh file that is going to be refined
- out_mesh is the ouput mesh filename


USAGE:

There are important considerations to take into account before using that 
program:

[1] This program should be used when several images of the area modelized by the
mesh are available. Most of the time, the mesh is obtained from the correlation
of a stereo pair of images. If only that pair of images is available, this 
program should NOT be used. At least no details retrieval should be expected. 
May be the program can be used as a denoiser, but that has not been tested in 
this configuration.
However, if more than two images on the area with reasonable incidence angles 
are available, this program could be used.

[2] The traditional way of obtaining meshes in mars pipeline is to generate a
mesh with vertices for every pixels of the image (because correlation is 
carried on every single pixel of the reference/master image). 
Given how this program works, the mesh must be subsampled to insure that a mesh 
face/triangle receive a couple of pixels. This can be achieved during the 
meshing (marsmesh program) by subsampling the output (X_SUBSAMPLE, Y_SUBSAMPLE 
parameters in marsmesh) by a factor of 4 for instance. We are not really loosing
information by subsampling the mesh, because in its full resolution mode, the 
mesh is highly oversampled as the correlation patch is at least 7x7 pixels, 
although most of the time around 7x11 pixels.

[3] The program is based on the optimization of a global score (coherency of the
images through the mesh) and a regularization score (smoothness of the surface).
However, the balancing between the data attachement (coherency of images) and the
regularization (surface smoothness) is not trivial, without any hard and fast 
rule. The scaling of the regularization (LAMBDA) has to be adjusted on a 
case-by-case study. To estimate what LAMBDA shoulde be, a first run of the 
program with -EVALUATE will provide the raw data and regularization costs. From
these values, LAMBDA can be estimated (still a tricky excercise which will 
require some experimentation) and the program can be re-run without -ESTIMATE.



METHOD:

This program is based on the following papers:
- High accuracy and visibility-consistent dense multiview stereo, Vu et al.,
  IEEE Transactions PAMI, vol 34., no. 5, 2012
- Discrete differential-geometry operators for triangulated 2-manifold, Meyer et
  al.,  Hege HC., Polthier K. (eds) Visualization and Mathematics III. Springer.
  2003.
- Implicit fairing of irregular meshes using diffusion and curvature flow, 
  SIGGRAPH conference proceedings, pp 317-324, 1999


The program is based on the variational refinement of the mesh vertices based on
photo-consistency.

A global score is computed that consists of the sum of the (inverse of) the 
correlation between all the images once they have been projected on the mesh and
back-projected to the reference images. That score is augmented with a 
measurement of the global curvature. The mesh vertices locations are iteratively
refined to minimize that global score using an unconstrained minimization 
algorithm. This is a classical regularized approach where the data attachement 
term is given by the inverse of the correlation score (the better the 
correlation, the smaller the contribution to the score) and a regularization 
term, given by the curvature cost, which favors smooth surface and penalize 
strong bending. 

At least one reference image is needed. If more than one reference image is 
given, that means that, in turn, all the images are projected onto the reference
and correlated, and the score cumulated. Potentially, all images of the list can
also be reference images.

The balancing between data attachement and regularization is controlled with
LAMBDA. A dry run of the program with -EVALUATE will provide estimates of the
data attachement and regularization costs, from which LAMBDA can be estimated.



NOTES:



COGNIZANT PROGRAMMER:  Francois Ayoub

HISTORY:
  2018-09-01 Francois Ayoub - Initial marsrefmesh implementation
  2019-12-10 Walt Bunch - IDS-7926 Initialized some variables; cleaned up other -Wall warnings; added unit test.
             Note line 2262:
             texturedTriangles[i] == 1; // TODO: was this intended to be an assignment?

PARAMETERS: