Image Descriptors — Elisp

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

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

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

Свойства дескриптора изображения, задающие размеры изображения: :width, :height, :max-width и :max-height, могут принимать целое число, обозначающее размер в пикселях, или пару (value . em), где value — длина размера в em. Один em равен размеру шрифта, а 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 увеличивают изображение, а значения меньше 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 преобразованного изображения вычисляется на основе исходных пикселей вокруг этой позиции. Для каждого пикселя в окрестности x/y в matrix указывается коэффициент, определяющий его влияние на преобразованный пиксель; элемент 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)

При обнаружении границ с эффектом рельефа используется матрица

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

disabled

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

:mask mask

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

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

:pointer shape

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

:map map

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

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

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

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

Многоугольник — это cons (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 изображения.

Если при создании изображения с помощью create-image не указано :original-map, оно будет вычислено на основе заданного :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 — кадр, в котором будет отображаться изображение. Значение nil для frame или отсутствие этого аргумента означает, что следует использовать выбранный кадр (см. Фокус ввода).

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

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

scale: Кадр frame поддерживает масштабирование изображений с помощью свойств :scale, :width, :height, :max-width и :max-height.
rotate90: Кадр frame поддерживает поворот изображений, если угол поворота кратен 90 градусам.

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