15.3.2 Объекты графики

Иерархия графических объектов была описана выше. См. Введение в структуры графики. Здесь описаны конкретные объекты, и обсуждаются свойства, содержащиеся в этих объектах. Имейте в виду, что графические объекты всегда ссылаются по указателю.

root

Верхний уровень иерархии и родитель всех фигур. Используйте groot для получения указателя на корневой графический объект.

figure

Окно фигуры.

axes

Набор осей. Этот объект является дочерним элементом объекта фигуры и может быть родителем линий, текста, изображений, участков, поверхностей или объектов света.

line

Линия в двух или трех измерениях.

text

Текстовые аннотации.

image

Растровое изображение.

patch

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

surface

Трехмерная поверхность.

light

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

15.3.2.1 Создание графических объектов

Вы можете создать любой примитивный графический объект, вызвав функцию с тем же именем, что и объект; другими словами, figure, axes, line, text, image, patch, surface, и light функции. Эти базовые графические объекты автоматически становятся дочерними элементами текущего объекта осей, как если бы hold on был на месте. Отдельно оси автоматически станут дочерними элементами текущего объекта фигуры, а фигуры — дочерними элементами корневого объекта.

Если функция автоматического присоединения нежелательна, то важно сначала вызвать newplot для подготовки новой фигуры и осей для построения графиков. Альтернативный, более простой способ — вызвать высокоуровневую графическую процедуру, которая будет как создавать график, так и заполнять его графическими объектами низкого уровня. Вместо вызова line, используйте plot. Или используйте surf вместо surface. Или используйте fill вместо patch.

: axes ()

: axes (property, value, …)

: axes (hpar, property, value, …)

: axes (hax)

: h = axes (…)

Создает объект декартовых осей и возвращает указатель на него или устанавливает текущие оси в hax.

Вызванный без аргументов или с парами «свойство/значение», создает новые оси. Необязательный аргумент hpar — это графический указатель, определяющий родителя для новых осей и может быть фигурой, панелью uipanel или вкладкой uitab.

Вызванный с одним аргументом-указателем осей hax, функция делает hax текущими осями (как возвращает gca). Она также делает фигуру, содержащую hax, текущей фигурой (как возвращает gcf). Наконец, она переупорядочивает свойство children родительского объекта, чтобы оси hax появлялись перед всеми другими указателями осей в списке. Это приводит к отображению hax поверх других объектов осей (стекинг по порядку Z). Кроме того, она переупорядочивает любые объекты легенды или цветовой шкалы, связанные с hax, чтобы они тоже были видны.

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

См. также: gca, set, get.

: line ()

: line (x, y)

: line (x, y, z)

: line ("xdata", x, "ydata", y)

: line ("xdata", x, "ydata", y, "zdata", z)

: line (…, property, value)

: line (hax, …)

: h = line (…)

Создает объект линии по x и y (и возможно z) и вставляет его в текущие оси.

В стандартном формате вызова данные x, y и z могут быть скалярами, векторами или матрицами. В случае матричных входных данных line попытается ориентировать скаляры и векторы, чтобы результаты могли быть отображены. Это требует, чтобы один из измерений вектора соответствовал либо числу строк, либо числу столбцов матрицы.

В формате вызова низкого уровня (на 50% выше производительность), где данные задаются по имени (line ("xdata", x, …)), данные должны быть векторами. Если данные не заданы (line ()), то x == y = [0, 1].

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

Если вызывается только с парами «свойство/значение», то любые не указанные свойства используют значения по умолчанию, заданные в корневом объекте.

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

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

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

Функция line отличается от plot тем, что объекты линий вставляются в текущие оси без предварительного очистки графика.

См. также: image, patch, rectangle, surface, text.

: patch ()

: patch (x, y, c)

: patch (x, y, z, c)

: patch ("Faces", faces, "Vertices", verts, …)

: patch (…, prop, val, …)

