15.2.3 Аннотации графиков

К существующему графику можно добавить заголовки, подписи осей, легенды и произвольный текст. Например:

x = -10:0.1:10;
plot (x, sin (x));
title ("sin(x) for x = -10:0.1:10");
xlabel ("x");
ylabel ("sin (x)");
text (pi, 0.7, "arbitrary text");
legend ("sin (x)");

Функции grid и box также можно использовать для добавления к графику линий сетки и рамки. По умолчанию сетка выключена, а линии рамки включены.

Наконец, с помощью функции annotation можно добавить стрелки, текст, а также прямоугольные или эллиптические рамки, чтобы выделить части графика. Эти объекты рисуются в невидимой системе координат поверх всех остальных систем координат.

: title (string)

: title (string, prop, val, …)

: title (hax, …)

: h = title (…)

Задаёт строку, используемую в качестве заголовка текущей оси.

Необязательный список пар свойство/значение можно использовать для изменения внешнего вида созданного текстового объекта заголовка.

Если первый аргумент hax является дескриптором оси или легенды, заголовок добавляется к этому объекту, а не к текущей оси, возвращаемой функцией gca.

Необязательное возвращаемое значение h — это графический дескриптор созданного текстового объекта.

См. также: xlabel, ylabel, zlabel, text.

: legend ()

: legend command

: legend (str1, str2, …)

: legend (charmat)

: legend ({cellstr})

: legend (…, property, value, …)

: legend (hobjs, …)

: legend ("command")

: legend (hax, …)

: legend (hleg, …)

: hleg = legend (…)

Отображает легенду для текущей оси, используя заданные строки в качестве подписей.

Записи легенды можно задать отдельными аргументами-строками, символьным массивом или массивом ячеек со строками. Если имена подписей можно спутать со свойствами легенды или аргументами command, подписи следует заключить в массив ячеек со строками.

Если первый аргумент hax является дескриптором оси, легенда добавляется к этой оси, а не к текущей оси, возвращаемой функцией gca.

Если первый аргумент hleg является дескриптором легенды, операция выполняется с этой легендой, а не с легендой текущей оси.

Подписи легенды связываются с дочерними объектами оси: первая подпись назначается первому объекту, построенному на оси, вторая — следующему построенному объекту и т. д. Чтобы подписать отдельные объекты данных, не подписывая их все, укажите их графические дескрипторы во входном аргументе hobjs.

С помощью command доступны следующие настройки:

"show"

Показать легенду на графике

"hide"

Скрыть легенду на графике

"toggle"

Переключение между "hide" и "show"

"boxon"

Показать рамку вокруг легенды (по умолчанию)

"boxoff"

Скрыть рамку вокруг легенды

"right"

Разместить текст подписи справа от условных обозначений (по умолчанию)

"left"

Разместить текст подписи слева от условных обозначений

"off"

Удалить объект легенды

Функция legend создаёт графический объект с различными свойствами, которыми можно управлять с помощью get/set. Кроме того, свойства можно задавать непосредственно при вызове legend, указывая пары свойство/значение. При использовании этой формы вызова подписи необходимо указывать как массив ячеек со строками. Свойства графических объектов подробно описаны в разделе Свойства графических объектов.

Ниже приведён неполный список поддерживаемых свойств легенды:

autoupdate: "off" | {"on"}

Управляет автоматическим обновлением числа элементов легенды при добавлении объектов в связанную ось или удалении их из неё. Например:

## Create a single plot with its legend.
figure ();
plot (1:10);
legend ("Slope 1");
## Add another plot and specify its displayname so that
## the legend is correctly updated.
hold on;
plot ((1:10) * 2, "displayname", "Slope 2");
## Stop automatic updates for further plots.
legend ("autoupdate", "off");
plot ((1:10) * 3);

box: "off" | {"on"}

Управляет отображением рамки вокруг легенды.

location: "best" | "bestoutside" |

"east" | "eastoutside" | "none" | "north" | {"northeast"} | "northeastoutside" | "northoutside" | "northwest"| "northwestoutside" | "south" | "southeast" | "southeastoutside" | "southoutside" | "southwest" | "southwestoutside" | "west" | "westoutside" Управляет расположением легенды.

numcolumns: скалярное целое число, по умолчанию 1

Управляет числом столбцов, используемых при расположении элементов легенды. Например:

figure ();
plot (rand (30));
legend ("numcolumns", 3);

При установке numcolumns свойство numcolumnsmode также принудительно получает значение "manual".

orientation: "horizontal" | {"vertical"}

Управляет расположением элементов легенды по вертикали (в столбцах) или по горизонтали (в строках).

string: строка | массив ячеек со строками

Список подписей элементов легенды. Например:

