groundTruth

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

説明

groundTruth オブジェクトには、一連のグラウンド トゥルース ラベルのデータ ソース、ラベル定義、およびマークされたラベルの注釈に関する情報が含まれます。groundTruth オブジェクトは、イメージ ラベラー アプリおよびビデオ ラベラー アプリからエクスポートまたはインポートできます。groundTruth オブジェクトに保存されているデータの概要については、Elements of Ground Truth Objectsを参照してください。

• groundTruth オブジェクトの配列からオブジェクト検出器の学習データを作成するには、関数 objectDetectorTrainingData を使用します。

• groundTruth オブジェクトの配列からセマンティック セグメンテーション ネットワークの学習データを作成するには、関数 pixelLabelTrainingData を使用します。

作成

ラベル付けアプリから groundTruth オブジェクトをエクスポートするには、アプリのツールストリップで、[ラベルをエクスポート] 、 [ワークスペースへ] を選択します。アプリがオブジェクトを MATLAB^® ワークスペースにエクスポートします。プログラムで groundTruth オブジェクトを作成するには、関数 groundTruth を使用します (ここで説明します)。

構文

gTruth = groundTruth(dataSource,labelDefs,labelData)

説明

gTruth = groundTruth(dataSource,labelDefs,labelData) は、イメージ ラベラー アプリおよびビデオ ラベラー アプリにインポートできるグラウンド トゥルース ラベルを含むオブジェクトを返します。

• dataSource では、グラウンド トゥルース データのソースを指定し、DataSource プロパティを設定します。

• labelDefs では、グラウンド トゥルース データのラベル、サブラベル、および属性の定義を指定し、LabelDefinitions プロパティを設定します。

• labelData では、マークされたラベルの識別情報、位置、およびタイムスタンプを指定し、LabelData プロパティを設定します。

プロパティ

DataSource — グラウンド トゥルース データのソース

groundTruthDataSource オブジェクト

グラウンド トゥルース データのソース。groundTruthDataSource オブジェクトとして指定します。オブジェクトには、ビデオ、イメージ シーケンス、またはグラウンドトゥルース データがラベル付けされたカスタムのデータ ソースを記述する情報が含まれます。

元のデータ ソースからイメージにアクセスするには、VideoReader または imageDatastore を使用します。また、カスタム読み取り関数を使用することもできます。詳細については、ラベル付けでのカスタム イメージ ソース リーダーの使用を参照してください。

LabelDefinitions — ラベルの定義

table

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

ラベルの定義。table として指定します。このテーブルを作成するには、次のいずれかの方法を使用します。

• ラベル付けアプリのいずれかにおいてラベル定義を作成し、それを groundTruth オブジェクトの一部としてエクスポートします。

• labelDefinitionCreator オブジェクトを使用して、ラベル定義テーブルを生成します。このテーブルを MAT ファイルに保存すると、ラベル定義をラベル付けアプリのセッションに読み込めます。アプリのツールストリップで、[読み込み] 、 [ラベルの定義] を選択してください。

• ラベル定義テーブルを MATLAB コマンド ラインで作成します。

次の表に、LabelDefinitions プロパティに指定するテーブルの必須およびオプションの列を示します。