: patch (…, propstruct, …)

: patch (hax, …)

: h = patch (…)

Создает объект patch в текущих осях с вершинами в координатах (x, y) и цветом c.

Если вершины являются матрицами размера MxN, то каждый многоугольный patch имеет M вершин, и будет создано N многоугольников. Если у некоторых многоугольников недостаточно M вершин, используйте NaN для обозначения "нет вершины". Если вход z присутствует, то будут созданы 3D-patches.

Аргумент цвета c может принимать множество форм. Чтобы создать многоугольники, которые все используют один цвет, используйте строковое значение (например, "r" для красного), скалярное значение, масштабированное на caxis, и индексирующее текущую палитру, или 3-элементный RGB-вектор с точным TrueColor.

Если c — вектор длины N, то i-й многоугольник будет иметь цвет, определяемый путем масштабирования элемента c(i) согласно caxis и индексирования в текущую палитру. Более сложные ситуации раскраски требуют непосредственного манипулирования парами свойство/значение patch.

Вместо указания многоугольников матрицами x и y, можно предоставить уникальный список вершин, а затем список граней многоугольников, созданных из этих вершин. В этом случае матрица "Vertices" будет Nx2 (2D patch) или Nx3 (3D patch). Матрица MxN "Faces" описывает M многоугольников, имеющих N вершин — каждая строка описывает один многоугольник, а каждый элемент столбца — индекс в матрицу "Vertices" для идентификации вершины. Объект patch можно создать, напрямую передав пары свойство/значение "Vertices"/verts, "Faces"/faces в качестве входных данных.

Вместо использования пар свойство/значение, любое свойство можно установить, передав структуру propstruct с соответствующими именами полей.

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

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

Примечание по программированию: Полный список свойств описан в Свойства Patch. Полезные свойства patch включают: "cdata", "edgecolor", "facecolor", "faces", и "facevertexcdata".

См. также: fill, get, set.

: surface (x, y, z, c)

: surface (x, y, z)

: surface (z, c)

: surface (z)

: surface (…, prop, val, …)

: surface (hax, …)

: h = surface (…)

Создаёт графический объект поверхности, используя матрицы x и y из meshgrid и матрицу значений z, соответствующих координатам x и y поверхности.

Если x и y являются векторами, то типичная вершина имеет вид (x(j), y(i), z(i,j)). Таким образом, столбцы матрицы z соответствуют различным значениям x, а строки — различным значениям y. Если задан только один входной параметр z, то x принимается равным 1:columns (z), а y — 1:rows (z).

Все пары свойство/значение, заданные в качестве входных данных, назначаются объекту поверхности.

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

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

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

См. также: surf, mesh, patch, line.

: light ()

: light (…, "prop", val, …)

: light (hax, …)

: h = light (…)

Создаёт объект света на текущих осях или для осей hax.

Когда объект света присутствует в объекте осей, а свойства "EdgeLighting" или "FaceLighting" объекта patch или surface устанавливаются в значение, отличное от "none", эти объекты отрисовываются с эффектами освещения. Поддерживаемые значения для свойств освещения: "none" (без эффектов освещения), "flat" (объекты с гранями), и "gouraud" (линейная интерполяция эффектов освещения между вершинами). Если режим освещения установлен в "flat", свойство "FaceNormals" используется для освещения. Для "gouraud", используется свойство "VertexNormals".

Поддерживается до восьми объектов света на оси. (Зависит от реализации)

Освещение поддерживается только для графических наборов инструментов OpenGL (т.е., "fltk" и "qt").

Объект света имеет следующие свойства, которые изменяют внешний вид графика.

"Color": Цвет света можно передать как

вектор RGB (например, [1 0 0] для красного) или как строку (например, "r" для красного). По умолчанию цвет — белый ([1 1 1]).

"Position": Направление испускания света в виде

вектора 1x3. По умолчанию направление — [1 0 1].

