Características y funcionalidades

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 parse

Utiliza 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:

FormatoBehavior
GIFFrameCount refleja el número de fotogramas cuando el archivo contiene varios fotogramas; se omite si no se puede determinar el recuento
BMPUna altura negativa en el encabezado (orden de filas de arriba a abajo) se normaliza — Height devuelve la magnitud positiva
DICOMEl 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:

FormatoAncho / AlturaProfundidad de bitsRecuento 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 null

Esto 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 DetectFormat en lugar de Probe cuando solo necesitas el formato, no las dimensiones
  • Comprueba Width/Height/BitDepth/FrameCount para null antes 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
  • ImageProbe es completamente estático — sin instancia, sin IDisposable, sin objeto de configuración

Problemas comunes

ProblemaCausaSolución
Format es ImageFormat.UnknownEl encabezado no coincide con ninguno de los 11 formatos reconocidosConfirme que el archivo sea uno de PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF o DICOM
Width/Height son nullEl encabezado del formato no contiene ese campo, o el encabezado fue truncado antes de ese campoVerifique Format primero; no todos los campos están poblados para cada formato
La altura BMP parece inesperadamente positivaEl archivo fuente utilizó una altura negativa (de arriba a abajo) en su encabezadoEsperado — 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étodoDescripció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[]
ImageInfoTipo de resultado: Format, Width, Height, BitDepth, FrameCount
ImageFormatEnum: Unknown, Png, Jpeg, Gif, Bmp, WebP, Ico, Tiff, Psd, Emf, Wmf, Dicom

Ver también

 Español