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

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

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

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

: axes () ¶

: axes (property, value, …) ¶

: axes (hpar, property, value, …) ¶

: axes (hax) ¶

: h = axes (…) ¶

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

Вызванный без каких-либо аргументов или с парами свойство/значение, строит новые оси. Необязательный аргумент hpar — это дескриптор графического объекта, определяющий родителя для новых осей, и может быть figure, 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 (…) ¶

: 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-пакеты.

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

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

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

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

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

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

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

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

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

: 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 во время выполнения обратного вызова. Выполнение обратного вызова может быть прервано другим обратным вызовом, и текущий объект может измениться.

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

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

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

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

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