Converter, redimensionar ou aplicar marca-d’água em imagens

🤖/image/resize redimensiona, recorta, altera a coloração e a rotação e aplica texto e marcas-d’água a imagens.

Exemplo de uso

{
  "steps": {
    "resized": {
      "robot": "/image/resize",
      "use": ":original",
      "width": 200
    }
  }
}

Parâmetros

• interpolate

  boolean | Record<string, boolean>

  Controla se as Assembly Variables são interpoladas em campos individuais de instruções.

  Por padrão, a maioria dos campos de instruções dos Robots interpola Assembly Variables. Defina isso como false para tratar todos os campos de instruções como texto literal, ou defina o caminho de um campo individual como false para tratar apenas esse campo como texto literal. Para campos específicos de um Robot que são literais por padrão, defina isso como true ou defina o caminho desse campo como true para voltar a usar a interpolação.

  Use nomes de campos como path ou caminhos com pontos como ffmpeg.vf para objetos aninhados.

• output_meta

  Record<string, boolean> | boolean | Array<string>

  Permite especificar um conjunto de metadados cujo cálculo exige mais CPU e que, por isso, vem desativado por padrão para manter o processamento das suas Assemblies rápido.

  Para imagens, você pode adicionar "has_transparency": true neste objeto para extrair se a imagem contém partes transparentes e "dominant_colors": true para extrair um array de códigos de cores hexadecimais da imagem.

  Para imagens, você também pode adicionar "blurhash": true para extrair uma string BlurHash⁠ — uma representação compacta de um placeholder da imagem, útil para exibir uma prévia desfocada enquanto a imagem completa carrega.

  Para vídeos, você pode adicionar o parâmetro "colorspace": true para extrair o espaço de cores do vídeo de saída.

  Para vídeos, você também pode adicionar "interlaced": true para detectar se o vídeo é entrelaçado. Isso combina a flag computacionalmente barata field_order do ffprobe com uma passagem de amostragem idet limitada sobre os primeiros quadros da origem, expondo interlaced, field_order e um objeto de diagnóstico interlace_detection em file.meta. Isso é computacionalmente caro e cobrado de acordo.

  Para áudio, você pode adicionar "mean_volume": true para obter um único valor que representa o volume médio do arquivo de áudio.

  Você também pode definir isso como false para pular a extração de metadados e acelerar a transcodificação.

• user_meta

  Record<string, any>(padrão: {})

  Adiciona metadados JSON personalizados a cada arquivo emitido sem modificar seu conteúdo. Objetos e arrays aninhados são suportados.

  A herança depende do Robot. Os valores são mesclados com o user_meta existente no arquivo de saída; o Step atual substitui as chaves de nível superior com o mesmo nome. Atribua explicitamente as chaves necessárias quando um Robot criar novas saídas.

  Nos Steps de processamento, ${file.*} se refere à primeira entrada e ${result.*} ao arquivo emitido. Os valores são avaliados para cada saída após a execução do Robot, antes da extração subsequente de metadados e do armazenamento temporário. Em :original, os valores são avaliados para cada upload antes da extração de metadados.

  Os Steps subsequentes leem ${file.user_meta.key}. Consulte Metadados personalizados para ver um exemplo completo e as regras de herança.

• result

  boolean(padrão: false)

  Se os resultados deste Step devem estar presentes no Assembly Status JSON

• queue

  batch

  Definir a fila como “batch” rebaixa manualmente a prioridade dos Jobs deste Step, para evitar o consumo de vagas prioritárias de Jobs em Jobs que não precisam de tempo zero de espera na fila

• force_accept

  boolean(padrão: false)

  Forçar um Robot a aceitar um tipo de arquivo que ele teria ignorado.

  Por padrão, os Robots ignoram arquivos que não conhecem. O 🤖/video/encode, por exemplo, ignora tranquilamente imagens de entrada.

  Com o parâmetro force_accept definido como true, você pode forçar os Robots a aceitar todos os arquivos enviados a eles. Isso normalmente leva a erros e só deve ser usado para depuração ou para lidar com casos extremos.

