This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

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.

example

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

Input Arguments

expand all

Files or folders to include in the datastore, specified as a character vector, cell array of character vectors, string scalar, or string array. If the files are not in the current folder, then location must be full or relative paths. Files within subfolders of the specified folder are not automatically included in the datastore.

You can use the wildcard character (*) when specifying location. This character indicates that all matching files or all files in the matching folders are included in the datastore.

If the files are not available locally, then the full path of the files or folders must be an internationalized resource identifier (IRI), such as
hdfs:///path_to_file.

For information on using datastore with Amazon S3™, Windows Azure® Blob Storage, and HDFS™, see Work with Remote Data.

When location represents a folder, the datastore includes only supported image file formats and ignores any other format. Supported files 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'

Data Types: char | cell | string

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: imds = imageDatastore('C:\dir\imagedata','FileExtensions',{'.jpg','.tif'})

Subfolder inclusion flag, specified as the comma-separated pair consisting of 'IncludeSubfolders' and true, false, 0, or 1. 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

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

Alternate file system root paths, specified as the comma-separated pair 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® Distributed Computing 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

Source providing label data, specified as the comma-separated pair consisting of 'LabelSource' and '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.

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

expand all

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 pair 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 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

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.

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

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.

Example: @customreader

Data Types: function_handle

Object Functions

countEachLabelCount files in ImageDatastore labels
hasdataDetermine if data is available to read
numpartitionsNumber of datastore partitions
partitionPartition a datastore
previewSubset of data in datastore
readRead data in datastore
readallRead all data in datastore
readimageRead specified image from datastore
resetReset datastore to initial state
shuffleShuffle files in ImageDatastore
splitEachLabelSplit ImageDatastore labels by proportions

Examples

collapse all

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\imagesci\corn.tif'
              }
      Labels: [demos; imagesci]
    ReadSize: 1
     ReadFcn: @readDatastoreImage

Create an ImageDatastore object containing four images, and preview the first image.

imds = imageDatastore({'street1.jpg','street2.jpg','peppers.png','corn.tif'})
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
              }
    ReadSize: 1
      Labels: {}
     ReadFcn: @readDatastoreImage

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})

Alternatives

You also can create an ImageDatastore object using the datastore function. For example, ds = datastore(location,'Type','image') creates a datastore from a collection of files specified by location.

Introduced in R2015b