bioformatsinfo

Read whole slide image file metadata using Bio-Formats library

Since R2026a

collapse all in page

    Syntax

    info = bioformatsinfo(filename)

    Description

    Add-On Required: This feature requires the Medical Imaging Toolbox Interface for Whole Slide Imaging File Reader add-on.

    info = bioformatsinfo(filename) reads the metadata from the whole slide imaging (WSI) file filename using the Bio-Formats library and returns the metadata structure info.

    example

    Examples

    collapse all

    This example uses:

    Open Live Script

    Run this code to download a whole slide image from the MathWorks® website, and unzip the downloaded folder. The image, stored in the NDPI format, contains an H&E stained microscopy slide provided by the OpenSlide library test data set [1].

    zipFile = matlab.internal.examples.downloadSupportFile("image","data/CMU-1.zip");
filepath = fileparts(zipFile);
if ~exist(filepath)
unzip(zipFile,filepath)
end
filename = fullfile(filepath,"CMU-1.ndpi");

    Read the metadata from the file. The function returns a structure, info, that contains metadata about the file.

    info = bioformatsinfo(filename);

    The AssociatedImages field specifies which, if any, associated label, macro, or thumbnail images are present in the file. The SeriesImages field provides names for the data series in the image file. A series image is any image that is not labeled in the metadata as a label, macro, or thumbnail. The file used in this example contains one unnamed series plus a macro image.

    info.AssociatedImages
    ans = 
"macro image"

    info.SeriesImages
    ans = 
""

    You can access details about the image data and acquisition settings in the RawMetadata field, which is organized into three nested structures.

    info.RawMetadata
    ans = struct with fields:
    GlobalInfo: [1×1 struct]
      CoreInfo: [1×5 struct]
    SeriesInfo: [1×1 struct]

    The CoreInfo structure is consistent across image files and formats, and specifies the size and order of spatial, channel, and time dimensions, as well as the underlying data type. The image count is the number of images in a series, and is the product of the number of z-slices, channels, and time points. Each row corresponds to one resolution level of an associated image or image series. The file used in this example contains 2-D image data with three channels at one time point. The number of rows is greater than the number of associated images and series, indicating multiple resolution levels.

    info.RawMetadata.CoreInfo
    ans=1×5 struct array with fields:
    51200    38144    1    3    1    "uint8"    1    "XYCZT"
    12800     9536    1    3    1    "uint8"    1    "XYCZT"
     3200     2384    1    3    1    "uint8"    1    "XYCZT"
      800      596    1    3    1    "uint8"    1    "XYCZT"
     1191      408    1    3    1    "uint8"    1    "XYCZT"

    The GlobalInfo field contains additional metadata available in the file. The global metadata varies between file formats and depends on your particular imaging setup.

    info.RawMetadata.GlobalInfo
    ans = struct with fields:
                          ImageLength: 38144
                   Slide_center_X_nm_: 4876667
    MetaDataPhotometricInterpretation: "RGB"
            PhotometricInterpretation: "YCbCr"
                          XResolution: 21910
                   Slide_center_Y_nm_: -2340000
                  ReferenceBlackWhite: 0
                             DateTime: "2009:12:31 09:11:46"
                             Software: "NDP.scan"
                          YResolution: 21975
                   Slide_center_Z_nm_: 0
                       ResolutionUnit: "Centimeter"
                        Magnification: 20
                          Compression: "JPEG"
                      Instrument_Make: "Hamamatsu"
                    NDP_image_version: 1
                         Capture_mode: "unknown"
                     NumberOfChannels: 3
                        BitsPerSample: 8
                           ImageWidth: 51200
                      SamplesPerPixel: 3
                         Tissue_index: 0
                     YCbCrSubSampling: "chroma image dimensions = luma image dimensions"
                     Instrument_Model: "NanoZoomer"

    The SeriesInfo field contains metadata specific to each series, if available. 

    info.RawMetadata.SeriesInfo
    ans = struct with no fields.

    This example uses:

    Open Live Script

    Run this code to download a whole slide image (WSI) from the MathWorks website, and unzip the downloaded folder. The image is provided by the OpenSlide library test data set [2]. The file is in the CZI format, which is associated with ZEISS microscope cameras. The image shows trichrome stain on a mouse kidney sample.

    zipFile = matlab.internal.examples.downloadSupportFile("image","data/Zeiss-5-JXR.zip/Zeiss-5-JXR.zip");
