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

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

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

Если эта функция автоматического объединения нежелательна, то важно сначала вызвать newplot, чтобы подготовить новую фигуру и оси для построения. Альтернативный, более простой способ — вызвать графический высокоуровневый метод, который создаст график и заполнит его графическими объектами низкого уровня. Вместо вызова line, используйте plot. Или используйте surf вместо surface. Или используйте fill или fill3 вместо 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 (…) ¶

Создать объект заливки на текущих осях с вершинами в координатах (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-заливка). Матрица "Faces" MxN описывает 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.

: tf = ishghandle (h) ¶

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

h также может быть матрицей указателей, в этом случае возвращается логический массив, в котором true соответствует графическим указателям, а 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 соответствует указателям на графические или Java-объекты, а false — нет.

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

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

: tf = isaxes (h) ¶

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

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

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

: tf = isfigure (h) ¶

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

Если h — матрица, возвращается логический массив, в котором true соответствует указателям на графические объекты фигур, а 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.

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

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

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

Например,

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 новых объектов.

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

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

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