Features and Functionalities

Features and Functionalities

This page covers every feature area of Aspose.Imaging FOSS for .NET’s format-detection and header-probing API, with working C# examples. The library never decodes pixel data — every method reads only the file header.

Format Detection

ImageProbe is the static entry point. Three overloads cover a file path, a stream, and a raw byte array:

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

Use DetectFormat when you only need to branch on the format; use Probe/ProbeFile when you also need dimensions, bit depth, or frame count.

Reading Header Metadata

ProbeFile/Probe return an ImageInfo with nullable Width, Height, BitDepth, and FrameCount — each populated only when the detected format’s header actually carries that value:

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

Format (an ImageFormat enum value) is always set once the header is recognized — it’s the one field guaranteed to be populated.

Per-Format Notes

A few formats have header quirks ImageInfo normalizes or exposes directly:

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

Supported Formats

All 11 formats are detected the same way — ImageProbe identifies the format and reads header metadata; it never decodes or re-encodes pixel data for any of them. Field population genuinely varies by format, though — every format sets Format, but only some carry bit depth or frame count in their header:

An unrecognized header resolves to ImageFormat.Unknown rather than throwing. A few notable field-population details: PNG’s FrameCount is always 1 (a constant, not real animated-PNG frame detection); ICO’s FrameCount is a genuine count of the embedded icon sizes in the directory, and a 0 dimension byte in an ICO directory entry means 256px per the format spec; TIFF’s FrameCount reflects a bounded walk of the file’s IFD chain (each IFD is one page); non-placeable WMF is still correctly identified as ImageFormat.Wmf but returns only Format — dimensions populate for placeable WMF only, via a hardcoded 96 DPI conversion from the header’s units-per-inch bounds; EMF has no explicit width/height field at all, so its dimensions are derived from the rclBounds device-space rectangle instead.

Resilient by Design

ImageProbe never throws on malformed or truncated input. Instead of raising an exception, it returns a partial ImageInfo — Format is set whenever the header’s format marker was recognized, even when the rest of the file is cut short or corrupt:

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

This makes it safe to run against untrusted, partial, or in-flight downloads without a try/catch around every call.

Tips and Best Practices

• Use DetectFormat instead of Probe when you only need the format, not dimensions
• Check Width/Height/BitDepth/FrameCount for null before using them — they are not populated for every format
• Prefer Probe(stream) over reading a whole file into a byte array first when working with large files
• ImageProbe is entirely static — no instance, no IDisposable, no configuration object

Common Issues

FAQ

Does ImageProbe decode pixel data?

No. Every method reads only the file header — dimensions, bit depth, and frame count — never pixel content. Decoding and rendering are outside this library’s scope.

What happens if I probe a corrupted or truncated file?

ImageProbe never throws for malformed or truncated input. It returns an ImageInfo with whatever fields it could determine from the available header bytes — Format is set whenever the format marker itself was recognized.

Can I probe a stream that isn’t seekable?

Yes. Probe(stream) accepts both seekable and non-seekable streams.

API Reference Summary

See Also

• Aspose.Imaging — Enterprise Documentation