Fonctionnalités et capacités

Fonctionnalités et capacités

Fonctionnalités et fonctions

Cette page couvre chaque zone de fonctionnalité de Aspose.Imaging FOSS pour la détection de format et le sondage d’en-tête de .NET API, avec des exemples C# fonctionnels. La bibliothèque ne décode jamais les données de pixels — chaque méthode ne lit que l’en-tête du fichier.


Détection de format

ImageProbe est le point d’entrée statique. Trois surcharges couvrent un chemin de fichier, un flux et un tableau d’octets brut:

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

Utilisez DetectFormat lorsque vous avez seulement besoin de vous ramifier selon le format; utilisez Probe/ProbeFile lorsque vous avez également besoin des dimensions, de la profondeur de bits ou du nombre d’images.


Lecture des métadonnées d’en-tête

ProbeFile/Probe renvoient un ImageInfo avec des Width, Height, BitDepth et FrameCount nullables — chacun étant rempli uniquement lorsque l’en-tête du format détecté contient réellement cette valeur:

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

Format (une valeur d’énumération ImageFormat) est toujours définie une fois l’en-tête reconnu — c’est le seul champ garanti d’être rempli.


Notes par format

Quelques formats ont des particularités d’en-tête que ImageInfo normalise ou expose directement:

FormatBehavior
GIFFrameCount reflète le nombre d’images lorsque le fichier contient plusieurs images ; omis si le nombre ne peut pas être déterminé
BMPUne hauteur négative dans l’en-tête (ordre des lignes de haut en bas) est normalisée — Height renvoie la magnitude positive
DICOML’analyse de l’en-tête gère les syntaxes de transfert Implicit VR Little Endian et Explicit VR Little/Big Endian, en extrayant les lignes, les colonnes et les bits alloués
// 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");

Formats pris en charge

Les 11 formats sont détectés de la même manière — ImageProbe identifie le format et lit les métadonnées de l’en-tête; il ne décode ni ne ré-encode jamais les données de pixels pour aucun d’eux. La population des champs varie réellement selon le format, cependant — chaque format définit Format, mais seuls certains contiennent la profondeur de couleur ou le nombre d’images dans leur en-tête:

FormatLargeur / HauteurProfondeur de bitsNombre d’images
PNG✓✓✓
JPEG✓✓—
GIF✓—✓
BMP✓✓—
WebP✓——
ICO✓✓✓
TIFF✓✓✓
PSD✓✓—
EMF✓ (à partir des limites)——
WMF (placable)✓ (suppose 96 DPI)——
DICOM✓ (Lignes/Colonnes)✓ (BitsAllocated)—

Un en-tête non reconnu se résout en ImageFormat.Unknown plutôt que de lever une exception. Quelques détails notables sur la population des champs: le FrameCount du PNG est toujours 1 (une constante, pas une vraie détection de trame PNG animée); le FrameCount de l’ICO est un véritable décompte des tailles d’icônes incorporées dans le répertoire, et un octet de dimension 0 dans une entrée de répertoire ICO signifie 256 px selon la spécification du format; le FrameCount du TIFF reflète une marche bornée de la chaîne IFD du fichier (chaque IFD représente une page); le WMF non placable est toujours correctement identifié comme ImageFormat.Wmf mais ne renvoie que Format — les dimensions sont renseignées uniquement pour le WMF placable, via une conversion codée en dur de 96 DPI à partir des limites d’unités-par-pouce de l’en-tête; l’EMF n’a aucun champ explicite de largeur/hauteur, donc ses dimensions sont dérivées du rectangle en espace dispositif rclBounds à la place.


Résilient par conception

ImageProbe ne lève jamais d’exception sur une entrée mal formée ou tronquée. Au lieu de lever une exception, il renvoie un ImageInfo partiel — Format est défini chaque fois que le marqueur de format de l’en-tête a été reconnu, même si le reste du fichier est coupé ou corrompu:

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

Cela le rend sûr à exécuter contre des téléchargements non fiables, partiels ou en cours, sans avoir besoin d’un try/catch autour de chaque appel.


Conseils et meilleures pratiques

  • Utilisez DetectFormat à la place de Probe lorsque vous n’avez besoin que du format, pas des dimensions
  • Vérifiez Width/Height/BitDepth/FrameCount pour null avant de les utiliser — ils ne sont pas remplis pour chaque format
  • Privilégiez Probe(stream) plutôt que de lire un fichier entier dans un tableau d’octets d’abord lorsque vous travaillez avec de gros fichiers
  • ImageProbe est entièrement statique — aucune instance, aucun IDisposable, aucun objet de configuration

Problèmes courants

ProblèmeCauseCorrection
Format est ImageFormat.UnknownL’en-tête ne correspond à aucun des 11 formats reconnusVérifiez que le fichier est l’un des suivants : PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF ou DICOM
Width/Height sont nullL’en-tête du format ne contient pas ce champ, ou l’en-tête a été tronqué avant ce champVérifiez d’abord Format ; tous les champs ne sont pas renseignés pour chaque format
La hauteur BMP semble inattendue positiveLe fichier source a utilisé une hauteur négative (de haut en bas) dans son en-têteAttendu — ImageInfo.Height se normalise toujours à la magnitude positive

FAQ

Est-ce que ImageProbe décode les données de pixels?

Non. Chaque méthode ne lit que l’en-tête du fichier — dimensions, profondeur de couleur et nombre d’images — jamais le contenu des pixels. Le décodage et le rendu sont hors du champ d’application de cette bibliothèque.

Que se passe-t-il si j’interroge un fichier corrompu ou tronqué?

ImageProbe ne lève jamais d’exception pour une entrée malformée ou tronquée. Il renvoie un ImageInfo avec les champs qu’il a pu déterminer à partir des octets d’en-tête disponibles — Format est défini chaque fois que le marqueur de format a été reconnu.

Puis-je interroger un flux qui n’est pas positionnable?

Oui. Probe(stream) accepte les flux positionnables et non positionnables.


API Reference Résumé

Classe / MéthodeDescription
ImageProbe.ProbeFile(path)Interrogez un fichier par chemin, en renvoyant un ImageInfo
ImageProbe.Probe(stream)Interrogez un Stream (déplaçable ou non)
ImageProbe.Probe(data)Interrogez un byte[] brut
ImageProbe.DetectFormat(stream)Retourner uniquement le ImageFormat pour un flux
ImageProbe.DetectFormat(data)Retourner uniquement le ImageFormat pour un byte[]
ImageInfoType de résultat : Format, Width, Height, BitDepth, FrameCount
ImageFormatÉnumération : Unknown, Png, Jpeg, Gif, Bmp, WebP, Ico, Tiff, Psd, Emf, Wmf, Dicom

Voir aussi

 Français