• ignore_errors

  boolean | Array<meta | execute>(padrão: [])

  Ignorar erros durante fases específicas do processamento.

  Definir isso como ["meta"] fará com que o Robot ignore erros durante a extração de metadados.

  Definir isso como ["execute"] fará com que o Robot ignore erros durante a fase principal de execução.

  Definir isso como true equivale a ["meta", "execute"] e fará com que erros sejam ignorados nas duas fases.

• use

  string | Array<string> | Array<object> | object

  Especifica quais Steps usar como entrada.

  • Você pode escolher qualquer nome para os Steps, exceto ":original" (reservado para uploads de usuários tratados pela Transloadit)
  • Você pode fornecer vários Steps como entrada usando arrays:

    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    

  • Você também pode marcar os Steps de entrada com as para transmitir intenção semântica aos Robots:

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Dica

  Provavelmente é tudo o que você precisa saber sobre use, mas você pode ver os casos de uso avançados.

• format

  string | null(padrão: null)

  O formato de saída da imagem modificada.

  Alguns dos formatos disponíveis mais importantes são "jpg", "png", "gif", "tiff" e "jxl" para JPEG XL. Para ver a lista completa de todos os formatos que podemos gerar, consulte nossa lista de formatos de imagem compatíveis EN (English).

  Se o valor for null (padrão), o formato da imagem de entrada será usado como formato de saída.

  Se você quiser converter para "pdf", considere usar 🤖/document/convert em vez disso.

• width

  number

  Largura do resultado em pixels. Se não for especificada, será usada a largura da imagem original por padrão.

• height

  number

  Altura da nova imagem, em pixels. Se não for especificada, será usada a altura da imagem de entrada.

• resize_strategy

  "crop" | "fillcrop" | "fit" | "min_fit" | "pad" | "stretch"(padrão: "fit")

  Veja a lista de estratégias de redimensionamento disponíveis.

• zoom

  boolean(padrão: true)

  Se este parâmetro estiver definido como false, imagens menores não serão ampliadas para a largura e a altura desejadas. Para detalhes sobre o impacto do zoom na sua estratégia de redimensionamento preferida, consulte a lista de estratégias de redimensionamento disponíveis.

• crop

  object | string

  Especifique um objeto contendo as coordenadas dos cantos superior esquerdo e inferior direito do retângulo a ser recortado da(s) imagem(ns) original(is). O sistema de coordenadas tem origem no canto superior esquerdo da imagem. Os valores podem ser inteiros para valores absolutos em pixels ou strings para valores baseados em porcentagens.

  Por exemplo:

  {
    "x1": 80,
    "y1": 100,
    "x2": "60%",
    "y2": "80%"
  }
  

  Isso recortará a área de (80, 100) a (600, 800) de uma imagem de 1000×1000 pixels, resultando em um quadrado com largura de 520px e altura de 700px. Se crop estiver definido, os parâmetros de largura e altura serão ignorados, e resize_strategy será definido como crop automaticamente.

  Você também pode usar uma string JSON desse tipo de objeto com coordenadas de forma semelhante:

  "{\"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer>}"
  

  Para recortar ao redor de rostos humanos, consulte 🤖/image/facedetect.

• gravity

  bottom | bottom-left | bottom-right | center | left | right | top | mais 2 ↓ | attention | entropy(padrão: "center")

  A direção a partir da qual a imagem deve ser recortada quando "resize_strategy" está definido como "crop" ou "fillcrop", mas nenhuma coordenada de recorte está definida.

  Você também pode usar "entropy" ou "attention" para recorte automático por ponto de interesse. "entropy" mantém a região com a maior entropia de Shannon, enquanto "attention" favorece áreas com indícios de frequência de luminância, saturação e tons de pele.

• strip

  boolean(padrão: false)

  Remove todos os metadados da imagem. Isso é útil para manter as miniaturas com o menor tamanho possível.

