Aspose.Imaging FOSS
Как работать с Aspose.Imaging FOSS Core API в .NET

Как работать с Aspose.Imaging FOSS Core API в .NET

Aspose.Imaging FOSS для публичного уровня .NET состоит из трёх классов: ImageProbe, ImageInfo и ImageFormat. Это руководство проходит процесс установки пакета и использования всех трёх вместе для определения формата и чтения метаданных заголовка из файла, потока и массива байт.

Пошаговое руководство

Шаг 1: Установить пакет 

git clone https://github.com/aspose-imaging-foss/Aspose.Imaging-FOSS-for-.NET.git
cd Aspose.Imaging-FOSS-for-.NET
dotnet build

Пакет ориентирован на net8.0 и netstandard2.0 и не имеет внешних зависимостей во время выполнения.

Шаг 2: Импортировать пространство имён

Добавьте одну директиву using — она раскрывает ImageProbe, ImageInfo и ImageFormat, всю поверхность API, так что больше ничего импортировать не нужно:

using Aspose.Imaging.Foss;

Шаг 3: Исследовать файл по пути

ImageProbe.ProbeFile считывает достаточно заголовка файла, чтобы заполнить результат ImageInfo — он никогда не декодирует пиксельные данные:

var info = ImageProbe.ProbeFile("photo.jpg");
Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}, {info.BitDepth}-bit");

Шаг 4: Исследовать поток или массив байтов

Когда изображение уже находится в памяти или пришло из потока (загрузка, сетевой ответ), используйте перегрузки, принимающие их напрямую, вместо записи во временный файл:

byte[] bytes = File.ReadAllBytes("photo.jpg");
var infoFromBytes = ImageProbe.Probe(bytes);

using var stream = File.OpenRead("photo.jpg");
var infoFromStream = ImageProbe.Probe(stream);

Probe(stream) работает как с позиционными, так и с непозиционными потоками.

Шаг 5: Используйте DetectFormat, когда вам нужен только формат

Если вам нужно лишь определить формат и не требуются размеры, глубина цвета или количество кадров, DetectFormat пропускает остальную часть разбора заголовка:

var format = ImageProbe.DetectFormat(bytes);
if (format == ImageFormat.Dicom)
{
    // route to DICOM-specific handling
}

Шаг 6: Безопасно считывать nullable-поля ImageInfo

Width, Height, BitDepth и FrameCount являются nullable — они заполняются только тогда, когда заголовок обнаруженного формата действительно содержит это значение. Format — единственное поле, которое всегда устанавливается после распознавания заголовка:

var info = ImageProbe.ProbeFile("scan.dcm");
if (info.Width.HasValue && info.Height.HasValue)
{
    Console.WriteLine($"{info.Format}: {info.Width}x{info.Height}");
}
else
{
    Console.WriteLine($"{info.Format}: dimensions not available in this header");
}

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

Формат отображается как ImageFormat.Unknown. Заголовок файла не соответствует ни одному из 11 распознанных форматов (PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF, DICOM). Убедитесь, что файл действительно один из этих форматов — ImageProbe не вызывает исключение при нераспознанном заголовке, а сообщает Unknown вместо этого.

Width/Height are null даже если Format установлен. Не каждый заголовок формата содержит все поля, и усечённый файл может обрезаться до байтов поля. Проверьте Format сначала, а затем рассматривайте остальное как необязательное.

Calling Probe when DetectFormat сделает. Probe and ProbeFile разобрать полный заголовок; DetectFormat читает только столько, чтобы определить формат. Используйте DetectFormat если вы никогда не читаете Width/Height/BitDepth/FrameCount.

Ожидается декодированные пиксельные данные. ImageProbe никогда не декодирует, не рендерит и не преобразует содержимое изображения — он только читает метаданные заголовка. Декодирование и операции на уровне пикселей требуют коммерческого SDK Aspose.Imaging.

Часто задаваемые вопросы

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

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

Является ли ImageProbe потокобезопасным?

Да. ImageProbe статичен и не хранит изменяемое состояние между вызовами, поэтому одновременные вызовы из нескольких потоков безопасны.

Могу ли я создать ImageInfo напрямую, без проверки реального файла?

Да. Конструктор ImageInfo публичный и требует лишь format — это удобно для создания тестовых двойников: new ImageInfo(ImageFormat.Png, width: 64, height: 48).

Нужно ли мне что-то освобождать?

Нет. ImageProbe не содержит собственных IDisposable ресурсов. Если вы передаёте Stream, который вы открыли сами, вы остаетесь ответственным за его освобождение.

См. также:

 Русский