Tính năng và chức năng

Tính năng và chức năng

Tổng quan

Trang này bao phủ mọi khu vực tính năng của Aspose.Imaging FOSS cho việc phát hiện định dạng và dò tiêu đề API của .NET, với các ví dụ C# hoạt động. Thư viện không bao giờ giải mã dữ liệu pixel — mọi phương pháp chỉ đọc tiêu đề tệp.


Phát hiện Định dạng

ImageProbe là điểm vào tĩnh. Ba overload bao phủ một đường dẫn tệp, một luồng, và một mảng byte thô:

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

Sử dụng DetectFormat khi bạn chỉ cần phân nhánh dựa trên định dạng; sử dụng Probe/ProbeFile khi bạn cũng cần kích thước, độ sâu bit, hoặc số khung hình.


Đọc Siêu dữ liệu Tiêu đề

ProbeFile/Probe trả về một ImageInfo với các trường nullable Width, Height, BitDepth, và FrameCount — mỗi trường chỉ được điền khi tiêu đề của định dạng được phát hiện thực sự chứa giá trị đó:

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

Format (một giá trị enum ImageFormat) luôn được đặt khi tiêu đề được nhận ra — đó là trường duy nhất được đảm bảo sẽ được điền.


Ghi chú theo định dạng

Một vài định dạng có những quirks trong tiêu đề mà ImageInfo chuẩn hoá hoặc hiển thị trực tiếp:

Định dạngBehavior
GIFFrameCount phản ánh số khung khi tệp chứa nhiều khung; bị bỏ qua nếu không thể xác định số lượng
BMPChiều cao âm trong tiêu đề (thứ tự hàng từ trên xuống) được chuẩn hoá — Height trả về giá trị dương
DICOMViệc phân tích tiêu đề xử lý các cú pháp truyền Implicit VR Little Endian và Explicit VR Little/Big Endian, trích xuất số hàng, số cột và số bit đã cấp phát
// 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");

Định dạng được hỗ trợ

Cả 11 định dạng đều được phát hiện theo cùng một cách — ImageProbe xác định định dạng và đọc siêu dữ liệu tiêu đề; nó không bao giờ giải mã hay mã hoá lại dữ liệu pixel cho bất kỳ định dạng nào. Tuy nhiên, việc điền các trường thực sự khác nhau tùy theo định dạng — mọi định dạng đều đặt Format, nhưng chỉ một số có độ sâu màu hoặc số khung trong tiêu đề của chúng:

Định dạngChiều rộng / Chiều caoĐộ sâu bitSố khung
PNG✓✓✓
JPEG✓✓—
GIF✓—✓
BMP✓✓—
WebP✓——
ICO✓✓✓
TIFF✓✓✓
PSD✓✓—
EMF✓ (từ giới hạn)——
WMF (có thể đặt)✓ (giả sử 96 DPI)——
DICOM✓ (Hàng/Cột)✓ (BitsAllocated)—

Một tiêu đề không được nhận dạng sẽ giải quyết thành ImageFormat.Unknown thay vì ném lỗi. Một vài chi tiết đáng chú ý về việc điền trường: FrameCount của PNG luôn luôn là 1 (một hằng số, không phải phát hiện khung PNG động thực tế); FrameCount của ICO là số đếm thực tế của các kích thước biểu tượng nhúng trong thư mục, và một byte kích thước 0 trong mục thư mục ICO có nghĩa là 256px theo đặc tả định dạng; FrameCount của TIFF phản ánh một quá trình duyệt có giới hạn qua chuỗi IFD của tệp (mỗi IFD là một trang); WMF không thể đặt vị trí vẫn được xác định đúng là ImageFormat.Wmf nhưng chỉ trả về Format — kích thước chỉ được điền cho WMF có thể đặt vị trí, thông qua chuyển đổi cố định 96 DPI từ giới hạn đơn vị-per-inch của tiêu đề; EMF không có trường chiều rộng/chiều cao rõ ràng nào, vì vậy kích thước của nó được suy ra từ hình chữ nhật không gian thiết bị rclBounds.


