gtIPFCmap.m

function [cmap, Vsst, Vc_symm] = gtIPFCmap(phaseid, LD, varargin)
% GTIPFCMAP  Returns a colour map for the specified phase and lab/sample direction.
%
%     [cmap, Vsst, Vc_symm] = gtIPFCmap(phaseid, LD, varargin)
%     --------------------------------------------------------
%     Makes an IPF colourmap of the lab_ direction (LD) in the crystal 
%     coordinates. This can be specified as a second argument, otherwise we
%     assume the z-axis [0 0 1]
%
%     INPUT:
%       phaseid          = <int>     ID of the specific phase {1}
%       LD               = <double>  Lab direction to study   {[0 0 1]}
%
%     OPTIONAL INPUT (varargin as a list of pairs, see parse_pv_pairs.m)
%       'saturate'       = <logical> Saturate colors in the SST         {true}
%       'save'           = <logical> Save color map to cmap_phase<phaseid>.mat
%                                                                       {true}
%       'crystal_system' = <string>  Legacy to set (force) the crystal system
%                                    for old datasets
%       'r_vectors'      = <double>  Rodrigues vectors as N x 3 array
%   
%     OUTPUT:
%       cmap             = <double>  RGB color map, color code is the inverse
%                                    pole figure in the SST
%       Vsst             = <double>  Row vectors expressed in crystal frame
%                                    moved to the SST triangle
%       Vc_symm          = <double>  Row vectors expressed in crystal frame
%
%     Version 002 08-02-2013 by YGuilhem
%       Add r_vectors as optional input
%
%     Version 003 08-01-2013 by LNervo
%       Added second output argument: Vsst
%
%     Version 002 03-01-2013 by YGuilhem
%       Renamed gtIVPCmap to gtIPFCmap, changed colour saturation
%
%     Version 001 15-11-2012 by YGuilhem
%       Built by gathering old gtIVPcubCmap and gtIVPhexCmap functions

% Default parameters
par.saturate = true;
par.save = false;
par.crystal_system = '';
par.r_vectors = [];
par = parse_pv_pairs(par, varargin);

% Set default phaseid
if ~exist('phaseid', 'var') || isempty(phaseid)
    phaseid = 1;
end

% Set default lab direction if LD empty
if ~exist('LD', 'var') || isempty(LD)
    LD = [0 0 1];
end

% Get the r-vectors
r_vectors = [];
phaseDir = fullfile('4_grains', sprintf('phase_%02d', phaseid));
if ~isempty(par.r_vectors)
    r_vectors = par.r_vectors;
elseif exist(fullfile(phaseDir, 'r_vectors.mat'), 'file')
    load(fullfile(phaseDir, 'r_vectors.mat'));
elseif exist(fullfile(phaseDir, 'index.mat'), 'file')
    grain = [];
    load(fullfile(phaseDir, 'index.mat'), 'grain');
    r_vectors = gtIndexAllGrainValues(grain, 'R_vector', [], 1, 1:3);
else
    gtError('gtIPFCmap:missing_file', 'Could not find r_vectors.mat or index.mat file!');
end

% Resize r_vectors if needed
if size(r_vectors, 2) == 4
    r_vectors = r_vectors(:, 2:4);
end

% Get the crystal system
if isempty(par.crystal_system)
    parameters = load('parameters.mat');
    par.crystal_system = parameters.parameters.cryst(phaseid).crystal_system;
end

% Compute all orientation matrices g
%   Gcry = g Gsam
%   g = U = gtMathsRod2OriMat(r_vectors.')
all_g = gtMathsRod2OriMat(r_vectors.');

% Compute LDc = LD expressed in the crystal CS
LDc = gtVectorLab2Cryst(LD, all_g);

% Get the color and vector in the SST triangle
[map, Vsst, ~, Vc_symm] = gtCrystVector2SST(LDc, par.crystal_system, [], par.saturate);

cmap = [ 0 0 0 ; map ];

if par.save
    fileName = fullfile('6_rendering', sprintf('cmap_phase%02d.mat', phaseid));
    save(fileName, 'cmap');
end

end % end of function