writeall

R2026b

Write blocked image datastore to files

Since R2023a

collapse all in page

    Syntax

    writeall(bimds,outputLocation)
    writeall(bimds,outputLocation,Name=Value)

    Description

    writeall(bimds,outputLocation) writes the data from the blocked image datastore bimds to PNG files at the location specified in outputLocation. The number of output files is the same as the number of files referenced by the datastore.

    example

    writeall(bimds,outputLocation,Name=Value) writes data with additional options specified by one or more name-value arguments. For example, you can specify OutputFormat and a file extension such as "png" to specify the type of files that writeall creates.

    example

    Examples

    collapse all

    Open Live Script

    Create a blocked image.

    bim = blockedImage("tumor_091R.tif");

    Create a datastore, specifying the resolution level and the block size.

    bls = selectBlockLocations(bim,Levels=2,BlockSize=[512, 512]);
bimds = blockedImageDatastore(bim,BlockLocationSet=bls);

    Write all blocks of the datastore as PNG files in a subdirectory of the current directory.

    dir = "tumor_091R_PNG_"+string(datetime("now",Format="yyyy-MM-dd-HH-mm-ss"));
writeall(bimds,dir)
    Open Live Script

    Create a blocked image datastore.

    bim = blockedImage("tumor_091R.tif");
bls = selectBlockLocations(bim,Levels=2,BlockSize=[512, 512]);
bimds = blockedImageDatastore(bim,BlockLocationSet=bls);

    Write all blocks of the datastore as TIFF files in a subdirectory of the current directory, and add a suffix with the current time to each filename.

    dir = "tumor_091R_TIFF";
writeall(bimds,dir,OutputFormat="TIFF",WriteFcn=@myTIFFWriteFcn, ...
    FilenameSuffix="__"+string(datetime("now",Format="yyyy-MM-dd-HH-mm-ss")))

    The custom write function myTIFFWriteFcn writes blocks of data as TIFF files.

    function myTIFFWriteFcn(data,writeInfo,outputType)
    if strcmp(outputType,"TIFF")
        dir =  writeInfo.Location;
        filename = writeInfo.SuggestedOutputName;
        imwrite(data,dir+filesep+filename,"tiff")
    end
end

    Input Arguments

    collapse all

    Blocked image datastore, specified as a blockedImageDatastore object.

    Folder location to write data, specified as a character vector or string scalar. outputLocation can specify a full or relative path. If the UseParallel name-value argument is "on" or "auto", then outputLocation should be a valid path on the client session.

    Example: outputLocation = "../../dir/data"

    Example: outputLocation = "C:\Users\MyName\Desktop"

    Data Types: char | string

    Name-Value Arguments

    expand all

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: writeall(bimds,outputLocation,OutputFormat="jpeg") writes the files from the datastore bimds to the output location in the JPEG format.

    General Options

    expand all

    Output file format, specified as "jpeg", "jpg", "png", "mat", or a string scalar or character vector. For the "jpeg" and "jpg" output formats, you can refine the writing operation using the Quality name-value argument.

    If you need to write files of a different format than JPEG, JPG, PNG, or MAT, then use both the OutputFormat and WriteFcn arguments.

    Data Types: char | string

    Prefix to filename, specified as a character vector or string scalar.

    The writeall function adds the specified prefix to each output filename. For example, this code adds the current date to the beginning of all filenames output from the datastore:

    prefixText = string(datetime("today"))
writeall(bimds,"C:\myFolder",FilenamePrefix=prefixText)
    By default, the function does not add a prefix to filenames.

    Data Types: char | string

    Suffix to filename, specified as a character vector or string scalar.

    The writeall function adds the specified suffix to each output filename. For example, this code adds the descriptive text "jpeg_qual70" to the end of all filenames output from the datastore:

    writeall(bimds,"C:\myFolder",FilenameSuffix="jpeg_qual70")
    By default, the function does not add a prefix to filenames.

    Data Types: char | string

    Option to perform computations in parallel using a parallel pool of workers, specified as one of these values:

    • "off" — Run in serial on the MATLAB® client.

    • "auto" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, then run in serial on the MATLAB client.

    • "on" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, then throw an error.

    Before R2026b: To run in parallel, set UseParallel to true (1).

    If you do not have a parallel pool open and automatic pool creation is enabled, then MATLAB opens a pool using the default cluster profile. To use a parallel pool to run computations in MATLAB, you must have Parallel Computing Toolbox™. For more information, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

    The writeall function does not support writing data in parallel using local threads.

    Data Types: char | string

    Custom writing function, specified as a function handle. writeall uses the specified function to create the output files.

    You can use the WriteFcn argument to write data in a variety of formats, even if writeall does not directly support the output format.

    Functional Signature

    The custom writing function must accept at least three input arguments, data, writeInfo, and outputType:

    function myWriteFcn(data,writeInfo,outputType)
    The function can also accept additional inputs, such as name-value arguments, after the three required inputs.

    • data contains the output of the read function operating on the datastore.

    • writeInfo is an object of type matlab.io.datastore.WriteInfo with the fields listed in this table.

      FieldDescriptionType
      ReadInfoThe second output of the read functionstruct
      SuggestedOutputNameA fully qualified, globally unique filename that meets the location and naming requirementsstring
      LocationThe outputLocation argument passed to the writeall functionstring

    • outputType is the output format to be written to, such as "jpg" or "png".

    Example Function

    This function writes TIFF files from a blocked image datastore:

    function myTIFFWriteFcn(data,writeInfo,outputType)
    if strcmp(outputType,"tiff")
        dir =  writeInfo.Location;
        filename = writeInfo.SuggestedOutputName;
        imwrite(data,dir+filesep+filename,"tiff")
    end
end
    To invoke myTIFFWriteFcn as the writing function for datastore bimds, use these commands:
    outputLocation = "C:/MyData";
writeall(bimds,outputLocation,WriteFcn=@myTIFFWriteFcn)

    Data Types: function_handle

    Options for jpeg or jpg Output

    expand all

    Quality of the JPEG-compressed file, specified as a number in the range [0, 100], where 0 is lower quality and higher compression, and 100 is higher quality and lower compression.

    Tips

    • The default output filename has the form Image_<N>_Level_<L>_Block_<blockOrigin>.<ext>. For example, Image_1_Level_1_Block_1_1_1.jpg. The function pads the values of <N> and <L> with leading 0s, if required.

    Extended Capabilities

    expand all

    Version History

    Introduced in R2023a

    expand all

    See Also

    | | |