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

: text (x, y, z, строка)

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

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

: h = text (…)

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

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

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

Если первый аргумент дескриптор_оси является дескриптором оси, то добавляет текст к этой оси, а не к текущей оси, возвращаемой 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 (строка)

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

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

: h = xlabel (…)

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

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

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

Если первый аргумент дескриптор_оси является дескриптором оси, то выполняется операция с этой осью, а не с текущей осью, возвращаемой 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.

: аннотация (тип)

: аннотация ("линия", x, y)

: аннотация ("стрелка", x, y)

: аннотация ("двухсторонняя стрелка", x, y)

: аннотация ("стрелка с текстом", x, y)

: аннотация ("текстовое поле", pos)

: аннотация ("прямоугольник", pos)

: аннотация ("эллипс", pos)

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

: аннотация (дескриптор_рисунка, …)

: h = аннотация (…)

Отображает аннотации для выделения частей рисунка.

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

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

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

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

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

Все объекты аннотаций обладают двумя свойствами:

• "units": единицы, в которых интерпретируются координаты.
  Его значение может быть одним из "centimeters" | "characters" | "inches" | "{normalized}" | "pixels" | "points".
• "position": четырёхэлементный вектор [x0 y0 ширина высота].
  Вектор задаёт координаты (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. Обратите внимание, что некоторые имена свойств текста имеют префикс "текст", чтобы отличить их от свойств стрелок: "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.