boxLabelDatastore

R2026b

Datastore for bounding box label data

Description

The boxLabelDatastore object creates a datastore for bounding box label data. Use this object to read labeled bounding box data for object detection.

To read bounding box label data from a boxLabelDatastore object, use the read function. You can create a datastore that combines the boxLabelDatastore object with a point cloud datastore using the combine object function. Use the combined datastore to train 3-D object detectors using training functions such as trainPointPillarsObjectDetector. For more information, see pointCloudObjectDetectorTrainingData. To modify the ReadSize property, you can use dot notation.

Creation

Syntax

blds = boxLabelDatastore(tbl1,...,tbln)

blds = boxLabelDatastore(tbl1,...,tbln,bSet)

Description

blds = boxLabelDatastore(tbl1,...,tbln) creates a boxLabelDatastore object from one or more tables containing labeled bounding box data.

blds = boxLabelDatastore(tbl1,...,tbln,bSet) creates a boxLabelDatastore object for block-based labeled bounding box data. The blocks have resolution level, block size, and block positions specified by the block locations in bSet.

Input Arguments

tbl1,...,tbln — Labeled bounding box data (as separate arguments)

table with one or more columns

Labeled bounding box data, specified as a table with one or more columns. Each table corresponds to a set of labels. The bounding boxes can be axis-aligned rectangles, rotated rectangles, or cuboids. The table below describes the format of the bounding boxes.

Bounding Box	Description
Axis-aligned rectangle	Defined in spatial coordinates as an M-by-4 numeric matrix with rows of the form [x y w h], where: M is the number of axis-aligned rectangles. x and y specify the upper-left corner of the rectangle. w specifies the width of the rectangle, which is its length along the x-axis. h specifies the height of the rectangle, which is its length along the y-axis.
Rotated rectangle	Defined in spatial coordinates as an M-by-5 numeric matrix with rows of the form [xctr yctr xlen ylen yaw], where: M is the number of rotated rectangles. xctr and yctr specify the center of the rectangle. xlen specifies the width of the rectangle, which is its length along the x-axis before rotation. ylen specifies the height of the rectangle, which is its length along the y-axis before rotation. yaw specifies the rotation angle in degrees. The rotation is clockwise-positive around the center of the bounding box.
Cuboid	Defined in spatial coordinates as an M-by-9 numeric matrix with rows of the form [xctr yctr zctr xlen ylen zlen xrot yrot zrot], where: M is the number of cuboids. xctr, yctr, and zctr specify the center of the cuboid. xlen, ylen, and zlen specify the length of the cuboid along the x-axis, y-axis, and z-axis, respectively, before rotation. xrot, yrot, and zrot specify the rotation angles of the cuboid around the x-axis, y-axis, and z-axis, respectively. The xrot, yrot, and zrot rotation angles are in degrees about the cuboid center. Each rotation is clockwise-positive with respect to the positive direction of the associated spatial axis. The function computes rotation matrices assuming ZYX order Euler angles [xrot yrot zrot]. The figure shows how these values determine the position of a cuboid.
Projected Cuboid	M-by-8 vector of the form [x1, y1, w1, h1, x2, y2, w2, h2], where: M is the number of labels in the frame. x1, y1 specifies the x,y coordinates for the upper-left location of the front-face of the projected cuboid w1 specifies the width for the front-face of the projected cuboid. h1 specifies the height for the front-face of the projected cuboid. x2, y2 specifies the x,y coordinates for the upper-left location of the back-face of the projected cuboid. w2 specifies the width for the back-face of the projected cuboid. h2 specifies the height for the back-face of the projected cuboid. The figure shows how these values determine the position of a cuboid.

• A table with one or more columns:

  All columns contain bounding boxes. Each column must be a cell vector containing M-by-N matrices. M is the number of images and N represents a single object class, such as stopSign, carRear, or carFront.

  

• A table with two columns.

  The first column contains bounding boxes. The second column must be a cell vector that contains the label names corresponding to each bounding box. Each element in the cell vector must be an M-by-1 categorical or string vector, where M represents the number of labels.

  

To create a ground truth table, use the Image Labeler (Computer Vision Toolbox) or Video Labeler (Computer Vision Toolbox) app. To create a table of training data from the generated ground truth, use the objectDetectorTrainingData (Computer Vision Toolbox) function.

Data Types: table

bSet — Block locations

blockLocationSet object

Block locations, specified as a blockLocationSet (Image Processing Toolbox) object. You can create this object by using the balanceBoxLabels (Computer Vision Toolbox) function or the blockLocationsWithROI (Computer Vision Toolbox) function.

Properties

LabelData — Labeled bounding box data

Read-only: N-by-2 cell array

This property is read-only.

Labeled bounding box data, specified as an N-by-2 cell matrix of N images. The first column must be a cell vector that contains bounding boxes. Each element in the cell contains a vector representing either an axis-aligned rectangle, rotated rectangle, or a cuboid. The second column must be a cell vector that contains the label names corresponding to each bounding box. An M-by-1 categorical vector represents each label name.

Bounding Box Descriptions

Bounding Box	Cell Vector	Format
Axis-aligned rectangle	M-by-4 for M bounding boxes	[x,y,width,height]
Rotated rectangle	M-by-5 for M bounding boxes	[xcenter,ycenter,width,height,yaw]
Cuboid	M-by-9 for M bounding boxes	[xcenter,ycenter,zcenter,width,height,depth,rx,ry,rz]
Projected cuboid	M-by-8 vector for M bounding boxes	[x1,y1,w1,h1,x2,y2,w2,h2]

ReadSize — Maximum number of rows of label data

1 (default) | positive integer

Maximum number of rows of label data to read in each call to the read (Computer Vision Toolbox) function, specified as a positive integer.

Object Functions

Read and Write from Datastore

read	Read data from label datastore
readall	Read all data in label datastore
preview	Preview subset of data in datastore
hasdata	Determine if data is available to read
reset	Reset datastore to initial state

Shuffle, Combine or Partition Datastore

subset	Create subset of datastore or FileSet
partition	Partition a datastore
numpartitions	Number of datastore partitions
shuffle	Shuffle all data in datastore
combine	Combine data from multiple datastores
transform	Transform datastore
isPartitionable	Determine whether datastore is partitionable
isShuffleable	Determine whether datastore is shuffleable

Version History

Introduced in R2019b

R2022b: Project cuboids from 3-D world coordinates to 2-D image coordinates

Updated to support 3-D projected cuboid labels.