read

Read data from a datastore

Syntax

C = read(ds)

[C,info] = read(ds)

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

ds — Input datastore

PixelLabelDatastore object | PixelImageLabelDatastore object | boxLabelDatastore object

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

Output Arguments

C — Output data

cell array of categorical matrices | M-by-2 cell array | table

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

Datastore	Output Description
PixelLabelDatastore	Table 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).

info — Information about read data

structure array

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

Datastore	Field Name	Description
PixelLabelDatastore	Filename	Fully 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.
PixelLabelImageDatastore	ImageFilename	Fully resolved path containing the path string, name of the image file, and file extension.
	PixelLabelFilename	Fully resolved path containing the path string, name of the pixel label file, and file extension.
boxLabelDatastore	CurrentIndex	Starting position of each read operation of the label data.
	ReadSize	ReadSize 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.