imageDatastore

イメージ データのデータストア

このページをすべて展開する

説明

個々のイメージはメモリに収まるが、イメージの集合全体が必ずしもメモリに収まるとは限らない場合、イメージ ファイルの集合を管理するには ImageDatastore オブジェクトを使用します。関数 imageDatastore を使用して ImageDatastore オブジェクトを作成し、そのプロパティを指定すると、オブジェクト関数を使用してデータのインポートおよび処理ができます。

作成

構文

imds = imageDatastore(location)
imds = imageDatastore(location,Name,Value)

説明

imds = imageDatastore(location) は、location で指定されたイメージ データの集合からデータストア imds を作成します。

imds = imageDatastore(location,Name,Value) は、1 つ以上の名前と値のペアの引数を使用して、imds の追加パラメーターとプロパティを指定します。

例

入力引数

すべて展開する

データストアに含めるファイルまたはフォルダー。次の値のいずれかとして指定します。

  • FileSet オブジェクト — 場所を FileSet オブジェクトとして指定すると、パスまたは DsFileSet オブジェクトを指定した場合に比べ、データストアの構築時間が短くなります。詳細については、matlab.io.datastore.FileSet を参照してください。

  • DsFileSet オブジェクト — 詳細については、matlab.io.datastore.DsFileSet を参照してください。

  • ファイル パス — 単一のファイル パスを string スカラーまたは文字ベクトルとして指定できます。複数のファイル パスは string 配列または文字ベクトルの cell 配列として指定できます。

ファイルまたはフォルダーはローカルでもリモートでもかまいません。

  • ローカルのファイルまたはフォルダー — 現在のフォルダー以外のファイルの場合は、絶対パスまたは相対パスを指定します。指定したフォルダーのサブフォルダー内にあるファイルは、自動ではデータストアに含まれません。ローカル パスを指定するときにワイルドカード文字 (*) を使用できます。この文字は、一致するフォルダー内にある、すべてのファイルまたは一致するすべてのファイルをデータストアに含めることを指定します。

  • リモートのファイルまたはフォルダー — hdfs:///path_to_file の形式の Uniform Resource Locator (URL) として、リモートのファイルまたはフォルダーの絶対パスを指定します。インターネット 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" と true または false で構成される名前と値の引数として指定します。各フォルダー内のすべてのファイルとサブフォルダーを含めるには true を指定し、各フォルダー内のファイルのみを含めるには false を指定します。

"IncludeSubfolders" を指定しない場合、既定値は false です。

例: "IncludeSubfolders",true

データ型: logical | double

イメージ ファイル拡張子。"FileExtensions" と、文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列で構成されるコンマ区切りのペアとして指定します。指定された拡張子に imformats 型式は不要であり、空の引用符 "" を使用して、拡張子なしでファイルを表すことができます。"FileExtensions" を指定しない場合、imageDatastore は、指定パス上の imformats 拡張子をもつすべてのイメージを自動的に含めます。imformats で認識されない拡張子を含める場合は、すべての拡張子を指定します。

例: "FileExtensions",".jpg"

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

データ型: char | cell | string

代替ファイル システムのルート パス。"AlternateFileSystemRoots" と string ベクトルまたは cell 配列で構成される名前と値の引数として指定します。ローカル マシン上にデータストアを作成するが、別のマシン (異なるオペレーティング システムの可能性がある) 上でデータにアクセスして処理する必要がある場合は、"AlternateFileSystemRoots" を使用します。また、Parallel Computing Toolbox™ と MATLAB® Parallel Server™ を使用してデータを処理し、そのデータがローカル マシンに保存され、そのデータのコピーが異なるプラットフォームのクラウドやクラスター マシンにある場合、"AlternateFileSystemRoots" を使用してルート パスを関連付けなければなりません。

  • 相互に対応する 1 組のルート パスを関連付けるには、"AlternateFileSystemRoots" を string ベクトルとして指定します。以下に例を示します。

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

  • データストアに対応する複数の組のルート パスを関連付けるには、複数行を含む cell 配列として "AlternateFileSystemRoots" を指定します。各行は対応するルート パスの組を表します。cell 配列内の各行を string ベクトル、または文字ベクトルの cell 配列のいずれかとして指定します。以下に例を示します。

    • "AlternateFileSystemRoots" を string ベクトルの cell 配列として指定します。

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

    • あるいは、"AlternateFileSystemRoots" を文字ベクトルの cell 配列からなる cell 配列として指定します。

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

"AlternateFileSystemRoots" の値は、次の条件を満たさなければなりません。

  • 1 行以上の行を含み、各行は 1 組の対応するルート パスを指定する。

  • 各行は複数のルート パスを指定し、各ルート パスは 2 文字以上を含まなければならない。

  • ルート パスは一意で、他のルート パスのサブフォルダーではない。

  • ファイルの場所を指す 1 つ以上のルート パス エントリを含む。

詳細については、異なるマシンまたはクラスターで処理するためのデータストアの設定を参照してください。

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

データ型: string | cell

ラベル データを提供するソース。"LabelSource" と "none" または "foldernames" のいずれかで構成される名前と値の引数として指定します。"none" を指定した場合、Labels プロパティは空になります。"foldernames" を指定した場合、フォルダー名に従ってラベルが割り当てられ、Labels プロパティに格納されます。後で Labels プロパティに直接アクセスして、ラベルを変更できます。