列	説明	必須またはオプション
Name	各ラベル定義の名前を指定する文字列または文字ベクトル。	必須
Type	各ラベル定義のタイプを指定する labelType 列挙。Rectangle、Scene など。	必須
LabelColor	ラベル定義の色を指定する RGB 3 成分の 1 行 3 列の行ベクトル。値は [0, 1] の範囲内です。黄色 (RGB 3 成分 [1 1 0]) は、ラベル付けアプリにおける選択ラベルの色として予約されています。	オプション ラベル付けアプリでラベルを定義する場合、色を指定しなければなりません。そのため、エクスポートされるラベル定義テーブルには必ずこの列が含まれます。 labelDefinitionCreator オブジェクトを使用して、色を指定せずにラベル定義を作成する場合、返されるラベル定義テーブルにはこの列が含まれますが、列の値はすべて空です。
PixelLabelID	スカラー、列ベクトル、または整数値ラベル ID の M 行 3 列の行列。PixelLabelID は、ラベル定義を表すために使用されるピクセル ラベル値を指定します。ピクセル ラベル ID の値は 0 ～ 255 の範囲でなければなりません。	オプション ラベル付けアプリまたは labelDefinitionCreator オブジェクトでピクセル ラベルを定義する場合、生成されるラベル定義テーブルにはこの列が含まれます。 ラベル定義テーブルを MATLAB コマンド ラインで作成するときに、いずれかのラベルの Type を labelType.PixelLabel に設定した場合、この列は必須になります。
Group	各ラベル定義が属するグループを指定する文字列または文字ベクトル。	オプション ラベル定義テーブルを MATLAB コマンド ラインで作成する場合、Group 列を含める必要はありません。 ラベル付けアプリからラベル定義をエクスポートする場合や、labelDefinitionCreator オブジェクトを使用してラベル定義を作成する場合、グループを指定していなくても、ラベル定義テーブルにはこの列が含まれます。アプリは各ラベル定義の Group の値として 'None' を割り当てます。
Description	各ラベル定義について説明する文字列または文字ベクトル。	オプション ラベル定義テーブルを MATLAB コマンド ラインで作成する場合、Description 列を含める必要はありません。 ラベル付けアプリからラベル定義をエクスポートする場合や、labelDefinitionCreator オブジェクトを使用してラベル定義を作成する場合、説明を指定していなくても、ラベル定義テーブルにはこの列が含まれます。こうしたラベル定義の Description は空の文字ベクトルになります。
Hierarchy	各ラベル定義のサブラベルと属性データを含む構造体。Hierarchy の形式の例については、イメージ ラベラー入門またはビデオ ラベラー入門を参照してください。	オプション ラベル付けアプリでサブラベルまたは属性を定義する場合、エクスポートされる groundTruth オブジェクトにはこの列が含まれます。

たとえば、Sky、Vegetation、Lanes、StopSign、および Vehicle という名前のラベル定義をもつテーブルについて考えます。これがビデオ ラベラー アプリからエクスポートされたものとします。

• ラベル定義にはピクセル ラベルが含まれているため、テーブルには PixelLabelID 列があります。

• ラベルのうち 2 つに属性があるため、アプリは Hierarchy 列を作成しました。これがすべてのラベル定義に適用されています。

• ラベル定義にはグループが割り当てられていないため、すべてのラベル定義の Group 列が 'None' になっています。

メモ

ラベラー アプリは、ピクセル ID が 1 ～ 255 のピクセル データのみを読み込むことができます。

LabelData — 各 ROI とシーン ラベルのラベル データ

table | timetable

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

各 ROI とシーン ラベルのラベル データ。イメージ コレクションの場合は table、ビデオまたはイメージ シーケンスの場合は timetable として指定します。LabelData の各列が 1 つのラベル定義のラベルを保持し、LabelDefinitions の各行の Name の値に対応します。これらの LabelData はテーブルの要素を表します。ラベル カテゴリは labelType 列挙として指定されます。

または、ラベル タイプごとにグループ化された ROI ラベル データの場合、ROILabelData というラベルの付いた単一の列を使用して、RectangleData、PolygonData、LineData、ProjCuboidData のうち少なくとも 1 つのラベル タイプを含む構造体として指定できます。

各ラベル タイプのストレージ形式を表に示します。