figure ();
plot (rand (20));
## Let legend choose names automatically
hl = legend ();
## Selectively change some names
str = get (hl, "string");
str(1:5:end) = "Garbage";
set (hl, "string", str);

textcolor: спецификация цвета, по умолчанию [0 0 0]

Управляет цветом текста подписей элементов легенды.

Полный список поддерживаемых свойств легенды приведён в разделе Свойства легенды.

Легенда реализована как дополнительный объект оси, свойство tag которого имеет значение "legend". Свойствами объекта легенды можно управлять напрямую с помощью set.

Необязательное выходное значение hleg — это дескриптор объекта легенды.

Примечание по реализации: Текст подписей легенды задаётся при вызове legend или берётся из свойства DisplayName графических объектов. Это свойство есть только у объектов данных, таких как линии, области и поверхности; у осей, рисунков и т. п. его нет, поэтому они никогда не отображаются в легенде. Если подписи или свойства DisplayName отсутствуют, текст подписей формируется просто как "data1", "data2", …, "dataN".

Изначально свойству FontSize легенды задаётся значение, равное 90% значения FontSize связанной с ней оси. При необходимости используйте set, чтобы переопределить это значение.

: text (x, y, string)

: text (x, y, z, string)

: text (…, prop, val, …)

: text (hax, …)

: h = text (…)

Создаёт на текущей оси текстовый объект со строкой string в точке x, y, (z).

Если x, y, (z) — векторы, можно задать несколько местоположений. Несколько строк можно указать с помощью символьной матрицы или массива ячеек со строками.

Для управления внешним видом текста можно использовать необязательные пары «свойство/значение».

Если первый аргумент hax является дескриптором оси, текст добавляется к этой оси, а не к текущей оси, возвращаемой функцией gca.

Необязательное возвращаемое значение h — это вектор графических дескрипторов созданных текстовых объектов.

Пример 1: многострочный текст тремя разными способами

text (0.5, 0.8, {"Line 1", "Line 2"})
text (0.5, 0.6, ["Line 1"; "Line 2"])
text (0.5, 0.4, "Line 1\nLine 2")

Пример 2: текст в нескольких местах

