imageDatastore

Datastore for image data

Description

Use an ImageDatastore object to manage a collection of image files, where each individual image fits in memory, but the entire collection of images does not necessarily fit. You can create an ImageDatastore object using the imageDatastore function, specify its properties, and then import and process the data using object functions.

Creation

Syntax

imds = imageDatastore(location)

imds = imageDatastore(location,Name,Value)

Description

imds = imageDatastore(location) creates a datastore imds from the collection of image data specified by location.

imds = imageDatastore(location,Name,Value) specifies additional parameters and properties for imds using one or more name-value pair arguments.

Input Arguments

location — Files or folders to include in datastore

FileSet | DsFileSet object | string array | character vector | cell array of character vectors

Files or folders to include in the datastore, specified as one of these values:

• FileSet object — Specifying the location as a FileSet object leads to a faster construction time for datastores compared to specifying a path or DsFileSet object. For more information, see matlab.io.datastore.FileSet.

• DsFileSet object — For more information, see matlab.io.datastore.DsFileSet.

• File path — You can specify a single file path as a string scalar or character vector. You can specify multiple file paths as a string array or cell array of character vectors.

Files or folders can be local or remote:

• Local files or folders — If the files are not in the current folder, then specify full or relative paths. Files within subfolders of a specified folder are not automatically included in the datastore. You can use the wildcard character (*) when specifying the local path. This character specifies that the datastore include all matching files or all files in the matching folders.

• Remote files or folders — Specify full paths to remote files or folders as a uniform resource locator (URL) of the form hdfs:///path_to_file. Internet URLs must include the protocol type "http://" or "https://". For more information, see Work with Remote Data.

When you specify a folder, the datastore includes only files with supported file formats and ignores files with any other format. To specify a custom list of file extensions to include in your datastore, see the FileExtensions name-value argument.

The imageDatastore function supports files that have an imformats format.

Example: "file1.jpg"

Example: "../dir/data/file1.png"

Example: ["C:\dir\data\file1.tif","C:\dir\data\file2.tif"]

Example: "C:\dir\data\*.jpg"

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: imds = imageDatastore("C:\dir\imagedata",FileExtensions=[".jpg",".tif"])

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: imds = imageDatastore("C:\dir\imagedata","FileExtensions",[".jpg",".tif"])

IncludeSubfolders — Subfolder inclusion flag

false (default) | true

Subfolder inclusion flag, specified as the name-value argument consisting of "IncludeSubfolders" and true or false. Specify true to include all files and subfolders within each folder or false to include only the files within each folder.

If you do not specify "IncludeSubfolders", then the default value is false.

Example: "IncludeSubfolders",true

Data Types: logical | double

FileExtensions — Image file extensions

character vector | cell array of character vectors | string scalar | string array

Image file extensions, specified as the comma-separated pair consisting of "FileExtensions" and a character vector, cell array of character vectors, string scalar, or string array. The specified extensions do not require an imformats format, and you can use the empty quotes "" to represent files without extensions. If you do not specify "FileExtensions", then imageDatastore automatically includes all images with imformats extensions in the specified path. If you want to include extensions that imformats does not recognize, then specify all extensions.

Example: "FileExtensions",".jpg"

Example: "FileExtensions",[".jpg",".png"]

Data Types: char | cell | string

AlternateFileSystemRoots — Alternate file system root paths

string vector | cell array

Alternate file system root paths, specified as the name-value argument consisting of "AlternateFileSystemRoots" and a string vector or a cell array. Use "AlternateFileSystemRoots" when you create a datastore on a local machine, but need to access and process the data on another machine (possibly of a different operating system). Also, when processing data using the Parallel Computing Toolbox™ and the MATLAB^® Parallel Server™, and the data is stored on your local machines with a copy of the data available on different platform cloud or cluster machines, you must use "AlternateFileSystemRoots" to associate the root paths.

• To associate a set of root paths that are equivalent to one another, specify "AlternateFileSystemRoots" as a string vector. For example,

  ["Z:\datasets","/mynetwork/datasets"]