名前と値の引数 "LabelSource" は、ファイルまたはフォルダーの場所として FileSet オブジェクトが使用されている場合は使用できません。

データ型: char | string

これらの名前と値のペアに加えて、このページの任意のプロパティも名前と値のペアとして指定できます。ただし、Files プロパティを除きます。

プロパティ

すべて展開する

ImageDatastore プロパティはデータを記述し、データストアからデータを読み取る方法を指定します。datastore オブジェクトの作成時に、名前と値の引数を使用して ImageDatastore プロパティの値を指定できます。オブジェクトの作成後にプロパティの表示または変更を行うには、ドット表記を使用します。

たとえば、ImageDatastore オブジェクトを作成して、"ReadFcn" パラメーターを指定できます。

imds = imageDatastore("peppers.png","ReadFcn",@customreader);
あるいは、ImageDatastore の作成後に "ReadFcn" を @customreader に割り当てることができます。 
imds = imageDatastore("peppers.png");
imds.ReadFcn = @customreader;

データストアに含まれるファイル。文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として解決されます。各文字ベクトルまたは string はファイルへの絶対パスです。関数 imageDatastore および関数 datastore の location 引数は、データ ストアの作成時に Files を定義します。

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

データ型: char | cell | string

この プロパティ は読み取り専用です。

データストアの作成に使用するフォルダー。文字ベクトルの cell 配列として返されます。cell 配列は列ベクトルとして方向付けされます。各文字ベクトルは、データ ファイルを含むフォルダーへのパスです。関数 imageDatastore および関数 datastore の location 引数は、データストアの作成時に Folders を定義します。

データ型: cell

関数 read の呼び出しで読み取るイメージ ファイルの数。正の整数スカラーとして指定します。関数 read の各呼び出しで、最大 ReadSize 個のイメージを読み取ります。

データストア内のファイルのラベル。ベクトル、cell 配列または string 配列として指定します。配列内のラベルの順序は、データストア内の関連付けられたファイルの順序に対応します。ImageDatastore オブジェクトの作成時に "LabelSource","foldernames" を指定した場合、ファイルのラベル名はそのファイルを含むフォルダーの名前になります。"LabelSource","foldernames" を指定しない場合、Labels は空の cell 配列または string 配列です。データストアの作成後に Files プロパティを変更した場合、追加されたファイルを含めるように Labels プロパティが自動更新されることはありません。

データ型: categorical | cell | logical | double | single | string

イメージ データを読み取る関数。関数ハンドルとして指定します。関数はイメージ ファイル名を入力として受け取らなければならず、その後に対応するイメージ データを出力します。たとえば、customreader がイメージ データを読み取る関数として指定された場合、この関数には次のようなシグネチャがなければなりません。

function data = customreader(filename)
...
end
複数の出力引数が存在する場合、imageDatastore は最初の引数のみを使用して、残りの引数を無視します。

メモ

2 次元イメージの変換または前処理に ReadFcn を使用することは推奨されません。imformats の認識するファイル形式について、ReadFcn を指定すると imageDatastore のパフォーマンスが遅くなります。イメージの変換および前処理の効率的な方法の詳細については、イメージの深層学習向け前処理 (Deep Learning Toolbox)を参照してください。

例: @customreader

データ型: function_handle

この プロパティ は読み取り専用です。

書き込みでサポートされる形式。string の行ベクトルとして返されます。このプロパティは、writeall を使用してデータストアから出力ファイルを書き込む際に使用可能な出力形式を指定します。

この プロパティ は読み取り専用です。

既定の出力形式。string スカラーとして返されます。このプロパティは、writeall を使用してデータストアから出力ファイルを書き込む際の既定の形式を指定します。

データ型: string

オブジェクト関数

countEachLabelImageDatastore ラベル内のファイルをカウントする
hasdataデータが読み取り可能かどうかを判別
numpartitionsデータストアの区画数
partitionデータストアを分割する
previewデータストア内のデータのサブセットをプレビュー
readデータストアのデータの読み取り
readallデータストアのすべてのデータの読み取り
readimage指定されたイメージをデータストアから読み取る
writeallファイルへのデータストアの書き込み
resetデータストアの初期状態へのリセット
shuffleデータストア内のすべてのデータをシャッフルする
splitEachLabelImageDatastore のラベルを比率で分割
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\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

4 つのイメージを含む 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

2 番目と 3 番目のイメージのみを 1 つずつ読み取ります。 

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

イメージを 4 つすべて読み取り、3 番目のイメージを表示します。

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

image of vegetables

制限

  • 2 次元イメージの変換または前処理に ReadFcn を使用することは推奨されません。imformats の認識するファイル形式について、ReadFcn を指定すると imageDatastore のパフォーマンスが遅くなります。イメージの変換および前処理の効率的な方法の詳細については、イメージの深層学習向け前処理 (Deep Learning Toolbox)を参照してください。

  • MATLAB では、認証が必要なインターネット URL はサポートされていません。

  • MATLAB Online™ では Microsoft® OneDrive™ ファイルおよびフォルダーに関連付けられたインターネット URL はサポートされていますが、MATLAB のインストール バージョンではローカル OneDrive ファイルのみがサポートされています。

拡張機能

すべて展開する

バージョン履歴

R2015b で導入

すべて展開する

参考

| |

トピック