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 (строка) ¶

: title (строка, свойство, значение, …) ¶

: title (дескриптор_оси, …) ¶

: h = title (…) ¶

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

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

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

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

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

: legend () ¶

: legend команда ¶

: legend (строка1, строка2, …) ¶

: legend (матрица_символов) ¶

: legend ({массив_строк}) ¶

: legend (…, свойство, значение, …) ¶

: legend (hobjs, …) ¶

: legend ("команда") ¶

: legend (hax, …) ¶

: legend (hleg, …) ¶

: hleg, hplt = 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 текущей оси.

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

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

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

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

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

: clabel (c, h) ¶

: clabel (c, h, v) ¶

: clabel (c, h, "manual") ¶

: clabel (c) ¶

: clabel (…, prop, val, …) ¶

: h = clabel (…) ¶

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

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

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

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

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

Необязательное возвращаемое значение h — вектор графических дескрипторов объектов текста, представляющих каждую метку. Свойство "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.