writeall

Write blocked image datastore to files

Since R2023a

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.

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.

Examples

Write All Blocks as PNG Files

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)

Write All Blocks as TIFF Files

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

bimds — Blocked image datastore

blockedImageDatastore object

Blocked image datastore, specified as a blockedImageDatastore object.

outputLocation — Folder location to write data

character vector | string scalar

Folder location to write data, specified as a character vector or string scalar. outputLocation can specify a full or relative path.

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

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

Data Types: char | string

Name-Value Arguments

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

OutputFormat — Output file format

"png" (default) | "jpeg" | "jpg" | "mat" | character vector | string scalar

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

FilenamePrefix — Prefix to filename

[] (default) | character vector | string scalar

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

FilenameSuffix — Suffix to filename

[] (default) | character vector | string scalar

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

UseParallel — Write in parallel

false or 0 (default) | true or 1

Write blocks in parallel, specified as a numeric or logical 0 (false) or 1 (true). By default, writeall writes in serial. If you set UseParallel to true, then writeall divides the writing operations into separate groups and runs the groups in parallel if:

• Parallel Computing Toolbox™ is installed.

• An open parallel pool exists or automatic pool creation is enabled in the Parallel Preferences.

Otherwise, writeall writes in serial regardless of the value for UseParallel. The writeall function does not support writing in parallel via local threads.

Data Types: logical

WriteFcn — Custom writing function

function handle

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.

  Field	Description	Type
  ReadInfo	The second output of the read function	struct
  SuggestedOutputName	A fully qualified, globally unique filename that meets the location and naming requirements	string
  Location	The outputLocation argument passed to the writeall function	string

• 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

Quality — Quality of JPEG-compressed file

75 (default) | number in range [0, 100]

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.

Version History

Introduced in R2023a