Características y funcionalidades
Visión general
Esta página cubre cada área de funcionalidad de Aspose.Imaging FOSS para la detección de formatos y la inspección de encabezados de .NET, con ejemplos funcionales de C#. La biblioteca nunca decodifica datos de píxeles — cada método lee solo el encabezado del archivo.
Detección de Formato
ImageProbe es el punto de entrada estático. Tres sobrecargas cubren una ruta de archivo, un flujo y una matriz de bytes cruda:
using Aspose.Imaging.Foss;
var fromPath = ImageProbe.ProbeFile("photo.jpg");
var fromBytes = ImageProbe.Probe(byteArray);
var fromStream = ImageProbe.Probe(stream);
var formatOnly = ImageProbe.DetectFormat(byteArray); // ImageFormat only, no header parseUtiliza DetectFormat cuando solo necesitas ramificar según el formato; utiliza Probe/ProbeFile cuando también necesitas dimensiones, profundidad de bits o recuento de fotogramas.
Lectura de Metadatos del Encabezado
ProbeFile/Probe devuelven un ImageInfo con nullable Width, Height, BitDepth y FrameCount — cada uno poblado solo cuando el encabezado del formato detectado realmente contiene ese valor:
var info = ImageProbe.ProbeFile("scan.dcm");
if (info.Width.HasValue && info.Height.HasValue)
{
Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}");
}Format (un valor enum ImageFormat) siempre se establece una vez que se reconoce la cabecera — es el único campo garantizado a ser poblado.
Notas por formato
Algunos formatos tienen peculiaridades en la cabecera que ImageInfo normaliza o expone directamente:
| Formato | Behavior |
|---|---|
| GIF | FrameCount refleja el número de fotogramas cuando el archivo contiene varios fotogramas; se omite si no se puede determinar el recuento |
| BMP | Una altura negativa en el encabezado (orden de filas de arriba a abajo) se normaliza — Height devuelve la magnitud positiva |
| DICOM | El análisis del encabezado maneja las sintaxis de transferencia Implicit VR Little Endian y Explicit VR Little/Big Endian, extrayendo filas, columnas y bits asignados |
// DICOM: rows -> Height, columns -> Width, bitsAllocated -> BitDepth,
// across any of the three common transfer syntaxes
var dicomInfo = ImageProbe.Probe(dicomBytes);
Console.WriteLine($"{dicomInfo.Width}x{dicomInfo.Height}, {dicomInfo.BitDepth}-bit");Formatos compatibles
Los 11 formatos se detectan de la misma manera — ImageProbe identifica el formato y lee los metadatos de la cabecera; nunca decodifica ni vuelve a codificar datos de píxeles para ninguno de ellos. La población de campos varía realmente según el formato, sin embargo — cada formato establece Format, pero solo algunos incluyen profundidad de bits o recuento de fotogramas en su cabecera:
| Formato | Ancho / Altura | Profundidad de bits | Recuento de fotogramas |
|---|---|---|---|
| PNG | ✓ | ✓ | ✓ |
| JPEG | ✓ | ✓ | — |
| GIF | ✓ | — | ✓ |
| BMP | ✓ | ✓ | — |
| WebP | ✓ | — | — |
| ICO | ✓ | ✓ | ✓ |
| TIFF | ✓ | ✓ | ✓ |
| PSD | ✓ | ✓ | — |
| EMF | ✓ (desde los límites) | — | — |
| WMF (colocable) | ✓ (asume 96 DPI) | — | — |
| DICOM | ✓ (Filas/Columnas) | ✓ (BitsAllocated) | — |
Una cabecera no reconocida se resuelve a ImageFormat.Unknown en lugar de lanzar una excepción. Algunos detalles notables de población de campos: el FrameCount de PNG es siempre 1 (una constante, no una detección real de fotogramas PNG animado); el FrameCount de ICO es un recuento genuino de los tamaños de íconos incrustados en el directorio, y un byte de dimensión 0 en una entrada de directorio ICO significa 256 px según la especificación del formato; el FrameCount de TIFF refleja una caminata acotada de la cadena IFD del archivo (cada IFD es una página); el WMF no colocable sigue siendo identificado correctamente como ImageFormat.Wmf pero solo devuelve Format — las dimensiones se rellenan solo para WMF colocable, mediante una conversión codificada de 96 DPI a partir de los límites de unidades-por-pulgada de la cabecera; EMF no tiene ningún campo explícito de ancho/alto, por lo que sus dimensiones se derivan del rectángulo de espacio de dispositivo rclBounds en su lugar.
Resistente por diseño
ImageProbe nunca lanza una excepción con entrada malformada o truncada. En lugar de levantar una excepción, devuelve un ImageInfo parcial — Format se establece siempre que se reconozca el marcador de formato de la cabecera, incluso cuando el resto del archivo está recortado o corrupto:
byte[] truncated = fullFileBytes[..^3];
var info = ImageProbe.Probe(truncated);
// info.Format is still populated; other fields may be nullEsto lo hace seguro para ejecutarse contra descargas no confiables, parciales o en curso sin necesidad de un try/catch alrededor de cada llamada.
Consejos y mejores prácticas
- Utiliza
DetectFormaten lugar deProbecuando solo necesitas el formato, no las dimensiones - Comprueba
Width/Height/BitDepth/FrameCountparanullantes de usarlos — no están poblados para todos los formatos - Prefiere
Probe(stream)sobre leer todo un archivo en una matriz de bytes primero al trabajar con archivos grandes ImageProbees completamente estático — sin instancia, sinIDisposable, sin objeto de configuración
Problemas comunes
| Problema | Causa | Solución |
|---|---|---|
Format es ImageFormat.Unknown | El encabezado no coincide con ninguno de los 11 formatos reconocidos | Confirme que el archivo sea uno de PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF o DICOM |
Width/Height son null | El encabezado del formato no contiene ese campo, o el encabezado fue truncado antes de ese campo | Verifique Format primero; no todos los campos están poblados para cada formato |
| La altura BMP parece inesperadamente positiva | El archivo fuente utilizó una altura negativa (de arriba a abajo) en su encabezado | Esperado — ImageInfo.Height siempre se normaliza a la magnitud positiva |
FAQ
¿ImageProbe decodifica datos de píxeles?
No. Cada método lee solo el encabezado del archivo — dimensiones, profundidad de bits y recuento de fotogramas — nunca el contenido de los píxeles. La decodificación y el renderizado están fuera del alcance de esta biblioteca.
¿Qué ocurre si inspecciono un archivo corrupto o truncado?
ImageProbe nunca lanza una excepción por entrada malformada o truncada. Devuelve un ImageInfo con los campos que pudo determinar a partir de los bytes de encabezado disponibles — Format se establece siempre que se reconozca el marcador de formato.
¿Puedo inspeccionar una secuencia que no sea buscable?
Sí. Probe(stream) acepta tanto secuencias buscables como no buscables.
Resumen de API Reference
| Clase / Método | Descripción |
|---|---|
ImageProbe.ProbeFile(path) | Sondea un archivo por ruta, devolviendo un ImageInfo |
ImageProbe.Probe(stream) | Sondea un Stream (buscable o no) |
ImageProbe.Probe(data) | Sondea un byte[] crudo |
ImageProbe.DetectFormat(stream) | Devuelve solo el ImageFormat para un stream |
ImageProbe.DetectFormat(data) | Devuelve solo el ImageFormat para un byte[] |
ImageInfo | Tipo de resultado: Format, Width, Height, BitDepth, FrameCount |
ImageFormat | Enum: Unknown, Png, Jpeg, Gif, Bmp, WebP, Ico, Tiff, Psd, Emf, Wmf, Dicom |