• alpha

  Activate | Background | Copy | Deactivate | Extract | Off | On | mais 5 ↓

  Permite controlar o canal alfa/matte de uma imagem.

• preclip_alpha

  Activate | Background | Copy | Deactivate | Extract | Off | On | mais 5 ↓

  Permite controlar o canal alfa/matte de uma imagem antes de aplicar o caminho de recorte via clip: true.

• flatten

  boolean(padrão: true)

  Mescla todas as camadas sobre o fundo especificado para obter melhores resultados na conversão de formatos com transparência para formatos sem transparência, conforme explicado na documentação do ImageMagick⁠.

  Para preservar as animações, os arquivos GIF não têm suas camadas mescladas quando este parâmetro está definido como true. Para mesclar os quadros de animações GIF, use o parâmetro frame.

• correct_gamma

  boolean(padrão: false)

  Evita erros de gama comuns em muitos algoritmos de redimensionamento de imagens⁠.

• quality

  string | number(padrão: 92)

  Controla a compressão de imagens JPG e PNG. Confira também 🤖/image/optimize.

• adaptive_filtering

  boolean(padrão: false)

  Controla a compressão de imagens PNG. Definir como true resulta em arquivos menores, mas aumenta o tempo de processamento. Recomendamos manter essa opção desativada.

• background

  string | transparent | none | black | white | red | green | blue | mais 6 ↓(padrão: "#FFFFFF")

  O código hexadecimal ou o nome⁠ da cor usada para preencher o fundo (usada na estratégia de redimensionamento pad).

  Nota: Por padrão, o fundo de imagens transparentes é alterado para branco. Para preservar a transparência, defina "background" como "none".

• frame

  string | number | null(padrão: null)

  Use este parâmetro ao trabalhar com arquivos GIF animados para especificar qual quadro do GIF será usado na operação. Especifique 1 para usar o primeiro quadro, 2 para usar o segundo, e assim por diante. null significa todos os quadros.

• colorspace

  CMY | CMYK | Gray | HCL | HCLp | HSB | HSI | mais 28 ↓

  Define o espaço de cores da imagem. Para detalhes sobre os valores disponíveis, consulte a documentação do ImageMagick⁠. Observe que, se você usava "RGB", recomendamos usar "sRGB" a partir de 2014-02-04. O ImageMagick pode tentar encontrar o colorspace mais eficiente com base na cor de uma imagem e adotar, por exemplo, "Gray" como padrão. Para forçar as cores, talvez você precise usar este parâmetro em combinação com type: "TrueColor".

• type

  Bilevel | ColorSeparation | ColorSeparationAlpha | Grayscale | GrayscaleAlpha | Palette | PaletteAlpha | mais 2 ↓

  Define o tipo de cor da imagem. Para detalhes sobre os valores disponíveis, consulte a documentação do ImageMagick⁠. Se você estiver usando colorspace, o ImageMagick poderá tentar encontrar o tipo mais eficiente com base na cor de uma imagem e adotar, por exemplo, "Gray" como padrão. Para forçar cores, você pode, por exemplo, definir este parâmetro como "TrueColor"

• sepia

  string | number | null(padrão: null)

  Aplica um efeito de tom sépia em porcentagem.

• rotation

  string | number | boolean | "auto"(padrão: true)

  Determina se a imagem deve ser rotacionada. Use qualquer número para especificar o ângulo de rotação em graus (por exemplo, 90, 180, 270, 360 ou valores precisos como 2.9). Use o valor true ou "auto" para rotacionar automaticamente imagens com rotação incorreta ou que dependem de configurações de rotação EXIF. Caso contrário, use false para desativar completamente a correção automática.

• compress

  BZip | Fax | Group4 | JPEG | JPEG2000 | Lossless | LZW | mais 3 ↓ | null(padrão: null)

  Especifica a compressão de pixels para quando a imagem for gravada. A compressão está desabilitada por padrão.

  Confira também 🤖/image/optimize.