"Style": Эта строка определяет, исходит ли свет от

источника света на бесконечном расстоянии ("infinite") или от локального точечного источника ("local"). По умолчанию — "infinite".

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

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

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

См. также: lighting, material, patch, surface.

15.3.2.2 Функции обработки дескрипторов

Чтобы определить, является ли переменная индексом графического объекта или индексом осей или фигуры, используйте функции ishghandle, isgraphics, isaxes, и isfigure.

: ishghandle (h)

Возвращает true, если h является дескриптором графического объекта, и false в противном случае.

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

См. также: isgraphics, isaxes, isfigure, ishandle.

: isgraphics (h)

: isgraphics (h, type)

Возвращает true, если h является дескриптором графического объекта (типа type), и false в противном случае.

Когда type не указан, функция эквивалентна ishghandle.

См. также: ishghandle, ishandle, isaxes, isfigure.

: ishandle (h)

Возвращает true, если h — дескриптор графического или Java-объекта, и false в противном случае.

h также может быть матрицей дескрипторов, в этом случае возвращается логический массив, равный true, где элементы h являются дескрипторами графических или Java-объектов, и false — в противном случае.

Примечание для программистов: Часто полезнее проверять тип объекта. Чтобы определить, принадлежит ли дескриптор графическому объекту, используйте ishghandle или isgraphics. Чтобы определить, принадлежит ли дескриптор Java-объекту, используйте isjava.

См. также: ishghandle, isgraphics, isjava.

: isaxes (h)

Возвращает true, если h — дескриптор графического объекта осей, и false в противном случае.

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

См. также: isfigure, ishghandle, isgraphics.

: isfigure (h)

Возвращает true, если h — дескриптор графического объекта фигуры, и false в противном случае.

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

См. также: isaxes, ishghandle, isgraphics.

Функция gcf возвращает индекс текущего объекта фигуры или создаёт его, если он не существует. Аналогично, gca возвращает текущий объект осей или создаёт его (и родительский объект фигуры), если он не существует.

: h = groot ()

Возвращает дескриптор корневого графического объекта.

Корневой графический объект — это родительский объект всех графических объектов.

Кроме того, корневой объект содержит информацию о графической системе в целом, например, ScreenSize. Используйте get (groot) для выяснения доступной информации.

Значения по умолчанию для графической системы в целом задаются путём установки свойств корневого графического объекта, начинающихся с "Default". Например, чтобы установить шрифт по умолчанию для всех текстовых объектов в FreeSans, используйте

set (groot, "DefaultTextFontName", "FreeSans")

Свойства по умолчанию можно удалить, используя set со специальным значением свойства "remove". Чтобы отменить указание шрифта по умолчанию, используйте

set (groot, "DefaultTextFontName", "remove")

Примечание для программистов: Корневой графический объект идентифицируется специальным значением дескриптора 0. В какой-то момент это уникальное значение может измениться, но код можно сделать устойчивым к будущим изменениям, используя groot, который гарантированно всегда возвращает корневой графический объект.

См. также: gcf, gca, get, set.

: h = gcf ()

Возвращает дескриптор текущей фигуры.

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

Если текущая фигура не существует, создаётся новая и возвращается её дескриптор. Затем дескриптор можно использовать для проверки или изменения свойств фигуры. Например,

fplot (@sin, [-10, 10]);
fig = gcf ();
set (fig, "numbertitle", "off", "name", "sin plot")

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

Примечание: Чтобы найти текущую фигуру без создания новой, если она не существует, обратитесь к свойству "CurrentFigure" корневого графического объекта.

get (groot, "currentfigure");

См. также: gca, gco, gcbf, gcbo, get, set.

: h = gca ()

Возвращает дескриптор текущего объекта осей.

Текущие оси являются целевым объектом по умолчанию для графического вывода. В случае фигуры с несколькими осями, gca возвращает последнюю созданную ось или последнюю ось, на которую был наведён курсор.

