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 (дескрипторы_объектов, …) ¶

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

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

: legend (дескриптор_легенды, …) ¶

: дескриптор_легенды = legend (…) ¶

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

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

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

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

Метки легенды связаны с дочерними элементами осей; первая метка назначается первому объекту, нарисованному на оси, вторая метка — следующему нарисованному объекту и т. д. Для маркировки определенных объектов данных, не маркируя все объекты, укажите их графические дескрипторы в входном аргументе дескрипторы_объектов.

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

"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.

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

Примечание к реализации: Текст метки легенды предоставляется в вызове 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 может быть использован для изменения свойств созданной текстовой метки.

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

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

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

См. также: ylabel, zlabel, 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.