ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

imageDatastore

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

説明

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

作成

説明

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

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

入力引数

すべて展開する

データ ストアに含めるファイルまたはフォルダー。パスまたは DsFileSet オブジェクトとして指定します。

  • パス — ローカルやリモートのファイルまたはフォルダーの場所を含む文字ベクトル、文字ベクトルの cell 配列、string スカラー、または string 配列としてパスを指定します。

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

    • リモートのファイルまたはフォルダー — locationhdfs:///path_to_file の形式の国際化リソース識別子 (IRI) として、ファイルまたはフォルダーの絶対パスに指定します。詳細については、リモート データの操作を参照してください。

  • DsFileSet オブジェクト — locationDsFileSet オブジェクトとして指定することもできます。詳細については、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' と、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 プロパティに直接アクセスして、ラベルを変更できます。

データ型: 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 および関数 datastorelocation 引数は、データ ストアの作成時に Files を定義します。

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

データ型: char | cell | string

関数 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

オブジェクト関数

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

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

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

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

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

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

制限

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

代替方法

関数 datastore を使用して、ImageDatastore オブジェクトを作成することもできます。たとえば、ds = datastore(location,'Type','image') は、location で指定されたファイルの集合からデータ ストアを作成します。

R2015b で導入