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 (…) ¶

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

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

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

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

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

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

"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: многострочный текст с помощью 3 различных методов

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.

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

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

Если первый аргумент 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 (…) ¶

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

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

В противном случае вы можете выбрать тип аннотации и затем установить её положение, используя либо координаты 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.