Tratamento de Escapes Percentuais

As imagens possuem uma grande quantidade de dados extras associados (metadados), além dos pixels da imagem propriamente ditos. Esses metadados podem ser úteis, seja para exibição, para diversos cálculos, ou para modificar o comportamento de operações de processamento de imagem posteriores. Você pode utilizar escapes percentuais em várias opções, por exemplo em -format ou no -label do montage, para exibir diversas propriedades e outras configurações associadas a uma imagem.

Dados de Perfil	Como EXIF: dados, contendo distâncias focais, exposições, datas e, em alguns casos, localizações GPS.
Atributos	Estão diretamente envolvidos com os dados da imagem e são mais comumente modificados como parte do processamento normal da imagem. Incluem largura, altura, profundidade, tipo de imagem (espaço de cor), atrasos de temporização e cor de fundo. A maioria dos escapes percentuais específicos serve para acessar essas informações.
Propriedades	São armazenadas como uma tabela de cadeias de caracteres de formato livre e são (se possível) salvas com a imagem (especialmente nos formatos de arquivo de imagem MIFF e PNG). Incluem: rótulos (Labels), legendas (Captions) e comentários (Comments).
Artefatos	São diversas configurações operacionais (avançadas) que são salvas para uso por vários operadores, ou pelo usuário para uso futuro. É apenas uma tabela de cadeias de caracteres de formato livre. Não são salvas com a imagem quando esta é gravada. Veja "Artefatos e Opções" abaixo para detalhes.
Opções	Também são configurações operacionais (avançadas) salvas para uso por vários operadores, mas são definidas globalmente para uso por toda uma lista de imagens (também não são salvas). Veja "Artefatos e Opções" abaixo.

Se você solicitar um escape percentual como %[key], a configuração é procurada na seguinte ordem até que a primeira correspondência seja encontrada…

Trata prefixos especiais como 'artifact:' 'option:' 'exif:' ou 'fx:'. Isso inclui cálculos e/ou globs desses prefixos, como 'exif:' ou 'artifact:' (veja abaixo).
Se key contém um padrão glob (mas nenhum prefixo conhecido), pesquisa na tabela de propriedades de formato livre.
Se key é um nome de "atributo" de imagem especial (veja a lista acima), retorna o atributo de imagem associado ou calculado.
Pesquisa a configuração como uma "propriedade" de formato livre.
Pesquisa a configuração como um "artefato" de formato livre.
Pesquisa a configuração como uma "opção" de formato livre.
Substitui o escape por uma cadeia de caracteres vazia e, talvez, produz um aviso.

Lembre-se de que todas as formas de nome longo dos escapes percentuais são tratadas sem distinção entre maiúsculas e minúsculas.

Agora você pode acessar diretamente as tabelas de cadeias de caracteres de formato livre de Artefatos e Opções, permitindo substituir a sequência acima e evitar acessar um atributo ou propriedade de mesmo nome.

%[artifact:setting]
%[option:setting]

O tratamento de escapes requer acesso a um contêiner de imagem. Se nenhum estiver disponível, uma imagem em branco é criada para garantir que a expressão possa ser processada e um valor retornado. Por exemplo, magick -print "%[fx:.8765/3.14]" null: null:.

Escapes Percentuais de Atributo de Uma Única Letra

Aqui estão os escapes comuns de uma única letra (forma curta) usados para reportar os atributos e propriedades mais comuns de uma imagem, como: o nome de arquivo da imagem, tipo, largura, altura.

