# image.dkh: tamaño, miniaturas, compresión y formatos de imágenes `image.dkh` trabaja con archivos de imagen: averigua su tamaño, las redimensiona, crea miniaturas proporcionales, las comprime y cambia su formato. Usa ImageMagick a través de Magick.NET (`Devkron.Ext.Image.dll`), así que **se instala aparte** del motor: vea [Bibliotecas de terceros](/es/devkron/2.0/bibliotecas/terceros/). ## Cuándo usarla - Galerías de productos y catálogos: generar la miniatura al subir la foto. - Bitácoras y evidencias con fotos de celular: reducirlas antes de guardarlas. - Convertir PNG a JPG o WebP para que las páginas carguen más rápido. ## Instalación Copie junto a `dkl` (o a la carpeta del servidor FastCGI) `image.dkh`, `Devkron.Ext.Image.dll`, `Magick.NET-Q16-HDRI-AnyCPU.dll`, `Magick.NET.Core.dll` y la biblioteca nativa de su plataforma (`Magick.Native-Q16-HDRI-x64.dll.so` en Linux x64, `Magick.Native-Q16-HDRI-x64.dll` en Windows x64; existen también las de arm64). La biblioteca nativa se busca junto a `Devkron.Ext.Image.dll`. ```dkl #include "image.dkh" ``` ## Si ya usa magick.dkh Algunas instalaciones de Devkron 1.x tienen la extensión `magick.dkh` (`Devkron.Magick.dll`), que define `image.size`, `image.resize`, `image.compress` e `image.newer`. `image.dkh` conserva esos nombres y su comportamiento, y agrega `image.thumbnail` e `image.convert`. Diferencias: `image.newer` devuelve `-2` cuando falta el segundo archivo (la anterior devolvía `1`) e `image.compress` con un archivo inexistente da un error en español. No incluya los dos encabezados en el mismo programa: definen las mismas funciones. ## Funciones | Función | Devuelve | Descripción | |---|---|---| | `image.size(archivo)` | registro o nulo | `width`, `height` (píxeles) y `size_kb` | | `image.resize(archivo, ancho, alto)` | 1 / 0 | Redimensiona sobrescribiendo el archivo | | `image.thumbnail(origen, destino, lado_mayor)` | 1 | Miniatura proporcional en otro archivo | | `image.compress(archivo, optimo, con_perdida)` | 1 / 0 | Optimiza el archivo en su lugar | | `image.convert(origen, destino)` | 1 | Cambia el formato según la extensión del destino | | `image.newer(archivo1, archivo2)` | número | Cuál de dos archivos se modificó después | ### image.size(archivo) Devuelve un registro `{width, height, size_kb}`; `size_kb` es el tamaño del archivo en KB con dos decimales. Si el archivo no existe o no es una imagen, devuelve **nulo** (no lanza error): compruébelo con `isnull()`. ### image.resize(archivo, ancho, alto) Redimensiona y **sobrescribe** el archivo. - Si `ancho` o `alto` es `0`, conserva la proporción con el otro valor. - Si los dos son distintos de `0`, deja la imagen de ese tamaño exacto (puede deformarla). - Devuelve `1` si lo logró y `0` si no (archivo inexistente, no es imagen); no lanza error. ### image.thumbnail(origen, destino, lado_mayor) Crea en `destino` una miniatura cuyo lado más largo mide `lado_mayor` píxeles, conservando la proporción. Además: - Endereza las fotos según su orientación EXIF (las de celular salen derechas). - Quita los metadatos (ubicación GPS, modelo de cámara). - **No agranda** imágenes más chicas que `lado_mayor`: las copia al formato de destino sin metadatos. - El formato sale de la extensión de `destino` (vea `image.convert`). Errores: `image: no existe el archivo '…'.`, `image: el lado mayor de la miniatura debe ser de 1 píxel o más.`, `image: no se pudo crear la miniatura de '…': …` (carpeta de destino inexistente, formato no admitido, archivo dañado). ### image.compress(archivo, optimo, con_perdida) Optimiza el archivo en su lugar (JPEG, PNG, GIF, ICO). - `optimo`: `@true` para la compresión más lenta y más pequeña. - `con_perdida`: `@true` permite perder calidad (JPEG); `@false` solo compresión sin pérdida. - Devuelve `1` si redujo el archivo y `0` si no pudo reducirlo (formato no admitido o ya optimizado). - Error: `image: no existe el archivo '…'.` o `image: no se pudo comprimir '…': …`. ### image.convert(origen, destino) Guarda `origen` en el formato que indica la extensión de `destino`: `jpg`/`jpeg`, `png`, `gif`, `webp`, `bmp`, `tif`/`tiff`, `ico`, `avif`, `heic` o `pdf`. Al pasar una imagen con transparencia a JPG o BMP el fondo queda blanco. Errores (todos con `image: no se pudo convertir '…' a '…': …` salvo el primero): | Detalle | Causa | |---|---| | `image: no existe el archivo '…'.` | No existe el origen | | `formato de destino no admitido: .xyz (…)` | Extensión que no está en la lista | | `el destino '…' no tiene extensión para elegir el formato` | Destino sin extensión | | `no existe la carpeta de destino '…'` | Cree la carpeta antes con `dir.create` | | `InsufficientImageDataInFile …` | El origen no es una imagen válida | ### image.newer(archivo1, archivo2) Compara las fechas de modificación: `1` si `archivo1` es más reciente, `2` si lo es `archivo2`, `0` si son iguales, `-1` si no existe `archivo1` y `-2` si no existe `archivo2`. Sirve para regenerar una miniatura solo cuando la foto original cambió. ## Ejemplo: miniaturas de una carpeta de fotos ```dkl #include "dkli.dkh" #! program "miniaturas" { #include "functions.dkh" #include "serialize.dkh" #include "image.dkh" origen = "fotos" destino = "fotos/miniaturas" if not(dir.exists(destino)) { do dir.create(destino) } ref archivos = list.files(origen, "*.*") for i=0; i " + str(field.num(m, "width")) + "x" + str(field.num(m, "height")) + " (" + str(field.num(m, "size_kb")) + " KB)") } } } ``` Salida (el orden de los archivos depende del sistema de archivos): ``` falsa: no es una imagen, se omite alpha: 300x200 -> 160x107 (1.65 KB) ancho: 1000x250 -> 160x40 (0.14 KB) foto: 800x600 -> 160x120 (0.55 KB) chico: 64x64 -> 64x64 (0.88 KB) ``` Para regenerar solo las que cambiaron, antes de `image.thumbnail` pregunte `if image.newer(ruta, th) != 2`. ## Buenas prácticas con imágenes que suben los usuarios ImageMagick reconoce el formato **por el contenido del archivo, no por la extensión**, y entiende muchos formatos (SVG, PostScript, MVG, MSL…). Con fotos que suben los usuarios: - **Limite el tamaño del archivo** antes de procesarlo (`field.num(httpreq.file(campo), "size")` de [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md)), por ejemplo a 10 MB. - **Acepte solo los formatos que necesita**: revise la extensión y además los primeros bytes del archivo (JPEG empieza con `FF D8 FF`, PNG con `89 50 4E 47`, GIF con `GIF8`, WebP con `RIFF`…`WEBP`). Rechace SVG, PDF y PostScript si no los necesita. - **Revise las dimensiones** con `image.size` antes de redimensionar: una imagen pequeña en bytes puede declarar 50 000 × 50 000 píxeles y agotar la memoria. Rechace las que pasen de un límite (por ejemplo, 8 000 píxeles por lado). - **No arme la ruta de destino con datos del cliente.** `image.convert`, `image.thumbnail` y `image.resize` escriben donde se les indica: genere usted el nombre (`hash.random_token(16) + ".webp"`) dentro de una carpeta fija. - Guarde el original fuera de la carpeta pública del sitio y publique solo la miniatura generada. ## Advertencias - **`image.resize` y `image.compress` sobrescriben el original.** Si necesita conservarlo, copie primero el archivo o use `image.thumbnail`/`image.convert`, que escriben en otro archivo. - **Memoria y CPU**: ImageMagick descomprime la imagen completa en memoria; una foto de 48 megapíxeles ocupa cientos de MB. En un servidor FastCGI no procese muchas fotos grandes a la vez: hágalo en una tarea de consola o limite la concurrencia con [threads.dkh](/es/devkron/2.0/bibliotecas/estandar/threads.md). - **Plataformas**: el zip trae la biblioteca nativa solo para **Linux x64 (glibc)** y **Windows x64**. En ARM, Alpine (musl) o macOS la biblioteca no funciona con el zip estándar. - **Versión**: Magick.NET 15.0.0 con ImageMagick 7.1.2-33. Si la carpeta de `dkl` ya tiene `Magick.NET-*.dll` de una versión anterior, los del zip los reemplazan. - **Formatos AVIF y HEIC** dependen de la biblioteca nativa de ImageMagick incluida; pruébelos en su servidor antes de ofrecerlos.