Recursos e Funcionalidades
Visão geral
Esta página cobre todas as áreas de recurso do Aspose.Imaging FOSS para a detecção de formato e sondagem de cabeçalho do .NET, com exemplos funcionais de C#. A biblioteca nunca decodifica dados de pixel — cada método lê apenas o cabeçalho do arquivo.
Detecção de Formato
ImageProbe é o ponto de entrada estático. Três sobrecargas cobrem um caminho de arquivo, um fluxo e um array de bytes bruto:
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 parseUse DetectFormat quando você só precisa ramificar com base no formato; use Probe/ProbeFile quando também precisar de dimensões, profundidade de bits ou contagem de quadros.
Lendo Metadados do Cabeçalho
ProbeFile/Probe retornam um ImageInfo com Width anulável, Height, BitDepth e FrameCount — cada um preenchido somente quando o cabeçalho do formato detectado realmente contém esse valor:
var info = ImageProbe.ProbeFile("scan.dcm");
if (info.Width.HasValue && info.Height.HasValue)
{
Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}");
}Format (um valor enum ImageFormat) é sempre definido assim que o cabeçalho é reconhecido — é o único campo garantido a ser preenchido.
Observações por Formato
Alguns formatos têm peculiaridades de cabeçalho que ImageInfo normaliza ou expõe diretamente:
| Formato | Behavior |
|---|---|
| GIF | FrameCount reflete o número de quadros quando o arquivo contém múltiplos quadros; omitido se a contagem não puder ser determinada |
| BMP | Uma altura negativa no cabeçalho (ordem de linhas de cima para baixo) é normalizada — Height devolve a magnitude positiva |
| DICOM | A análise do cabeçalho lida com as sintaxes de transferência Implicit VR Little Endian e Explicit VR Little/Big Endian, extraindo linhas, colunas e bits alocados |
// 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 Suportados
Todos os 11 formatos são detectados da mesma forma — ImageProbe identifica o formato e lê os metadados do cabeçalho; nunca decodifica ou reencoda dados de pixel para nenhum deles. A população de campos realmente varia por formato, porém — cada formato define Format, mas apenas alguns contêm profundidade de bits ou contagem de quadros em seu cabeçalho:
| Formato | Largura / Altura | Profundidade de bits | Contagem de quadros |
|---|---|---|---|
| PNG | ✓ | ✓ | ✓ |
| JPEG | ✓ | ✓ | — |
| GIF | ✓ | — | ✓ |
| BMP | ✓ | ✓ | — |
| WebP | ✓ | — | — |
| ICO | ✓ | ✓ | ✓ |
| TIFF | ✓ | ✓ | ✓ |
| PSD | ✓ | ✓ | — |
| EMF | ✓ (dos limites) | — | — |
| WMF (colocável) | ✓ (presume 96 DPI) | — | — |
| DICOM | ✓ (Linhas/Colunas) | ✓ (BitsAllocated) | — |
Um cabeçalho não reconhecido resolve para ImageFormat.Unknown em vez de lançar exceção. Alguns detalhes notáveis de população de campos: o FrameCount do PNG é sempre 1 (uma constante, não detecção real de quadros PNG animados); o FrameCount do ICO é uma contagem genuína dos tamanhos de ícone incorporados no diretório, e um byte de dimensão 0 em uma entrada de diretório ICO significa 256 px conforme a especificação do formato; o FrameCount do TIFF reflete uma caminhada limitada da cadeia IFD do arquivo (cada IFD é uma página); o WMF não posicionável ainda é identificado corretamente como ImageFormat.Wmf, mas retorna apenas Format — as dimensões são preenchidas apenas para WMF posicionável, via conversão fixa de 96 DPI a partir dos limites de unidades-por-polegada do cabeçalho; o EMF não possui campo explícito de largura/altura, portanto suas dimensões são derivadas do retângulo de espaço de dispositivo rclBounds.
Resiliente por Design
ImageProbe nunca lança exceção em entrada malformada ou truncada. Em vez de gerar uma exceção, ele devolve um ImageInfo parcial — Format é definido sempre que o marcador de formato do cabeçalho foi reconhecido, mesmo quando o resto do arquivo está cortado ou corrompido:
byte[] truncated = fullFileBytes[..^3];
var info = ImageProbe.Probe(truncated);
// info.Format is still populated; other fields may be nullIsso torna seguro executar contra downloads não confiáveis, parciais ou em andamento, sem a necessidade de um try/catch ao redor de cada chamada.
Dicas e Melhores Práticas
- Use
DetectFormatem vez deProbequando você só precisa do formato, não das dimensões - Verifique
Width/Height/BitDepth/FrameCountparanullantes de usá-los — eles não são preenchidos para todos os formatos - Prefira
Probe(stream)em vez de ler um arquivo inteiro para um array de bytes primeiro ao trabalhar com arquivos grandes ImageProbeé totalmente estático — sem instância, semIDisposable, sem objeto de configuração
Problemas Comuns
| Problema | Causa | Corrigir |
|---|---|---|
Format é ImageFormat.Unknown | O cabeçalho não corresponde a nenhum dos 11 formatos reconhecidos | Confirme que o arquivo é um dos seguintes: PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF ou DICOM |
Width/Height são null | O cabeçalho do formato não contém esse campo, ou o cabeçalho foi truncado antes desse campo | Verifique Format primeiro; nem todo campo é preenchido para todos os formatos |
| A altura BMP parece inesperadamente positiva | O arquivo de origem usou uma altura negativa (de cima para baixo) em seu cabeçalho | Esperado — ImageInfo.Height sempre normaliza para a magnitude positiva |
FAQ
O ImageProbe decodifica dados de pixel?
Não. Cada método lê apenas o cabeçalho do arquivo — dimensões, profundidade de bits e contagem de quadros — nunca o conteúdo dos pixels. Decodificação e renderização estão fora do escopo desta biblioteca.
O que acontece se eu sondar um arquivo corrompido ou truncado?
ImageProbe nunca lança exceção para entrada malformada ou truncada. Ele retorna um ImageInfo com os campos que pôde determinar a partir dos bytes de cabeçalho disponíveis — Format é definido sempre que o marcador de formato foi reconhecido.
Posso sondar um fluxo que não seja buscável?
Sim. Probe(stream) aceita fluxos tanto buscáveis quanto não buscáveis.
API Reference Resumo
| Classe / Método | Descrição |
|---|---|
ImageProbe.ProbeFile(path) | Investigue um arquivo por caminho, retornando um ImageInfo |
ImageProbe.Probe(stream) | Investigue um Stream (buscável ou não) |
ImageProbe.Probe(data) | Teste um byte[] bruto |
ImageProbe.DetectFormat(stream) | Retorne apenas o ImageFormat para um fluxo |
ImageProbe.DetectFormat(data) | Retorne apenas o ImageFormat para um byte[] |
ImageInfo | Tipo de resultado: Format, Width, Height, BitDepth, FrameCount |
ImageFormat | Enum: Unknown, Png, Jpeg, Gif, Bmp, WebP, Ico, Tiff, Psd, Emf, Wmf, Dicom |