• blur

  string | null(padrão: null)

  Especifica o desfoque gaussiano usando um valor no formato {radius}x{sigma}. O valor do raio especifica o tamanho da área que o operador deve considerar ao espalhar os pixels e normalmente deve ser "0" ou pelo menos duas vezes o valor de sigma. O valor de sigma é uma aproximação de quantos pixels a imagem é “espalhada”; pense nele como o tamanho do pincel usado para desfocar a imagem. Esse número é um valor de ponto flutuante, permitindo o uso de valores pequenos como "0.5".

• blur_regions

  Array<object> | null(padrão: null)

  Especifica um array de objetos de elipse que devem ser desfocados na imagem. Cada objeto tem as seguintes chaves: x, y, width, height. Se blur_regions tiver um valor, o parâmetro blur será usado como a intensidade do desfoque de cada região.

• brightness

  string | number(padrão: 1)

  Aumenta ou diminui o brilho da imagem usando um multiplicador. Por exemplo, 1.5 aumentaria o brilho em 50%, e 0.75 diminuiria o brilho em 25%.

• saturation

  string | number(padrão: 1)

  Aumenta ou diminui a saturação da imagem usando um multiplicador. Por exemplo, 1.5 aumentaria a saturação em 50%, e 0.75 diminuiria a saturação em 25%.

• hue

  string | number(padrão: 100)

  Altera a matiz por meio da rotação das cores da imagem. O valor 100 não produziria nenhuma alteração, enquanto 0 e 200 inverterão as cores da imagem.

• contrast

  string | number(padrão: 1)

  Ajusta o contraste da imagem. Um valor de 1 não produz alterações. Valores abaixo de 1 diminuem o contraste (sendo 0 o contraste mínimo), e valores acima de 1 aumentam o contraste (sendo 2 o contraste máximo). Isso funciona como o parâmetro brightness.

• watermark_url

  string

  Uma URL que indica uma imagem PNG a ser sobreposta a esta imagem. Observe que você também pode fornecer a marca-d’água por meio de outro Assembly Step. Com a aplicação de marca-d’água, você pode adicionar uma imagem sobre outra. Isso geralmente é usado para logotipos.

• watermark_position

  bottom | bottom-left | bottom-right | center | left | right | top | mais 2 ↓ | Array<bottom | bottom-left | bottom-right | center | left | right | top | mais 2 ↓>(padrão: "center")

  A posição em que a marca-d’água é colocada. As opções disponíveis são "center", "top", "bottom", "left" e "right". Você também pode combinar opções, como "bottom-right".

  Também é possível especificar um array de valores possíveis, como [ "center", "left", "bottom-left", "bottom-right" ], caso em que um valor será selecionado aleatoriamente.

  Esta configuração coloca a marca-d’água no canto especificado. Para usar um deslocamento específico em pixels para a marca-d’água, você precisará adicionar o preenchimento à própria imagem.

• watermark_x_offset

  string | number(padrão: 0)

  O deslocamento no eixo x, em número de pixels, no qual a marca-d’água será colocada em relação à posição determinada por watermark_position.

  Os valores podem ser positivos ou negativos e produzem resultados diferentes dependendo do parâmetro watermark_position. Valores positivos aproximam a marca-d’água do ponto central da imagem, enquanto valores negativos a afastam do ponto central da imagem.

• watermark_y_offset

  string | number(padrão: 0)

  O deslocamento no eixo y, em número de pixels, no qual a marca-d’água será colocada em relação à posição determinada por watermark_position.

  Os valores podem ser positivos ou negativos e produzem resultados diferentes dependendo do parâmetro watermark_position. Valores positivos aproximam a marca-d’água do ponto central da imagem, enquanto valores negativos a afastam do ponto central da imagem.