text ([0.2, 0.2], [0.8, 0.6], "Same text at two locations")
text ([0.4, 0.4], [0.8, 0.6], {"Point 1 Text", "Point 2 text"})
text ([0.6, 0.6], [0.8, 0.6], {{"Point 1 Line 1", "Point 1 Line 2},
                               "Point 2 text"})

Пример 2: настройка внешнего вида с помощью свойств текста

ht = text (0.5, 0.5, "Hello World", "fontsize", 20);
set (ht, "color", "red");

Примечания по программированию: полный список свойств приведён в разделе Свойства текста.

Любые числовые элементы массива ячеек будут преобразованы в текст с помощью sprintf ("%g"). Для более точного управления внешним видом преобразуйте числовые элементы в строки с помощью num2str, sprintf и т. д. до вызова text.

См. также: gtext, title, xlabel, ylabel, zlabel.

: xlabel (string)

: xlabel (string, property, val, …)

: xlabel (hax, …)

: h = xlabel (…)

Задаёт строку для подписи оси x текущей оси.

Необязательный список пар свойство/значение можно использовать для изменения свойств созданной текстовой подписи.

Полный список свойств текстовых объектов приведён в разделе Свойства текста.

Если первый аргумент hax является дескриптором оси, операция выполняется с этой осью, а не с текущей осью, возвращаемой функцией gca.

Необязательное возвращаемое значение h — это графический дескриптор созданного текстового объекта.

См. также: ylabel, zlabel, datetick, title, text.

: ylabel (string)

: ylabel (string, property, val, …)

: ylabel (hax, …)

: h = ylabel (…)

Задаёт строку для подписи оси y текущей оси.

Если указан hax, подпись добавляется к определённой им оси.

Необязательный список пар свойство/значение можно использовать для изменения свойств созданной текстовой подписи.

Полный список свойств текстовых объектов приведён в разделе Свойства текста.

Если первый аргумент hax является дескриптором оси, операция выполняется с этой осью, а не с текущей осью, возвращаемой функцией gca.

Необязательное возвращаемое значение h — это графический дескриптор созданного текстового объекта.

См. также: xlabel, zlabel, datetick, title, text.

: zlabel (string)

: zlabel (string, property, val, …)

: zlabel (hax, …)

: h = zlabel (…)

Задаёт строку для подписи оси z текущей оси.

Необязательный список пар свойство/значение можно использовать для изменения свойств созданной текстовой подписи.

Полный список свойств текстовых объектов приведён в разделе Свойства текста.

Если первый аргумент hax является дескриптором оси, операция выполняется с этой осью, а не с текущей осью, возвращаемой функцией gca.

Необязательное возвращаемое значение h — это графический дескриптор созданного текстового объекта.

См. также: xlabel, ylabel, datetick, title, text.

: clabel (c, h)

: clabel (c, h, v)

: clabel (c, h, "manual")

: clabel (c)

: clabel (…, prop, val, …)

: hlabels = clabel (…)

Добавляет подписи к линиям уровня на контурном графике.

Уровни задаются матрицей контуров c, возвращаемой функциями contour, contourc, contourf и contour3. Подписи контуров поворачиваются в соответствии с локальным направлением линии и располагаются по её центру. Положение подписей вдоль линии контура выбирается случайным образом.

Если аргумент h является дескриптором объекта группы контуров, подписи добавляются к этому графику, а не к графику на текущей оси, возвращаемой функцией gca.

По умолчанию подписываются все контуры. Однако контуры для подписей можно задать вектором v. Если указан аргумент "manual", контуры для подписей можно выбрать с помощью мыши.

Можно указать дополнительные пары «свойство/значение», допустимые для текстовых объектов; они передаются базовым текстовым объектам. Кроме того, доступно свойство группы контуров "LabelSpacing", определяющее расстояние между подписями на контуре. По умолчанию оно равно 144 пунктам, или 2 дюймам.

Необязательное возвращаемое значение hlabels — это вектор графических дескрипторов текстовых объектов, представляющих каждую подпись. Свойство "userdata" текстовых объектов содержит числовое значение подписи контура.

Полный список свойств текстовых объектов приведён в разделе Свойства текста.

[c, h] = contour (peaks (), -4 : 6);
clabel (c, h, -4:2:6, "fontsize", 12);

См. также: contour, contourf, contour3, meshc, surfc, text.

: box

: box on

: box off

: box (hax, …)

Управляет отображением рамки оси.

Аргументом может быть "on" или "off". Если аргумент не указан, текущее состояние рамки переключается.

Если первый аргумент hax является дескриптором оси, операция выполняется с этой осью, а не с текущей осью, возвращаемой функцией gca.

См. также: axis, grid.

: grid

: grid on

: grid off

: grid minor

: grid minor on

: grid minor off

: grid (hax, …)

Управляет отображением линий сетки графика.

В качестве аргумента состояния функции можно указать "on" или "off". Если аргумент не указан, текущее состояние сетки переключается.

Если первый аргумент — "minor", все последующие команды изменяют минорную сетку, а не основную.

Если первый аргумент hax является дескриптором оси, операция выполняется с этой осью, а не с текущей осью, возвращаемой функцией gca.

Для управления линиями сетки отдельной оси используйте функцию set. Например:

set (gca, "ygrid", "on");

См. также: axis, box.

: colorbar

: colorbar (…, loc)

: colorbar (delete_option)

: colorbar (hcb, …)

: colorbar (hax, …)

: colorbar (…, "peer", hax, …)

: colorbar (…, "location", loc, …)

: colorbar (…, prop, val, …)

: h = colorbar (…)

Добавляет цветовую шкалу к текущей оси.

Цветовая шкала отображает текущую карту цветов и числовые отметки, позволяющие интерпретировать шкалу цветов.

Необязательный входной аргумент loc задаёт положение цветовой шкалы. Если он указан, то должен быть последним аргументом функции colorbar. Допустимые значения loc:

"EastOutside"

Разместить цветовую шкалу справа от графика, снаружи. Это значение используется по умолчанию.

"East"

Разместить цветовую шкалу справа внутри графика.

"WestOutside"

Разместить цветовую шкалу слева от графика, снаружи.

"West"

Разместить цветовую шкалу слева внутри графика.

"NorthOutside"

Разместить цветовую шкалу над графиком.

"North"

Разместить цветовую шкалу в верхней части графика.

"SouthOutside"

Разместить цветовую шкалу под графиком.

"South"

Разместить цветовую шкалу в нижней части графика.

Чтобы удалить цветовую шкалу с графика, используйте любое из следующих ключевых слов в качестве delete_option: "off", "delete", "hide".

Если первый аргумент hax является дескриптором оси, цветовая шкала добавляется к этой оси, а не к текущей оси, возвращаемой функцией gca. Кроме того, если указан аргумент "peer", следующий аргумент рассматривается как дескриптор оси, к которой нужно добавить цветовую шкалу. Синтаксис вызова "peer" может быть удалён в будущем и не рекомендуется к использованию.

Если первый аргумент hcb является дескриптором объекта цветовой шкалы, операция выполняется непосредственно с этой цветовой шкалой.

Дополнительные пары «свойство/значение» передаются непосредственно базовому объекту оси. Полный список свойств приведён в разделе Свойства осей.

Необязательное возвращаемое значение h — это графический дескриптор созданного объекта цветовой шкалы.

Примечание по реализации: цветовая шкала создаётся как дополнительный объект оси, свойству "tag" которого присваивается значение "colorbar". Созданный объект имеет дополнительное свойство "location", управляющее расположением цветовой шкалы.

См. также: colormap.

: annotation (type)

: annotation ("line", x, y)

: annotation ("arrow", x, y)

: annotation ("doublearrow", x, y)

: annotation ("textarrow", x, y)

: annotation ("textbox", pos)

: annotation ("rectangle", pos)

: annotation ("ellipse", pos)

: annotation (…, prop, val)

: annotation (hf, …)

: h = annotation (…)

Наносит аннотации, чтобы выделить части рисунка.

Аннотацию по умолчанию можно создать, указав только ее type.

В противном случае можно выбрать тип аннотации, а затем задать ее положение: координатами x и y для аннотаций на основе линий или вектором положения pos для остальных. В обоих случаях координаты интерпретируются с учетом свойства "units" объекта аннотации. По умолчанию используется "normalized", то есть координаты нижнего левого угла рисунка равны ‘[0 0]’, а верхнего правого угла — ‘[1 1]’.

Если первый аргумент hf — дескриптор рисунка, график будет построен в этом рисунке, а не в текущем рисунке, возвращаемом функцией gcf.

Для настройки внешнего вида аннотации можно передать дополнительные аргументы в виде пар prop/val.

Необязательное возвращаемое значение h — это графический дескриптор созданного объекта аннотации. Его можно использовать с функцией set для настройки существующего объекта аннотации.

У всех объектов аннотаций есть два общих свойства:

• "units": единицы измерения, в которых интерпретируются координаты.
  Значением может быть одно из "centimeters" | "characters" | "inches" | "{normalized}" | "pixels" | "points".
• "position": вектор из четырех элементов [x0 y0 width height].
  Вектор задает координаты (x0,y0) начала объекта аннотации, а также его ширину и высоту. Ширина и высота могут быть отрицательными в зависимости от ориентации объекта.

Допустимые типы аннотаций и их свойства описаны ниже:

"line"

Создает линию. x и y должны быть двухэлементными векторами, задающими координаты x и y обоих концов линии.

Линию можно настроить с помощью свойств "linewidth", "linestyle" и "color" так же, как и объекты line.

"arrow"

Создает стрелку. Вторая точка в векторах x и y задает координаты наконечника стрелки.

Помимо свойств линии, наконечник стрелки можно настроить с помощью свойств "headlength", "headwidth" и "headstyle". Допустимые значения свойства "headstyle": ["diamond" | "ellipse" | "plain" | "rectangle" | "vback1" | "{vback2}" | "vback3"]

"doublearrow"

Создает двунаправленную стрелку. Векторы x и y задают координаты наконечников стрелки.

Линию и наконечники стрелки можно настроить так же, как для аннотаций-стрелок, но некоторые имена свойств дублируются: "head1length"/"head2length", "head1width"/"head2width" и т. д. Индекс 1 обозначает свойства наконечника стрелки в первой точке координат x и y.

"textarrow"

Создает стрелку с текстовой меткой на конце, противоположном наконечнику.

Чтобы изменить текст, используйте свойство "string". Линию и наконечник стрелки можно настроить так же, как для аннотаций-стрелок, а текст можно настроить с помощью тех же свойств, что и графические объекты text. Однако обратите внимание, что перед некоторыми именами свойств текста добавлен префикс "text", чтобы отличать их от свойств стрелки: "textbackgroundcolor", "textcolor", "textedgecolor", "textlinewidth", "textmargin", "textrotation".

"textbox"

Создает рамку с текстом внутри. pos задает свойство "position" аннотации.

Чтобы изменить текст, используйте свойство "string". Для настройки цвета фона рамки и внешнего вида ее границ можно использовать свойства "backgroundcolor", "edgecolor", "linestyle" и "linewidth". Также доступен ограниченный набор свойств объектов text; помимо свойств "font…", для позиционирования текста внутри рамки можно использовать "horizontalalignment" и "verticalalignment".

Наконец, свойство "fitboxtotext" управляет фактическими размерами рамки. Если задано "on" (значение по умолчанию), границы рамки подгоняются под размер текста.

"rectangle"

Создает прямоугольник. pos задает свойство "position" аннотации.

Для настройки цвета фона прямоугольника и внешнего вида его границ можно использовать свойства "facecolor", "color", "linestyle" и "linewidth".

"ellipse"

Создает эллипс. pos задает свойство "position" аннотации.

Настройка описана для аннотаций "rectangle".

См. также: xlabel, ylabel, zlabel, title, text, gtext, legend, colorbar.