\	barra invertida; o próximo caractere é literal e não está sujeito a interpretação
\n	nova linha
\r	retorno de carro
<	caractere menor-que.
>	caractere maior-que.
&	caractere e comercial.
%%	um sinal de porcentagem
%b	tamanho do arquivo da imagem lida (use -precision 16 para forçar resultados em B)
%c	propriedade de metadados comment
%d	componente de diretório do caminho
%e	extensão ou sufixo do nome de arquivo
%f	nome de arquivo (incluindo sufixo)
%g	geometria da página de canvas da camada (equivalente a "%Wx%H%X%Y")
%h	altura atual da imagem em pixels
%i	nome de arquivo da imagem (nota: torna-se o nome de arquivo de saída para "info:")
%k	CALCULADO: número de cores únicas
%l	propriedade de metadados label
%m	formato do arquivo de imagem (file magic)
%n	número de imagens na sequência de imagens atual, reportado uma vez por quadro
%o	nome de arquivo de saída (usado para delegates)
%p	índice da imagem na lista de imagens atual
%q	profundidade quântica (constante de tempo de compilação)
%r	classe da imagem e espaço de cor
%s	número da cena (da entrada, a menos que reatribuído)
%t	nome de arquivo sem diretório ou extensão (sufixo)
%u	nome de arquivo temporário único (usado para delegates)
%w	largura atual em pixels
%x	resolução x (densidade)
%y	resolução y (densidade)
%z	profundidade da imagem (como lida, a menos que modificada; profundidade de gravação da imagem)
%A	canal de transparência da imagem. Os valores incluem Undefined (sem canal de transparência), Blend, Copy ou Update.
%B	tamanho do arquivo da imagem lida em bytes
%C	tipo de compressão da imagem
%D	método de descarte GIF da imagem
%G	tamanho original da imagem (%wx%h; antes de quaisquer redimensionamentos)
%H	altura da página (canvas)
%M	nome de arquivo Magick (arquivo original exatamente como fornecido, incluindo modificadores de leitura)
%N	número de imagens na sequência de imagens atual, reportado uma vez por sequência de imagens
%O	deslocamento da página (canvas) ( = %X%Y )
%P	tamanho da página (canvas) ( = %Wx%H )
%Q	qualidade de compressão da imagem ( 0 = padrão )
%S	?? cenas ??
%T	atraso de tempo da imagem (em centissegundos)
%U	unidades de resolução da imagem
%W	largura da página (canvas)
%X	deslocamento x da página (canvas) (incluindo sinal)
%Y	deslocamento y da página (canvas) (incluindo sinal)
%Z	nome de arquivo único (usado para delegates)
%@	CALCULADO: caixa delimitadora de corte (sem realmente cortar)
%#	CALCULADO: hash de 'assinatura' dos valores da imagem

Aqui está um comando de exemplo e sua saída para uma imagem com nome de arquivo bird.miff e cuja largura é 512 e altura é 480.

-> identify -format "%m:%f %wx%h" bird.miff
MIFF:bird.miff 512x480

Note que todos os escapes percentuais de uma única letra também podem ser usados na forma longa (a partir do IM versão 6.7.6-9, veja a seguir). Por exemplo, %[f] é equivalente à forma curta %f.

AVISO: os escapes percentuais de forma curta NÃO são realizados quando o sinal de porcentagem vem após um número. Por exemplo, 10%x10 não expande o %x como um escape percentual. Se você quiser especificamente expandir o 'x', use a forma longa, que substitui esse caso especial. Por exemplo: 10%[x]10.

Esteja ciente também de que atributos calculados podem levar algum tempo para serem gerados, especialmente em imagens grandes.

Escapes Percentuais de Atributo em Forma Longa

Além dos atributos específicos e calculados acima, os seguintes também são reconhecidos quando colocados entre chaves (forma longa):

