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

Вызванная с одним аргументом-дескриптором осей 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 (…)

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

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

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

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

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

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

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

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

Примечание для программистов: Полный список свойств приведен в документе Свойства заплатки. Полезные свойства заплатки включают "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, а строки z — различным значениям 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.