Function cg = colourgrade_plot(cg)
cg = colourgrade_plot(cg,icm)
produces (data for) plots of a colour bar,
based on the colour grade given in the input
struct cg.
Two types of plots can be produced:
-- a plot in a window on screen, which is
requested by setting the input
cg.medium_plot{imedium} to 1;
-- a plot in an html/javascript page for
display in a webbrowser, which is
requested by setting the input
cg.medium_plot{imedium} to 2 or to
a string with the filename of the html
file.
The function stores a special struct
in the output struct, cg.hgeo_plot{imedium},
which can be used for further manipulation,
or e.g. to feed m-file hgeo_to_html.m
to make html files.
Multiple instantiations of these types can be
requested at once. Each particular instantiation
imedium has its own parameters and settings given
by input cg.(field){imedium}, where field is
a field name (ending with "_plot").
The second input argument icm is optional, and it
contains row indices to cg.colourmap, e.g. by
issuing icm = colourmap_icm(x,cg). In combination
with cg.exclude_plot{imedium}, one can exclude the
drawing of colours for one or more special values
(infra, max, ultra, NA/NaN) in the colour bar,
_unless_ they appear in icm.
At input, the struct cg must have the following
fields:
cg.gradeticks (column vector of booleans)
cg.gradetexts (column cell-array of strings)
cg.ordinal (boolean; false at default)
cg.colourmap (colourmap, an N*3 matrix
for N colours in total)
cg.icm_infra (row index to cg.colourmap)
cg.icm_min (row index to cg.colourmap)
cg.icm_max (row index to cg.colourmap)
cg.icm_ultra (row index to cg.colourmap)
cg.icm_nanan (row index to cg.colourmap)
The following fields in the input struct cg are
also required and they all contain a row cell-array
of the same number, in which element imedium
gives a setting for instatiation imedium:
cg.medium_plot = {m,...}
(if m is 1, the colour bar is
directly plotted in an Octave
figure window;
if m is 2, intermediate data
for html/js is produced;
if m contains a string, not
only intermediate data for
html/js is produced, but also
an html file)
cg.ncol_plot = {n,...}
(n is a scalar for the number of
columns into which the colour
bar is divided;
the grades in the colour bar are
always stacked vertically,
starting from the upper left
corner)
cg.proportional_plot = {b,...}
(if b is a boolean, it indicates
whether the grades in the colour
bar have to be displayed with
heights proportional to their
interval values;
if b contains an empty matrix [],
it will be internally set to
(~ is.ordinal))
cg.weight_plot = {w,...}
(w is the factor by which the
smallest ordinary grade height
is multiplied to obtain the height
of a special grade (i.e. for the
infra, upper bound, ultra and NA/NaN
values);
if w contains an empty matrix [],
it will be internally set to 1)
cg.barwidthfactor_plot = {c,...}
(c is the factor by which the
default width of the colour bar
is multiplied; setting c to a
smaller value than 1 yields more
space for texts within the columns;
if c contains an empty matrix [],
it will be internally set to 1)
cg.exclude_plot = {imun,...}
(the letters "i", "m", "u" and "n"
in string imun indicate which
special patches (for the infra,
maximum, ultra and NA/NaN values,
respectively) are excluded in
the drawing of the colour bar,
unless the respective values of
cg.icm_infra, cg.icm_max,
cg.icm_ultra and cg.icm_nanan
appear in the second input
argument icm respectively)
cg.scale_plot = {[sx sy],...}
(the row vector [sx sy] gives
the scale factors by which the
width and height of the colour
bar are multiplied;
put an NA value instead of a
scale factor to disable scaling
in the particular direction, or
put an empty matrix [] to disable
scaling totally)
cg.size_plot = {[lx ly],...}
(the row vector [lx ly] gives
the desired width and length of
the colour bar in absolute length
units;
put an NA value instead of a
size value to disable sizing
in the particular direction, or
put an empty matrix [] to disable
sizing totally)
Note that for each direction either scaling
or sizing is applied. A given finite value
for sizing has priority over a given finite
value for scaling.
Scaling or sizing is done before adding a
title or border.
cg.title_plot = {t,...}
(if t is a non-empty string, it is
printed as the title above the colour
bar)
cg.margin_plot = {[mx my],...}
(by the row vector [mx my], the
margins (in horizontal and vertical
directions, respectively) are set
for a border around the colour bar,
including the possible title;
put an empty matrix [] to disable
drawing a border)
cg.ul_plot = {[x0 y0] or [x0 y0 z0],...}
(the upper left corner of the total
drawing, i.e. the colour bar,
including the possible title and/or
border;
note that a 3d position is needed
for html/js output;
put an empty matrix [] to disable
the translation)
cg.linecolour_plot = {[r g b],...}
(the row vector with the 3 red-
green-blue fractions (0...1,
inclusively) defines the colour
for the tick lines and the border;
it defines also the text colour on
the html/js page)
cg.fontsizefactor_plot = {fs,...}
(the scalar fs is the factor by
which the (default) font size
is scaled;
put an empty matrix [] to disable
scaling)
cg.titlesizefactor_plot = {ts,...}
(the scalar ts is the factor by
which the actual font size
is scaled to obtain the font size
for the title;
if both fs and ts have been set,
the title font size is ts*fs times
the original (default) font size;
put an empty matrix [] to disable
scaling)
cg.division_plot = {[w1 w2 fl],...}
(this parameter applies only to
plots in an Octave figure;
the row vector indicates that
two plots (two sets of axes) are
drawn next to each other in the
figure window: the colour bar is
drawn in the right plot with a
relative width w2, and the left
plot with a relative width w1 is
left to the user;
if boolean fl is true, the colour
bar is stretched vertically to
fill the vertical space -- so
scaling and sizing have no visual
effect;
put an empty matrix [] to disable
the division)
cg.vh_plot = {[hx hy hz],...}
(this parameter applies only to
html/js output;
the row vector represents the 3-d
direction of the "horizontal" axis
of the colour bar and the direction
of text baselines)
cg.vv_plot = {[vx vy vz],...}
(this parameter applies only to
html/js output;
the row vector represents the 3-d
direction of the "vertical" axis
of the colour bar and the direction
orthogonal to the text baselines)
cg.textcode_plot = {tc,...}
(this parameter applies only to
html/js output;
tc indicates the coding of the
texts in cg.gradetexts;
the value of tc is either "html"
or "latex";
in the latter case, super- and
subscripts should always contain
braces, i.e. ^{...} and _{...})
At output, the struc cg contains new or renewed
fields:
cg.data_plot{imedium}
(a struct with basic common data
for the Octave and html/js plots)
cg.hgeo{imedium}
(a struct with intermediate data
for html/js;
the element is empty for Octave
plots)
The function internally calls the following
non-standard m-file:
-- colourgrade_plot_on_screen.m
-- colourgrade_plot_hgeo.m
-- reindexise.m
(c) 2026 fabien van mook
2026.08.20 release of this file within package "fvm-colourgrade" under GNU GPLv3+
