Convertir, redimensionar o añadir marcas de agua a imágenes

🤖/image/resize redimensiona, recorta, cambia la colorización y la rotación, y aplica texto y marcas de agua a las imágenes.

Ejemplo de uso

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

Parámetros

• interpolate

  boolean | Record<string, boolean>

  Controla si las Assembly Variables se interpolan en campos de instrucciones individuales.

  De forma predeterminada, la mayoría de los campos de instrucciones de los Robots interpolan Assembly Variables. Establece esta opción en false para tratar todos los campos de instrucciones como texto literal, o establece la ruta de un campo individual en false para tratar únicamente ese campo como texto literal. En el caso de los campos específicos de un Robot que son literales de forma predeterminada, establece esta opción en true o la ruta de ese campo en true para volver a habilitar la interpolación.

  Usa nombres de campos como path o rutas con puntos como ffmpeg.vf para los objetos anidados.

• output_meta

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

  Te permite especificar un conjunto de metadatos cuyo cálculo requiere más recursos de CPU y que, por lo tanto, está desactivado de forma predeterminada para que tus Assemblies se procesen rápidamente.

  Para imágenes, puedes añadir "has_transparency": true a este objeto para determinar si la imagen contiene partes transparentes y "dominant_colors": true para extraer un array de códigos de color hexadecimales de la imagen.

  Para imágenes, también puedes añadir "blurhash": true para extraer una cadena BlurHash⁠, una representación compacta de un marcador de posición para la imagen que resulta útil para mostrar una vista previa desenfocada mientras se carga la imagen completa.

  Para videos, puedes añadir el parámetro "colorspace": true para extraer el espacio de color del video de salida.

  Para videos, también puedes añadir "interlaced": true para detectar si el video está entrelazado. Esto combina el indicador field_order de ffprobe, cuyo costo en recursos de procesamiento es bajo, con una pasada de muestreo limitada mediante idet sobre los primeros fotogramas de la fuente, y expone interlaced, field_order y un objeto de diagnóstico interlace_detection en file.meta. Esto requiere muchos recursos computacionales y se factura en consecuencia.

  Para audio, puedes añadir "mean_volume": true para obtener un único valor que represente el volumen promedio del archivo de audio.

  También puedes establecerlo en false para omitir la extracción de metadatos y acelerar la transcodificación.

• user_meta

  Record<string, any>(valor predeterminado: {})

  Añade metadatos personalizados a cada archivo emitido por este Robot sin modificar el contenido del archivo.

  Los valores se combinan con los user_meta existentes en el archivo de entrada. Si ambos objetos contienen la misma clave, el valor de este Robot tiene prioridad. Se admiten Assembly Variables, por ejemplo { "internal_file_id": "${file.id}" }.

• result

  boolean(valor predeterminado: false)

  Indica si los resultados de este Step deben aparecer en el Assembly Status JSON

• queue

  batch

  Establecer la cola en «batch» reduce manualmente la prioridad de los Jobs de este Step para evitar consumir cupos prioritarios con Jobs que no necesitan un tiempo de espera cero en la cola

• force_accept

  boolean(valor predeterminado: false)

  Forzar a un Robot a aceptar un tipo de archivo que habría ignorado.

  De forma predeterminada, los Robots ignoran los archivos que no reconocen. 🤖/video/encode, por ejemplo, ignorará sin problemas las imágenes de entrada.

  Si configuras el parámetro force_accept como true, puedes forzar a los Robots a aceptar todos los archivos que reciban. Esto normalmente provocará errores y solo debe usarse para depuración o para abordar casos extremos.

• ignore_errors

  boolean | Array<meta | execute>(valor predeterminado: [])

  Ignorar errores durante fases específicas del procesamiento.

  Establecer este parámetro en ["meta"] hará que el Robot ignore los errores durante la extracción de metadatos.

  Establecer este parámetro en ["execute"] hará que el Robot ignore los errores durante la fase principal de ejecución.

  Configurar este parámetro como true equivale a ["meta", "execute"] y hará que se ignoren los errores en ambas fases.

• use

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

  Especifica qué Step o Steps se usarán como entrada.

  • Puedes elegir cualquier nombre para los Steps, excepto ":original" (reservado para las subidas de usuarios gestionadas por Transloadit)
  • Puedes proporcionar varios Steps como entrada mediante arrays:

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

  • También puedes etiquetar los Steps de entrada con as para comunicar la intención semántica a los Robots:

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

  Consejo

  Probablemente eso sea todo lo que necesitas saber sobre use, pero puedes consultar los casos de uso avanzados.

