---

42.17.2 Дескрипторы изображений

Дескриптор изображения — это список, который определяет исходные данные для изображения и способ его отображения. Обычно он используется как значение свойства display в оверлеях или текстовых свойствах (см. Другие спецификации отображения); но см. Показ изображений для удобных вспомогательных функций вставки изображений в буферы.

Каждый дескриптор изображения имеет форму (image . props), где props — это список свойств, состоящий из чередующихся символьных ключей и значений, включающий как минимум пару :type type, определяющую тип изображения.

Дескрипторы изображений, определяющие размеры изображения — :width, :height, :max-width и :max-height — могут принимать либо целое число, представляющее размер в пикселях, либо пару (value . em), где value — это длина размера в эмах³³. Один эм эквивалентен размеру шрифта, и value может быть целым числом или числом с плавающей запятой. Также размер может быть задан в формах (value . ch) и (value . cw), где ch означает высоту канонического символа, а cw — ширину канонического символа.

Ниже приведен список свойств, имеющих смысл для всех типов изображений (также существуют свойства, имеющие смысл только для определенных типов изображений, как описано в следующих подразделах):

:type type

Тип изображения. См. Форматы изображений. Каждый дескриптор изображения должен включать это свойство.

:file file

Указывает загрузить изображение из файла file. Если file не является абсолютным именем файла, он расширяется относительно каждого из каталогов, указанных в image-load-path (см. Определение изображений).

:data data

Задает сырые данные изображения. Каждый дескриптор изображения должен иметь либо :data, либо :file, но не оба одновременно.

Для большинства типов изображений значением свойства :data должна быть строка, содержащая данные изображения. Некоторые типы изображений не поддерживают :data; для других одного :data недостаточно, поэтому вам нужно использовать другие свойства изображения вместе с :data. Подробности см. в следующих подразделах.

:margin margin

Задает, сколько пикселей добавить в качестве дополнительного поля вокруг изображения. Значение margin должно быть неотрицательным числом или парой (x . y) таких чисел. Если это пара, x определяет, сколько пикселей добавить по горизонтали, а y — сколько по вертикали. Если :margin не указан, по умолчанию используется ноль.

:ascent ascent

Задает, какая часть высоты изображения используется для его подъема — то есть части над базовой линией. Значение ascent должно быть числом в диапазоне от 0 до 100 или символом center.

Если ascent — число, этот процент высоты изображения используется для его подъема.

Если ascent равно center, изображение вертикально центрируется относительно центральной линии, которая была бы вертикальной центральной линией текста, отображаемого в позиции изображения, в соответствии с текстовыми свойствами и оверлеями, применяемыми к изображению.

Если это свойство опущено, по умолчанию используется 50.

:relief relief

Добавляет теневой прямоугольник вокруг изображения. Значение relief задает ширину теневых линий в пикселях. Если relief отрицательное, тени рисуются так, что изображение выглядит как нажатая кнопка; в противном случае — как ненажатая кнопка.

:width width, :height height

Ключевые слова :width и :height используются для масштабирования изображения. Если указано только одно из них, другое будет вычислено так, чтобы сохранить соотношение сторон. Если указаны оба, соотношение сторон может не сохраняться.

:max-width max-width, :max-height max-height

Ключевые слова :max-width и :max-height используются для масштабирования, если размер изображения превышает эти значения. Если задано :width, оно имеет приоритет над max-width, а если задано :height, оно имеет приоритет над max-height, но вы можете смешивать эти ключевые слова по своему усмотрению.

Если заданы и :max-width, и :height, но не задано :width, сохранение соотношения сторон может потребовать, чтобы ширина превышала :max-width. Если это происходит, масштабирование будет использовать меньшее значение для высоты, чтобы сохранить соотношение сторон и не превысить :max-width. Аналогично, когда заданы и :max-height, и :width, но не задано :height. Например, если у вас есть изображение 200x100 и вы указываете, что :width должно быть 400, а :max-height должно быть 150, вы получите изображение размером 300x150: сохранение соотношения сторон и непревышение «максимального» значения. Эта комбинация параметров — полезный способ сказать «отобрази это изображение как можно больше, но не больше доступной области отображения».

