insertObjectInImage

Insert object from source image into image

Since R2025a

collapse all in page

Syntax

[newImage,boundingBox,newMask] = insertObjectInImage(destinationImage,sourceImage,mask)
[newImage,boundingBox,newMask] = insertObjectInImage(___,Name=Value)

Description

[newImage,boundingBox,newMask] = 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 bounding box, boundingBox, and a corresponding object mask, newMask.

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,boundingBox,newMask] = 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 into 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

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.

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 matrix. 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 M-by-N 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 in the destination image, and is defined as true(size(destinationImage,[1 2])).

Boundary constraint mode, specified as "inbounds" or "center". This argument specifies the method used to constrain objects at the boundaries of the destination image destinationImage, specified as one of these options:

ValueEdge Detection Mechanism
"inbounds"

To insert an object, it must be completely within the destination image.

"center"To insert an object, only the object centroid must lie 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 in the destinationImage that already contain an inserted object. By default, the destination image does not contain inserted objects.

Maximum object overlap between an object in the source image sourceImage and a previously inserted object, specified as a positive scalar in the 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, specified as "guidedfilter", "poisson", or "none". This argument specifies the method to use to insert objects from the source image into the destination image.

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 with the source image pixel values.

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

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

  • x and y specify the upper-left corner of the bounding box.

  • w specifies the width of the bounding box, which is its length along the x-axis.

  • h specifies the height of the bounding box, which is its length along the y-axis.

Inserted object region mask, 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.

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. https://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. https://doi:10.1145/1201775.882269.

Version History

Introduced in R2025a

See Also

| | | |

Topics