• format

  string | null(valor predeterminado: null)

  El formato de salida de la imagen modificada.

  Algunos de los formatos disponibles más importantes son "jpg", "png", "gif", "tiff" y "jxl" para JPEG XL. Para consultar la lista completa de formatos en los que podemos escribir, revisa nuestra lista de formatos de imagen compatibles.

  Si se establece en null (valor predeterminado), el formato de la imagen de entrada se usará como formato de salida.

  Si deseas convertir a "pdf", considera usar 🤖/document/convert en su lugar.

• width

  number

  Ancho del resultado en píxeles. Si no se especifica, se usará de forma predeterminada el ancho de la imagen original.

• height

  number

  Altura de la nueva imagen en píxeles. Si no se especifica, se usará de forma predeterminada la altura de la imagen de entrada.

• resize_strategy

  "crop" | "fillcrop" | "fit" | "min_fit" | "pad" | "stretch"(valor predeterminado: "fit")

  Consulta la lista de estrategias de cambio de tamaño disponibles.

• zoom

  boolean(valor predeterminado: true)

  Si se establece en false, las imágenes más pequeñas no se estirarán hasta alcanzar el ancho y la altura deseados. Para obtener detalles sobre el efecto del zoom con tu estrategia de cambio de tamaño preferida, consulta la lista de estrategias de cambio de tamaño.

• crop

  object | string

  Especifica un objeto que contenga las coordenadas de las esquinas superior izquierda e inferior derecha del rectángulo que se recortará de las imágenes originales. El sistema de coordenadas tiene su origen en la esquina superior izquierda de la imagen. Los valores pueden ser números enteros para indicar valores absolutos en píxeles o strings para indicar valores porcentuales.

  Por ejemplo:

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

  Esto recortará el área comprendida entre (80, 100) y (600, 800) de una imagen de 1000×1000 píxeles, lo que da como resultado un cuadrado con un ancho de 520px y una altura de 700px. Si se establece crop, se ignoran los parámetros de ancho y altura, y resize_strategy se establece automáticamente en crop.

  También puedes usar de manera similar un string JSON de dicho objeto con coordenadas:

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

  Para recortar alrededor de rostros humanos, consulta 🤖/image/facedetect.

• gravity

  bottom | bottom-left | bottom-right | center | left | right | top | 2 más ↓ | attention | entropy(valor predeterminado: "center")

  La dirección desde la que se recortará la imagen cuando "resize_strategy" esté establecido en "crop" o "fillcrop", pero no se hayan definido coordenadas de recorte.

  También puedes usar "entropy" o "attention" para recortar automáticamente según el punto de interés. "entropy" conserva la región con la mayor entropía de Shannon, mientras que "attention" favorece las áreas con indicios de frecuencia de luminancia, saturación y tonos de piel.

• strip

  boolean(valor predeterminado: false)

  Elimina todos los metadatos de la imagen. Esto resulta útil para mantener las miniaturas lo más pequeñas posible.

• alpha

  Activate | Background | Copy | Deactivate | Extract | Off | On | 5 más ↓

  Permite controlar el canal alfa/mate de una imagen.

• preclip_alpha

  Activate | Background | Copy | Deactivate | Extract | Off | On | 5 más ↓

  Permite controlar el canal alfa/mate de una imagen antes de aplicar el trazado de recorte mediante clip: true.

• flatten

  boolean(valor predeterminado: true)

  Acopla todas las capas sobre el fondo especificado para obtener mejores resultados al convertir formatos transparentes en formatos no transparentes, como se explica en la documentación de ImageMagick⁠.

  Para conservar las animaciones, los archivos GIF no se acoplan cuando esta opción se establece en true. Para acoplar animaciones GIF, usa el parámetro frame.

• correct_gamma

  boolean(valor predeterminado: false)

  Evita los errores de gamma comunes en muchos algoritmos de escalado de imágenes⁠.

• quality

  string | number(valor predeterminado: 92)

  Controla la compresión de imágenes JPG y PNG. Consulta también 🤖/image/optimize.

• adaptive_filtering

  boolean(valor predeterminado: false)

  Controla la compresión de imágenes PNG. Establecerlo en true reduce el tamaño del archivo, pero aumenta el tiempo de procesamiento. Se recomienda mantener esta opción deshabilitada.

• background

  string | transparent | none | black | white | red | green | blue | 6 más ↓(valor predeterminado: "#FFFFFF")

  El código hexadecimal o el nombre⁠ del color utilizado para rellenar el fondo (se usa con la estrategia de redimensionamiento pad).

  Nota: De forma predeterminada, el fondo de las imágenes transparentes se cambia a blanco. Para conservar la transparencia, establece "background" en "none".

