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

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

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

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

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

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

legend ()

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

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

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

legend (…, "расположение", позиция)

legend (…, "ориентация", ориентация)

legend (hax, …)

legend (hobjs, …)

legend (hax, hobjs, …)

legend ("опция")

legend (…, {массив строк}, свойство, значение, …)

[hleg, hleg_obj, hplot, метки] = legend (…)

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

Элементы легенды могут быть заданы как отдельные аргументы типа строка, массивом символов или массивом строк. Когда имена меток могут быть спутаны с параметрами функции legend, метки следует защитить, указав их как массив строк.

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

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

Необязательный параметр pos определяет расположение легенды следующим образом:

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

Необязательный параметр orient определяет, располагать ли элементы легенды вертикально или горизонтально. Допустимые значения — "vertical" (по умолчанию) или "horizontal".

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

"show"

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

"hide"

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

"toggle"

Переключаться между "hide" и "show"

"boxon"

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

"boxoff"

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

"right"

Расположить текст метки справа от ключей (по умолчанию)

"left"

Расположить текст метки слева от ключей

"off"

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

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

Необязательные значения возврата:

hleg

Графический дескриптор объекта легенды.

hleg_obj

Графические дескрипторы текстовых, паттерновых и линейных объектов, образующих легенду.

hplot

Графические дескрипторы объектов графика, которые были использованы для создания легенды.

метки

Массив строк меток в легенде.

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

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

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

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

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

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

h = text (…)

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

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

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

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

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

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

См. раздел Свойства текста для свойств, которые можно задать.

xlabel (строка)

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

xlabel (hax, …)

h = xlabel (…)

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

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

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

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

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

clabel (c, h)

clabel (c, h, v)

clabel (c, h, "manual")

clabel (c)

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

h = clabel (…)

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

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

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

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

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

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

Пример использования clabel:

[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". Если он опущен, текущее состояние box переключается.

Если первый аргумент 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 ширина высота].
  Вектор задаёт координаты (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" аннотации.

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

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