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 parseUtilisez 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:
| Format | Behavior |
|---|---|
| GIF | FrameCount reflète le nombre d’images lorsque le fichier contient plusieurs images ; omis si le nombre ne peut pas être déterminé |
| BMP | Une hauteur négative dans l’en-tête (ordre des lignes de haut en bas) est normalisée — Height renvoie la magnitude positive |
| DICOM | L’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:
| Format | Largeur / Hauteur | Profondeur de bits | Nombre 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 nullCela 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 deProbelorsque vous n’avez besoin que du format, pas des dimensions - Vérifiez
Width/Height/BitDepth/FrameCountpournullavant 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 ImageProbeest entièrement statique — aucune instance, aucunIDisposable, aucun objet de configuration
Problèmes courants
| Problème | Cause | Correction |
|---|---|---|
Format est ImageFormat.Unknown | L’en-tête ne correspond à aucun des 11 formats reconnus | Vérifiez que le fichier est l’un des suivants : PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF ou DICOM |
Width/Height sont null | L’en-tête du format ne contient pas ce champ, ou l’en-tête a été tronqué avant ce champ | Vérifiez d’abord Format ; tous les champs ne sont pas renseignés pour chaque format |
| La hauteur BMP semble inattendue positive | Le fichier source a utilisé une hauteur négative (de haut en bas) dans son en-tête | Attendu — 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éthode | Description |
|---|---|
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[] |
ImageInfo | Type de résultat : Format, Width, Height, BitDepth, FrameCount |
ImageFormat | Énumération : Unknown, Png, Jpeg, Gif, Bmp, WebP, Ico, Tiff, Psd, Emf, Wmf, Dicom |