pixelLabelDatastore

ピクセル ラベル データのデータストア

説明

PixelLabelDatastore オブジェクトを使用して、セマンティック セグメンテーションのピクセル ラベル データを読み取ることができます。

PixelLabelDatastore からピクセル ラベル データを読み取るには、関数 read を使用します。この関数は、すべてのピクセル位置 (i,j) またはボクセル位置 (i,j,k) に割り当てられたカテゴリカル ラベルを含む categorical 配列を返します。

作成

ここで説明する関数 pixelLabelDatastore を使用して PixelLabelDatastore オブジェクトを作成します。オブジェクトを作成すると、データのアクセスや管理を行う関数を使用できます。ドット表記を使用して、ReadSize プロパティと ReadFcn プロパティを変更できます。

構文

pxds = pixelLabelDatastore(gTruth)

pxds = pixelLabelDatastore(location,classNames,pixelLabelIDs)

pxds = pixelLabelDatastore(___,Name=Value)

説明

pxds = pixelLabelDatastore(gTruth) は、groundTruth オブジェクトまたは groundTruth オブジェクトの配列から PixelLabelDatastore オブジェクトを作成します。

pxds = pixelLabelDatastore(location,classNames,pixelLabelIDs) は、ピクセル ラベル データが保存されているイメージ ファイルから PixelLabelDatastore オブジェクトを、location で指定されたフォルダーまたはファイルに作成します。この関数は、イメージ ピクセル ラベルの値をクラス名にマップするピクセル ID を使用してオブジェクトを作成します。

pxds = pixelLabelDatastore(___,Name=Value) は、名前と値の引数を使用して ReadSize プロパティと AlternateFileSystemRoots プロパティのいずれかまたは両方を設定し、PixelLabelDatastore オブジェクトを作成します。イメージ ファイルの入力では、名前と値のペアの引数を使用して ReadFcn プロパティを設定するか、データストアに含めるファイルに関するオプションを指定することができます。複数の名前と値のペアを指定できます。各プロパティ名を引用符で囲みます。

たとえば、pixelLabelDatastore(loc,names,ids,ReadSize=8,FileExtensions="png") は、PNG イメージのみが含まれるピクセル ラベル データストアを作成し、read 関数の呼び出しごとに 8 個のイメージを読み取ります。

入力引数

gTruth — グラウンド トゥルース データ

groundTruth オブジェクト | groundTruth オブジェクトの配列

グラウンド トゥルース データ。groundTruth オブジェクトまたは groundTruth オブジェクトの配列として指定します。各 groundTruth オブジェクトには、一連のグラウンド トゥルース ラベルのデータ ソース、ラベルの定義のリスト、およびマークされたすべてのラベルに関する情報が含まれます。

location — フォルダーまたはイメージ ファイルの名前

文字ベクトル | 文字ベクトルの cell 配列 | string 配列

フォルダーまたはイメージ ファイルの名前。文字ベクトル、string 配列、または文字ベクトルの cell 配列として指定します。イメージには uint8 データが含まれなければなりません。

location	説明
文字ベクトル、string スカラー	フォルダーの名前。指定されたフォルダーのサブフォルダー内のファイルは、自動的にはデータストアに含まれません。データストアにはサポートされているファイル形式のイメージのみが含まれ、他の形式は無視されます。関数 imformats を使用して、サポートされているファイル形式の一覧を確認します。
文字ベクトルの cell 配列、string の配列	複数のイメージのファイルの名前。

pixelLabelDatastore はファイル名を拡張し、絶対ファイル パスを Files プロパティに保存します。

location を指定する際、ワイルドカード文字 (*) を使用できます。この文字は、すべての一致するファイル、または一致するフォルダー内のすべてのファイルがデータストアに含まれることを示します。

ファイルが現在のフォルダーに存在しない場合、絶対パスまたは相対パスを含めなければなりません。

ファイルがローカルで使用できない場合、ファイルまたはフォルダーの絶対パスを hdfs://hostname:portnumber/path_to_file のような国際化リソース識別子 (IRI) にしなければなりません。Amazon S3™ および HDFS™ での datastore の使用に関する詳細については、リモート データの操作を参照してください。

例: "file1.jpg"

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

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

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

データ型: char | string

classNames — クラス名

文字ベクトルの cell 配列 | string の cell 配列

クラス名。string または文字ベクトルの cell 配列として指定します。pixelLabelDatastore は名前を cell 配列に変換し、ClassNames プロパティに名前を保存します。

例: ["sky" "grass" "building" "sidewalk"]

pixelLabelIDs — ピクセル ラベルをクラス名に関連付けるための ID

ベクトル | m 行 3 列の行列 | 列ベクトルの cell 配列 | m 行 3 列の行列の cell 配列

ピクセル ラベルを ClassNames にマップするための ID。ベクトル、m 行 3 列の行列、列ベクトルの cell 配列、または m 行 3 列の行列の cell 配列として指定します。値は [0, 255] の範囲の整数でなければなりません。m 行 3 列の行列は RGB イメージでのみサポートされています。

