Функции и возможности

Функции и возможности

Эта страница охватывает все области функций Aspose.Imaging FOSS для .NET обнаружения форматов и проверки заголовков API, с работающими примерами C#. Библиотека никогда не декодирует пиксельные данные — каждый метод читает только заголовок файла.

Обнаружение формата

ImageProbe является статической точкой входа. Три перегрузки охватывают путь к файлу, поток и массив необработанных байтов:

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

Используйте DetectFormat, когда вам нужно лишь определить формат; используйте Probe/ProbeFile, когда также требуются размеры, глубина цвета или количество кадров.

Чтение метаданных заголовка

ProbeFile/Probe возвращают ImageInfo с nullable Width, Height, BitDepth и FrameCount — каждый из которых заполняется только тогда, когда заголовок обнаруженного формата действительно содержит это значение:

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

Format (значение перечисления ImageFormat) всегда устанавливается, как только заголовок распознан — это единственное поле, гарантированно заполненное.

Примечания по форматам

У некоторых форматов есть особенности заголовка, которые ImageInfo нормализует или раскрывает напрямую:

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

Поддерживаемые форматы

Все 11 форматов обнаруживаются одинаково — ImageProbe определяет формат и считывает метаданные заголовка; он никогда не декодирует и не перекодирует пиксельные данные для любого из них. Однако заполнение полей действительно различается в зависимости от формата — каждый формат задает Format, но только некоторые включают глубину цвета или количество кадров в своем заголовке:

Неопознанный заголовок приводит к ImageFormat.Unknown, а не к исключению. Несколько примечательных деталей заполнения полей: FrameCount PNG всегда равно 1 (константа, а не реальное обнаружение анимированных PNG-кадров); FrameCount ICO представляет собой реальное количество встроенных размеров иконок в каталоге, а байт измерения 0 в записи каталога ICO означает 256px согласно спецификации формата; FrameCount TIFF отражает ограниченный обход цепочки IFD файла (каждый IFD — это одна страница); не-placeable WMF всё ещё правильно идентифицируется как ImageFormat.Wmf, но возвращает только Format — размеры заполняются только для placeable WMF через жёстко заданное преобразование 96DPI из границ единиц-на-дюйм заголовка; EMF вообще не имеет явного поля ширины/высоты, поэтому его размеры выводятся из прямоугольника rclBounds в пространстве устройства.

Устойчивый по дизайну

ImageProbe никогда не генерирует исключение при повреждённом или усечённом вводе. Вместо выброса исключения он возвращает частичный ImageInfo — Format устанавливается каждый раз, когда маркер формата заголовка был распознан, даже если остальная часть файла обрезана или повреждена:

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

Это делает безопасным запуск против недоверенных, частичных или загружающихся в реальном времени загрузок без try/catch вокруг каждого вызова.

Советы и лучшие практики

• Используйте DetectFormat вместо Probe, когда нужен только формат, а не размеры.
• Проверьте Width/Height/BitDepth/FrameCount на наличие null перед их использованием — они не заполняются для каждого формата.
• Отдавайте предпочтение Probe(stream) вместо чтения всего файла в массив байтов сначала при работе с большими файлами.
• ImageProbe полностью статичен — нет экземпляра, нет IDisposable, нет объекта конфигурации.

Распространённые проблемы

FAQ

Декодирует ли ImageProbe данные пикселей?

Нет. Каждый метод читает только заголовок файла — размеры, глубину цвета и количество кадров — но никогда не содержимое пикселей. Декодирование и рендеринг находятся за пределами области этой библиотеки.

Что происходит, если я проверяю повреждённый или усечённый файл?

ImageProbe никогда не бросает исключение при некорректном или усечённом вводе. Он возвращает ImageInfo со всеми полями, которые удалось определить из доступных байтов заголовка — Format устанавливается, когда маркер формата был распознан.

Могу ли я проверить поток, который не поддерживает поиск?

Да. Probe(stream) принимает как потоки с поддержкой поиска, так и без неё.

API Reference Сводка

См. также:

• Aspose.Imaging — Enterprise Documentation