• frame

  string | number | null(valor predeterminado: null)

  Usa este parámetro al trabajar con archivos GIF animados para especificar qué fotograma del GIF se usa en la operación. Especifica 1 para usar el primer fotograma, 2 para usar el segundo y así sucesivamente. null indica todos los fotogramas.

• colorspace

  CMY | CMYK | Gray | HCL | HCLp | HSB | HSI | 28 más ↓

  Establece el espacio de color de la imagen. Para obtener detalles sobre los valores disponibles, consulta la documentación de ImageMagick⁠. Ten en cuenta que, si usabas "RGB", a partir de 2014-02-04 recomendamos usar "sRGB" en su lugar. ImageMagick podría intentar encontrar el valor de colorspace más eficiente según el color de una imagen y usar de forma predeterminada, por ejemplo, "Gray". Para forzar los colores, quizá debas usar este parámetro junto con type: "TrueColor".

• type

  Bilevel | ColorSeparation | ColorSeparationAlpha | Grayscale | GrayscaleAlpha | Palette | PaletteAlpha | 2 más ↓

  Establece el tipo de color de la imagen. Para obtener detalles sobre los valores disponibles, consulta la documentación de ImageMagick⁠. Si usas colorspace, ImageMagick podría intentar encontrar el valor más eficiente según el color de una imagen y usar de forma predeterminada, por ejemplo, "Gray". Para forzar los colores, podrías, por ejemplo, establecer este parámetro en "TrueColor"

• sepia

  string | number | null(valor predeterminado: null)

  Aplica un efecto de tono sepia expresado como porcentaje.

• rotation

  string | number | boolean | "auto"(valor predeterminado: true)

  Determina si se debe rotar la imagen. Usa cualquier número para especificar el ángulo de rotación en grados (por ejemplo, 90, 180, 270, 360 o valores precisos como 2.9). Usa el valor true o "auto" para rotar automáticamente las imágenes que estén giradas de forma incorrecta o que dependan de la configuración de rotación EXIF. De lo contrario, usa false para desactivar por completo la corrección automática.

• compress

  BZip | Fax | Group4 | JPEG | JPEG2000 | Lossless | LZW | 3 más ↓ | null(valor predeterminado: null)

  Especifica la compresión de píxeles que se aplica cuando se escribe la imagen. La compresión está desactivada de forma predeterminada.

  Consulta también 🤖/image/optimize.

• blur

  string | null(valor predeterminado: null)

  Especifica el desenfoque gaussiano mediante un valor con el formato {radius}x{sigma}. El valor de radio especifica el tamaño del área que el operador debe examinar al dispersar los píxeles y, por lo general, debe ser "0" o, como mínimo, dos veces el valor de sigma. El valor de sigma es una aproximación de cuántos píxeles se «dispersa» la imagen; considéralo el tamaño del pincel utilizado para desenfocarla. Este número es un valor de punto flotante, lo que permite usar valores pequeños como "0.5".

• blur_regions

  Array<object> | null(valor predeterminado: null)

  Especifica un array de objetos elípticos que deben desenfocarse en la imagen. Cada objeto tiene las siguientes claves: x, y, width, height. Si blur_regions tiene un valor, el parámetro blur se utiliza como intensidad del desenfoque de cada región.

• brightness

  string | number(valor predeterminado: 1)

  Aumenta o disminuye el brillo de la imagen mediante un multiplicador. Por ejemplo, 1.5 aumentaría el brillo en 50 % y 0.75 lo disminuiría en 25 %.

• saturation

  string | number(valor predeterminado: 1)

  Aumenta o disminuye la saturación de la imagen mediante un multiplicador. Por ejemplo, 1.5 aumentaría la saturación en 50 % y 0.75 la disminuiría en 25 %.

• hue

  string | number(valor predeterminado: 100)

  Cambia el matiz rotando el color de la imagen. El valor 100 no produciría ningún cambio, mientras que 0 y 200 invertirían los colores de la imagen.

• contrast

  string | number(valor predeterminado: 1)

  Ajusta el contraste de la imagen. Un valor de 1 no produce ningún cambio. Los valores inferiores a 1 disminuyen el contraste (0 corresponde al contraste mínimo), mientras que los valores superiores a 1 lo aumentan (2 corresponde al contraste máximo). Funciona como el parámetro brightness.

• watermark_url

  string

  Una URL que indica una imagen PNG que se superpondrá sobre esta imagen. Ten en cuenta que también puedes proporcionar la marca de agua mediante otro Assembly Step. Con una marca de agua puedes añadir una imagen sobre otra. Por lo general, se usa para logotipos.