Kiên cường theo thiết kế

ImageProbe không bao giờ ném lỗi khi đầu vào bị sai dạng hoặc bị cắt ngắn. Thay vì phát sinh ngoại lệ, nó trả về một ImageInfo một phần — Format được đặt mỗi khi dấu hiệu định dạng của tiêu đề được nhận ra, ngay cả khi phần còn lại của tệp bị cắt ngắn hoặc hỏng:

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

Điều này khiến nó an toàn khi chạy đối với các bản tải xuống không đáng tin cậy, không đầy đủ hoặc đang trong quá trình tải mà không cần try/catch cho mỗi lời gọi.


Mẹo và Thực hành tốt nhất

  • Sử dụng DetectFormat thay vì Probe khi bạn chỉ cần định dạng, không cần kích thước
  • Kiểm tra Width/Height/BitDepth/FrameCount cho null trước khi sử dụng chúng — chúng không được điền cho mọi định dạng
  • Ưu tiên Probe(stream) hơn việc đọc toàn bộ tệp vào mảng byte trước khi làm việc với các tệp lớn
  • ImageProbe hoàn toàn tĩnh — không có thể hiện, không có IDisposable, không có đối tượng cấu hình

Các vấn đề thường gặp

Vấn đềNguyên nhânSửa
Format là ImageFormat.UnknownHeader không khớp với bất kỳ 11 định dạng được công nhận nàoXác nhận tệp là một trong các định dạng PNG, JPEG, GIF, BMP, WebP, ICO, TIFF, PSD, EMF, WMF hoặc DICOM
Width/Height là nullHeader của định dạng không chứa trường đó, hoặc header đã bị cắt ngắn trước trường đóKiểm tra Format trước; không phải mọi trường đều được điền cho mọi định dạng
Chiều cao BMP trông bất ngờ là dươngTệp nguồn đã sử dụng chiều cao âm (top-down) trong headerKỳ vọng — ImageInfo.Height luôn chuẩn hoá thành độ lớn dương

FAQ

Liệu ImageProbe có giải mã dữ liệu pixel không?

Không. Mỗi phương thức chỉ đọc phần đầu của tệp — kích thước, độ sâu màu và số khung — không bao giờ đọc nội dung pixel. Việc giải mã và hiển thị nằm ngoài phạm vi của thư viện này.

Điều gì sẽ xảy ra nếu tôi kiểm tra một tệp bị hỏng hoặc bị cắt ngắn?

ImageProbe không bao giờ ném ngoại lệ cho đầu vào bị sai định dạng hoặc bị cắt ngắn. Nó trả về một ImageInfo với bất kỳ trường nào mà nó có thể xác định được từ các byte phần đầu có sẵn — Format được đặt mỗi khi dấu hiệu định dạng được nhận dạng.

Tôi có thể kiểm tra một luồng không hỗ trợ seek không?

Có. Probe(stream) chấp nhận cả luồng có thể seek và không thể seek.


API Reference Tóm tắt

Lớp / Phương thứcMô tả
ImageProbe.ProbeFile(path)Kiểm tra một tệp theo đường dẫn, trả về một ImageInfo
ImageProbe.Probe(stream)Kiểm tra một Stream (có thể seek hoặc không)
ImageProbe.Probe(data)Kiểm tra một byte[] thô
ImageProbe.DetectFormat(stream)Chỉ trả về ImageFormat cho một luồng
ImageProbe.DetectFormat(data)Chỉ trả về ImageFormat cho một byte[]
ImageInfoKiểu kết quả: Format, Width, Height, BitDepth, FrameCount
ImageFormatLiệt kê: Unknown, Png, Jpeg, Gif, Bmp, WebP, Ico, Tiff, Psd, Emf, Wmf, Dicom

Xem thêm

 Tiếng Việt