Main Content

read

Read data from a datastore

Description

C = read(ds) returns data from a pixel label, pixel image label, 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, pixelLabelImageDatastore, 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.
PixelLabelImageDatastore
boxLabelDatastore

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.

  • imageDatastore — Create a datastore containing images.

  • PixelLabelDatastore — Create a datastore containing pixel data.

  • boxLabelDatastore — Create a datastore containing bounding boxes and labels.

  • combine(imds,blds) — Combine images, bounding boxes, and labels into one datastore.

  • combine(pxds,blds) — Combine pixel data, bounding boxes, and labels into one datastore.

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.
FileSize

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.

PixelLabelImageDatastoreImageFilenameFully resolved path containing the path string, name of the image file, and file extension.
PixelLabelFilenameFully resolved path containing the path string, name of the pixel label file, and file extension.
boxLabelDatastoreCurrentIndexStarting position of each read operation of the label data.
ReadSizeReadSize property of the datastore.

Tips

  • 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