• watermark_size

  string

  O tamanho da marca-d’água, em porcentagem.

  Por exemplo, um valor de "50%" significa que o tamanho da marca-d’água será 50% do tamanho da imagem sobre a qual ela é colocada. O dimensionamento exato também depende de watermark_resize_strategy.

• watermark_resize_strategy

  area | fit | min_fit | stretch(padrão: "fit")

  Os valores disponíveis são "fit", "min_fit", "stretch" e "area".

  Para explicar como as estratégias de redimensionamento funcionam, vamos supor que o tamanho da nossa imagem de destino seja 800×800 pixels e que a imagem da nossa marca-d’água tenha 400×300 pixels. Vamos supor também que o parâmetro watermark_size esteja definido como "25%".

  Na estratégia de redimensionamento "fit", a marca-d’água é redimensionada para que seu lado maior ocupe 25% do lado correspondente da imagem. O outro lado é redimensionado de acordo com a proporção da imagem da marca-d’água. Portanto, na nossa marca-d’água, a largura é o lado maior, e 25% do tamanho da imagem seria 200px. Assim, a marca-d’água seria redimensionada para 200×150 pixels. Se o parâmetro watermark_size estivesse definido como "50%", ela seria redimensionada para 400×300 pixels (ou seja, apenas manteria seu tamanho original).

  Na estratégia de redimensionamento "min_fit", a marca-d’água é redimensionada para que seu lado menor ocupe 25% do lado correspondente da imagem. O outro lado é redimensionado de acordo com a proporção da imagem da marca-d’água. Portanto, na nossa marca-d’água, a altura é o lado menor, e 25% do tamanho da imagem seria 200px. Assim, a marca-d’água seria redimensionada para 267×200 pixels. Se o parâmetro watermark_size estivesse definido como "50%", ela seria redimensionada para 533×400 pixels (ou seja, ficaria maior que seu tamanho original).

  Na estratégia de redimensionamento "stretch", a marca-d’água é esticada (ou seja, redimensionada sem levar em conta sua proporção) para que ambos os lados ocupem 25% do lado correspondente da imagem. Como nossa imagem tem 800×800 pixels, para um tamanho de marca-d’água de 25%, a marca-d’água seria redimensionada para 200×200 pixels. Sua altura pareceria esticada, pois, levando em conta a proporção, ela seria redimensionada para 200×150 pixels.

  Na estratégia de redimensionamento "area", a marca-d’água é redimensionada (mantendo sua proporção) para cobrir "xx%" da área da superfície da imagem. O valor de watermark_size é usado como porcentagem da área.

• watermark_opacity

  string | number(padrão: 1)

  A opacidade da marca-d’água, em que 0.0 é totalmente transparente e 1.0 é totalmente opaca.

  Por exemplo, um valor de 0.5 significa que a marca-d’água será 50% transparente, permitindo que a imagem abaixo dela fique visível. Isso é útil para uma identificação de marca sutil ou quando você quer que a marca-d’água seja menos intrusiva.

• watermark_repeat_x

  boolean(padrão: false)

  Quando definido como true, a marca-d’água será repetida horizontalmente por toda a largura da imagem.

  Isso é útil para criar padrões de marca-d’água em mosaico que cubram a imagem inteira e dificultem a remoção da marca-d’água por recorte.

• watermark_repeat_y

  boolean(padrão: false)

  Quando definido como true, a marca-d’água será repetida verticalmente por toda a altura da imagem.

  Isso é útil para criar padrões de marca-d’água em mosaico que cubram a imagem inteira. Pode ser combinado com watermark_repeat_x para criar um mosaico nas duas direções.

• text

  object | Array<object>

  Sobreposições de texto a serem aplicadas à imagem. Pode ser um único objeto de texto ou um array de objetos de texto. Cada objeto de texto contém regras de texto. Os parâmetros de texto a seguir são destinados ao uso como propriedades das suas sobreposições de texto. Veja um exemplo:

  "watermarked": {
    "use": "resized",
    "robot": "/image/resize",
    "text": [
      {
        "text": "© 2018 Transloadit.com",
        "size": 12,
        "font": "Ubuntu",
        "color": "#eeeeee",
        "valign": "bottom",
        "align": "right",
        "x_offset": 16,
        "y_offset": -10
      }
    ]
  }
  

