function file "colourgrade_init.m"

Function cg = colourgrade_init(cg)

completes struct cg with defaults and
and checks (some of) its consistency.

See into the code of the function for the
considered fields in cg and their default 
values.

In general, the series of functions of m-files 
colourgrade_XXX.m are applied in the following 
way and in the following ordre:

-1- define a series of grade values by setting
    reals in, e.g.:
      cg.gradevalues = [-1.0; -0.5; 0; 0.5; 1.0];

    and/or texts in, e.g.:
      cg.gradetexts = {"-1.0"; "-0.5"; "0"; "0.5"; "1.0"};

  - One can instantiate defaults with: 
      cg = colourgrade_init(cg);

  - Or, one can automatically define grade values
    ranging from the values in a given matrix v:
      cg = colourgrade_range(v,cg);

    This function provides a nicely legible
    range of grade values at default.

  - After setting cg.gradevalues and in the advent
    of using colourmap_bluered(), one can set 
    automatically cg.offset by:
      cg = colourgrade_range(v,cg);
    to obtain e.g. blue to cyan colours for negative
    values and yellow to red colours for positive 
    values (i.e. for cg.offsetthreshold = 0).

-2- define a colourmap with extra colours for
    infra, ultra and na/nan values, e.g. by 
    setting:
      cg.colourmapfun = @(n) jet(n);
      ngrade = length(cg.gradevalues) - 1;
      cg.colourmap = cg.colourmapfun(ngrade + 4);
      cg.icm_infra = 1;
      cg.icm_min   = 2;
      cg.icm_max   = 1+ngrade+1; 
      cg.icm_ultra = 1+ngrade+2;
      cg.icm_nanan = 1+ngrade+3;

  - This is executed by default by:
      cg = colourgrade_init(cg);

    and one can reproduce such a colourmap
    by issuing:
      cg.colourmap = [];
      cg = colourgrade_init(cg);

  - To automatically define a colourmap
    with given grade values and a given 
    colourmap function handle one can 
    also issue:
      cg = colourgrade_map(cg);

    By this function one can manipulate the
    "spacing" in the range of colours, so
    that the colours in the eventual 
    colourmap are optically rather
    distinct. 

  - To define a colourmap with colours ranging
    from blue to cyan and yellow to red, issue:
      cg = colourgrade_bluered(cg,n,reverse);

  - To define a colourmap with "streaked" 
    (very distinct) colours, issue:
      cg = colourgrade_streaked(cg,m,n);

-3- If one or more of the above mentioned 
    m-files colourgrade_XXX.m has not been 
    used so far, issue now: 
      cg = colourgrade_init(cg);

    to instantiate missing fields in struct
    cg and fill them with defaults, which
    are needed for the following steps.

    Note that the above mentioned m-files
    internally call colourgrade_init.m.
    M-files colourgrade_plot.m and 
    colourgrade_icm.m do not internally 
    call colourgrade_init.m. This is 
    designed on purpose to reduce overhead,
    and because these two m-files are used
    as final steps.

-4- to plot the grades:
      cg = colourgrade_plot(cg);

-5- to calculate the index to the colourmap
    cg.colourmap for each value in matrix x:
      icm = colourgrade_icm(x,cg);

The function internally calls the following
non-standard m-file:
  colourgrade_init_ngrade.m


(c) 2026 fabien van mook

2026.08.20 release of this file within package "fvm-colourgrade" under GNU GPLv3+