:scale scale

Должен быть коэффициентом масштабирования для изображения — числом. Значения больше 1 означают увеличение размера изображения, а меньшие — уменьшение, путем умножения ширины и высоты изображения на этот коэффициент. Например, значение 0.25 сделает изображение в четыре раза меньше исходного. Если масштабирование делает изображение больше, чем указано в :max-width или :max-height, итоговый размер не превысит эти два значения. Если указаны и :scale, и :height/:width, высота/ширина будут скорректированы с учетом указанного коэффициента масштабирования.

Значением scale также может быть символ default, что означает использование значения image-scaling-factor. Если это значение — число, оно используется как коэффициент масштабирования; если оно равно auto (по умолчанию), это означает вычисление коэффициента масштабирования на основе размера пикселей шрифта, используемого в стандартном лице фрейма (см. Низкоуровневое представление шрифтов). В частности, если ширина пикселя шрифта стандартного лица больше 10, изображение увеличивается на коэффициент, вычисляемый как отношение ширины шрифта к 10; если ширина шрифта составляет 10 пикселей или меньше, изображение не масштабируется. Например, если ширина стандартного шрифта равна 15, изображение будет масштабировано с коэффициентом 1.5.

Если scale не указан, create-image масштабирует изображение в соответствии со значением image-scaling-factor.

:rotation angle

Задает угол поворота в градусах. Поддерживаются только углы, кратные 90 градусам, если только тип изображения не imagemagick. Положительные значения вращают по часовой стрелке, отрицательные — против часовой стрелки. Поворот выполняется после масштабирования и обрезки.

:flip flip

Если это t, изображение будет отражено по горизонтали. В настоящее время это не влияет на изображения типа imagemagick. Вертикальное отражение можно получить, повернув изображение на 180 градусов и переключив это значение.

:transform-smoothing smooth

Если это t, к любому преобразованию изображения будет применено сглаживание; если nil, сглаживание применяться не будет. Точный используемый алгоритм зависит от платформы, но должен быть эквивалентен билинейной фильтрации. Отключение сглаживания будет использовать алгоритм ближайшего соседа.

Если это свойство не указано, create-image использует пользовательскую опцию image-transform-smoothing, чтобы определить, следует ли применять сглаживание. Эта опция может быть nil (без сглаживания), t (использовать сглаживание) или функцией-предикатом, которая вызывается с объектом изображения в качестве единственного параметра и должна возвращать либо nil, либо t. По умолчанию сглаживание применяется при уменьшении масштаба и не применяется при большом увеличении.

:index frame

См. Многокадровые изображения.

:conversion algorithm

Задает алгоритм преобразования, который должен быть применен к изображению перед его отображением; значение algorithm определяет, какой алгоритм.

laplace

emboss

Задает алгоритм выделения границ Лапласа, который сглаживает небольшие различия в цвете, выделяя более крупные. Иногда это считается полезным для отображения изображения для отключенной кнопки.

(edge-detection :matrix matrix :color-adjust adjust) ¶

Задает общий алгоритм выделения границ. matrix должен быть либо девятиэлементным списком, либо девятиэлементным вектором чисел. Пиксель в позиции x/y преобразованного изображения вычисляется из исходных пикселей вокруг этой позиции. matrix определяет для каждого пикселя в окрестности x/y коэффициент, с которым этот пиксель будет влиять на преобразованный пиксель; элемент 0 задает коэффициент для пикселя в x-1/y-1, элемент 1 — коэффициент для пикселя в x/y-1 и т. д., как показано ниже:

  (x-1/y-1  x/y-1  x+1/y-1
   x-1/y    x/y    x+1/y
   x-1/y+1  x/y+1  x+1/y+1)

Результирующий пиксель вычисляется из интенсивности цвета, полученной суммированием значений RGB окружающих пикселей, умноженных на указанные коэффициенты, и делением этой суммы на сумму абсолютных значений коэффициентов.

Выделение границ по Лапласу в настоящее время использует матрицу

  (1  0  0
   0  0  0
   0  0 -1)

Тиснение (emboss) использует матрицу

  ( 2 -1  0
   -1  0  1
    0  1 -2)

