Main Content

imageDatastore

图像数据的数据存储

说明

如果一个图像文件集合中的每个图像可以单独放入内存,但整个集合不一定能放入内存,则可以使用 ImageDatastore 对象来管理。您可以使用 imageDatastore 函数创建 ImageDatastore 对象,指定其属性,然后使用对象函数导入和处理数据。

创建对象

描述

imds = imageDatastore(location) 根据 location 指定的图像数据集合创建一个数据存储 imds

示例

imds = imageDatastore(location,Name,Value) 使用一个或多个名称-值对组参数为 imds 指定其他参数和属性

输入参数

全部展开

数据存储中包含的文件或文件夹,指定为 FileSet 对象、文件路径或 DsFileSet 对象。

  • FileSet 对象 - 您可以将 location 指定为 FileSet 对象。与指定路径或 DsFileSet 对象相比,将位置指定为 FileSet 对象会加快数据存储的构造时间。有关详细信息,请参阅 matlab.io.datastore.FileSet

  • 文件路径 - 您可以将单个文件路径指定为字符向量或字符串标量。您可以将多个文件路径指定为字符向量元胞数组或字符串数组。

  • DsFileSet 对象 - 您可以指定 DsFileSet 对象。有关详细信息,请参阅 matlab.io.datastore.DsFileSet

文件或文件夹可以是本地的或远程的:

  • 本地文件或文件夹 - 指定文件或文件夹的本地路径。如果文件不在当前文件夹中,则指定完整路径或相对路径。指定文件夹的子文件夹中的文件不会自动包括在数据存储中。在指定本地路径时可以使用通配符 (*)。此字符指定数据存储包含所有匹配的文件或匹配文件夹中的所有文件。

  • 远程文件或文件夹 - 将远程文件或文件夹的完整路径指定为 hdfs:///path_to_file 形式的统一资源定位器 (URL)。有关详细信息,请参阅处理远程数据

当您指定文件夹时,数据存储仅包括具有支持的文件格式的文件,而忽略任何其他格式的文件。要指定要包含在数据存储中的自定义文件扩展名列表,请参阅 FileExtensions 属性。

imageDatastore 函数支持具有 imformats 格式的文件。

示例: "file1.jpg"

示例: "../dir/data/file1.png"

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

示例: "C:\dir\data\*.jpg"

名称-值参数

将可选的参数对组指定为 Name1=Value1,...,NameN=ValueN,其中 Name 是参数名称,Value 是对应的值。名称-值参数必须出现在其他参数之后,但参数对组的顺序无关紧要。

在 R2021a 之前,使用逗号分隔每个名称和值,并用引号将 Name 引起来。

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

子文件夹包含标志,指定为由 "IncludeSubfolders"truefalse 组成的名称-值参数。指定 true 可包含每个文件夹中的所有文件和子文件夹,指定 false 则仅包含每个文件夹中的文件。

如果不指定 "IncludeSubfolders",则默认值为 false

示例: "IncludeSubfolders",true

数据类型: logical | double

图像文件扩展名,指定为以逗号分隔的对组,其中包含 "FileExtensions" 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。指定的扩展名不要求采用 imformats 格式,您可以使用空引号 "" 来表示不带扩展名的文件。如果未指定 "FileExtensions"imageDatastore 将自动包含指定路径中具有 imformats 扩展名的所有图像。如果要包含 imformats 无法识别的扩展名,请指定所有扩展名。

示例: "FileExtensions",".jpg"

示例: "FileExtensions",[".jpg",".png"]

数据类型: char | cell | string

备用文件系统根路径,以名称-值参数形式指定,其中包含 "AlternateFileSystemRoots" 和一个字符串向量或元胞数组。当您在本地计算机上创建数据存储,但需要访问和处理另一台计算机(可能是不同操作系统)上的数据时,请使用 "AlternateFileSystemRoots"。此外,如果您使用 Parallel Computing Toolbox™ 和 MATLAB® Parallel Server™ 处理数据,而数据存储在本地计算机上并且在不同平台云或集群计算机上存储数据副本,则必须使用 "AlternateFileSystemRoots" 关联根路径。

  • 要关联一组等效的根路径,请将 "AlternateFileSystemRoots" 指定为字符串向量。例如,

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

  • 要将在数据存储方面等效的多组根路径关联起来,请将 "AlternateFileSystemRoots" 指定为包含多个行的元胞数组,其中每一行代表一组等效的根路径。将元胞数组中的每一行指定为一个字符串向量或字符向量元胞数组。例如:

    • "AlternateFileSystemRoots" 指定为字符串向量元胞数组。

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

    • 也可以将 "AlternateFileSystemRoots" 指定为字符向量元胞数组。

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

"AlternateFileSystemRoots" 的值必须满足以下条件:

  • 包含一行或多行,每一行指定一组等效的根路径。

  • 每一行指定多个根路径,每个根路径必须至少包含两个字符。

  • 根路径是唯一的,并且不是彼此的子文件夹。

  • 包含至少一个指向文件位置的根路径条目。

有关详细信息,请参阅Set Up Datastore for Processing on Different Machines or Clusters

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

数据类型: string | cell

