功能和特性

功能和特性

本页涵盖了 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，其中的 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 而不是抛出异常。以下是一些值得注意的字段填充细节：PNG 的 FrameCount 始终为 1（一个常量，而非真实的 animated-PNG 帧检测）；ICO 的 FrameCount 是目录中嵌入图标尺寸的真实计数，并且 ICO 目录项中的 0 尺寸字节表示根据格式规范为 256 像素；TIFF 的 FrameCount 反映了对文件 IFD 链的有界遍历（每个 IFD 相当于一页）；非可放置的 WMF 仍被正确识别为 ImageFormat.Wmf，但仅返回 Format——仅对可放置的 WMF 填充尺寸信息，采用从标头的每英寸单位边界硬编码的 96 DPI 转换；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