本页对应的英文页面已更新,但尚未翻译。 若要查看最新内容,请点击此处访问英文页面。

imageDatastore

图像数据的数据存储

说明

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

创建对象

说明

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

示例

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

输入参数

全部展开

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

  • 路径 - 将路径指定为字符向量、字符向量元胞数组、字符串标量或字符串数组,其中包含本地或远程文件或文件夹的位置。

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

    • 远程文件或文件夹 - 以 hdfs:///path_to_file 格式的国际化资源标识符 (IRI) 将 location 指定为文件或文件夹的完整路径。有关详细信息,请参阅处理远程数据

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

location 表示文件夹时,数据存储只包含支持的文件格式,并忽略任何其他格式。要指定要包含在数据存储中的自定义文件扩展名列表,请参阅 FileExtensions 属性。

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

示例: 'file1.jpg'

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

示例: {'C:\dir\data\file1.tif','C:\dir\data\file2.tif'}

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

名称-值对组参数

指定可选的、以逗号分隔的 Name,Value 对组参数。Name 为参数名称,Value 为对应的值。Name 必须放在引号中。您可采用任意顺序指定多个名称-值对组参数,如 Name1,Value1,...,NameN,ValueN 所示。

示例: 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 属性来修改标签。

数据类型: 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

调用 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 的性能。有关转换和预处理图像的更高效方法,请参阅Preprocess Images for Deep Learning (Deep Learning Toolbox)。

示例: @customreader

数据类型: function_handle

对象函数

countEachLabel对 ImageDatastore 标签中的文件进行计数
hasdata确定是否有数据可读取
numpartitions数据存储分区数
partition划分数据存储
preview数据存储中的数据子集
read读取数据存储中的数据
readall读取数据存储中的所有数据
readimage从数据存储读取指定的图像
reset将数据存储重置为初始状态
shuffle无序排列 ImageDatastore 中的文件
splitEachLabel按比例拆分 ImageDatastore 标签
subset创建数据存储或文件集的子集
transform转换数据存储
combine合并来自多个数据存储的数据

示例

全部折叠

创建与 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'
              }
      Labels: [demos; imagesci]
    ReadSize: 1
     ReadFcn: @readDatastoreImage

创建一个包含四个图像的 ImageDatastore 对象,并预览第一个图像。

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

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

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

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

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

局限性

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

备选方法

您还可以使用 datastore 函数创建 ImageDatastore 对象。例如,ds = datastore(location,'Type','image') 根据 location 指定的文件集合创建一个数据存储。

在 R2015b 中推出