Funkcje i funkcjonalności

Funkcje i możliwości

Ta strona obejmuje każdy obszar funkcji Aspose.Imaging FOSS dla wykrywania formatu .NET i sondowania nagłówka API, wraz z działającymi przykładami C#. Biblioteka nigdy nie dekoduje danych pikseli — każda metoda odczytuje wyłącznie nagłówek pliku.

Wykrywanie formatu

ImageProbe jest statycznym punktem wejścia. Trzy przeciążenia obsługują ścieżkę pliku, strumień i surową tablicę bajtów:

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

Użyj DetectFormat, gdy potrzebujesz jedynie rozgałęzić się w zależności od formatu; użyj Probe/ProbeFile, gdy potrzebujesz także wymiarów, głębi bitowej lub liczby klatek.

Odczytywanie metadanych nagłówka

ProbeFile/Probe zwracają ImageInfo z nullable Width, Height, BitDepth i FrameCount — każdy wypełniany tylko wtedy, gdy nagłówek wykrytego formatu rzeczywiście zawiera tę wartość:

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

Format (wartość wyliczenia ImageFormat) jest zawsze ustawiana po rozpoznaniu nagłówka — jest to jedyne pole gwarantująco wypełnione.

Uwagi dotyczące poszczególnych formatów

Niektóre formaty mają specyficzne cechy nagłówka, które ImageInfo normalizuje lub udostępnia bezpośrednio:

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

Obsługiwane formaty

Wszystkie 11 formatów jest wykrywanych w ten sam sposób — ImageProbe identyfikuje format i odczytuje metadane nagłówka; nigdy nie dekoduje ani nie przekodowuje danych pikseli dla żadnego z nich. Wypełnianie pól rzeczywiście różni się w zależności od formatu — każdy format ustawia Format, ale tylko niektóre zawierają w nagłówku głębię bitową lub liczbę klatek:

Nierozpoznany nagłówek rozwiązuje się do ImageFormat.Unknown zamiast zgłaszać wyjątek. Kilka godnych uwagi szczegółów dotyczących wypełniania pól: FrameCount w PNG jest zawsze 1 (stała, a nie prawdziwe wykrywanie klatek w animowanym PNG); FrameCount w ICO jest rzeczywistą liczbą osadzonych rozmiarów ikon w katalogu, a bajt wymiaru 0 w wpisie katalogu ICO oznacza 256px zgodnie ze specyfikacją formatu; FrameCount w TIFF odzwierciedla ograniczony przebieg łańcucha IFD pliku (każdy IFD to jedna strona); non-placeable WMF jest nadal prawidłowo identyfikowany jako ImageFormat.Wmf, ale zwraca tylko Format — wymiary są wypełniane tylko dla placeable WMF, poprzez sztywno zakodowaną konwersję 96DPI z granic jednostek na cal w nagłówku; EMF nie posiada w ogóle explicite pola szerokości/wysokości, więc jego wymiary są wyprowadzane z prostokąta rclBounds w przestrzeni urządzenia.

Odporne z konstrukcji

ImageProbe nigdy nie zgłasza wyjątku przy nieprawidłowym lub uciętym wejściu. Zamiast podnosić wyjątek, zwraca częściowy ImageInfo — Format jest ustawiane zawsze, gdy rozpoznano znacznik formatu w nagłówku, nawet jeśli reszta pliku jest przycięta lub uszkodzona:

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

To sprawia, że jest to bezpieczne do uruchamiania na niezaufanych, częściowych lub w trakcie pobierania plikach, bez konieczności używania try/catch przy każdym wywołaniu.

Wskazówki i najlepsze praktyki

• Użyj DetectFormat zamiast Probe, gdy potrzebny jest tylko format, a nie wymiary.
• Sprawdź Width/Height/BitDepth/FrameCount pod kątem null przed ich użyciem — nie są wypełniane dla każdego formatu.
• Preferuj Probe(stream) zamiast najpierw wczytywać cały plik do tablicy bajtów przy pracy z dużymi plikami.
• ImageProbe jest całkowicie statyczny — brak instancji, brak IDisposable, brak obiektu konfiguracyjnego.

Typowe problemy

FAQ

Czy ImageProbe dekoduje dane pikseli?

Nie. Każda metoda odczytuje tylko nagłówek pliku — wymiary, głębię bitową i liczbę klatek — nigdy nie zawartość pikseli. Dekodowanie i renderowanie wykraczają poza zakres tej biblioteki.

Co się stanie, jeśli spróbuję zbadać uszkodzony lub ucięty plik?

ImageProbe nigdy nie zgłasza wyjątków przy niepoprawnym lub uciętym wejściu. Zwraca ImageInfo z wszystkimi polami, które udało się określić na podstawie dostępnych bajtów nagłówka — Format jest ustawiane zawsze, gdy rozpoznano znacznik formatu.

Czy mogę zbadać strumień, który nie jest przeszukiwalny?

Tak. Probe(stream) akceptuje zarówno strumienie przeszukiwalne, jak i nieprzeszukiwalne.

API Reference Podsumowanie

Zobacz także

• Aspose.Imaging — Enterprise Documentation