%[basename]	nome de arquivo base, sem sufixos (como %t)
%[bit-depth]	profundidade de bits real dos dados de pixel
%[bounding-box]	cantos superior esquerdo e inferior direito da caixa delimitadora da imagem
%[caption]	propriedade de metadados caption
%[caption:lines]	retorna o número de linhas geradas ao quebrar a legenda
%[caption:pointsize]	retorna o pointsize calculado durante o processamento de caption:
%[channels]	mnemônico do espaço de cor seguido do número total de canais e meta-canais, por exemplo, `cmyka 8.3` indica uma imagem CMYK com canal alfa, totalizando 8 canais e 3 meta-canais.
%[colors]	número de cores únicas na imagem (a partir do IM 7.0.3.8)
%[colorspace]	espaço de cor dos dados da imagem (excluindo transparência)
%[compose]
%[compression]	tipo de compressão da imagem
%[convex-hull]	pontos que formam um fecho convexo ao redor do objeto em primeiro plano. Use -define convex-hull:background-color=color para identificar a cor de fundo da imagem. Use -fuzz para permitir uma cor de fundo não uniforme.
%[convex-hull:extreme-points]	retorna os pontos extremos superior, direito, inferior e esquerdo do fecho convexo.
%[copyright]	cadeia de copyright do ImageMagick
%[depth]	profundidade da imagem para gravação (como na entrada, a menos que alterada)
%[deskew:angle]	o ângulo de correção de inclinação em graus de rotação
%[directory]	parte do diretório do nome de arquivo (como %d)
%[distortion]	quão bem uma imagem se assemelha a uma imagem de referência (-compare)
%[dominant-color]	retorna a cor dominante da imagem em hexadecimal. Preceda o uso com -kmeans.
%[entropy]	CALCULADO: entropia da imagem
%[extension]	parte da extensão do nome de arquivo (como %e)
%[gamma]	valor da gama da imagem
%[group]	??? grupo de janela ???
%[height]	altura original da imagem (quando foi lida)
%[histogram:contrast-stretch]	porcentagem mínima e máxima de contrast stretch calculada
%[histogram:linear-stretch]	porcentagem mínima e máxima de linear stretch calculada
%[input]	o nome de arquivo da imagem de entrada.
%[interlace]	modo de entrelaçamento da imagem (a partir do IM 7.0.3.8)
%[kurtosis]	CALCULADO: estatística de curtose da imagem
%[label]	propriedade de metadados label
%[label:pointsize]	retorna o pointsize calculado durante o processamento de label:
%[magick]	codificador (coder) usado para ler a imagem (não o sufixo do arquivo)
%[max]	CALCULADO: estatística de valor máximo da imagem
%[mean]	CALCULADO: estatística de valor médio da imagem
%[median]	CALCULADO: estatística de valor mediano da imagem
%[min]	CALCULADO: estatística de valor mínimo da imagem
%[minimum-bounding-box]	Use -define convex-hull:background-color=color para identificar a cor de fundo da imagem. Use -fuzz para permitir uma cor de fundo não uniforme. Além dos pontos da caixa delimitadora, estas propriedades são definidas: minimum-bounding-box:area, minimum-bounding-box:width, minimum-bounding-box:height, minimum-bounding-box:angle e minimum-bounding-box:unrotate.
%[opaque]	CALCULADO: a imagem é totalmente opaca?
%[orientation]	orientação da imagem
%[page]	geometria do canvas virtual (página)
%[papersize:name]	tamanho de papel para name em pixels a 72DPI (por exemplo, papersize:A4)
%[printsize.x]	printsize X
%[printsize.y]	printsize Y
%[profile:icc]	informações do perfil ICC
%[profile:icm]	informações do perfil ICM
%[profiles]	lista de quaisquer perfis incorporados
%[quality]	valor de qualidade da imagem (a partir do IM 7.0.3.8)
%[rendering-intent]	intenção de renderização da imagem (a partir do IM 7.0.3.8)
%[resolution.x]	densidade X (resolução) sem unidades
%[resolution.y]	densidade Y (resolução) sem unidades
%[scene]	número de cena original da imagem no arquivo de entrada
%[size]	tamanho original da imagem (quando foi lida)
%[skewness]	CALCULADO: estatística de assimetria da imagem
%[standard-deviation]	CALCULADO: estatística de desvio padrão da imagem
%[type]	CALCULADO: tipo da imagem
%[unique]	nome de arquivo temporário único ???
%[units]	unidades de resolução da imagem
%[version]	informações de versão deste ImageMagick em execução
%[width]	largura original da imagem (quando foi lida)
%[zero]	zero (nome de arquivo único para uso de delegate)

Propriedades

Todas as demais formas longas dos escapes percentuais (que não a forma longa de uma única letra) são tratadas sem distinção entre maiúsculas e minúsculas. Esses escapes tentarão procurar dados específicos associados a esse nome.

O espaço de pesquisa primário (se não for um atributo específico listado acima) é uma cadeia de propriedade de formato livre. Essas cadeias são associadas e salvas com as imagens e normalmente são definidas usando a opção de CLI -set (ou seu equivalente na API), ou a partir de opções de conveniência especiais (como -label, -comment, -caption).

Essas opções de conveniência são salvas globalmente (como 'opções globais', de modo que podem ser definidas antes de as imagens serem lidas) e, posteriormente, são transferidas para a propriedade de imagens individuais apenas quando elas são lidas. Nesse momento, qualquer escape percentual interno presente é então tratado.