disabled

Задает преобразование изображения, чтобы оно выглядело отключенным.

:mask mask

Если mask равно heuristic или (heuristic bg), строит маску обрезки для изображения, чтобы фон фрейма был виден за изображением. Если bg не указан или если bg равен t, определяет цвет фона изображения, просматривая четыре угла изображения, предполагая, что наиболее часто встречающийся цвет из углов является цветом фона изображения. В противном случае bg должен быть списком (red green blue), задающим цвет, принимаемый за фон изображения.

Если mask равен nil, удаляет маску из изображения, если она есть. Изображения в некоторых форматах включают маску, которую можно удалить, указав :mask nil.

:pointer shape

Задает форму указателя мыши, когда указатель находится над этим изображением. См. Форма указателя для доступных форм указателя.

:map map ¶

Связывает с этим изображением карту изображения из активных областей.

Карта изображения — это ассоциативный список, где каждый элемент имеет формат (area id plist). Область area задается как прямоугольник, круг или многоугольник.

Прямоугольник — это пара (rect . ((x0 . y0) . (x1 . y1))), которая задает пиксельные координаты верхнего левого и нижнего правого углов прямоугольной области.

Круг — это пара (circle . ((x0 . y0) . r)), которая задает центр и радиус круга; r может быть числом с плавающей запятой или целым числом.

Многоугольник — это пара (poly . [x0 y0 x1 y1 ...]), где каждая пара в векторе описывает один угол многоугольника.

Когда указатель мыши находится в области активной зоны изображения, используется plist этой активной зоны; если она содержит свойство help-echo, оно определяет всплывающую подсказку для этой зоны, а если она содержит свойство pointer, оно определяет форму курсора мыши при наведении на эту зону. См. Форма указателя для доступных форм указателя.

Когда вы щелкаете мышью, когда указатель находится над активной зоной, формируется событие путем объединения id активной зоны с событием мыши; например, [area4 mouse-1], если id активной зоны равен area4.

Обратите внимание, что координаты карты должны соответствовать отображаемому изображению после всех выполненных преобразований (поворота, масштабирования и т. д.), а также учтите, что Emacs (по умолчанию) выполняет автоматическое масштабирование изображений, поэтому для согласованности вам следует либо указать :scale 1.0 при создании изображения, либо использовать результат image-compute-scaling-factor для вычисления элементов карты.

Когда изменяются :scale, :rotation или :flip изображения, :map будет пересчитан на основе значения :original-map и значений этих преобразований.

:original-map original-map ¶

Задает непреобразованную карту изображения, которая будет использоваться для пересчета :map после изменения :scale, :rotation или :flip изображения.

Если :original-map не указан при создании изображения с помощью create-image, он будет вычислен на основе предоставленного :map, а также любых :scale, :rotation или :flip, которые не равны nil.

И наоборот, если указан :original-map, но не указан :map, то :map будет вычислен на основе :original-map, :scale, :rotation и :flip.

Пользовательская опция: image-recompute-map-p ¶

Установите эту пользовательскую опцию в nil, чтобы предотвратить автоматический пересчет Emacs карты :map изображения на основе его :original-map.

Функция: image-mask-p spec &optional frame ¶

Эта функция возвращает t, если изображение spec имеет битовую маску. frame — это фрейм, на котором будет отображаться изображение. Если frame равен nil или опущен, используется выбранный фрейм (см. Ввод фокуса).

Функция: image-transforms-p &optional frame ¶

Эта функция возвращает не nil, если frame поддерживает масштабирование и поворот изображений. Если frame равен nil или опущен, используется выбранный фрейм (см. Ввод фокуса). Возвращаемый список включает символы, указывающие, какие операции преобразования изображения поддерживаются:

scale

Масштабирование изображений поддерживается frame через свойства :scale, :width, :height, :max-width и :max-height.

rotate90

Поворот изображений поддерживается frame, если угол поворота кратен 90 градусам.

Если преобразования изображений не поддерживаются, :rotation, :crop, :width, :height, :scale, :max-width и :max-height будут доступны только через ImageMagick, если он доступен (см. Изображения ImageMagick).