Multiple-illuminant recovery routine

Contents

Syntax:

     [L, model] = recover_multi_illuminant(I);
     [L, model] = recover_multi_illuminant(I, options);

Description:

     Computes the power spectrum of multiple light sources in a scene.

Inputs:

     I: 3D hyperspectral image data cube (height x width x bands).
     options: Structure with the following fields
          bitdepth: Data type for the spectral cube, i.e. number of bits per
               spectral measurement. By fault this is 16.
          use_gaussian: If this variable is set to unity, the illuminants are
               recovered using a Gaussian prior. If this field is set to zero, a
               kernel density estimator (KDE) is used instead. The default is
               options.use_gaussian = 0.
          ndims: Upper bound for the number of illuminants in the scene.
               If ndims is not provided, it is automatically set to 3.
          ngmm: Number of mixtures used for the initialisation. This is only
              used if no initmodel is provided and, by default, is set to 3.
          method: Selects the method used to compute each of the illuminants in the scene.
               It can be any of the following strings:
              'HRK': Employs the method of Huynh and Robles-Kelly (A Solution of the
                  Dichromatic Model for Multispectral Photometric Invariance, International
                  Journal of Computer Vision 2010).
              'FS': Uses the method of Finlayson and Schaefer (Convex and Non-convex Illuminant
                  Constraints for Dichromatic Colour Constancy, CVPR 2001).
              'GW': Uses the Grey World method.
              'SG': Uses the Shade of Grey method.
              'WP': Uses the White Patch method.
              '1stOGE': Uses the 1st order Grey Edge method.
              '2ndOGE': Uses the 2nd order Grey Edge method.
          drate: Image downsampling rate for the Grey World, Shade of Grey,
                 White Patch and Grey Edge methods. The default is 1,
                 i.e. no downsampling.
          shadeOfGreyOrder: The order of the L^p mean used for the Shade of Grey method.
                 The default is 1.
          alpha: The value for the regularisation term used for the HRK
               (Huynh and Robles-Kelly) method. The default is 50.
          patches: Pre-selected patch geometry (can be left empty). This could be a set  
              of geometry data for image patches whose format is 
              [Top_left_y, top_left_x, height, width].
          PSFFactor: The factor used for the PSF employed to 'soften' the distribution of
              abundances for the illuminants. The default is 10.
          DEBUG: Defines the level of debugging information shown at execusion time (0<DEBUG<6).
             the default is 0.

Outputs:

     L: illuminants recovered from the scene.
     model: Structure containing the initial mixture model. This
          contains the following fields
          q: Number of components for the mixture.
          T_idx: Cell array containing the indexes for the pixels classified based
               upon the distance to the mixture means.
          centres_w: Means for the mixture weights.
          covars_w: Covariance matrices for the weighted mixtures.
          centres: Means for the unweighted mixtures.
          covars: Covariance matrices for the unweighted mixtures.
          Uq: Principal components for the sampled pixels. This is computed using SVD.
          EM_options: Set of options used for the em_gmm routine.
          prioL: Prior for each of the components over the data (image pixels).
          tip_record: Value of the pixel (instance) in the data which corresponds to the simplex
               that is better aligned to the mixture.
          pLx_map: Map of labels for the data accroding to the GMM and the
               Markov random field used for the train_gmm_model.
          pLx_prob: Map of probabilities for the data as delivered by the
               Markov random field.

See also:

     recover_global_illuminant, recover_dichromatic_parameters

Notes:

     This routine requires the use of the randwalk function and, hence,
     the SuiteSparse package, which can be downloaded from
     http://www.cise.ufl.edu/research/sparse/SuiteSparse.