Compor imagens remotas com cURL e ImageMagick

Tim Koschützki

Cofundador · Berlim, Alemanha ·

Combinar um fundo baixado com uma sobreposição é útil para relatórios, dashboards e prévias geradas automaticamente. Este exemplo compõe imagens da NASA; não se trata de uma integração com dados meteorológicos em tempo real. A mesma estrutura de processamento pode funcionar com um provedor de dados meteorológicos, desde que as URLs das imagens, o licenciamento e os requisitos de atualização sejam verificados.

Compatibilidade de versões

Use Bash, ImageMagick 7 com o comando magick e cURL 8.4 ou mais recente. O requisito do cURL é importante porque o limite de tamanho do download também precisa interromper respostas sem um tamanho de conteúdo conhecido. Mantenha tanto a ferramenta de download quanto a de decodificação de imagens em versões com manutenção ativa.

Visão geral

Um pipeline confiável precisa verificar os downloads que realmente processa, em vez de baixar uma vez para testar uma URL e depois baixar de novo sem verificação. O script baixa cada fonte para um diretório privado da tarefa, compõe a imagem e remove as entradas temporárias. Um diretório de saída novo evita colisões com resultados anteriores.

Configurando o pipeline

O exemplo usa uma foto do pouso na Lua e um logotipo da NASA, a partir de URLs hospedadas pela NASA. Siga as orientações da NASA sobre o uso de imagens e mídia, incluindo as restrições ao uso de sua insígnia; estes arquivos de exemplo não implicam endosso.

Requisitos da substituição de processos

A substituição de processos, como <(curl ...), é um recurso do Bash, não um requisito do shell POSIX. Mais importante ainda: uma falha em um download em segundo plano não se torna automaticamente o status de saída do comando de imagem. Esta implementação usa downloads verificados explicitamente em vez de substituição de processos.

Baixando e compondo imagens sob demanda

Salve o conteúdo a seguir como compose.sh. Informe duas URLs HTTPS confiáveis e um diretório de saída novo:

#!/bin/bash
set -euo pipefail

if [ "$#" -ne 3 ]; then
  echo "Usage: $0 <background-https-url> <overlay-https-url> <new-output-directory>" >&2
  exit 1
fi

background_url=$1
overlay_url=$2
output_dir=$3
[[ $output_dir = /* ]] || output_dir=$PWD/$output_dir
if ! mkdir -m 700 -- "$output_dir"; then
  echo "Use a new output directory" >&2
  exit 1
fi

cleanup() {
  local status=$?
  rm -f -- "$output_dir/background.image" "$output_dir/overlay.image"
  if [ "$status" -ne 0 ]; then
    rm -f -- "$output_dir/result.jpg"
    rmdir -- "$output_dir"
  fi
}
trap cleanup EXIT

fetch_image() {
  curl --disable --globoff --fail --silent --show-error --location \
    --proto '=https' --proto-redir '=https' --max-redirs 3 \
    --connect-timeout 10 --max-time 30 --retry 2 --retry-max-time 60 \
    --max-filesize 10485760 --output "$2" --url "$1"
}

fetch_image "$background_url" "$output_dir/background.image"
fetch_image "$overlay_url" "$output_dir/overlay.image"
cd -P -- "$output_dir"
output_dir=$PWD
magick -limit memory 256MiB -limit map 512MiB -limit disk 1GiB \
  -limit width 10000 -limit height 10000 \
  background.image -resize '1600x1600>' \
  \( overlay.image -resize '300x300>' \) \
  -gravity southeast -geometry +20+20 -composite result.jpg
[ -s result.jpg ] || { echo "No image produced" >&2; exit 1; }
echo "Composite saved: $output_dir/result.jpg"

Execute-o com um armazenamento de saída novo:

bash compose.sh \
  'https://images-assets.nasa.gov/image/as11-40-5874/as11-40-5874~orig.jpg' \
  'https://www.nasa.gov/wp-content/uploads/2023/04/nasa-logo-web-rgb.png' \
  nasa-composite

Uma tarefa concluída contém result.jpg. Falhas de download ou de decodificação retornam um status de saída diferente de zero e removem apenas os arquivos parciais da própria tarefa. Não deixe outros processos gravarem nesse diretório enquanto a tarefa estiver em execução.

Considerações sobre memória

Um arquivo compactado pequeno pode ser decodificado em uma imagem grande. O script limita os bytes baixados, as dimensões da imagem decodificada e os recursos de cache do ImageMagick, mas essas configurações não são um limite completo de memória do processo nem de tempo de execução. O ImageMagick pode usar armazenamento temporário em disco para caches de pixels. Configure a política de segurança dele e aplique limites de memória, disco e tempo no sistema operacional para os workers de produção.

Considerações de segurança

Use fontes de imagem conhecidas e confiáveis. Transferência somente por HTTPS e verificação de certificados não impedem SSRF: uma URL arbitrária ou um redirecionamento ainda pode apontar para um serviço de rede privada. Uma API pública de upload ou de processamento de URLs precisa de uma política de origens separada, validação de redirecionamentos, controles de saída de rede e autenticação. Não exponha este script de shell como um buscador de URLs sem restrições.

Não desative a verificação TLS nem as checagens de revogação de certificados para fazer um download com falha passar. Mantenha a configuração e as credenciais do cURL fora deste worker; --disable impede o carregamento automático do arquivo de configuração padrão do curl do usuário.

Aplicações práticas

Essa estrutura pode compor imagens de dashboards, sobreposições de eventos ou ilustrações de relatórios. Valide a fonte de dados real, a política de atualização, as dimensões das imagens e os direitos de uso de cada fluxo de trabalho. O exemplo da NASA demonstra a composição, não uma previsão do tempo nem um benchmark de latência.

Tratamento de erros e otimização

O único helper fetch_image concentra as opções de download e a política de novas tentativas para as duas fontes. As novas tentativas são limitadas e se aplicam às falhas do cURL que admitem nova tentativa. Um 404 ou uma imagem inválida precisa falhar de forma visível, em vez de ser tratado como uma sobreposição vazia, mas bem-sucedida. Verifique o status de saída do script antes de publicar o resultado.

Armazenar em cache as entradas validadas pode reduzir downloads repetidos. Deixe explícitas a validade e a integridade do cache; não adicione um segundo download não verificado depois de uma verificação bem-sucedida.

Conclusão

cURL e ImageMagick formam um pipeline de automação útil quando as transferências reais, o resultado do decodificador e a propriedade da saída são verificados. Reutilize uma única política de download, mantenha os arquivos intermediários privados e inspecione a imagem composta antes de publicá-la.

Para fluxos de trabalho de imagem gerenciados, conheça o serviço de processamento de imagens da Transloadit.