ラベル タイプ	各タイムスタンプでのラベルのストレージ形式
labelType.Rectangle	[x, y, w, h] 形式の M 行 4 列の数値行列。ここで、 M は、フレームに含まれるラベルの数です。 x と y は四角形の左上隅を指定します。 w は四角形の幅、つまり x 軸に沿った長さを指定します。 h は四角形の高さ、つまり y 軸に沿った長さを指定します。
labelType.RotatedRectangle	1 つ以上の回転した四角形の場合、空間座標で M 行 5 列の数値行列として指定します。ここで、各行は [xctr yctr w h yaw] 形式の回転した四角形を指定します。 M は回転した四角形の数です。 xctr および yctr は四角形の中心を指定します。 w は四角形の幅、つまり、回転前の x 軸に沿った長さを指定します。 h は四角形の高さ、つまり、回転前の y 軸に沿った長さを指定します。 yaw は回転角度 (度単位) を指定します。回転は四角形の中心を軸として時計回りに正となります。
labelType.Cuboid	[xctr, yctr, zctr, xlen, ylen, zlen, xrot, yrot, zrot] 形式の行をもつ M 行 9 列の数値行列。ここで、 M は、フレームに含まれるラベルの数です。 xctr、yctr、および zctr は直方体の中心を指定します。 xlen、ylen、および zlen はそれぞれ、回転の適用前における x 軸、y 軸、および z 軸に沿った直方体の長さを指定します。 xrot、yrot、および zrot はそれぞれ、x 軸、y 軸、および z 軸に沿った直方体の回転角度を指定します。これらの角度は、それぞれが対応する軸の正方向を見たときに、時計回りが正となります。 次の図は、これらの値で直方体の位置がどのように決定されるかを示しています。
labelType.ProjectedCuboid	[x1, y1, w1, h1, x2, y2, w2, h2] 形式の M 行 8 列の数値ベクトル。ここで、 M は、フレームに含まれるラベルの数です。 x1, y1 は、投影された直方体の前面の左上の位置の x,y 座標を指定します。 w1 は、投影された直方体の前面の幅を指定します。 h1 は、投影された直方体の前面の高さを指定します。 x2, y2 は、投影された直方体の背面の左上の位置の x,y 座標を指定します。 w2 は、投影された直方体の背面の幅を指定します。 h2 は、投影された直方体の背面の高さを指定します。 次の図は、これらの値で直方体の位置がどのように決定されるかを示しています。
labelType.Line	cell 配列の M 行 1 列のベクトル。ここで、M は、フレームに含まれるラベルの数です。各 cell 配列に、ポリラインの N 個の点に関する [x1 y1; x2 y2; ... ; xN yN] 形式の N 行 2 列の数値行列が含まれています。
labelType.PixelLabel	すべてのピクセル ラベル定義のラベル データは、M 個のイメージまたはフレームについて、M 行 1 列の単一の PixelLabelData 列に格納されます。各要素には、ピクセル ラベル イメージのファイル名が含まれます。ピクセル ラベル イメージは、対応するイメージに含まれる 1 つ以上のラベルを表します。ラベルは、1 チャネルまたは 3 チャネルのラベル行列で表すことができます。ラベラー アプリのいずれかで PixelLabelData を使用するには、値が uint8 型である単一チャネルのラベル行列を使用しなければなりません。3 チャネルのピクセル ラベル データ行列をプログラムで単一チャネルのラベル行列に変換して、ラベラー アプリで使用できます。
labelType.Polygon	cell 配列の M 行 1 列のベクトル。ここで、M はラベルの数です。各 cell 配列には、多角形の N 個の点に関する [x1 y1; x2 y2; ... ; xN yN] 形式の N 行 2 列の数値行列が含まれます。
labelType.Custom	ラベルは、timetable で指定されているとおりに正確に保存されます。カスタム ラベル データを含む groundTruthMultisignal オブジェクトをグラウンド トゥルース ラベラー アプリにインポートする場合、このデータはアプリにインポートされません。学習用のラベル データを収集し、アプリでラベル付けされたデータと組み合わせる場合は、カスタム データを使用します。
labelType.Scene	logical として保存されます。

ネイティブでサポートされている ROI または Scene ラベル カテゴリのいずれにも含まれていないグラウンド トゥルース データを groundTruth オブジェクトに追加するには、Custom の labelType を使用するラベル定義を指定しなければなりません。カスタム データは、ラベル付けアプリに読み込むときに表示されません。

オブジェクト関数

