Recursos e Funcionalidades

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 parse

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

FormatoBehavior
GIFFrameCount reflete o número de quadros quando o arquivo contém múltiplos quadros; omitido se a contagem não puder ser determinada
BMPUma altura negativa no cabeçalho (ordem de linhas de cima para baixo) é normalizada — Height devolve a magnitude positiva
DICOMA 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:

FormatoLargura / AlturaProfundidade de bitsContagem 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 null

Isso 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 DetectFormat em vez de Probe quando você só precisa do formato, não das dimensões
  • Verifique Width/Height/BitDepth/FrameCount para null antes 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, sem IDisposable, sem objeto de configuração

Problemas Comuns

ProblemaCausaCorrigir
Format é ImageFormat.UnknownO cabeçalho não corresponde a nenhum dos 11 formatos reconhecidosConfirme que o arquivo é um dos seguintes: PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF ou DICOM
Width/Height são nullO cabeçalho do formato não contém esse campo, ou o cabeçalho foi truncado antes desse campoVerifique Format primeiro; nem todo campo é preenchido para todos os formatos
A altura BMP parece inesperadamente positivaO arquivo de origem usou uma altura negativa (de cima para baixo) em seu cabeçalhoEsperado — 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étodoDescriçã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[]
ImageInfoTipo de resultado: Format, Width, Height, BitDepth, FrameCount
ImageFormatEnum: Unknown, Png, Jpeg, Gif, Bmp, WebP, Ico, Tiff, Psd, Emf, Wmf, Dicom

Ver também

 Português