Main Content

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 個のイメージを読み取ります。

入力引数

すべて展開する

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

フォルダーまたはイメージ ファイルの名前。文字ベクトル、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

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

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

ピクセル ラベルを 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 を引用符で囲みます。

例: "IncludeSubfolders",true

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

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

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

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

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

プロパティ

すべて展開する

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

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

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

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

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

代替ファイル システムのルート パス。"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

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

function C = customreader(filename)
...
end
読み取り関数に複数の出力引数がある場合は、最初の出力引数のみが使用されます。残りは無視されます。

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

例: @customreader

オブジェクト関数

combine複数のデータストアのデータを統合
countEachLabelCount occurrence of pixel or box labels
hasdataDetermine if data is available to read from label datastore
numpartitionsNumber of partitions for label datastore
partitionPartition label datastore
previewRead first row of data in datastore
readRead data from label datastore
readallRead all data in label datastore
readimageRead specified pixel label data file
resetReset label datastore to initial state
shuffleReturn 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 = 4x1 cell
    {'sky'     }
    {'grass'   }
    {'building'}
    {'sidewalk'}

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

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

ライブ スクリプトを開く

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'  }

nonEnhancingTumor ラベルを可視化するために選択します。

showLabels = strcmp(C',"nonEnhancingTumor");

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

viewer = viewer3d(BackgroundColor="white",BackgroundGradient="off",CameraZoom=1.2);
h = volshow(V,OverlayData=L{1},Parent=viewer, ... 
    RenderingStyle="GradientOpacity",GradientOpacityValue=0.8, ... 
    Alphamap=linspace(0,0.2,256),OverlayAlphamap=[0 showLabels]);

この例では、イメージ ファイルから 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 で導入

参考

アプリ

関数

オブジェクト

トピック