selectLabelsByGroup	Select ground truth labels by label group
selectLabelsByType	Select ground truth labels by label type
selectLabelsByName	Select ground truth labels by label name
changeFilePaths	Change file paths in ground truth data
gatherLabelData	Gather label data from ground truth
merge	Merge two or more ground truth objects

例

一時停止標識と自動車のグラウンド トゥルースの作成

イメージのコレクションからデータ ソースを作成します。

data = load('stopSignsAndCars.mat');
imageFilenames = data.stopSignsAndCars.imageFilename(1:2)

imageFilenames = 2x1 cell
    {'stopSignImages/image001.jpg'}
    {'stopSignImages/image002.jpg'}

imageFilenames = fullfile(toolboxdir('vision'),'visiondata',imageFilenames);
dataSource = groundTruthDataSource(imageFilenames);

グラウンド トゥルースを指定するために使用されるラベルを定義します。ラベル定義の table を作成するには、labelDefinitionCreatorを使用します。

ldc = labelDefinitionCreator();
addLabel(ldc,'stopSign',labelType.Rectangle);
addLabel(ldc,'carRear',labelType.Rectangle);
labelDefs = create(ldc)

labelDefs=2×5 table
        Name          Type       LabelColor     Group      Description
    ____________    _________    __________    ________    ___________

    {'stopSign'}    Rectangle    {0x0 char}    {'None'}       {' '}   
    {'carRear' }    Rectangle    {0x0 char}    {'None'}       {' '}   

四角形 ROI のラベル データを初期化します。

stopSignTruth = {[856   318    39    41];[445   523    52    54]};
carRearTruth = {[398   378   315   210];[332   633   691   287]};

ラベル データの table を構築します。

labelNames = {'stopSign';'carRear'};
labelData = table(stopSignTruth,carRearTruth,'VariableNames',labelNames)

labelData=2×2 table
        stopSign               carRear      
    _________________    ___________________

    {[856 318 39 41]}    {[398 378 315 210]}
    {[445 523 52 54]}    {[332 633 691 287]}

グラウンド トゥルース オブジェクトを作成します。

gTruth = groundTruth(dataSource,labelDefs,labelData)

gTruth = 
  groundTruth with properties:

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [2x5 table]
           LabelData: [2x2 table]

道路の車線のグラウンド トゥルース データの作成

マークした車線を表すデータを格納する groundTruth オブジェクトを作成します。

イメージからデータ ソースを作成します。

dataSource = groundTruthDataSource({'stopSignTest.jpg'});

グラウンド トゥルースを指定するために使用されるラベルを定義します。ラベル定義の table を作成するには、labelDefinitionCreatorを使用します。

ldc = labelDefinitionCreator();
addLabel(ldc,'Lane',labelType.Line);
labelDefs = create(ldc);

イメージに 2 つの車線マーカーを割り当てます。

laneMarkerTruth = {[257 254;311 180] [327 183;338 205;374 250]};

ラベル データの table を構築します。

labelNames = {'Lane'};
labelData = table(laneMarkerTruth,'VariableNames',labelNames)

labelData=table
                Lane            
    ____________________________

    {2x2 double}    {3x2 double}

groundTruth オブジェクトを作成します。

gTruth = groundTruth(dataSource,labelDefs,labelData)

gTruth = 
  groundTruth with properties:

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [1x5 table]
           LabelData: [1x1 table]

ピクセル ラベル用のグラウンド トゥルース データの作成

シーンの各部分を表すデータを格納する groundTruth オブジェクトを作成します。

データ ソースを作成します。

dataSource = groundTruthDataSource({'visionteam.jpg'});

ラベル定義の table を作成するには、labelDefinitionCreatorを使用します。ラベル 'Person' と 'Background' を定義します。対応するラベルのタイプを PixelLabel として割り当てます。

ldc =labelDefinitionCreator();
addLabel(ldc,'Person',labelType.PixelLabel);
addLabel(ldc,'Background',labelType.PixelLabel);
labelDefs = create(ldc)             

