Caratteristiche e funzionalità

Funzionalità e Caratteristiche

Questa pagina copre ogni area funzionale di Aspose.Imaging FOSS per il rilevamento del formato e l’analisi dell’header API di .NET, con esempi funzionanti di C#. La libreria non decodifica mai i dati dei pixel — ogni metodo legge solo l’header del file.

Rilevamento del formato

ImageProbe è il punto di ingresso statico. Tre overload coprono un percorso file, uno stream e un array di byte grezzo:

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

Usa DetectFormat quando hai solo bisogno di distinguere il formato; usa Probe/ProbeFile quando ti servono anche dimensioni, profondità di bit o conteggio dei fotogrammi.

Lettura dei metadati dell’header

ProbeFile/Probe restituiscono un ImageInfo con nullable Width, Height, BitDepth e FrameCount — ciascuno popolato solo quando l’header del formato rilevato contiene effettivamente quel valore:

var info = ImageProbe.ProbeFile("scan.dcm");
if (info.Width.HasValue && info.Height.HasValue)
{
    Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}");
}

Format (un valore enum ImageFormat) è sempre impostato una volta che l’intestazione è riconosciuta — è l’unico campo garantito di essere popolato.

Note per formato

Alcuni formati hanno stranezze nell’intestazione che ImageInfo normalizza o espone direttamente:

// 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");

Formati supportati

Tutti gli 11 formati vengono rilevati nello stesso modo — ImageProbe identifica il formato e legge i metadati dell’intestazione; non decodifica né ricodifica mai i dati pixel per alcuno di essi. La popolazione dei campi varia realmente a seconda del formato, però — ogni formato imposta Format, ma solo alcuni includono la profondità di colore o il conteggio dei fotogrammi nella loro intestazione:

Un’intestazione non riconosciuta si risolve in ImageFormat.Unknown invece di generare un’eccezione. Alcuni dettagli notevoli sulla popolazione dei campi: il FrameCount di PNG è sempre 1 (una costante, non una reale rilevazione di fotogrammi PNG animati); il FrameCount di ICO è un vero conteggio delle dimensioni delle icone incorporate nella directory, e un byte di dimensione 0 in una voce della directory ICO significa 256px secondo le specifiche del formato; il FrameCount di TIFF riflette un percorso limitato della catena IFD del file (ogni IFD è una pagina); il WMF non posizionabile viene comunque identificato correttamente come ImageFormat.Wmf ma restituisce solo Format — le dimensioni vengono popolate solo per WMF posizionabile, tramite una conversione codificata a 96DPI dai limiti di unità-per-pollice dell’intestazione; EMF non ha alcun campo esplicito di larghezza/altezza, quindi le sue dimensioni sono derivate dal rettangolo dello spazio dispositivo rclBounds invece.

Resiliente per progettazione

ImageProbe non genera mai eccezioni su input malformati o troncati. Invece di sollevare un’eccezione, restituisce un ImageInfo parziale — Format è impostato ogni volta che il marcatore di formato dell’intestazione è stato riconosciuto, anche quando il resto del file è tagliato o corrotto:

byte[] truncated = fullFileBytes[..^3];
var info = ImageProbe.Probe(truncated);
// info.Format is still populated; other fields may be null

Ciò lo rende sicuro da eseguire su download non attendibili, parziali o in corso senza un try/catch intorno a ogni chiamata.

Suggerimenti e migliori pratiche

• Usa DetectFormat al posto di Probe quando ti serve solo il formato, non le dimensioni
• Controlla Width/Height/BitDepth/FrameCount per null prima di usarli — non sono popolati per ogni formato
• Preferisci Probe(stream) rispetto a leggere un intero file in un array di byte prima quando lavori con file di grandi dimensioni
• ImageProbe è interamente statico — nessuna istanza, nessun IDisposable, nessun oggetto di configurazione

Problemi comuni

FAQ

Il ImageProbe decodifica i dati dei pixel?

No. Ogni metodo legge solo l’intestazione del file — dimensioni, profondità di colore e conteggio dei fotogrammi — mai il contenuto dei pixel. Decodifica e rendering sono al di fuori dello scopo di questa libreria.

Cosa succede se interrogo un file corrotto o troncato?

ImageProbe non genera mai eccezioni per input malformato o troncato. Restituisce un ImageInfo con i campi che è riuscito a determinare dai byte di intestazione disponibili — Format è impostato ogni volta che il marcatore del formato è stato riconosciuto.

Posso interrogare un stream che non è ricercabile?

Sì. Probe(stream) accetta sia stream ricercabili che non ricercabili.

API Reference Riepilogo

Vedi anche

• Aspose.Imaging — Enterprise Documentation