Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old


Replaces an image with another image.

Component Version macOS Windows Linux Server iOS SDK
DynaPDF 7.5 ✅ Yes ✅ Yes ✅ Yes ✅ Yes ✅ Yes
MBS( "DynaPDF.ReplaceImage"; PDF; ImageIndex; Image { ; ImageIndex; Colorspace; ColorSpaceHandle; Flags } )   More


Parameter Description Example Flags
PDF The PDF reference returned from DynaPDF.New. $pdf
ImageIndex The index of the image to replace.
From 0 to DynaPDF.GetImageCount-1.
Image The new image.
Can be container or native file path.
ImageIndex The index of the image.
This is for a multi picture tiff file to pick the image.
Default is 1 for first image.
1 Optional
Colorspace The color space to use.
Can be DeviceRGB, DeviceCMYK, DeviceGray, CalGray, CalRGB, Lab, ICCBased, Pattern, Indexed, Separation, DeviceN or NChannel.
Default is DeviceRGB.
"DeviceRGB" Optional
ColorSpaceHandle The color space handle.
Can be empty if you want to use device colorspace.
"" Optional
Flags The flags.
Can be number or text with various flags.
Can be set to DeleteAltImages, DeleteMetadata, DeleteOCG and/or DeleteSoftMask.
"DeleteAltImages¶DeleteMetadata" Optional


Returns OK or error.


Replaces an image with another image.
The resolution, aspect ratio, color space and so on can be freely chosen. However, note that this function does not change the output position or size. If the aspect ratio of the new image is different, then it will be stretched or shrunken to fit into the output rectangle.
The parameter CS specifies the destination color space into which the image should be converted or saved, if the image is already defined in that color space. CSHandle must be the handle of that color space if a non-device space is used. The will be ignored for devices spaces.
The function works in the very same way as DynaPDF.InsertImage with the following differences:
  • The color of an image mask cannot be set or changed because this would require changes on the content stream in which the image is used. An image mask will be created if the image color depth is 1 bit and if color key masking is enabled (see SetUseTransparency()). SetUseTransparency() should normally be set to false before calling this function. 

The image will never be downscaled, independent of the current resolution, because the size of the output rectangle is not known. 
If the image that should be replaced is a soft mask of another base image, then make sure that the destination color space is set to DeviceGray, CalGray, or to a one channel ICC based color space because a soft mask must not contain more than one color channel. 
The flags UseImageColorSpace, IgnoreICCProfiles, RealPassThrough, and NoBitmapAlpha are all supported. See DynaPDF.SetGStateFlags for further information.

Needs DynaPDF Lite license.

See also ReplaceImage function in DynaPDF manual.


Replace image:

# Initialize DynaPDF if needed
If [ MBS("DynaPDF.IsInitialized") ≠ 1 ]
    Perform Script [ “InitDynaPDF” ]
End If
# Start new PDF session
Set Variable [ $pdf ; Value: MBS("DynaPDF.New") ]
# Import pages
Set Variable [ $r ; Value: MBS("DynaPDF.OpenPDFFromContainer"; $pdf; Replace Image::Input PDF) ]
Set Variable [ $r ; Value: MBS("DynaPDF.ImportPDFFile"; $pdf; 1) ]
# Replace Image
Set Variable [ $r ; Value: MBS("DynaPDF.ReplaceImage"; $pdf; 0; Replace Image::New Image) ]
# Save PDF
Set Field [ Replace Image::Output PDF ; MBS("DynaPDF.Save"; $pdf) ]
# Cleanup
Set Variable [ $r ; Value: MBS( "DynaPDF.Release"; $pdf ) ]

See also

Release notes

Example Databases

Blog Entries

This function checks for a license.

Created 30th September 2017, last changed 15th September 2020

DynaPDF.RenderPage - DynaPDF.ReplacePattern