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
Description
creates a datastore imds
= imageDatastore(location
)imds
from the collection of image data
specified by location
.
specifies additional parameters and properties for imds
= imageDatastore(location
,Name,Value
)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 aFileSet
object leads to a faster construction time for datastores compared to specifying a path orDsFileSet
object. For more information, seematlab.io.datastore.FileSet
.DsFileSet
object — For more information, seematlab.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:///
. Internet URLs must include the protocol typepath_to_file
"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"
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);
"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
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
, specifyingReadFcn
slows down the performance ofimageDatastore
. 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
, andreadimage
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
andtransform
with onlyImageDatastore
,CombinedDatastore
,SequentialDatastore
, orTransformedDatastore
objects in a thread-based environment.
For more information, see Run MATLAB Functions in Thread-Based Environment.
Version History
Introduced in R2015bR2024b: 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.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)