形式	説明
ベクトル	ベクトルの長さとクラス名の数は等しくなければなりません。値は一意でなければなりません。
m 行 3 列の行列	m は、クラス名の数に対応します。各行には、各クラス名と関連付ける RGB ピクセル値を表す 3 要素ベクトルが含まれます。ベクトルは一意でなければなりません。この形式を、RGB イメージとして保存されているピクセル ラベル データに使用します。
列ベクトルの cell 配列 m 行 3 列の行列の cell 配列	cell 配列を使用して、複数のピクセル ラベル ID を 1 つのクラス名にマップします。

名前と値の引数

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで、Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、コンマを使用して名前と値をそれぞれ区切り、Name を引用符で囲みます。

例: pixelLabelDatastore(IncludeSubfolders=true) は、すべてのファイルとサブフォルダーを各フォルダー内に含めることを指定します。

IncludeSubfolders — サブフォルダーを含める

false (既定値) | true

サブフォルダーを含める。false (0) または true (1) として指定します。すべてのファイルとサブフォルダーを各フォルダー内に含める場合は true を、ファイルのみを各フォルダー内に含める場合は false を指定します。

グラウンド トゥルース データ gTruth を指定した場合、IncludeSubfolders 引数はサポートされません。

FileExtensions — ファイルの拡張子

文字ベクトル | 文字ベクトルの cell 配列 | string スカラー | string 配列

データ ストアに含まれるファイルのファイル拡張子。文字ベクトル、文字ベクトルの cell 配列、string スカラー、または string 配列として指定します。既定では、データストアには関数 imformats によってサポートされるすべての拡張子をもつファイルが含まれます。

グラウンド トゥルース データ gTruth を指定した場合、FileExtensions 引数はサポートされません。

例: ["png" "gif" "bmp"]

プロパティ

Files — データストアに含まれるファイル

読み取り専用: 文字ベクトル | 文字ベクトルの cell 配列

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

データストアに含まれるファイル。文字ベクトル、または文字ベクトルの cell 配列として指定します。各文字ベクトルは、ファイルへの絶対パスです。PixelLabelDatastore オブジェクトを作成する場合、このプロパティを設定するには location 引数を使用します。

ClassNames — クラス名

読み取り専用: 文字ベクトルの cell 配列

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

クラス名。文字ベクトルの cell 配列を指定します。

ReadSize — イメージ ファイルの最大数

1 (既定値) | 正の整数

関数 read への各呼び出しで読み取るイメージ ファイルの最大数。正の整数として指定します。

AlternateFileSystemRoots — 代替ファイル システムのルート パス

string ベクトル | cell 配列

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

• 互いに等価なルート パスのセットを関連付けるには、"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 つ以上の行を含む。各行は等価なルート パスのセットを指定する。

• 各行は複数のルート パスを指定する。各ルート パスは少なくとも 2 文字を含まなければならない。

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

• ファイルの場所を指すルート パス エントリを少なくとも 1 つ含む。

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

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

データ型: string | cell

ReadFcn — ピクセル ラベル付きイメージ データを読み取る関数

@readDatastoreImage (既定値) | 関数ハンドル

ピクセル ラベル付きイメージ データを読み取る関数。関数ハンドルとして指定します。カスタム読み取り関数は、入力としてイメージ ファイル名を取った後、対応するピクセル ラベル付きデータを categorical 配列として出力しなければなりません。たとえば、customreader がイメージ データを読み取るために指定された関数である場合、この関数は次のようなシグネチャを持たなければなりません。

function C = customreader(filename)
...
end

読み取り関数に複数の出力引数がある場合は、最初の出力引数のみが使用されます。残りは無視されます。

グラウンド トゥルース データ gTruth を指定した場合、ReadFcn プロパティはサポートされません。

例: @customreader

オブジェクト関数

combine	複数のデータストアのデータを統合
countEachLabel	Count occurrence of pixel or box labels
hasdata	Determine if data is available to read from label datastore
numpartitions	Number of partitions for label datastore
partition	Partition label datastore
preview	Read first row of data in datastore
read	Read data from label datastore
readall	Read all data in label datastore
readimage	Read specified pixel label data file
reset	Reset label datastore to initial state
shuffle	Return shuffled version of label datastore
transform	データストアの変換
subset	データストアまたは FileSet のサブセットの作成
isPartitionable	データストアが分割可能かどうかを判別
isShuffleable	データストアがシャッフル可能かどうかを判別

例

ピクセル ラベル データの読み取りと表示

ピクセル ラベル データをイメージに重ね合わせます。

イメージとピクセル ラベル データの場所を設定します。

dataDir = fullfile(toolboxdir('vision'),'visiondata');
imDir = fullfile(dataDir,'building');
pxDir = fullfile(dataDir,'buildingPixelLabels');

イメージ データストアを作成します。

imds = imageDatastore(imDir);

ピクセル ラベル データストアを作成します。

