createcolormap.m

function cmap = createcolormap(varargin)
%% create a user-specified colormap
% This function allows to create colormap Nx3 array (RGB) with an arbitrary combination of colors. 
% RGB values between the specified colors will be smoothly connected by linear interpolation.
%
%    cmap = createcolormap(C);
%    cmap = createcolormap(n,C);
%    cmap = createcolormap(colorA, colorB);
%    cmap = createcolormap(n, colorA, colorB);
%    cmap = createcolormap(colorA, colorB, colorC, colorD, ...);
%    cmap = createcolormap(n, colorA, colorB, colorC, colorD, ...);
%
% where n is the number of segments for the output color scheme,
% and C is the RGB matrix of color junctions.
% 
% Usage examples:
% 1) blue-white-red (polar)
%   ```matlab
%   b = [0,0,1];
%   w = [1,1,1];
%   r = [1,0,0];
% 
%   bwr = createcolormap(b,w,r); % 256x3 array
%   
%   colormap(bwr)
%   colorbar
%   ```
% 
%   If you want to use dark blue and red colors, try below:
%   ```matlab
%   b = [0.0,0.0,0.5];
%   w = [1.0,1.0,1.0];
%   r = [0.5,0.0,0.0];
% 
%   bwr = createcolormap(b,w,r); % 256x3 array
% 
%   colormap(bwr)
%   colorbar
%   ```
% 
%   To create a more discrete color structure, input the number of elements in the first argument as shown below.
%   ```matlab
%   bwr = createcolormap(16,b,w,r); % 16x3 array 
%   ```
% 
% 
% 2) more complicated combination
% 
%   ```matlab
%   colorA = [0.0,1.0,0.0];
%   colorB = [1.0,0.5,0.5];
%   colorC = [0.5,0.5,0.5];
%   colorD = [1.0,1.0,0.0];
% 
%   cmap = createcolormap(64,colorA,colorB,colorC,colorD); % 64x3 array
% 
%   surf(peaks); 
%   colormap(cmap);
%   colorbar;
%   ```
% 
%
% 3) RGB matrix
%
%   ```matlab
%   cmap = createcolormap(rand(10,3)); % 10 random colors
%
%   surf(peaks);
%   colormap(cmap);
%   colorbar;
%   ```
%
%
% License:
%   MIT
% 
% Author:
%   Takuya Miyashita
%   Disaster Prevention Research Institute, Kyoto University, Japan
%   miyashita@hydrocoast.jp
% 
% Update (yyyy/mm/dd):
%   v0.1  2021/10/01
%   v0.2  2021/10/09
% 

%% nargin check
if nargin < 1
    error('Invalid number of arguments. At least one input argument is required.')
end

%% nargin==1, Color RGB matrix
if nargin==1
    n = 256;
    cmap = createcolormap(n,varargin{1});
    return
end

%% nargin >= 2
arg1 = varargin{1};
arg2 = varargin{2};

%% createcolormap(n,C) or createcolormap(colorA, colorB)
if nargin==2
    switch numel(arg1)
        case 1
            %% number of colors and RGB matrix input
            %      cmap = createcolormap(n,C)
            %  ->  cmap = createcolormap(n, C(1,:), C(2,:), C(3,:), ...)
            C = varargin{2};
            if size(C,1)<2 || size(C,2)~=3
                error('The color RGB array input must be an Nx3 (N>1) array.')
            end
            n = arg1;
            ncolor = size(C,1);
            Ccell = cell(ncolor,1);
            for i = 1:ncolor
                Ccell{i} = C(i,:);
            end
            cmap = createcolormap(n,Ccell{:});
            
        case 3
            %% two different colors input
            %      cmap = createcolormap(colorA, colorB)
            %  ->  cmap = createcolormap(256, colorA, colorB)
            if numel(arg2)~=3
                error('At least two different colors must be specified.')
            end
            color1 = arg1;
            color2 = arg2;
            n = 256;
            cmap = createcolormap(n,color1,color2);
        otherwise
            error('The number of elements in the input argument is invalid. It must be 1, 3, or Nx3.');
    end
    return
end

%% nargin >= 3
%% assign args
switch numel(arg1)
    case 1
        n = arg1;
        offset_color = 1;
        ncolor = nargin-1;
        color1 = arg2;
        color2 = varargin{3};
        if ncolor > 2
            color3 = varargin{4};
        end
    case 3
        n = 256;
        offset_color = 0;
        ncolor = nargin;
        color1 = arg1;
        color2 = arg2;
        color3 = varargin{3};
    otherwise
        error('The number of elements in the input argument is invalid. It must be 1, 3, or Nx3.');
end

%% arg validity
if numel(color1)~=3 || numel(color2)~=3
    error('Each color must be a three-element RGB array.')
end
if any(color1>1) || any(color2>1)  || ...
   any(color1<0) || any(color2<0)
    error('All RGB values must be in a range between 0 and 1.')
end
if n < 2*ncolor
    error('The number of segments is too small for the number of colors.')
end

%% 2 colors; main routine of this function
if ncolor == 2
    rv = linspace(color1(1),color2(1),n);
    gv = linspace(color1(2),color2(2),n);
    bv = linspace(color1(3),color2(3),n);
    cmap = [rv(:),gv(:),bv(:)];
    return
end

%% 3 colors; the main routine is recursively applied
if ncolor == 3
    if mod(n,2)==1
        nmid = floor(n/2);
        cmap1 = createcolormap(nmid,color1,color2);
        cmap2 = createcolormap(nmid,color2,color3);
        cmap = vertcat(cmap1,[color2(1),color2(2),color2(3)],cmap2);
    else
        nmid = n/2;
        cmap1 = createcolormap(nmid,color1,color2);
        cmap2 = createcolormap(nmid,color2,color3);
        cmap = vertcat(cmap1,cmap2);
    end
    return
end

%% 4+ colors; the main routine is recursively applied
if ncolor > 3
    n_each = diff(round(linspace(0,n,ncolor+1)));
    cmap = cell(ncolor,1);
    for i = 1:ncolor-1
        cmap{i} = createcolormap(n_each(i), varargin{i+offset_color}, varargin{i+1+offset_color});
    end
    cmap = vertcat(cmap{:});
    return
end

end