Main Content


Read data from label datastore


C = read(ds) returns data from a pixel label datastore or box label datastore. Subsequent calls to the read function continue reading from the endpoint of the previous call.

[C,info] = read(ds) also returns information about the extracted data in info, including metadata.

Input Arguments

collapse all

Input datastore, specified as a PixelLabelDatastore or a boxLabelDatastore object.

Output Arguments

collapse all

Output data, returned as an M-by-2 cell array, cell array of categorical matrices, or a table.

DatastoreOutput Description
PixelLabelDatastoreTable with MiniBatchSize number of rows. For the last batch of data in the datastore, numObservations must be divisible by MiniBatchSize or read returns a partial batch containing all the remaining observations in the datastore.

N-by-2 or N-by-3 cell matrix. N must be less than or equal to ReadSize(ds).

The first column can contain data, such as point cloud data for point cloud detectors, or images for object detectors.

The second column must be a cell vector that contains M-by-5 matrices of bounding boxes in the format[xcenter,ycenter,width,height,yaw].

The third column must be a cell vector that contains the label names corresponding to each bounding box. Label names are represented as an M-by-1 categorical vector.

You can use the combine function to create a datastore to use for training.

For more information, see Datastores for Deep Learning (Deep Learning Toolbox).

Information about read data, returned as a structure array. The structure array can contain the following fields.

DatastoreField NameDescription
PixelLabelDatastoreFilenameFully resolved path containing the path string, name of the file, and file extension. For PixelLabelDatastore objects whose ReadSize property is greater than 1, Filename is a cell array of file names corresponding to each image.

Total file size, in bytes. For MAT-files, FileSize is the total number of key-value pairs in the file. For PixelLabelDatastore objects whose ReadSize property is greater than 1, FileSize is a vector of file sizes corresponding to each image.

boxLabelDatastoreCurrentIndexStarting position of each read operation of the label data.
ReadSizeReadSize property of the datastore.


  • read(ds) returns an error if there is no more data in the input datastore, ds. Use hasdata(ds) with read(ds) to avoid the error.

Version History

Introduced in R2017b