classNames = ["sky" "grass" "building" "sidewalk"];
pixelLabelID = [1 2 3 4];
pxds = pixelLabelDatastore(pxDir,classNames,pixelLabelID);

イメージとピクセル ラベル データを読み取ります。read(pxds) は、categorical 行列 C を返します。この行列の要素 C(i,j) は、位置 l(i,j) のピクセルに割り当てられたカテゴリカル ラベルです。

I = read(imds);
C = read(pxds);

C のラベル カテゴリを表示します。

categories(C{1})

ans = 4×1 cell
    {'sky'     }
    {'grass'   }
    {'building'}
    {'sidewalk'}

ピクセル ラベル データをイメージに重ね合わせて表示します。

B = labeloverlay(I,C{1});
figure
imshow(B)

3 次元ピクセル ラベル データの読み取りと表示

3 次元ボリュームおよびピクセル ラベル データの位置を指定します。このデータは、ラベル付けされた脳の 3 次元 MRI スキャンです。

dataDir = fullfile(toolboxdir("images"),"imdata");
imDir = fullfile(dataDir,"BrainMRILabeled","images");
pxDir = fullfile(dataDir,"BrainMRILabeled","labels");

カスタム読み取り関数を指定します。この例では、MAT イメージ ファイルから 3 次元イメージ データを読み取る samplePXDSMatReader と呼ばれる関数 (この例の終わりで定義) を指定します。

matReader = @samplePXDSMatReader;

イメージ データストアを作成します。

imds = imageDatastore(imDir,"FileExtensions",".mat","ReadFcn",matReader);

ピクセル ラベル データストアを作成します。

classNames = ["edema","nonEnhancingTumor","enhancingTumour"];
pixelLabelID = [1 2 3];
pxds = pixelLabelDatastore(pxDir,classNames,pixelLabelID,"FileExtensions",".mat","ReadFcn",matReader);

ボリュームとピクセル ラベル データを読み取ります。L は categorical 行列であり、L(i,j,k) は V(i,j,k) に割り当てられたカテゴリカル ラベルです。

V = read(imds);
L = read(pxds);

ラベル カテゴリを表示します。

C = categories(L{1})

C = 3×1 cell
    {'edema'            }
    {'nonEnhancingTumor'}
    {'enhancingTumour'  }

関数 viewer3d と関数 volshow を使用して結果を可視化します。名前と値の引数 OverlayData および OverlayAlpha を指定してラベルを表示します。

viewer = viewer3d(BackgroundColor="white",BackgroundGradient="off",CameraZoom=2);

h = volshow(V,Parent=viewer, ... 
    RenderingStyle="GradientOpacity", ...
    GradientOpacityValue=0.8, ... 
    Alphamap=linspace(0,0.2,256), ...
    OverlayData=L{1}, ...
    OverlayAlpha=0.8);

この例では、イメージ ファイルから 3 次元イメージ データを読み取るための補助関数 samplePXDSMatReader を定義します。この関数は MAT ファイルを読み込んで、ファイルに保存された最初の変数を返します。

function data = samplePXDSMatReader(filename)
    inp = load(filename);
    f = fields(inp);
    data = inp.(f{1});
end

ヒント

• pixelLabelDatastore は、ファイルを辞書式順序で格納します。たとえば、"file1.jpg"、"file2.jpg"、…、"file11.jpg"、および "file12.jpg" という名前の 12 個のファイルがある場合、ファイルは次の順序で格納されます。

  "file1.jpg"
  "file10.jpg"
  "file11.jpg"
  "file12.jpg"
  "file2.jpg"
  "file3.jpg"
  ...
  "file9.jpg"

  対照的に、imageDatastore は、データストアに追加された順にファイルを格納します。グラウンド トゥルース イメージとピクセル ラベル データを同時に読み取る場合、イメージとラベルの間の不一致が発生する可能性があります。これが発生した場合は、ピクセル ラベル ファイルの名前を変更して、適切な順序になるようにします。たとえば、"file1.jpg"、…、"file9.jpg" の名前を "file01.jpg"、…、"file09.jpg" に変更します。

• ビデオ ラベラー アプリを使用して生成された groundTruth オブジェクトからセマンティック セグメンテーション データを抽出するには、関数 pixelLabelTrainingData を使用します。

バージョン履歴

R2017b で導入

参考

アプリ

• イメージ ラベラー | ビデオ ラベラー | 医用画像ラベラー (Medical Imaging Toolbox)

関数

• evaluateSemanticSegmentation | semanticseg

オブジェクト

• ImageDatastore | groundTruth | semanticSegmentationMetrics | randomPatchExtractionDatastore

トピック

• 深層学習を使用した脳腫瘍の 3 次元セグメンテーション
• 深層学習を使用したセマンティック セグメンテーション入門
• 深層学習用のデータストア (Deep Learning Toolbox)
• MATLAB による深層学習 (Deep Learning Toolbox)
• オブジェクト検出およびセマンティック セグメンテーション用の学習データ