• To associate multiple sets of root paths that are equivalent for the datastore, specify "AlternateFileSystemRoots" as a cell array containing multiple rows where each row represents a set of equivalent root paths. Specify each row in the cell array as either a string vector or a cell array of character vectors. For example:

  • Specify "AlternateFileSystemRoots" as a cell array of string vectors.

    {["Z:\datasets", "/mynetwork/datasets"];...
     ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}

  • Alternatively, specify "AlternateFileSystemRoots" as a cell array of cell array of character vectors.

    {{'Z:\datasets','/mynetwork/datasets'};...
     {'Y:\datasets', '/mynetwork2/datasets','S:\datasets'}}

The value of "AlternateFileSystemRoots" must satisfy these conditions:

• Contains one or more rows, where each row specifies a set of equivalent root paths.

• Each row specifies multiple root paths and each root path must contain at least two characters.

• Root paths are unique and are not subfolders of one another.

• Contains at least one root path entry that points to the location of the files.

For more information, see Set Up Datastore for Processing on Different Machines or Clusters.

Example: ["Z:\datasets","/mynetwork/datasets"]

Data Types: string | cell

LabelSource — Source providing label data

"none" (default) | "foldernames"

Source providing label data, specified as the name-value argument consisting of "LabelSource" and either "none" or "foldernames". If "none" is specified, then the Labels property is empty. If "foldernames" is specified, then labels are assigned according to the folder names and stored in the Labels property. You can later modify the labels by accessing the Labels property directly.

The "LabelSource" name-value argument is not usable if a FileSet object is used as the file or folder location.

Data Types: char | string

In addition to these name-value pairs, you also can specify any of the properties on this page as name-value pairs, except for the Files property.

Properties

ImageDatastore properties describe the data and specify how to read the data from the datastore. You can specify the value of ImageDatastore properties using name-value arguments when you create the datastore object. To view or modify a property after creating the object, use the dot notation.

For example, you can create an ImageDatastore object and specify the "ReadFcn" parameter:

imds = imageDatastore("peppers.png","ReadFcn",@customreader);

Alternatively, you can assign "ReadFcn" to @customreader after you create the ImageDatastore:

imds = imageDatastore("peppers.png");
imds.ReadFcn = @customreader;

Files — Files included in datastore

character vector | cell array of character vectors | string scalar | string array

Files included in the datastore, resolved as a character vector, cell array of character vectors, string scalar, or string array. Each character vector or string is a full path to a file. The location argument in the imageDatastore and datastore functions defines Files when the datastore is created.

Example: {"C:\dir\data\file1.jpg";"C:\dir\data\file2.jpg"}

Data Types: char | cell | string

Folders — Folders used to construct datastore

cell array of character vectors

This property is read-only.

Folders used to construct datastore, returned as a cell array of character vectors. The cell array is oriented as a column vector. Each character vector is a path to a folder that contains data files. The location argument in the imageDatastore and datastore functions defines Folders when the datastore is created.

Data Types: cell

ReadSize — Number of image files to read

1 (default) | positive integer scalar

Number of image files to read in a call to the read function, specified as a positive integer scalar. Each call to the read function reads at most ReadSize images.

Labels — File labels

categorical, logical, or numeric vector | cell array | string array

File labels for the files in the datastore, specified as a vector, a cell array, or a string array. The order of the labels in the array corresponds to the order of the associated files in the datastore. If you specify "LabelSource","foldernames" when creating the ImageDatastore object, then the label name for a file is the name of the folder containing it. If you do not specify "LabelSource","foldernames", then Labels is an empty cell array or string array. If you change the Files property after the datastore is created, then the Labels property is not automatically updated to incorporate the added files.

Data Types: categorical | cell | logical | double | single | string

ReadFcn — Function that reads image data

@readDatastoreImage (default) | function handle

Function that reads image data, specified as a function handle. The function must take an image file name as input, and then it outputs the corresponding image data. For example, if customreader is the specified function to read the image data, then it must have a signature similar to this:

function data = customreader(filename)
...
end

If more than one output argument exists, then imageDatastore uses only the first argument and ignores the rest.

Note

Using ReadFcn to transform or pre-process 2-D images is not recommended. For file formats recognized by imformats, specifying ReadFcn slows down the performance of imageDatastore. For more efficient ways to transform and pre-process images, see Preprocess Images for Deep Learning (Deep Learning Toolbox).

Example: @customreader

Data Types: function_handle

SupportedOutputFormats — Formats supported for writing

string row vector

This property is read-only.

