groundTruthDataSource

Object for storing ground truth data sources

Description

The groundTruthDataSource object defines the source of ground truth data. Use this object to specify a data source for the groundTruth object. To label the data source, load the groundTruthDataSource object into a labeling app.

• The Image Labeler supports data sources for collections of images.

• The Video Labeler supports data sources for videos and image sequences. This app also supports custom data sources.

Creation

Syntax

gtSource = groundTruthDataSource(imds)

gtSource = groundTruthDataSource(imageFiles)

gtSource = groundTruthDataSource(videoName)

gtSource = groundTruthDataSource(imageSeqFolder)

gtSource = groundTruthDataSource(imageSeqFolder,timestamps)

gtSource = groundTruthDataSource(sourceName,readerFcn,timestamps)

Description

Image Datastore Source

gtSource = groundTruthDataSource(imds) returns a ground truth data source object for an imageDatastore specified by imds.

Collection of Images Source

gtSource = groundTruthDataSource(imageFiles) returns a ground truth data source object for a collection of images specified by imageFiles. Images must be in a file format readable by imread.

Video File Source

gtSource = groundTruthDataSource(videoName) returns a ground truth data source object for a video file specified by videoName. Videos must be in a file format readable by VideoReader.

Video as a Sequence of Images Source

gtSource = groundTruthDataSource(imageSeqFolder) returns a ground truth data source object for an image sequence located in the folder specified by imageSeqFolder.

gtSource = groundTruthDataSource(imageSeqFolder,timestamps) returns a ground truth data source object for an image sequence with a corresponding timestamp for each image contained in the specified folder. timestamps sets the TimeStamps property.

Custom Data Source

gtSource = groundTruthDataSource(sourceName,readerFcn,timestamps) returns a ground truth data source object by using the custom reader function handle, readerFcn. sourceName sets the Source property and timestamps set the TimeStamps property. The custom reader function loads an image from sourceName that corresponds to the current timestamp specified in the duration vector timestamps.

Input Arguments

imds — Image datastore

imagedatastore object

Image datastore, specified as an imageDatastore object.

imageFiles — Image file names

string array | cell array of character vectors

Image file names, specified as a string array or a cell array of character vectors. Images must be in a file format readable by imread. For a list of the supported image file formats, see imformats.

videoName — Name of video file

string scalar | character vector

Name of video file, specified as a string scalar or character vector. Videos must be in a file format readable by VideoReader. For a list of the supported video file formats, see VideoReader.getFileFormats. If your video format is not supported, specify a custom reader function, readerFcn.

imageSeqFolder — Image sequence folder

string scalar | character vector

Image sequence folder, specified as a string scalar or a character vector. The image files name extensions must be supported by imformats. If your video format is not supported, specify a custom reader function, readerFcn.

The images are loaded in the order returned by the dir command.

readerFcn — Custom reader function

function handle

Custom reader function, specified as a function handle. The custom reader function must load an image from a source at a specified timestamp by using this syntax:

outputImage = readerFcn(sourceName,currentTimestamp)

• readerFcn is the name of your custom reader function.

• sourceName is the name of the data source.

• currentTimestamp is the current timestamp, as specified by the input vector timestamp.

The outputImage returned by the custom function must be a grayscale or RGB image in any format supported by imshow. For more information, see Use Custom Image Source Reader for Labeling.

Properties

TimeStamps — Timestamps of video or image sequence

Read-only: duration vector

This property is read-only.

Timestamps of video or image sequence, specified as a duration vector.

• For a video file, Timestamps is automatically populated with the timestamps that are present for the video frames.

• For an image sequence or custom reader, Timestamps is populated with the values in the input duration vector timestamps.

• For an image collection, the TimeStamps property remains empty.

.

Source — Source of ground truth data

Read-only: character vector | cell array of character vectors

This property is read-only.

Source of ground truth data, specified as a character vector or cell array of character vectors. The source name can refer to image file names, a video file name, image sequence file names, or custom data source names.

Examples

Create Data Source from Image Datastore

Load image collection file names.

imageDir = fullfile(matlabroot,'toolbox','vision','visiondata','bookCovers');
imds = imageDatastore(imageDir);

Create a data source from an image datastore.

dataSource = groundTruthDataSource(imds);

Read and display an image from the datastore.

I = read(dataSource.Source);
figure,imshow(I)

Create a Ground Truth Data Source from a Video File

Use the groundTruthDataSource object to create a data source.

Read a video file and create a data source.

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

dataSource = 
groundTruthDataSource for a video file with properties

        Source: ...tlab/toolbox/vision/visiondata/vipunmarkedroad.avi
    TimeStamps: [84×1 duration]

Create a VideoReader to read the video frames.

reader = VideoReader(videoName);

Read the 5th frame in the video and display

 timeStamp = seconds(dataSource.TimeStamps(5));
 reader.CurrentTime = timeStamp;
 I = readFrame(reader);
 
 figure
 imshow(I)

Create Data Source from Image Sequence

Create a ground truth data source from an image sequence stored in a specified folder.

Specify the folder containing a sequence of images.

imageDir = fullfile(matlabroot,'toolbox','vision',...
        'visiondata','building');

Create a data source for the images that are in the imageDir folder.

    dataSource = groundTruthDataSource(imageDir)

dataSource = 
groundTruthDataSource for a video as an image sequence with properties

                      Source: {
                              ' .../runnable/matlab/toolbox/vision/visiondata/building/building1.JPG';
                              ' .../runnable/matlab/toolbox/vision/visiondata/building/building2.JPG';
                              ' .../runnable/matlab/toolbox/vision/visiondata/building/building3.JPG'
                               ... and 2 more
                              }
                  TimeStamps: [5×1 duration]

Read the 5th frame in the sequence.

    I = imread(dataSource.Source{5});
    figure
    imshow(I)

Create Data Source Using Custom Reader

Create a ground truth data source by using a custom reader function.

Specify an image folder containing a sequence of road images.

imgFolder = fullfile(matlabroot,'toolbox','vision','visiondata','building');

Use an image datastore as the custom data source.

imgDataStore = imageDatastore(imgFolder);

Write a reader function, readerFcn, to read images from the datastore. The first input argument, sourceName, is not used. The second input argument, currentTimestamp, is the current timestamp. The function converts currentTimestamp from a duration scalar to a 1-based index suitable for reading images from the datastore.

readerFcn = @(~,idx)readimage(imgDataStore,seconds(idx));

Create a data source for the images in the image folder by using the custom reader function.

dataSource = groundTruthDataSource(imgFolder,readerFcn,1:5)

dataSource = 
groundTruthDataSource for a custom data source with properties

        Source: ...runnable/matlab/toolbox/vision/visiondata/building
    TimeStamps: [5×1 duration]

Read the fifth frame in the sequence.

I = readerFcn(imgFolder,seconds(5));
figure
imshow(I)

Tips

• groundTruth objects for video-based groundTruthDataSource objects rely on the video reading capabilities of your operating system. A groundTruth object created using a video data source remains consistent only for the same platform that was used to create it. To create a platform-specific groundTruth object, convert the video into a sequence of images.

Version History

Introduced in R2017a