The image resource name of the destination image, previously returned by the AddImageFrom...(), AddJpegImageFrom...() or GetPageImageResName methods.
The unique image identifier of the source image refering to an object of the type GdPictureImage. You need to add this image as a resource into the currently loaded PDF document, for example, using methods of the GdPictureImaging class, whose returned value is the unique image identifier.
Applicable only for 1 bit per pixel images. Indicates, whether the source image shall be treated as an image mask (or stencil mask). The commonly recommended default value is false.

Please refer to the Remarks section below or go over the GetPageImageMaskMode method directly for further information on how to use this parameter.

Set to true, if you want to overwrite the original image resource only if the size (in bytes) of the newly added image resource is smaller then size (in bytes) of the original image. Be aware that if you set this parameter to true and the size (in bytes) of the source image is bigger than the size (in bytes) of the destination image, the method will fail with the GdPictureStatus.Aborted.
Example





In This Topic
GdPicture14 Namespace / GdPicturePDF Class / ReplaceImage Method / ReplaceImage(String,Int32,Boolean,Boolean) Method

ReplaceImage(String,Int32,Boolean,Boolean) Method

In This Topic
Replaces a destination image, specified by its resource name, located in the currently loaded PDF document, by the newly added source image, specified by its unique image identifier. You can obtain this identifier, for example, using the ExtractPageImage method or using methods of the GdPictureImaging class when creating the source image as an object of the type GdPictureImage. If the destination image is used either elsewhere on the same page or on another page, it is replaced by the source image on all places within the current document.
Syntax
'Declaration

 

Public Overloads Function ReplaceImage( _

   ByVal ImageResName As String, _

   ByVal ImageID As Integer, _

   ByVal ImageMask As Boolean, _

   ByVal CheckSize As Boolean _

) As GdPictureStatus
public GdPictureStatus ReplaceImage( 

   string ImageResName,

   int ImageID,

   bool ImageMask,

   bool CheckSize

)
public function ReplaceImage( 

    ImageResName: String;

    ImageID: Integer;

    ImageMask: Boolean;

    CheckSize: Boolean

): GdPictureStatus; 
public function ReplaceImage( 

   ImageResName : String,

   ImageID : int,

   ImageMask : boolean,

   CheckSize : boolean

) : GdPictureStatus;
public: GdPictureStatus ReplaceImage( 

   string* ImageResName,

   int ImageID,

   bool ImageMask,

   bool CheckSize

) 
public:

GdPictureStatus ReplaceImage( 

   String^ ImageResName,

   int ImageID,

   bool ImageMask,

   bool CheckSize

) 

Parameters

ImageResName
The image resource name of the destination image, previously returned by the AddImageFrom...(), AddJpegImageFrom...() or GetPageImageResName methods.
ImageID
The unique image identifier of the source image refering to an object of the type GdPictureImage. You need to add this image as a resource into the currently loaded PDF document, for example, using methods of the GdPictureImaging class, whose returned value is the unique image identifier.
ImageMask
Applicable only for 1 bit per pixel images. Indicates, whether the source image shall be treated as an image mask (or stencil mask). The commonly recommended default value is false.

Please refer to the Remarks section below or go over the GetPageImageMaskMode method directly for further information on how to use this parameter.

CheckSize
Set to true, if you want to overwrite the original image resource only if the size (in bytes) of the newly added image resource is smaller then size (in bytes) of the original image. Be aware that if you set this parameter to true and the size (in bytes) of the source image is bigger than the size (in bytes) of the destination image, the method will fail with the GdPictureStatus.Aborted.

Return Value

A member of the GdPictureStatus enumeration. If the method has been successfully followed, then the return value is GdPictureStatus.OK.

We strongly recommend always checking this status first.

Remarks
This method is only allowed for use with non-encrypted documents.

Just to inform you, that you can check the current image masking using the GetPageImageMaskMode method to apply the ImageMask parameter properly. If the value returned by the above mentioned method is PdfMaskTypeNone or PdfMaskTypeUnknown, set the ImageMask parameter to false. Otherwise you can set it to true.

Example
How to replace all images in the PDF document after converting them into 1 bit per pixel (black and white) images.
Dim caption As String = "Example: ReplaceImage"

