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 (…) ¶

Создает объект декартовых осей и возвращает дескриптор (handle) к нему или устанавливает текущие оси в 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, то каждый полигональный патч имеет 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, независимо от их размеров.

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