Formats supported for writing, returned as a row vector of strings. This property specifies the possible output formats when using writeall to write output files from the datastore.

DefaultOutputFormat — Default output format

string scalar

This property is read-only.

Default output format, returned as a string scalar. This property specifies the default format when using writeall to write output files from the datastore.

Data Types: string

Object Functions

countEachLabel	Count files in ImageDatastore labels
hasdata	Determine if data is available to read
numpartitions	Number of datastore partitions
partition	Partition a datastore
preview	Preview subset of data in datastore
read	Read data in datastore
readall	Read all data in datastore
readimage	Read specified image from datastore
writeall	Write datastore to files
reset	Reset datastore to initial state
shuffle	Shuffle all data in datastore
splitEachLabel	Split ImageDatastore labels by proportions
subset	Create subset of datastore or FileSet
transform	Transform datastore
combine	Combine data from multiple datastores
isPartitionable	Determine whether datastore is partitionable
isSubsettable	Determine whether datastore is subsettable
isShuffleable	Determine whether datastore is shuffleable

Examples

Create ImageDatastore Object Using Subfolders and Labels

Create an ImageDatastore object associated with all .tif files in the MATLAB® path and its subfolders. Use the folder names as label names.

imds = imageDatastore(fullfile(matlabroot,"toolbox","matlab"),...
"IncludeSubfolders",true,"FileExtensions",".tif","LabelSource","foldernames")

imds = ImageDatastore with properties:
                       Files: {
                              '...\matlab\toolbox\matlab\demos\example.tif';
                              '...\matlab\toolbox\matlab\matlab_images\tif\corn.tif'
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab'
                              }
                      Labels: [demos; imagesci]
    AlternateFileSystemRoots: {}
                    ReadSize: 1
      SupportedOutputFormats: ["png"    "jpg"    "jpeg"    "tif"    "tiff"]
         DefaultOutputFormat: "png"
                     ReadFcn: @readDatastoreImage

Specify Images to Read

Create a FileSet object containing four images. Create an ImageDatastore object.

fs = matlab.io.datastore.FileSet(["street1.jpg","street2.jpg","peppers.png","corn.tif"])

fs = 
  FileSet with properties:

                    NumFiles: 4
                NumFilesRead: 0
                    FileInfo: Show FileInfo for all 4 files
    AlternateFileSystemRoots: {}

imds = imageDatastore(fs)

imds = ImageDatastore with properties:
                       Files: {
                              '...\matlab\toolbox\matlab\demos\street1.jpg';
                              '...\matlab\toolbox\matlab\demos\street2.jpg';
                              ' ...\matlab\toolbox\matlab\imagesci\peppers.png'
                               ... and 1 more
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab\demos';
                              '...\matlab\toolbox\matlab\imagesci'
                              }
    AlternateFileSystemRoots: {}
                    ReadSize: 1
                      Labels: {}
      SupportedOutputFormats: ["png"    "jpg"    "jpeg"    "tif"    "tiff"]
         DefaultOutputFormat: "png"
                     ReadFcn: @readDatastoreImage

Preview the first image.

imshow(preview(imds));

Read only the second and third images, one at a time.

for i = 2:3
    img = readimage(imds,i);
end

Read all four images and view the third image.

imgs = readall(imds);
imshow(imgs{3})

Limitations

• Using ReadFcn to transform or pre-process 2-D images is not recommended. For file formats recognized by imformats, specifying ReadFcn slows down the performance of imageDatastore. For more efficient ways to transform and pre-process images, see Preprocess Images for Deep Learning (Deep Learning Toolbox).

• MATLAB does not support internet URLs that require authentication.

• MATLAB Online™ supports internet URLs associated with Microsoft^® OneDrive™ files and folders, while the installed version of MATLAB supports only local OneDrive files.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Usage notes and limitations:

• read, readall, and readimage do not support the following image formats in a thread-based environment.

  • Hierarchical Data Format (HDF)

  • SVS

  • TIFF

• writeall is not supported in a thread-based environment.

• You can use combine and transform with only ImageDatastore, CombinedDatastore, SequentialDatastore, or TransformedDatastore objects in a thread-based environment.

For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2015b

R2024b: Read data over HTTP and HTTPS using datastore functions

You can read data from primary online sources by performing datastore operations over an internet URL.