zipPath = fileparts(zipFile);
filepath = fileparts(zipPath);
if ~exist(filepath)
unzip(zipFile,filepath)
end

filename = fullfile(filepath,"Zeiss-5-JXR.czi");

    Read the file metadata. The function returns a structure, info, that contains metadata about the file.

    info = bioformatsinfo(filename);

    View the AssociatedImages field, which indicates that the file contains a macro image and a label image.

    info.AssociatedImages
    ans = 2×1 string array
    "label image"
    "macro image"

    View the SeriesImages field, which indicates that the file contains two image series corresponding to two different scan regions.

    info.SeriesImages
    ans = 2×1 string array
    "scanregion0"
    "scanregion1"

    The core metadata indicates that all images in the file are 2-D RGB images with one time point. There are 12 rows, indicating a total of 12 resolution levels across the image series and associated images.

    info.RawMetadata.CoreInfo
    ans=1×12 struct array with fields:
    11323    11338    1    3    1     "uint8"    1    "XYCZT"
     5661     5669    1    3    1     "uint8"    1    "XYCZT"
     2830     2834    1    3    1     "uint8"    1    "XYCZT"
     1415     1417    1    3    1     "uint8"    1    "XYCZT"
      707      708    1    3    1     "uint8"    1    "XYCZT"
    11300    11335    1    3    1     "uint8"    1    "XYCZT"
     5650     5667    1    3    1     "uint8"    1    "XYCZT"
     2825     2833    1    3    1     "uint8"    1    "XYCZT"
     1412     1416    1    3    1     "uint8"    1    "XYCZT"
      706      708    1    3    1     "uint8"    1    "XYCZT"
      640      515    1    3    1     "uint8"    1    "XYCZT"
     1260      615    1    3    1    "uint16"    1    "XYCZT"

    Input Arguments

    collapse all

    Name of the file, specified as a string scalar or a character vector. Specify filename as the absolute path to the file, a relative path from the current directory, or a relative path from a directory on the MATLAB® path.

    The file must be in a format supported by the Bio-Formats library. For a list of supported formats, see the Supported Formats page in the Bio-Formats documentation.

    Data Types: char | string

    Output Arguments

    collapse all

    File metadata, returned as a structure that contains these fields.

    FieldDescription
    FilenameThe full path to the file.
    VendorInfoInformation about the instrument used to acquire the image.
    AssociatedImagesList of related images in the file, such as thumbnails or low-resolution overviews.
    SeriesImagesList of the main data images in the file.
    RawMetadata

    Raw metadata from the file, organized into these nested fields. The contents of each field can vary between files, depending on the file format and acquisition details.

    • GlobalInfo, which includes details such as the acquisition date.

    • CoreInfo, which includes basic properties such as image width, height, and number of channels and time points.

    • SeriesInfo, which includes information about the different image series in the file.

    References

    [1] "CMU‑1.ndpi". OpenSlide Test Data. Accessed November 10, 2025. https://openslide.cs.cmu.edu/download/openslide-testdata/Hamamatsu/.

    [2] Venklab, Pathology, UT Health San Antonio. "Zeiss‑5‑JXR.czi". OpenSlide Test Data. Accessed November 10, 2025. https://openslide.cs.cmu.edu/download/openslide-testdata/Zeiss/.

    Version History

    Introduced in R2026a

    See Also

    | | |

    Topics

    External Websites