labelDefs=2×6 table
         Name            Type       LabelColor    PixelLabelID     Group      Description
    ______________    __________    __________    ____________    ________    ___________

    {'Person'    }    PixelLabel    {0x0 char}       {[1]}        {'None'}       {' '}   
    {'Background'}    PixelLabel    {0x0 char}       {[2]}        {'None'}       {' '}   

イメージのピクセル ラベル データの位置を指定します。

dataFile = {'visionteamPixelLabels.png'}    

dataFile = 1x1 cell array
    {'visionteamPixelLabels.png'}

ピクセル ラベル データ用のラベル データの table を作成します。

labelData = table(dataFile,'VariableNames',{'PixelLabelData'})

labelData=table
           PixelLabelData        
    _____________________________

    {'visionteamPixelLabels.png'}

groundTruth オブジェクトを作成します。

gTruth = groundTruth(dataSource,labelDefs,labelData)

gTruth = 
  groundTruth with properties:

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [2x6 table]
           LabelData: [1x1 table]

自動車と車線マーカーのグラウンド トゥルースの作成

ビデオからデータ ソースを作成します。

videoName = 'caltech_cordova1.avi';
dataSource = groundTruthDataSource(videoName);

グラウンド トゥルースを指定するために使用されるラベルを定義します。ラベル定義の table を作成するには、labelDefinitionCreator オブジェクトを使用します。

ldc = labelDefinitionCreator();
addLabel(ldc,'Cars',labelType.Rectangle);
addLabel(ldc,'LaneMarkers',labelType.Line);
labelDefs = create(ldc)

labelDefs=2×5 table
         Name            Type       LabelColor     Group      Description
    _______________    _________    __________    ________    ___________

    {'Cars'       }    Rectangle    {0x0 char}    {'None'}       {' '}   
    {'LaneMarkers'}    Line         {0x0 char}    {'None'}       {' '}   

自動車と車線マーカーのラベル データを作成します。

numRows = numel(dataSource.TimeStamps);
carsTruth = cell(numRows,1);
laneMarkerTruth = cell(numRows,1);

2 つの自動車ラベルと 2 つの車線マーカーを最初のフレームに追加します。

carsTruth{1} = [182 186 31 22;404 191 53 34];
laneMarkerTruth{1} = {[257 254;311 180] [327 183;338 205;374 250]};

ラベル データの table を作成します。

labelNames = {'Cars','LaneMarkers'};
labelData = table(carsTruth,laneMarkerTruth,'VariableNames',labelNames);

groundTruth オブジェクトを作成します。このオブジェクトをラベル付けアプリにインポートするには、[開く]、[ラベルをインポート] メニューのオプションを選択します。

gTruth = groundTruth(dataSource,labelDefs,labelData)

gTruth = 
  groundTruth with properties:

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [2x5 table]
           LabelData: [250x2 timetable]

ヒント

• ビデオベースのデータ ソースの groundTruth オブジェクトは、オペレーティング システムのビデオ読み取り機能に依存します。ビデオ データ ソースを使用して作成された groundTruth オブジェクトは、そのオブジェクトを作成するために使用された同じプラットフォームでのみ整合性を維持します。プラットフォーム固有の groundTruth オブジェクトを作成するには、ビデオをイメージのシーケンスに変換し、関連付けられたタイムスタンプをイメージのシーケンスに含めます。

バージョン履歴

R2017a で導入

参考

アプリ

• イメージ ラベラー | ビデオ ラベラー

関数

• pixelLabelTrainingData | objectDetectorTrainingData | pixelLabelDatastore | groundTruthToOpenLabel

オブジェクト

• labelDefinitionCreator | groundTruthDataSource | labelType | attributeType

トピック

• Elements of Ground Truth Objects
• イメージ ラベラー入門
• ビデオ ラベラー入門
• ラベル付けでのカスタム イメージ ソース リーダーの使用
• ラベル付きのグラウンド トゥルース データの共有と保存
• ラベラー アプリにおけるエクスポートしたピクセル ラベルの保存方法