Para alterar uma propriedade de uma imagem já em memória, você precisa usar -set.

Note que as propriedades, assim como os atributos (e os perfis), são salvas com as imagens na gravação, se o formato de arquivo de imagem permitir.

Artefatos e Opções

Os escapes percentuais anteriores estão associados aos Atributos e Propriedades primários. Esse é o foco original e primário desses escapes percentuais.

No entanto, há muitas configurações operacionais usadas por vários operadores do ImageMagick que podem ser úteis de definir e acessar posteriormente. Elas consistem em Artefatos por imagem e Opções globais (associadas a uma lista de imagens, normalmente a lista de imagens atual).

Note que a principal diferença entre um artefato e uma propriedade é que os artefatos, sendo uma configuração operacional interna, não são salvos com as imagens (quando isso é possível).

Por exemplo, quando você usa -define 'distort:viewport=100x100', na verdade está gerando uma opção global, que o operador -distort usará para modificar seu comportamento (a 'visão' da imagem de saída distorcida).

Uma Opção é essencialmente um Artefato que foi armazenado globalmente como parte de uma lista de imagens (especificamente um 'Wand' de imagens). Como tal, são idênticos, no sentido de que uma Opção é simplesmente um Artefato global para todas as imagens associadas.

Assim, você pode usar -set 'option:distort:viewport' '100x100' para obter o mesmo resultado de definir um Artefato para a operação de distort usar.

Tratamento Interno de uma Opção Global…

A biblioteca de núcleo ('MagickCore') geralmente não entende diretamente as Opções Globais. Assim, continuando o exemplo anterior, a função DistortImages() apenas consulta um artefato para descobrir se um 'viewport' foi fornecido a ela.

Como as Opções Globais são usadas quando uma função de biblioteca solicita um Artefato é uma das diferenças-chave entre o IMv6 e o IMv7.

Define um vínculo de volta para os dados das opções globais, de modo que, se um Artefato específico por imagem não for encontrado, ele procurará por uma Opção global equivalente para aquela lista de imagens diretamente. Isso evita copiar repetidamente essas opções de formato livre para os artefatos, e significa que você agora pode definir separadamente uma opção global para uma lista e um artefato de substituição individual para uma imagem específica nessa lista.

Note que muitas APIs não usam Wands (o PerlMagick, por exemplo, usa arrays de imagens em vez de um Wand). Nessas APIs você não terá Opções Globais, apenas Artefatos por imagem.

Em resumo, uma Opção Global, se disponível, é equivalente a um Artefato por imagem.

Listagem por Padrão Glob de Propriedades, Artefatos e Opções

A configuração pode conter um padrão glob. Assim, você agora pode listar todas as propriedades, artefatos e opções de formato livre (mas não atributos de imagem específicos) usando…

magick ... \
   -print "__Properties__\n%[*]" \
   -print "__Artifacts__\n%[artifact:*]" \
   -print "__Options__\n%[option:*]" \
   ...

O formato dos padrões glob é muito específico e, como tal, geralmente é usado apenas para listar configurações específicas, como ao depurar, em vez de ser usado para processamento de imagem.

Prefixos de Escape Percentual Calculados

Há alguns prefixos especiais (antes do primeiro ':') que realizam cálculos com base na cadeia fornecida pelo usuário que segue esse prefixo. Por exemplo, você pode fazer um cálculo numérico usando %[fx:...] para avaliar as expressões FX fornecidas:

%[fx:expression]

Use pixel: ou hex: para avaliar a cor de um pixel conforme definida pela expressão FX:

%[pixel:expression]

Use -define para especificar a conformidade da cor (por exemplo, -define pixel:compliance=css)

Prefixos de Escape Percentual de Perfil Específico

Você também pode usar a seguinte sintaxe de formatação especial para exibir os metadados de imagem EXIF que foram incluídos na imagem lida:

%[EXIF:tag]

Escolha tag entre os seguintes:

*  (print all EXIF tags, in keyword=data format)
!  (print all EXIF tags, in tag_number data format)
#hhhh (print data for EXIF tag #hhhh)
ImageWidth
ImageLength
BitsPerSample
Compression
PhotometricInterpretation
FillOrder
DocumentName
ImageDescription
Make
Model
StripOffsets
Orientation
SamplesPerPixel
RowsPerStrip
StripByteCounts
XResolution
YResolution
PlanarConfiguration
ResolutionUnit
TransferFunction
Software
DateTime
Artist
WhitePoint
PrimaryChromaticities
TransferRange
JPEGProc
JPEGInterchangeFormat
JPEGInterchangeFormatLength
YCbCrCoefficients
YCbCrSubSampling
YCbCrPositioning
ReferenceBlackWhite
CFARepeatPatternDim
CFAPattern
BatteryLevel
Copyright
ExposureTime
FNumber
IPTC/NAA
EXIFOffset
InterColorProfile
ExposureProgram
SpectralSensitivity
GPSInfo
ISOSpeedRatings
OECF
EXIFVersion
DateTimeOriginal
DateTimeDigitized
ComponentsConfiguration
CompressedBitsPerPixel
ShutterSpeedValue
ApertureValue
BrightnessValue
ExposureBiasValue
MaxApertureValue
SubjectDistance
MeteringMode
LightSource
Flash
FocalLength
MakerNote
UserComment
SubSecTime
SubSecTimeOriginal
SubSecTimeDigitized
FlashPixVersion
ColorSpace
EXIFImageWidth
EXIFImageLength
InteroperabilityOffset
FlashEnergy
SpatialFrequencyResponse
FocalPlaneXResolution
FocalPlaneYResolution
FocalPlaneResolutionUnit
SubjectLocation
ExposureIndex
SensingMethod
FileSource
SceneType

Coloque a especificação de formato entre aspas para evitar que seu shell interprete incorretamente quaisquer espaços e colchetes.

A seguinte sintaxe de formatação especial pode ser usada para exibir as informações IPTC contidas no arquivo:

%[IPTC:dataset:record]

Selecione dataset e record entre os seguintes:

  Envelope Record
  1:00  Model Version
  1:05  Destination
  1:20  File Format
  1:22  File Format Version
  1:30  Service Identifier
  1:40  Envelope Number
  1:50  Product ID
  1:60  Envelope Priority
  1:70  Date Sent
  1:80  Time Sent
  1:90  Coded Character Set
  1:100  UNO (Unique Name of Object)
  1:120  ARM Identifier
  1:122  ARM Version

Application Record
  2:00  Record Version
  2:03  Object Type Reference
  2:05  Object Name (Title)
  2:07  Edit Status
  2:08  Editorial Update
  2:10  Urgency
  2:12  Subject Reference
  2:15  Category
  2:20  Supplemental Category
  2:22  Fixture Identifier
  2:25  Keywords
  2:26  Content Location Code
  2:27  Content Location Name
  2:30  Release Date
  2:35  Release Time
  2:37  Expiration Date
  2:38  Expiration Time
  2:40  Special Instructions
  2:42  Action Advised
  2:45  Reference Service
  2:47  Reference Date
  2:50  Reference Number
  2:55  Date Created
  2:60  Time Created
  2:62  Digital Creation Date
  2:63  Digital Creation Time
  2:65  Originating Program
  2:70  Program Version
  2:75  Object Cycle
  2:80  By-Line (Author)
  2:85  By-Line Title (Author Position) [Not used in Photoshop 7]
  2:90  City
  2:92  Sub-Location
  2:95  Province/State
  2:100  Country/Primary Location Code
  2:101  Country/Primary Location Name
  2:103  Original Transmission Reference
  2:105  Headline
  2:110  Credit
  2:115  Source
  2:116  Copyright Notice
  2:118  Contact
  2:120  Caption/Abstract
  2:122  Caption Writer/Editor
  2:125  Rasterized Caption
  2:130  Image Type
  2:131  Image Orientation
  2:135  Language Identifier
  2:150  Audio Type
  2:151  Audio Sampling Rate
  2:152  Audio Sampling Resolution
  2:153  Audio Duration
  2:154  Audio Outcue
  2:200  ObjectData Preview File Format
  2:201  ObjectData Preview File Format Version
  2:202  ObjectData Preview Data

Pre-ObjectData Descriptor Record
  7:10   Size Mode
  7:20   Max Subfile Size
  7:90   ObjectData Size Announced
  7:95   Maximum ObjectData Size

ObjectData Record
  8:10   Subfile

Post ObjectData Descriptor Record
  9:10   Confirmed ObjectData Size