Если текущий объект осей не существует, создаётся новый и возвращается его дескриптор. Дескриптор можно использовать для проверки или изменения свойств осей. Например,

ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);

создаёт пустой объект осей и затем изменяет его положение и размер в окне фигуры.

Примечание: Чтобы найти текущие оси без создания нового объекта осей, если он не существует, обратитесь к свойству "CurrentAxes" фигуры.

get (gcf, "currentaxes");

См. также: gcf, gco, gcbf, gcbo, get, set.

: h = gco ()

: h = gco (fig)

Возвращает дескриптор текущего объекта текущей фигуры или дескриптор текущего объекта фигуры с дескриптором fig.

Текущий объект фигуры — это объект, на который был наведён курсор последним. Он хранится в свойстве "CurrentObject" целевой фигуры.

Если последнее нажатие мыши не произошло на каком-либо дочернем объекте фигуры, то текущий объект — это сама фигура.

Если в целевой фигуре не было нажатий мыши, эта функция возвращает пустую матрицу.

Примечание для программирования: значение, возвращаемое этой функцией, необязательно совпадает со значением, возвращаемым gcbo во время выполнения обратного вызова. Выполняемый обратный вызов может быть прерван другим обратным вызовом, и текущий объект может измениться.

См. также: gcbo, gca, gcf, gcbf, get, set.

Функции get и set могут использоваться для проверки и изменения свойств графических объектов. Например,

get (groot)
    ⇒ ans =
       {
         type = root
         currentfigure = [](0x0)
         children = [](0x0)
         visible = on
         …
       }

возвращает структуру, содержащую все свойства корневого графического объекта. Как и во всех функциях Octave, структура возвращается по значению, поэтому её изменение не изменит внутренний корневой объект. Для этого необходимо использовать функцию set. Также обратите внимание, что в данном случае свойство currentfigure пусто, что указывает на отсутствие текущего окна фигуры.

Функция get также может использоваться для поиска значения отдельного свойства. Например,

get (gca (), "xlim")
    ⇒ [ 0 1 ]

возвращает диапазон оси X для текущего объекта осей в текущей фигуре.

Для изменения свойств графических объектов используйте функцию set. Например,

set (gca (), "xlim", [-10, 10]);

устанавливает диапазон оси X для текущего объекта осей в текущей фигуре в ‘[-10, 10]’.

Значения свойств по умолчанию также можно запросить, если функция set вызвана без аргумента значения. Если указан только один аргумент (дескриптор графического объекта), то возвращается структура с значениями по умолчанию для всех свойств данного типа объекта. Например,

set (gca ())

возвращает структуру, содержащую значения свойств по умолчанию для объектов осей. Если set вызывается с двумя аргументами (дескриптор графического объекта и имя свойства), то возвращаются только значения по умолчанию для запрошенного свойства.

: val = get (h)

: val = get (h, p)

Возвращает значение указанного свойства p объекта с дескриптором h.

Если p опущено, возвращается полный список свойств объекта h.

Если h является вектором, возвращается массив ячеек, содержащий значения или списки свойств соответственно.

См. также: set.

: set (h, property, value, …)

: set (h, properties, values)

: set (h, pv)

: value_list = set (h, property)

: all_value_list = set (h)

Изменяет значения указанных свойств для дескриптора графического объекта (или вектора дескрипторов) h.

Существует три способа указания имён и значений свойств:

• в виде списка пар «свойство» — «значение», разделённых запятыми

  Здесь каждое «свойство» — это строка, содержащая имя свойства, каждое «значение» — значение соответствующего типа для свойства.