提供标签数据的源,指定为由 "LabelSource""none""foldernames" 组成的名称-值参数。如果指定了 "none",则 Labels 属性为空。如果指定了 "foldernames",将根据文件夹名称分配标签并存储在 Labels 属性中。您以后可以通过直接访问 Labels 属性来修改标签。

如果将 FileSet 对象用作文件或文件夹位置,则不可以使用 "LabelSource" 名称-值参数。

数据类型: char | string

除了这些名称-值对组外,还可以指定本页上除 Files 属性之外的任何属性作为名称-值对组。

属性

全部展开

ImageDatastore 属性描述数据并指定如何从数据存储中读取数据。创建数据存储对象时,可以使用名称-值参数指定 ImageDatastore 属性的值。要在创建对象后查看或修改属性,请使用圆点表示法。

例如,您可以创建 ImageDatastore 对象并指定 "ReadFcn" 参数:

imds = imageDatastore("peppers.png","ReadFcn",@customreader);
也可以在创建 ImageDatastore 之后为 @customreader 指定 "ReadFcn"
imds = imageDatastore("peppers.png");
imds.ReadFcn = @customreader;

包含在数据存储中的文件,解析为字符向量、字符向量元胞数组、字符串标量或字符串数组。每个字符向量或字符串表示文件的一个完整路径。创建数据存储时,imageDatastoredatastore 函数中的 location 参数用来定义 Files

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

数据类型: char | cell | string

此 属性 为只读。

用于构造数据存储的文件夹,以字符向量元胞数组形式返回。该元胞数组定向为一个列向量。每个字符向量均为指向一个包含数据文件的文件夹的路径。创建数据存储时,imageDatastoredatastore 函数中的 location 参数用来定义 Folders

数据类型: cell

调用 read 函数时要读取的图像文件的数量,指定为正整数标量。每次调用 read 函数最多读取 ReadSize 个图像。

数据存储中文件的文件标签,指定为向量、元胞数组或字符串数组。标签在数组中的顺序对应于关联文件在数据存储中的顺序。如果创建 ImageDatastore 对象时指定 "LabelSource","foldernames",则文件的标签名称就是所在文件夹的名称。如果不指定 "LabelSource","foldernames",则 Labels 是一个空的元胞数组或字符串数组。如果在创建数据存储后更改 Files 属性,则 Labels 属性不会自动更新以纳入添加的文件。

数据类型: categorical | cell | logical | double | single | string

读取图像数据的函数,指定为函数句柄。函数必须以图像文件名作为输入,然后输出对应的图像数据。例如,如果 customreader 是指定用来读取图像数据的函数,则它必须具有类似于以下内容的签名:

function data = customreader(filename)
...
end
如果存在多个输出参数,则 imageDatastore 仅使用第一个参数并忽略其余参数。

注意

不推荐使用 ReadFcn 变换或预处理二维图像。对于由 imformats 识别的文件格式,指定 ReadFcn 会降低 imageDatastore 的性能。有关变换和预处理图像的更高效方法,请参阅预处理图像以进行深度学习 (Deep Learning Toolbox)

示例: @customreader

数据类型: function_handle

此 属性 为只读。

支持写入的格式,以字符串组成的行向量形式返回。此属性指定使用 writeall 从数据存储写入输出文件时可能的输出格式。

此 属性 为只读。

默认输出格式,以字符串标量形式返回。此属性指定使用 writeall 从数据存储写入输出文件时的默认格式。

数据类型: string

对象函数

countEachLabel对 ImageDatastore 标签中的文件进行计数
hasdata确定是否有数据可读取
numpartitions数据存储分区数
partition划分数据存储
preview预览数据存储中的数据子集
read读取数据存储中的数据
readall读取数据存储中的所有数据
readimage从数据存储读取指定的图像
writeall将数据存储写入文件
reset将数据存储重置为初始状态
shuffle对数据存储中的所有数据进行乱序处理
splitEachLabel按比例拆分 ImageDatastore 标签
subset创建数据存储或 FileSet 的子集
transform变换数据存储
combine合并来自多个数据存储的数据
isPartitionable确定数据存储是否可分区
isSubsettableDetermine whether datastore is subsettable
isShuffleable确定数据存储是否可乱序

示例

全部折叠

创建与 MATLAB® 路径及其子文件夹中的所有 .tif 文件相关联的 ImageDatastore 对象。使用文件夹名称作为标签名称。

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'
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab'
                              }
                      Labels: [demos; imagesci]
    AlternateFileSystemRoots: {}
                    ReadSize: 1
      SupportedOutputFormats: ["png"    "jpg"    "jpeg"    "tif"    "tiff"]
         DefaultOutputFormat: "png"
                     ReadFcn: @readDatastoreImage

创建一个包含四个图像的 FileSet 对象。创建 ImageDatastore 对象。

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

预览第一个图像。

imshow(preview(imds));

image of street

只读取第二个和第三个图像,每次一个图像。

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

读取所有四个图像并查看第三个图像。

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

image of vegetables

局限性

  • 不推荐使用 ReadFcn 变换或预处理二维图像。对于由 imformats 识别的文件格式,指定 ReadFcn 会降低 imageDatastore 的性能。有关变换和预处理图像的更高效方法,请参阅预处理图像以进行深度学习 (Deep Learning Toolbox)

扩展功能

版本历史记录

在 R2015b 中推出