• progressive

  boolean(padrão: false)

  Entrelaça a imagem se definido como true, o que faz com que a imagem carregue progressivamente nos navegadores. Em vez de renderizar a imagem de cima para baixo, o navegador primeiro mostrará uma versão desfocada e de baixa resolução da imagem, que será rapidamente substituída pela imagem real à medida que os dados chegarem. Isso melhora muito a experiência do usuário, mas aumenta o tamanho do arquivo em cerca de 10%.

• transparent

  string | transparent | none | black | white | red | green | blue | mais 6 ↓ | string

  Torna esta cor transparente na imagem. Exemplo: "255,255,255".

• trim_whitespace

  boolean(padrão: false)

  Determina se o espaço em branco adicional ao redor da imagem deve ser removido primeiro. Se você definir este parâmetro como true, ele removerá todas as bordas que tenham exatamente a mesma cor dos pixels dos cantos.

• clip

  string | boolean(padrão: false)

  Aplica o caminho de recorte às outras operações do Job de redimensionamento, se houver um. Se definido como true, usará automaticamente o primeiro caminho de recorte. Se definido como uma String, buscará um caminho de recorte com esse nome.

• negate

  boolean(padrão: false)

  Substitui cada pixel por sua cor complementar, produzindo o negativo da imagem. Especialmente útil ao testar recortes.

• clut

  boolean(padrão: false)

  Aplica uma imagem de tabela de consulta de cores (Color Look-Up Table, CLUT) para remapear as cores da imagem de entrada usando o operador -clut do ImageMagick. Quando habilitado, um segundo arquivo de entrada deve ser fornecido pelo parâmetro use com "as": "clut".

  Atualmente, essa operação é executada pelo stack convert do ImageMagick (não pelo daemon image-resizer), mesmo se stack: "daemon" for solicitado.

  Ao usar várias entradas, você deve fornecer sua imagem principal como "as": "base". Se nenhum alias base explícito for definido, a Transloadit usará a primeira entrada não auxiliar (um arquivo que não esteja marcado como watermark ou clut) como imagem principal.

  A imagem CLUT funciona como um mapa de gradiente: os canais de cor de cada pixel da entrada são substituídos pela cor correspondente da imagem CLUT, com base na intensidade do canal. Essa é uma técnica poderosa de gradação de cores, amplamente usada em fluxos de trabalho de fotografia e design.

  Exemplo:

  {
    "steps": {
      ":original": {
        "robot": "/upload/handle"
      },
      "lut_image": {
        "robot": "/upload/handle"
      },
      "color_graded": {
        "robot": "/image/resize",
        "use": {
          "steps": [
            { "name": ":original", "as": "base" },
            { "name": "lut_image", "as": "clut" }
          ]
        },
        "clut": true
      }
    }
  }
  

• density

  string | null(padrão: null)

  Enquanto a qualidade em memória e a profundidade do formato de arquivo especificam a resolução de cores, a densidade de uma imagem é sua resolução espacial. Ou seja, é a densidade (em pixels por polegada) de uma imagem e define a distância entre os pixels individuais (ou o tamanho deles). Ela define o tamanho físico da imagem quando exibida em dispositivos ou impressa.

  Você pode definir este valor como um width específico ou no formato widthxheight.

  Se a imagem convertida não estiver nítida, tente aumentar a densidade.

• monochrome

  boolean(padrão: false)

  Transforma a imagem em preto e branco. Este é um atalho para definir o espaço de cores como Gray e o tipo como Bilevel.

• shave

  string | number

  Remove pixels das bordas da imagem. O valor deve estar no formato width ou widthxheight para especificar o número de pixels a remover de cada lado.

Demonstrações

Publicações relacionadas no blog