Funktionen und Funktionalitäten

Funktionen und Merkmale

Diese Seite deckt jeden Funktionsbereich von Aspose.Imaging FOSS für die Format-Erkennung und Header-Abfrage API von .NET ab, mit funktionierenden C#-Beispielen. Die Bibliothek dekodiert niemals Pixeldaten – jede Methode liest nur den Dateikopf.

Format-Erkennung

ImageProbe ist der statische Einstiegspunkt. Drei Überladungen decken einen Dateipfad, einen Stream und ein rohes Byte-Array ab:

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

Verwenden Sie DetectFormat, wenn Sie nur nach dem Format verzweigen müssen; verwenden Sie Probe/ProbeFile, wenn Sie zusätzlich Abmessungen, Bit-Tiefe oder Frame-Anzahl benötigen.

Lesen von Header-Metadaten

ProbeFile/Probe geben ein ImageInfo mit nullable Width, Height, BitDepth und FrameCount zurück – jedes wird nur befüllt, wenn der Header des erkannten Formats diesen Wert tatsächlich enthält:

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

Format (ein ImageFormat Enum-Wert) wird immer gesetzt, sobald der Header erkannt wird — es ist das einzige Feld, das garantiert befüllt ist.

Hinweise pro Format

Einige Formate haben Header-Eigenheiten, die ImageInfo normalisiert oder direkt zugänglich macht:

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

Unterstützte Formate

Alle 11 Formate werden auf dieselbe Weise erkannt — ImageProbe identifiziert das Format und liest die Header-Metadaten; es dekodiert oder re-kodiert niemals Pixeldaten für irgendeines davon. Die Befüllung der Felder variiert jedoch tatsächlich je nach Format — jedes Format setzt Format, aber nur einige enthalten Farbtiefe oder Bildanzahl im Header:

Ein nicht erkannter Header wird zu ImageFormat.Unknown aufgelöst, anstatt eine Ausnahme zu werfen. Einige bemerkenswerte Details zur Feldbefüllung: PNGs FrameCount ist immer 1 (eine Konstante, nicht die echte Erkennung von animierten PNG-Frames); ICOs FrameCount ist eine echte Zählung der im Verzeichnis eingebetteten Icon-Größen, und ein 0 Dimensionsbyte in einem ICO-Verzeichniseintrag bedeutet 256px gemäß der Formatspezifikation; TIFFs FrameCount spiegelt einen begrenzten Durchlauf der IFD-Kette der Datei wider (jede IFD ist eine Seite); nicht-platzierbares WMF wird weiterhin korrekt als ImageFormat.Wmf identifiziert, gibt jedoch nur Format zurück — Dimensionen werden nur für platzierbares WMF befüllt, über eine fest codierte 96DPI-Umrechnung aus den Einheiten-pro-Zoll-Grenzwerten des Headers; EMF hat überhaupt kein explizites Breiten-/Höhenfeld, sodass seine Dimensionen stattdessen aus dem rclBounds gerätebezogenen Rechteck abgeleitet werden.

Robust durch Design

ImageProbe wirft bei fehlerhaften oder abgeschnittenen Eingaben niemals eine Ausnahme. Anstatt eine Ausnahme zu erzeugen, gibt es ein partielles ImageInfo zurück — Format wird gesetzt, sobald das Format-Marker des Headers erkannt wurde, selbst wenn der Rest der Datei zu kurz oder beschädigt ist:

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

Damit ist es sicher, gegen nicht vertrauenswürdige, teilweise oder in der Übertragung befindliche Downloads zu laufen, ohne für jeden Aufruf ein try/catch zu benötigen.

Tipps und bewährte Verfahren

• Verwenden Sie DetectFormat anstelle von Probe, wenn Sie nur das Format benötigen, nicht die Abmessungen.
• Überprüfen Sie Width/Height/BitDepth/FrameCount auf null, bevor Sie sie verwenden— sie sind nicht für jedes Format ausgefüllt.
• Bevorzugen Sie Probe(stream) gegenüber dem Einlesen einer gesamten Datei in ein Byte-Array, wenn Sie mit großen Dateien arbeiten.
• ImageProbe ist vollständig statisch— keine Instanz, kein IDisposable, kein Konfigurationsobjekt.

Häufige Probleme

FAQ

Dekodiert ImageProbe Pixeldaten?

Nein. Jede Methode liest nur den Dateikopf—Abmessungen, Farbtiefe und Bildanzahl—niemals den Pixelinhalt. Dekodieren und Rendern liegen außerhalb des Umfangs dieser Bibliothek.

Was passiert, wenn ich eine beschädigte oder abgeschnittene Datei prüfe?

ImageProbe wirft niemals bei fehlerhaften oder abgeschnittenen Eingaben. Es gibt ein ImageInfo zurück mit allen Feldern, die aus den verfügbaren Header-Bytes ermittelt werden konnten—Format wird gesetzt, sobald das Formatkennzeichen selbst erkannt wurde.

Kann ich einen Stream prüfen, der nicht seekable ist?

Ja. Probe(stream) akzeptiert sowohl seekable als auch non-seekable Streams.

API Reference Zusammenfassung

Siehe auch

• Aspose.Imaging — Enterprise Documentation