Dim gdpicturePDF As New GdPicturePDF()

If gdpicturePDF.LoadFromFile("test.pdf", False) = GdPictureStatus.OK Then

    Dim imageCount As Integer = 0, imageID As Integer = 0, bitDepth As Integer = 0

    Dim message As String = "", imageResName As String = ""

    Dim maskMode As PdfImageMaskType = PdfImageMaskType.PdfMaskTypeUnknown

    Dim mask As Boolean = False

    Dim oImage As New GdPictureImaging()

    Dim pageCount As Integer = gdpicturePDF.GetPageCount()

    Dim status As GdPictureStatus = gdpicturePDF.GetStat()

    If (status = GdPictureStatus.OK) AndAlso (pageCount > 0) Then

        For i As Integer = 1 To pageCount

            status = gdpicturePDF.SelectPage(i)

            If status = GdPictureStatus.OK Then

                message = message + "Page nr." + i.ToString() + vbCrLf

                imageCount = gdpicturePDF.GetPageImageCount()

                status = gdpicturePDF.GetStat()

                If (status = GdPictureStatus.OK) AndAlso (imageCount > 0) Then

                    For j As Integer = 0 To imageCount - 1

                        imageResName = gdpicturePDF.GetPageImageResName(j)

                        status = gdpicturePDF.GetStat()

                        If status = GdPictureStatus.OK Then

                            imageID = gdpicturePDF.ExtractPageImage(j + 1)

                            status = gdpicturePDF.GetStat()

                            If status = GdPictureStatus.OK Then

                                bitDepth = oImage.GetBitDepth(imageID)

                                status = oImage.GetStat()

                                If (status = GdPictureStatus.OK) AndAlso

                                   (oImage.GetBitDepth(imageID) > 1) AndAlso

                                   (oImage.ConvertTo1Bpp(imageID) = GdPictureStatus.OK) Then

                                    maskMode = gdpicturePDF.GetPageImageMaskMode(j)

                                    mask = ((maskMode <> PdfImageMaskType.PdfMaskTypeNone) AndAlso (maskMode <> PdfImageMaskType.PdfMaskTypeUnknown))

                                    status = gdpicturePDF.ReplaceImage(imageResName, imageID, mask, True)

                                    If status = GdPictureStatus.OK Then

                                        message = message + "The image named as " + imageResName + " has been successfully replaced." + vbCrLf

                                    Else

                                        message = message + "The ReplaceImage() method has failed for the image numbered as " + (j + 1).ToString() + " with the status: " + status.ToString() + vbCrLf

                                    End If

                                Else

                                    message = message + "The image numbered as " + (j + 1).ToString() + " has not been converted and replaced." + vbCrLf

                                End If

                            Else

                                message = message + "The ExtractPageImage() method has failed for the image numbered as " + (j + 1).ToString() + " with the status: " + status.ToString() + vbCrLf

                            End If

                            'The extracted image need to be released.

                            oImage.ReleaseGdPictureImage(imageID)

                        Else

                            message = message + "The GetPageImageResName() method has failed for the image indexed as " + j.ToString() + " with the status: " + status.ToString() + vbCrLf

                        End If

                    Next

                Else

                    If status = GdPictureStatus.OK Then

                        message = message + "This page doesn't contain any image." + vbCrLf

                    Else

                        message = message + "The GetPageImageCount() method has failed with the status: " + status.ToString() + vbCrLf

                    End If

                End If

            Else

                message = message + "The SelectPage() method has failed with the status: " + status.ToString() + vbCrLf

            End If

        Next

        'It is recommended to pack the document in such cases.

        If gdpicturePDF.SaveToFile("test_ReplaceImage.pdf", True) = GdPictureStatus.OK Then

            message = message + "The file has been saved successfully."

        Else

            message = message + "The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString()

        End If

        MessageBox.Show(message, caption)

    Else

        If status = GdPictureStatus.OK Then

            MessageBox.Show("This file doesn't contain any page.", caption)

        Else

            MessageBox.Show("The GetPageCount() method has failed with the status: " + status.ToString(), caption)

        End If

    End If

    oImage.Dispose()

Else

    MessageBox.Show("The file can't be loaded.", caption)

