imageDatastore

图像数据的数据存储

说明

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

创建对象

语法

imds = imageDatastore(location)

imds = imageDatastore(location,Name,Value)

描述

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

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

示例

输入参量

全部展开

`location` — 要包括在数据存储中的文件或文件夹
`FileSet` | `DsFileSet` 对象 | 字符串数组 | 字符向量 | 字符向量元胞数组

要包含在数据存储中的文件或文件夹，指定为以下值之一：

FileSet 对象 - 与指定路径或 DsFileSet 对象相比，将位置指定为 FileSet 对象会加快数据存储的构造时间。有关详细信息，请参阅 matlab.io.datastore.FileSet。
DsFileSet 对象 - 有关详细信息，请参阅 matlab.io.datastore.DsFileSet。
文件路径 - 您可以将单个文件路径指定为字符串标量或字符向量。您可以将多个文件路径指定为字符串数组或字符向量元胞数组。

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

本地文件或文件夹 - 如果文件不在当前文件夹中，则指定完整路径或相对路径。指定文件夹的子文件夹中的文件不会自动包括在数据存储中。在指定本地路径时可以使用通配符 (*)。此字符指定数据存储包含所有匹配的文件或匹配文件夹中的所有文件。
远程文件或文件夹 - 将远程文件或文件夹的完整路径指定为 hdfs:///path_to_file 形式的统一资源定位器 (URL)。Internet URL 必须包含协议类型 "http://" 或 "https://"。在 URL 的任何位置使用通配符指定多个远程文件 (自 R2025a 起)。有关详细信息，请参阅处理远程数据。

当您指定文件夹时，数据存储仅包括具有支持的文件格式的文件，而忽略任何其他格式的文件。要指定要包含在数据存储中的自定义文件扩展名列表，请参阅 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 是对应的值。名称-值参量必须出现在其他参量之后，但参量对组的顺序无关紧要。

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

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

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

`IncludeSubfolders` — 子文件夹包含标记
`false` (默认) | `true`

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

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

示例: "IncludeSubfolders",true

数据类型: logical | double

`FileExtensions` — 图像文件扩展名
字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

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

示例: "FileExtensions",".jpg"

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

数据类型: char | cell | string

`AlternateFileSystemRoots` — 备用文件系统根路径
字符串向量 | 元胞数组

备用文件系统根路径，以名称-值参量形式指定，其中包含 "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"`

提供标签数据的源，指定为由 "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;

`Files` — 包含在数据存储中的文件
字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

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

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

数据类型: char | cell | string

`Folders` — 用于构造数据存储的文件夹
只读: 字符向量元胞数组

此属性为只读。

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

数据类型: cell

`ReadSize` — 要读取的图像文件的数量
1 (默认) | 正整数标量

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

`Labels` — 文件标签
分类、逻辑或数值向量 | 元胞数组 | 字符串数组

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

`ReadFcn` — 用于读取图像数据的函数
`@readDatastoreImage` (默认) | 函数句柄

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

function data = customreader(filename)
...
end

如果存在多个输出参量，则 imageDatastore 仅使用第一个参量并忽略其余参量。

注意

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

示例: @customreader

数据类型: function_handle

`SupportedOutputFormats` — 支持写入的格式
只读: 字符串行向量

此属性为只读。

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

`DefaultOutputFormat` — 默认输出格式
只读: 字符串标量

此属性为只读。

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

数据类型: string

对象函数

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

示例

全部折叠

使用子文件夹和标签创建 ImageDatastore 对象

创建与 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\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

指定要读取的图像

创建一个包含四个图像的 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)。
MATLAB 不支持要求身份验证的 Internet URL。
MATLAB Online™ 支持与 Microsoft^® OneDrive™ 文件和文件夹相关联的 Internet URL，而 MATLAB 的安装版本仅支持本地 OneDrive 文件。

扩展功能

全部展开

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

用法说明和限制：

read、readall 和 readimage 在基于线程的环境中不支持以下图像格式。
- 分层数据格式 (HDF)
- SVS
- TIFF
基于线程的环境不支持 writeall。
在基于线程的环境中，只能对 ImageDatastore、CombinedDatastore、SequentialDatastore 或 TransformedDatastore 对象使用 combine 和 transform。

有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

版本历史记录

在 R2015b 中推出

全部展开

R2025a: 使用通配符指定多个远程文件

您可以从多个远程文件创建一个数据存储。在 URL 的任何位置使用通配符指定多个远程文件。

R2024b: 使用数据存储函数通过 HTTP 和 HTTPS 读取数据

您可以通过在 Internet URL 上执行数据存储操作，从主要在线数据源读取数据。

另请参阅

imformats | mapreduce | tall

imageDatastore

说明

创建对象

语法

描述

输入参量

location — 要包括在数据存储中的文件或文件夹 FileSet | DsFileSet 对象 | 字符串数组 | 字符向量 | 字符向量元胞数组

名称-值参数

IncludeSubfolders — 子文件夹包含标记 false (默认) | true

FileExtensions — 图像文件扩展名 字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

AlternateFileSystemRoots — 备用文件系统根路径 字符串向量 | 元胞数组

LabelSource — 提供标签数据的源 "none" (默认) | "foldernames"

属性

Files — 包含在数据存储中的文件 字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

Folders — 用于构造数据存储的文件夹 只读: 字符向量元胞数组

ReadSize — 要读取的图像文件的数量 1 (默认) | 正整数标量

Labels — 文件标签 分类、逻辑或数值向量 | 元胞数组 | 字符串数组

ReadFcn — 用于读取图像数据的函数 @readDatastoreImage (默认) | 函数句柄

SupportedOutputFormats — 支持写入的格式 只读: 字符串行向量

DefaultOutputFormat — 默认输出格式 只读: 字符串标量

对象函数

示例

使用子文件夹和标签创建 ImageDatastore 对象

指定要读取的图像

局限性

扩展功能

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

版本历史记录

R2025a: 使用通配符指定多个远程文件

R2024b: 使用数据存储函数通过 HTTP 和 HTTPS 读取数据

另请参阅

主题

`location` — 要包括在数据存储中的文件或文件夹
`FileSet` | `DsFileSet` 对象 | 字符串数组 | 字符向量 | 字符向量元胞数组

`IncludeSubfolders` — 子文件夹包含标记
`false` (默认) | `true`

`FileExtensions` — 图像文件扩展名
字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

`AlternateFileSystemRoots` — 备用文件系统根路径
字符串向量 | 元胞数组

`LabelSource` — 提供标签数据的源
`"none"` (默认) | `"foldernames"`

`Files` — 包含在数据存储中的文件
字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

`Folders` — 用于构造数据存储的文件夹
只读: 字符向量元胞数组

`ReadSize` — 要读取的图像文件的数量
1 (默认) | 正整数标量

`Labels` — 文件标签
分类、逻辑或数值向量 | 元胞数组 | 字符串数组

`ReadFcn` — 用于读取图像数据的函数
`@readDatastoreImage` (默认) | 函数句柄

`SupportedOutputFormats` — 支持写入的格式
只读: 字符串行向量

`DefaultOutputFormat` — 默认输出格式
只读: 字符串标量

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。