Main Content

insertObjectInImage

Insert object in image from source image

Since R2025a

Description

[newImage,newMask,boundingBox] = insertObjectInImage(destinationImage,sourceImage,mask) inserts an object from a source image, sourceImage, into a destination image, destinationImage. By default, the insertObjectInImage function inserts an object from the source image into a randomized location on the destination image. The function returns the result as an augmented image newImage, a object mask newMask, and a corresponding bounding box boundingBox.

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.

[newImage,newMask,boundingBox] = insertObjectInImage(___,Name=Value) specifies options using one or more name-value arguments, in addition to the input arguments from the previous syntax. For example, BoundaryConstraintMode="inbounds" specifies to insert objects only when they are completely within the destination image.

Input Arguments

collapse all

Destination image in which to insert an object, specified as one of these options:

Image TypeData Format
GrayscaleH-by-W numeric matrix
BinaryH-by-W logical matrix
RGBH-by-W-by-3 numeric array

Source image containing an object to insert into the destination image, specified as one of these options:

Image TypeData Format
GrayscaleH-by-W numeric matrix
BinaryH-by-W logical matrix
RGBH-by-W-by-3 numeric array

Object mask on the source image, specified as an H-by-W logical array. H and W are the height and width of the source image, sourceImage, respectively.

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: BoundaryConstraintMode="inbounds" specifies to insert objects only when they are completely within the destination image.

Region constraint mask, specified as an H-by-W logical array. M and N are the height and width of the destination image destinationImage, respectively.

Specify the RegionConstraintMask value as true (or 1) for only select pixel locations to insert the object from the source image into a specific location on the destination image. By default, the insertObjectInImage function inserts the object at a randomized location on the destination image, and is defined as true(size(destinationImage,[1 2])).

Boundary constraint mode used to constrain objects at the boundaries of the destination image destinationImage, specified as one of these options:

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

Stack of mask images containing inserted objects, specified as an M-by-N-by-P logical array. P is the total number of masks in the stack, and M and N are the height and width of the destination image destinationImage, respectively. The value of ObjectsInSceneMasks is true (or 1) at the pixel locations which already contain an inserted object. By default, there are no existing inserted objects in the image.

Maximum object overlap between an object in a source image sourceImage 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.

Maximum insertion attempts to satisfy the overlap value, specified as a positive scalar. The overlap value is specified by the ObjectsInSceneMaxOverlap name-value argument. If no insertion location can be found on the destination image after MaxInsertionAttempts iterations, the insertObjectInImage function will not insert the object from the source image into the destination image.

Blend method to use for inserting objects from the source image into the destination image, specified as one of these options:

BlendMethod ValueBlend 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.

Geometric augmentation, specified as a function handle that returns an affinetform2d object. The geometric augmentation warps a source image and the mask associated with the 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 an inserted object.

Output Arguments

collapse all

Augmented image containing an inserted object, returned as one of these options:

Image TypeData Format
GrayscaleM-by-N numeric matrix
BinaryM-by-N logical matrix
RGBM-by-N-by-3 numeric array

Tip

Specify the RegionConstraintMask name-value argument to specify the region in the destination image in which to insert the object. Otherwise, the insertObjectInImage function inserts the object in the destination image at a randomized location.

Axis-aligned bounding box enclosing mask of inserted object region, returned as a 1-by-4 row vector. The row vector is of the form [x y w h], where:

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

Mask containing inserted object region, returned as an M-by-N logical array. M and N are the height and width of the destination image, destinationImage, respectively. The value of the logical array returned by newMask is true (or 1) at the pixel locations where object content is inserted into the destination image from the source image.

Tip

Specify the RegionConstraintMask name-value argument to specify the region in the destination image in which to insert the object and the object mask. Otherwise, the insertObjectInImage function inserts the object and its corresponding mask in the destination image at a randomized location.

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