End If

gdpicturePDF.Dispose()
string caption = "Example: ReplaceImage";

GdPicturePDF gdpicturePDF = new GdPicturePDF();

if (gdpicturePDF.LoadFromFile("test.pdf", false) == GdPictureStatus.OK)

{

    int imageCount = 0, imageID = 0, bitDepth = 0;

    string message = "", imageResName = "";

    PdfImageMaskType maskMode = PdfImageMaskType.PdfMaskTypeUnknown;

    bool mask = false;

    GdPictureImaging oImage = new GdPictureImaging();

    int pageCount = gdpicturePDF.GetPageCount();

    GdPictureStatus status = gdpicturePDF.GetStat();

    if ((status == GdPictureStatus.OK) && (pageCount > 0))

    {

        for (int i = 1; i <= pageCount; i++)

        {

            status = gdpicturePDF.SelectPage(i);

            if (status == GdPictureStatus.OK)

            {

                message = message + "Page nr." + i.ToString() + "\n";

                imageCount = gdpicturePDF.GetPageImageCount();

                status = gdpicturePDF.GetStat();

                if ((status == GdPictureStatus.OK) && (imageCount > 0))

                {

                    for (int j = 0; j < imageCount; j++)

                    {

                        imageResName = gdpicturePDF.GetPageImageResName(j);

                        status = gdpicturePDF.GetStat();

                        if (status == GdPictureStatus.OK)

                        {

                            imageID = gdpicturePDF.ExtractPageImage(j+1);

                            status = gdpicturePDF.GetStat();

                            if (status == GdPictureStatus.OK)

                            {

                                bitDepth = oImage.GetBitDepth(imageID);

                                status = oImage.GetStat();

                                if ((status == GdPictureStatus.OK) &&

                                    (oImage.GetBitDepth(imageID) > 1) &&

                                    (oImage.ConvertTo1Bpp(imageID) == GdPictureStatus.OK))

                                {

                                    maskMode = gdpicturePDF.GetPageImageMaskMode(j);

                                    mask = ((maskMode != PdfImageMaskType.PdfMaskTypeNone) && (maskMode != PdfImageMaskType.PdfMaskTypeUnknown));

                                    status = gdpicturePDF.ReplaceImage(imageResName, imageID, mask, true);

                                    if (status == GdPictureStatus.OK)

                                        message = message + "The image named as " + imageResName + " has been successfully replaced.\n";

                                    else

                                        message = message + "The ReplaceImage() method has failed for the image numbered as " + (j + 1).ToString() + " with the status: " + status.ToString() + "\n";

                                }

                                else

                                    message = message + "The image numbered as " + (j + 1).ToString() + " has not been converted and replaced.\n";

                            }

                            else

                                message = message + "The ExtractPageImage() method has failed for the image numbered as " + (j+1).ToString() + " with the status: " + status.ToString() + "\n";

                            //The extracted image need to be released.

                            oImage.ReleaseGdPictureImage(imageID);

                        }

                        else

                            message = message + "The GetPageImageResName() method has failed for the image indexed as " + j.ToString() + " with the status: " + status.ToString() + "\n";

                    }

                }

                else

                {

                    if (status == GdPictureStatus.OK)

                        message = message + "This page doesn't contain any image.\n";

                    else

                        message = message + "The GetPageImageCount() method has failed with the status: " + status.ToString() + "\n";

                }

            }

            else

                message = message + "The SelectPage() method has failed with the status: " + status.ToString() + "\n";

        }

        //It is recommended to pack the document in such cases.

        if (gdpicturePDF.SaveToFile("test_ReplaceImage.pdf", true) == GdPictureStatus.OK)

            message = message + "The file has been saved successfully.";

        else

            message = message + "The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString();

        MessageBox.Show(message, caption);

    }

    else

    {

        if (status == GdPictureStatus.OK)

            MessageBox.Show("This file doesn't contain any page.", caption);

        else

            MessageBox.Show("The GetPageCount() method has failed with the status: " + status.ToString(), caption);

    }

    oImage.Dispose();

}

else

    MessageBox.Show("The file can't be loaded.", caption);

gdpicturePDF.Dispose();
See Also