15.3.2 Графические объекты

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

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

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

: axes ()

: axes (property, value, …)

: axes (hpar, property, value, …)

: axes (hax)

: h = axes (…)

Создаёт объект декартовых осей и возвращает его дескриптор либо задаёт hax в качестве текущего объекта axes.

При вызове без аргументов или с парами property/value создаётся новый объект axes. Необязательный аргумент hpar — это графический дескриптор, задающий родительский объект для новых осей; им может быть figure, uipanel или uitab.

При вызове с единственным аргументом-дескриптором осей hax функция задаёт hax в качестве текущего объекта axes (возвращаемого функцией gca). Она также задаёт figure, содержащий hax, в качестве текущего figure (возвращаемого функцией gcf). Наконец, она изменяет порядок объектов в свойстве children родительского объекта так, чтобы объект axes hax находился перед всеми остальными дескрипторами axes в списке. Благодаря этому hax отображается поверх всех остальных объектов axes (порядок наложения по оси Z). Кроме того, она изменяет порядок связанных с hax объектов legend и colorbar, чтобы они также оставались видимыми.

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

См. также: 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 (…)

Создаёт объект line по данным x и y (и, возможно, z) и добавляет его в текущий объект axes.

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

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

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

Если функция вызвана только с парами property/value, для всех неуказанных свойств используются значения по умолчанию, заданные для объекта root.

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

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

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

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

См. также: 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 в текущем объекте axes с вершинами в точках (x, y) и цветом c.

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

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

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

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

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

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

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

Примечания по программированию:

1. Полный список свойств приведён в разделе Свойства patch. К полезным свойствам patch относятся: "edgecolor", "facecolor", "faces", "vertices" и "facevertexcdata".
2. Смешение способов задания геометрии по x-y-z и по граням и вершинам может привести к неожиданным результатам.
3. Использование определений цвета "cdata" для геометрии, заданной гранями и вершинами, или определений цвета "facevertexcdata" для геометрии, заданной по x-y-z, может привести к неожиданным результатам раскраски объектов patch.

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

: surface (x, y, z, c)

: surface (x, y, z)

: surface (z, c)

: surface (z)

: surface (…, prop, val, …)

: surface (hax, …)

: h = surface (…)

Создаёт графический объект 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).

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

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

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

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

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

: light ()

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

: light (hax, …)

: h = light (…)

Создаёт объект light в текущем объекте axes или в объекте axes hax.

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

Для каждого объекта axes поддерживается до восьми объектов light. (Зависит от реализации.)

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

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

"Color": Цвет источника света можно задать как

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

"Position": Направление, из которого исходит свет, задаётся как

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

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

источника, находящегося на бесконечном расстоянии ("infinite"), или от локального точечного источника ("local"). По умолчанию используется значение "infinite".

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

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

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

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

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

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

: tf = ishghandle (h)

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

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

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

: tf = isgraphics (h)

: tf = isgraphics (h, type)

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

Если type не указан, функция эквивалентна ishghandle.

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

: tf = ishandle (h)

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

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

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

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

: tf = isaxes (h)

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

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

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

: tf = 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 (hfig)

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

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

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

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

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

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

Есть три способа указать имена и значения свойств:

• в виде разделенного запятыми списка пар property, value

  Каждое значение property — это строка с именем свойства, а каждое значение value имеет тип, соответствующий свойству. Если в h несколько дескрипторов, каждому из них присваивается одно и то же значение value. Например:

  h = plot ([0, 1]);
  set (h, 'color', 'green');

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

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

  h = plot ([0, 1; 1, 0]);
  set (h, {'color'}, {'green'; 'red'});

• в виде структуры pv

  Этот способ аналогичен первому: имена полей pv задают имена свойств, а значения полей — значения свойств. Как и в первом случае, для каждого свойства можно задать только одно значение, которое будет применено ко всем дескрипторам в h. Например:

  h = plot ([0, 1]);
  props.color = 'green';
  set (h, props);

Три способа задания свойств можно использовать в любом сочетании.

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

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

При запросе свойств допускается указывать только один графический дескриптор 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 можно передать, чтобы указать, должна ли функция сохранять слушатели и callback-функции, например для легенд или hggroups. По умолчанию используется значение false.

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

: hnew = copyobj (horig)

: hnew = copyobj (horig, hparent)

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

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

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

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