• watermark_position

  bottom | bottom-left | bottom-right | center | left | right | top | 2 más ↓ | Array<bottom | bottom-left | bottom-right | center | left | right | top | 2 más ↓>(valor predeterminado: "center")

  La posición en la que se coloca la marca de agua. Las opciones disponibles son "center", "top", "bottom", "left" y "right". También puedes combinar opciones, como "bottom-right".

  También se puede especificar un array de valores posibles, en cuyo caso se seleccionará uno al azar, como [ "center", "left", "bottom-left", "bottom-right" ].

  Este ajuste coloca la marca de agua en la esquina especificada. Para aplicar un desplazamiento específico en píxeles a la marca de agua, tendrás que añadir el relleno a la propia imagen.

• watermark_x_offset

  string | number(valor predeterminado: 0)

  El desplazamiento en x, expresado en píxeles, con el que se colocará la marca de agua respecto de la posición que tiene debido a watermark_position.

  Los valores pueden ser positivos o negativos y producen resultados diferentes según el parámetro watermark_position. Los valores positivos acercan la marca de agua al punto central de la imagen, mientras que los valores negativos la alejan de él.

• watermark_y_offset

  string | number(valor predeterminado: 0)

  El desplazamiento en y, expresado en píxeles, con el que se colocará la marca de agua respecto de la posición que tiene debido a watermark_position.

  Los valores pueden ser positivos o negativos y producen resultados diferentes según el parámetro watermark_position. Los valores positivos acercan la marca de agua al punto central de la imagen, mientras que los valores negativos la alejan de él.

• watermark_size

  string

  El tamaño de la marca de agua, expresado como porcentaje.

  Por ejemplo, un valor de "50%" significa que el tamaño de la marca de agua será 50 % del tamaño de la imagen sobre la que se coloca. El tamaño exacto también depende de watermark_resize_strategy.

• watermark_resize_strategy

  area | fit | min_fit | stretch(valor predeterminado: "fit")

  Los valores disponibles son "fit", "min_fit", "stretch" y "area".

  Para explicar cómo funcionan las estrategias de redimensionamiento, supongamos que el tamaño de nuestra imagen de destino es de 800×800 píxeles y que nuestra imagen de marca de agua es de 400×300 píxeles. Supongamos también que el parámetro watermark_size está configurado como "25%".

  Con la estrategia de redimensionamiento "fit", la marca de agua se escala de modo que su lado más largo ocupe 25 % del lado correspondiente de la imagen. El otro lado se escala según la relación de aspecto de la imagen de la marca de agua. En nuestra marca de agua, el ancho es el lado más largo y 25 % del tamaño de la imagen equivaldría a 200px. Por lo tanto, la marca de agua se redimensionaría a 200×150 píxeles. Si watermark_size estuviera configurado como "50%", se redimensionaría a 400×300 píxeles (es decir, conservaría su tamaño original).

  Con la estrategia de redimensionamiento "min_fit", la marca de agua se escala de modo que su lado más corto ocupe 25 % del lado correspondiente de la imagen. El otro lado se escala según la relación de aspecto de la imagen de la marca de agua. En nuestra marca de agua, la altura es el lado más corto y 25 % del tamaño de la imagen equivaldría a 200px. Por lo tanto, la marca de agua se redimensionaría a 267×200 píxeles. Si watermark_size estuviera configurado como "50%", se redimensionaría a 533×400 píxeles (es decir, sería más grande que su tamaño original).

  Con la estrategia de redimensionamiento "stretch", la marca de agua se estira (es decir, se redimensiona sin conservar su relación de aspecto) para que ambos lados ocupen 25 % del lado correspondiente de la imagen. Como nuestra imagen es de 800×800 píxeles, con un tamaño de marca de agua de 25 %, esta se redimensionaría a 200×200 píxeles. Su altura se vería estirada porque, si se conservara la relación de aspecto, se redimensionaría a 200×150 píxeles.

  Con la estrategia de redimensionamiento "area", la marca de agua se redimensiona conservando su relación de aspecto para que cubra "xx%" de la superficie de la imagen. El valor de watermark_size se utiliza como porcentaje de la superficie.

• watermark_opacity

  string | number(valor predeterminado: 1)

  La opacidad de la marca de agua, donde 0.0 representa una transparencia total y 1.0 una opacidad total.

  Por ejemplo, un valor de 0.5 significa que la marca de agua tendrá una transparencia de 50 %, lo que permitirá ver la imagen subyacente. Esto resulta útil para mostrar una marca de forma sutil o cuando quieres que la marca de agua sea menos intrusiva.