• в виде массива ячеек строк properties содержащих имена свойств и массива ячеек values содержащих значения свойств.

  В этом случае число столбцов в values должно совпадать с числом элементов в properties. Первый столбец values содержит значения для первого элемента в properties и т. д. Число строк в values должно быть 1 или совпадать с числом элементов в h. В первом случае каждому элементу в h будут присвоены одинаковые значения. Во втором случае первому элементу в h будут присвоены значения из первой строки values и так далее.

• в виде массива структур pv

  Здесь имена полей структуры pv представляют имена свойств, а значения полей — значения свойств. В отличие от предыдущего случая, все элементы pv будут установлены для всех элементов в h независимо от размерностей pv.

set также используется для запроса списка значений, которые может принимать указанное свойство. clist = set (h, "property") вернёт список возможных значений для "property" в списке ячеек clist. Если переменная результата не указана, список форматируется и выводится на экран.

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

Например,

hf = figure ();
set (hf, "paperorientation")
⇒  [ landscape | {portrait} ]

показывает, что свойство paperorientation может принимать два значения, по умолчанию "portrait".

См. также: get.

: parent = ancestor (h, type)

: parent = ancestor (h, type, "toplevel")

Возвращает первого предка объекта с дескриптором h, тип которого совпадает с type, где type — строковая переменная.

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

Если сам объект с дескриптором h является типом type, возвращается h.

Если "toplevel" используется в качестве третьего аргумента, возвращается самый высокий родитель в иерархии объектов, который соответствует условию, вместо первого (ближайшего).

См. также: findobj, findall, allchild.

: h = allchild (handles)

Находит всех потомков, включая скрытые, графического объекта.

Эта функция похожа на get (h, "children"), но также возвращает скрытые объекты (HandleVisibility = "off").

Если handles — скаляр, h будет вектором. В противном случае h будет матрицей ячеек того же размера, что и handles, и каждая ячейка будет содержать вектор дескрипторов.

См. также: findall, findobj, get, set.

: findfigs ()

Находит все видимые фигуры, которые в данный момент находятся вне экрана, и перемещает их на экран.

См. также: allchild, figure, get, set.

Фигуры могут быть распечатаны или сохранены во многих графических форматах с помощью print и saveas. Однако иногда может быть полезно сохранить исходный графический объект Octave напрямую, чтобы можно было произвести дальнейшие изменения, такие как изменение заголовка или легенды.

Это можно сделать с помощью следующих функций:

fig_struct = hdl2struct (gcf);
save myplot.fig -struct fig_struct;
…
fig_struct = load ("myplot.fig");
struct2hdl (fig_struct);

: s = hdl2struct (h)

Возвращает структуру s, поля которой описывают свойства объекта и его потомков, связанных с дескриптором h.

Поля структуры s — "type", "handle", "properties", "children", и "special".

См. также: struct2hdl, hgsave, findobj.

: h = struct2hdl (s)

: h = struct2hdl (s, p)

: h = struct2hdl (s, p, hilev)

Создаёт графический объект с дескриптором h из структуры s.

Структура должна содержать поля "handle", "type", "children", "properties", и "special".

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

Третий булевый аргумент hilev может быть передан для указания, сохранять ли слушателей/обратные вызовы, например, для легенд или групп hggroups. Значение по умолчанию — false.

См. также: hdl2struct, hgload, findobj.

: hnew = copyobj (horig)

: hnew = copyobj (horig, hparent)

Создает копию графических объектов, связанных с маркерами horig, и возвращает новые маркеры hnew новых объектов.

Если указан маркер родителя hparent (корень, фигура, ось или группа hggroup), скопированный объект будет создан как дочерний элемент hparent.

Если horig является вектором маркеров, а hparent — скаляром, то каждый маркер в векторе hnew имеет свойство "Parent" установленное в hparent. И наоборот, если horig является скаляром, а hparent вектором, то каждый родительский объект получит копию horig. Если horig и hparent являются векторами с одинаковым количеством элементов, то hnew(i) будет иметь родителя hparent(i).

См. также: struct2hdl, hdl2struct, findobj.