objectInsertionDatastore

Create synthetic labeled datastore for training an instance segmentation or object detection network

Since R2025a

Description

The objectInsertionDatastore object blends datastores of labeled images containing foreground objects with destination images containing the background. Using this object, you can create a synthetic labeled datastore for training an instance segmentation or object detection network.

To insert an object into a single background image at a randomized or specified location, use the insertObjectInImage function.

Note

This functionality requires Deep Learning Toolbox™ and the Automated Visual Inspection Library for Computer Vision Toolbox™. You can install the Automated Visual Inspection Library for Computer Vision Toolbox from Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

Creation

Syntax

dsNew = objectInsertionDatastore(dsDestination,dsObject,numNewImages)

dsNew = objectInsertionDatastore(___,PropertyName=Value)

Description

dsNew = objectInsertionDatastore(dsDestination,dsObject,numNewImages) creates an augmented datastore dsNew by inserting objects from the source datastore dsObject into the destination datastore containing image data, dsDestination. The objects from the source images are inserted at randomized locations on the destination images. You must specify the number of images synthetic images to create, numNewImages.

dsNew = objectInsertionDatastore(___,PropertyName=Value) sets writeable properties using one or more name-value arguments, in addition to the input argument from the previous syntax. For example, NumObjectsToInsert=2 specifies the number of objects to insert as 2.

Input Arguments

dsDestination — Destination datastore

datastore

Destination datastore of images, specified as a datastore such as an ImageDatastore or CombinedDatastore object.

To insert objects at specific image locations using a region constraint mask, specify the dsDestination argument as a datastore that returns a cell array with two columns, {Image ObjectMask}, when called with the read function. Image is an array of RGB or grayscale images, and ObjectMask is a logical array of masks which span object regions to insert.

dsObject — Datastore of source images containing objects

datastore

Datastore of source images containing objects, specified as a datastore such as an ImageDatastore or CombinedDatastore object. You must set up your data so that calling the read and readall functions on the datastore returns a cell array with these columns.

Image Data	Boxes	Labels	Masks
RGB or grayscale image containing objects to insert, specified as an H-by-W-by-3 or H-by-W-by-1 numeric array, respectively.	Bounding boxes, 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.	Object class names, specified as an M-by-1 categorical vector, where M is the number of specified bounding boxes. All categorical data read from the datastore must contain the same categories.	Binary masks, specified as a logical array of size H-by-W-by-M, where M is the number of specified bounding boxes. Each channel is a mask, and each mask is the segmentation of one object in the image.

numNewImages — Number of augmented images

positive integer

Number of augmented images to create, specified as a positive integer. In every call to the datastore with the read function, the objectInsertionDatastore object inserts random object from the datastore dsObject into a random image from the datastore dsDestination.

Properties

NumObjectsToInsert — Number of objects to insert

1 (default) | positive integer | range of positive integers

Number of objects to insert from the source datastore, dsObject, specified as a positive integer or a range of positive integers [minNum,maxNum]. If you specify a range of positive integers [minNum,maxNum], the objectInsertionDatastore object inserts a random number of objects into each image in the destination datastore dsDestination.

OutputFormat — Output format

"InstanceSegmentation" (default) | "ObjectDetection" | "SceneClassification"

Output format of the data returned by calling the augmented datastore dsNew with the read function, specified as one of these options:

• "InstanceSegmentation" – Instance segmentation data containing image data, bounding boxes, masks, and labels

• "ObjectDetection" – Object detection data containing image data, bounding boxes and labels

• "SceneClassification" – Scene classification, or semantic segmentation data, containing image data and masks

ObjectsInSceneMaxOverlap — Maximum object overlap

1 (default) | positive scalar in range [0, 1]

Maximum object overlap between an object in an image from the datastore dsObject and a previously inserted object, specified as a positive scalar in range [0, 1]. Specify the ObjectsInSceneMaxOverlap value as 1 to insert new objects on top of existing objects. Decrease this value to decrease the overlap between the newly inserted objects and existing objects.

BoundaryConstraintMode — Boundary constraint mode

"inbounds" (default) | "center"

Boundary constraint mode used to constrain objects at the boundaries of images in the destination datastore dsDestination, specified as one of these options:

Value	Edge Detection Mechanism
"inbounds"	Objects are inserted only when they are completely within the destination image.
"center"	Objects are inserted when the object centroid lies inside the destination image, so objects can be partially visible and clipped at the image boundary.

MaxInsertionAttempts — Maximum insertion attempts

10 (default) | positive scalar

Maximum insertion attempts to satisfy the overlap value, specified as a positive scalar. The overlap value is represented by the ObjectsInSceneMaxOverlap property. If no insertion location can be found on the destination image after MaxInsertionAttempts iterations, the object from the source datastore image will not be inserted into the destination datastore image.

BlendMethod — Blend method

"guidedfilter" (default) | "poisson" | "none"

Blend method to use for inserting objects from the images in the source datastore dsObject into the images in the destination datastore dsDestination, specified as a one of these options:

BlendMethod Value	Blend Method
"guidedfilter"	Guided filter blending [1] – Blur the object mask of the source image at the mask-object boundary. Guided image filtering uses edge context from the source image to filter the mask prior to blending the object image with the destination image.
"poisson"	Poisson blending [2] – Blend the source object into the destination image by matching the color distribution of the source object to that of the boundary between the destination image and source object mask.
"none"	No blending – At insertion locations of the destination image, replace pixels of the destination image by the source image pixel values.

GeometricAugmentation — Geometric augmentation

[] (default) | function handle

Geometric augmentation, specified as a function handle that returns an affinetform2d object. The geometric augmentation warps a source image and the mask associated with each object in the image before it is inserted into the destination image. For example, specify the GeometricAugmentation value as @() randomAffine2d("Scale",[0.9,1.1]) to apply a randomized scale transformation to each inserted object.

References

[1] He, Kaiming, Jian Sun, and Xiaoou Tang. “Guided Image Filtering.” IEEE Transactions on Pattern Analysis and Machine Intelligence 35, no. 6 (June 2013): 1397–1409. doi:10.1109/TPAMI.2012.213.

[2] Pérez, Patrick, Michel Gangnet, and Andrew Blake. “Poisson Image Editing.” In ACM SIGGRAPH 2003 Papers, 313–18. San Diego California: ACM, 2003. doi:10.1145/1201775.882269.

Version History

Introduced in R2025a