• watermark_repeat_x

  boolean(valor predeterminado: false)

  Cuando se configura como true, la marca de agua se repite horizontalmente a lo largo de todo el ancho de la imagen.

  Esto resulta útil para crear patrones de mosaico de marcas de agua que cubran toda la imagen y dificulten la eliminación de la marca de agua mediante un recorte.

• watermark_repeat_y

  boolean(valor predeterminado: false)

  Cuando se configura como true, la marca de agua se repite verticalmente a lo largo de toda la altura de la imagen.

  Esto resulta útil para crear patrones de mosaico de marcas de agua que cubran toda la imagen. Se puede combinar con watermark_repeat_x para repetir el patrón en ambas direcciones.

• text

  object | Array<object>

  Superposiciones de texto que se aplicarán a la imagen. Pueden ser un solo objeto de texto o un array de objetos de texto. Cada objeto de texto contiene reglas de texto. Los siguientes parámetros de texto están diseñados para utilizarse como propiedades de tus superposiciones de texto. Este es un ejemplo:

  "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(valor predeterminado: false)

  Entrelaza la imagen cuando se configura como true, lo que hace que se cargue progresivamente en los navegadores. En lugar de renderizar la imagen de arriba abajo, el navegador muestra primero una versión borrosa de baja resolución, que luego se sustituye rápidamente por la imagen real a medida que llegan los datos. Esto mejora considerablemente la experiencia del usuario, pero aumenta el tamaño del archivo en aproximadamente 10 %.

• transparent

  string | transparent | none | black | white | red | green | blue | 6 más ↓ | string

  Haz que este color sea transparente dentro de la imagen. Ejemplo: "255,255,255".

• trim_whitespace

  boolean(valor predeterminado: false)

  Esto determina si primero se debe recortar el espacio en blanco adicional alrededor de la imagen. Si estableces este parámetro en true, se eliminarán todos los bordes que tengan exactamente el mismo color que los píxeles de las esquinas.

• clip

  string | boolean(valor predeterminado: false)

  Aplica el trazado de recorte a otras operaciones del trabajo de redimensionamiento, si existe uno. Si se establece en true, se usará automáticamente el primer trazado de recorte. Si se establece en una cadena, se buscará un trazado de recorte con ese nombre.

• negate

  boolean(valor predeterminado: false)

  Reemplaza cada píxel por su color complementario, lo que en la práctica crea el negativo de la imagen. Resulta especialmente útil al probar el recorte.

• clut

  boolean(valor predeterminado: false)

  Aplica una imagen de tabla de consulta de colores (CLUT) para reasignar los colores de la imagen de entrada mediante el operador -clut de ImageMagick. Cuando esta opción está habilitada, debes proporcionar un segundo archivo de entrada mediante el parámetro use con "as": "clut".

  Actualmente, esta operación se ejecuta mediante el stack de conversión de ImageMagick (no mediante el daemon image-resizer), incluso si se solicita stack: "daemon".

  Cuando uses varias entradas, debes proporcionar la imagen principal como "as": "base". Si no se establece explícitamente el alias base, Transloadit usará como imagen principal la primera entrada que no sea auxiliar (un archivo que no esté etiquetado como watermark ni clut).

  La imagen CLUT funciona como un mapa de degradado: los canales de color de cada píxel de la entrada se reemplazan por el color correspondiente de la imagen CLUT según la intensidad del canal. Esta es una potente técnica de gradación de color muy utilizada en flujos de trabajo de fotografía y diseño.

  Ejemplo:

  {
    "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(valor predeterminado: null)

  Mientras que la calidad en memoria y la profundidad del formato de archivo especifican la resolución de color, la densidad de una imagen es su resolución espacial. Es decir, es la densidad de una imagen (en píxeles por pulgada) y define la separación entre los píxeles individuales (o su tamaño). Define el tamaño de la imagen en términos reales cuando se muestra en dispositivos o se imprime.

  Puedes establecer este valor como width o con el formato widthxheight.

  Si la imagen convertida está poco nítida, prueba a aumentar la densidad.

• monochrome

  boolean(valor predeterminado: false)

  Transforma la imagen a blanco y negro. Es una forma abreviada de establecer el espacio de color en Gray y el tipo en Bilevel.

• shave

  string | number

  Elimina píxeles de los bordes de la imagen. El valor debe tener el formato width o widthxheight para especificar la cantidad de píxeles que se eliminarán de cada lado.

Demos

Publicaciones relacionadas del blog