In This Topic

Best Practices

In This Topic

Summary

There are a number of best practices, that will eliminate any chances of encountering problems in programming your applications.

 Error checking

After each function or method call, you should always check for errors reported. Those can vary between invalid parameters, all the way up to functional or memory errors. There are various ways to check for errors depending on your preference and the functionality you are expecting to accomplish. The method in which you check for errors is illustrated in our many sample demo applications.

For example, if you want to check, that you have successfully displayed an image from a file, you can either:

  • Check the value of the returned GdPictureStatus enumeration of the called Display method.
    How to check the returned status of the previous operation.
    Copy Code 
    'Display an image

If oGdViewer.DisplayFromFile("C:\Nature.jpg") <> GdPictureStatus.OK Then

    MessageBox.Show("Error: " + oGdViewer.GetStat().ToString())

End If
    How to check the returned status of the previous operation.
    Copy Code 
    //Display an image

if(oGdViewer.DisplayFromFile("C:\\Nature.jpg") != GdPictureStatus.OK)

{

    MessageBox.Show("Error: " + oGdViewer.GetStat().ToString());

}

    As you can see here, we checked the returned status, and if there was an error of any type, we display the error in a message box. The GetStat() method returns the status of the last function or method called.
    The GdPictureImaging class and also the GdPicturePDF class contain the GetStat() methods that act accordingly. For TWAIN acquisition, please use GdPictureImaging.TwainGetState() instead.

  • Check the status of the called Create or Load method using the GetStat() method first. You can subsequently check the image identifier, the valid value of the returned imageID should be different than 0.
    How to check the returned status of the called method.
    Copy Code 
    'Create GdPictureImage from file

 Dim imageID As Integer = oGdPictureImaging.CreateGdPictureImageFromFile("C:\Nature.jpg")

 If (oGdPictureImaging.GetStat() <> GdPictureStatus.OK) OrElse (imageID = 0) Then

    MessageBox.Show("Error: " + oGdPictureImaging.GetStat().ToString())

 Else 'it stands for (oGdPictureImaging.GetStat() = GdPictureStatus.OK) AndAlso (imageID <> 0)

    'creating was successful: continue your operations

 End If
    How to check the returned status of the called method.
    Copy Code 
    //Create GdPictureImage from file

 int imageID = oGdPictureImaging.CreateGdPictureImageFromFile("C:\\Nature.jpg");

 if ((oGdPictureImaging.GetStat() != GdPictureStatus.OK) || (imageID == 0))

 {

    MessageBox.Show("Error: " + oGdPictureImaging.GetStat().ToString());

 }

 else // it stands for (oGdPictureImaging.GetStat() == GdPictureStatus.OK) && (imageID != 0)

 {

    //creating was successful: continue your operations

 }
 Releasing your images

Memory is an essential topic in any imaging applications.
We all have encountered needs to deal with hundreds if not thousands of images, some of them very extreme, and if your program is not robust in handling the memory creation and release of those images, you can very quickly overcome your computer’s limit, either slowing your application or worse, crashing it. Thus, it is really important to release images you have created using GdPicture.NET once you have no use for them.

If you are going to release already used image, you can select the method according to the object you are working with.

  • If you operate with the instance of the GdPictureImaging class, use the ReleaseGdPictureImage() method.
    For example, you are creating a multipage TIFF image file. So you create a GdPictureImage for each new page. Once you add the created image to your multipage TIFF image file, you should release the image source before you create a new image for a new page. This should be done via the GdPictureImaging.ReleaseGdPictureImage() method, as it is shown in these code snippets.               
    Releasing image resources.
    Copy Code 
    'We assume that GdPicture has been correctly installed and unlocked.

Dim oGdPictureImaging As New GdPictureImaging

'Variable to hold the image identifier.

Dim imageId As Integer

'Variable to hold the created multipage image handle.

Dim multipageHandle As Integer

'Number of images.

Dim imageCount As Integer = 0

'Setting up the Twain features.

oGdPictureImaging.TwainOpenDefaultSource(Me.Handle)

oGdPictureImaging.TwainSetAutoFeed(True) 'Enable AutoFeed

oGdPictureImaging.TwainSetAutoScan(True) 'To achieve the maximum scanning rate

oGdPictureImaging.TwainSetPixelType(TwainPixelType.TWPT_BW) '1 bit bw image

oGdPictureImaging.TwainEnableDuplex(True) 'Duplex acquisition if supported

oGdPictureImaging.TwainSetHideUI(True) 'Asks to the device to hide his GUI

'Scanning each page and adding it to a multipage TIFF GdPictureImage identifier.

Do

    'Acquiring image from scanner.

    imageId = oGdPictureImaging.TwainAcquireToGdPictureImage(Me.Handle)

    'Checking, if image was loaded correctly.

    If (oGdPictureImaging.GetStat() = GdPictureStatus.OK) AndAlso (imageId <> 0) Then

        imageCount = imageCount + 1

        'If it is the first image, then create a new multipage TIFF file.

        If imageCount = 1 Then

            multipageHandle = imageId

            oGdPictureImaging.TiffSaveAsMultiPageFile(multipageHandle, "multipage.tif", TiffCompression.TiffCompressionAUTO)

        Else 'If it is the second image or more, add it to the previously created multipage TIFF file.

            oGdPictureImaging.TiffAddToMultiPageFile(multipageHandle, imageId)

            'Release current image to minimize memory usage.

            oGdPictureImaging.ReleaseGdPictureImage(imageId)

        End If

    Else

        MessageBox.Show("The image can't be loaded. Status: " + oGdPictureImaging.GetStat().ToString())

    End If

Loop While oGdPictureImaging.TwainGetState() > TwainStatus.TWAIN_SOURCE_ENABLED

'Clean up all resources.

oGdPictureImaging.TwainCloseSource() 'Closing the source.

oGdPictureImaging.TiffCloseMultiPageFile(multipageHandle) 'Closing the multipage file.

oGdPictureImaging.ReleaseGdPictureImage(multipageHandle) 'Releasing the multipage image.
    Releasing image resources.
    Copy Code 
    //We assume that GdPicture has been correctly installed and unlocked.

GdPictureImaging oGdPictureImaging = new GdPictureImaging();

//Variable to hold the image identifier.

int imageId = 0;

//Variable to hold the created multipage image handle.

int multipageHandle = 0;

//Number of images.

int imageCount = 0;

//Setting up the Twain features.

oGdPictureImaging.TwainOpenDefaultSource(this.Handle);

oGdPictureImaging.TwainSetAutoFeed(true); //Enable AutoFeed

oGdPictureImaging.TwainSetAutoScan(true); //To achieve the maximum scanning rate

oGdPictureImaging.TwainSetPixelType(TwainPixelType.TWPT_BW); //1 bit bw image

oGdPictureImaging.TwainEnableDuplex(true); //Duplex acquisition if supported

oGdPictureImaging.TwainSetHideUI(true); //Asks to the device to hide his GUI

//Scanning each page and adding it to a multipage TIFF GdPictureImage identifier.

do

{

    //Acquiring image from scanner.

    imageId = oGdPictureImaging.TwainAcquireToGdPictureImage(this.Handle);

    //Checking, if image was loaded correctly.

    if ((oGdPictureImaging.GetStat() == GdPictureStatus.OK) && (imageId != 0))

    {

        imageCount++;

        //If it is the first image, then create a new multipage TIFF file.

        if (imageCount == 1)

        {

           multipageHandle = imageId;

           oGdPictureImaging.TiffSaveAsMultiPageFile(multipageHandle, "multipage.tif", TiffCompression.TiffCompressionAUTO);

        }

        else //If it is the second image or more, add it to the previously created multipage TIFF file.

        {

            oGdPictureImaging.TiffAddToMultiPageFile(multipageHandle, imageId);

            //Release current image to minimize memory usage.

            oGdPictureImaging.ReleaseGdPictureImage(imageId);

        }

    }

    else

    {

        MessageBox.Show("The image can't be loaded. Status: " + oGdPictureImaging.GetStat().ToString());

    }

} while (oGdPictureImaging.TwainGetState() > TwainStatus.TWAIN_SOURCE_ENABLED);

//Clean up all resources.

oGdPictureImaging.TwainCloseSource(); //Closing the source.

oGdPictureImaging.TiffCloseMultiPageFile(multipageHandle); //Closing the multipage file.

oGdPictureImaging.ReleaseGdPictureImage(multipageHandle); //Releasing the multipage image.

    As you can see, we used the GdPictureImaging.ReleaseGdPictureImage() method on each added page and on the multipage TIFF file once we finished using it.

  • If you operate with the instance of the GdPicturePDF class, use the static GdPictureDocumentUtilities.DisposeImage() method.
    For example, you are extracting images from your source PDF document. So you extract an image from the page using a GdPictureImage object. Once you add and draw the created image on the new page in the destination PDF document,  you should release the image source before you create a new image. This should be done via the static GdPictureDocumentUtilities.DisposeImage() method, as it is shown in these code snippets.
    Disposing image resources.
    Copy Code 
    'We assume that GdPicture has been correctly installed and unlocked.

Dim oGdPicturePDFSrc As GdPicturePDF = New GdPicturePDF() ' the source PDF document

If oGdPicturePDFSrc.LoadFromFile("source.pdf", False) = GdPictureStatus.OK Then

    Dim pageCount As Integer = oGdPicturePDFSrc.GetPageCount()

    Dim status As GdPictureStatus = oGdPicturePDFSrc.GetStat()

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

        ' the first page is automatically selected as the current page

        Dim imageCount As Integer = oGdPicturePDFSrc.GetPageImageCount()

        status = oGdPicturePDFSrc.GetStat()

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

            Dim oGdPicturePDFDest As GdPicturePDF = New GdPicturePDF() ' the destination PDF document

            If oGdPicturePDFDest.NewPDF() = GdPictureStatus.OK Then

                Dim message As String = ""

                Dim imageID As Integer = 0

                For i As Integer = 1 To imageCount

                    ' extracting the image from the source PDF document

                    imageID = oGdPicturePDFSrc.ExtractPageImage(i)

                    status = oGdPicturePDFSrc.GetStat()

                    If status = GdPictureStatus.OK Then

                        ' drawing the extracted image on the newly created page in the destination PDF document

                        Dim res_name As String = oGdPicturePDFDest.AddImageFromGdPictureImage(imageID, PdfAdvancedImageCompression.PdfAdvancedImageCompressionMRC)

                        status = oGdPicturePDFSrc.GetStat()

                        If status = GdPictureStatus.OK Then

                            message = message + "The image nr. " + i.ToString() + " has been successfully drawn." + vbCrLf

                        Else

                            message = message + "The AddImageFromGdPictureImage() method has failed for the image nr. " + i.ToString() + " with the status: " + status.ToString() + vbCrLf

                        End If

                        ' releasing already used image

                        If GdPictureDocumentUtilities.DisposeImage(imageID) <> GdPictureStatus.OK Then

                            message = message + "The DisposeImage() method has failed for the image nr. " + i.ToString() + " with the status: " + status.ToString() + vbCrLf

                        End If

                    Else

                        message = message + "The ExtractPageImage() method has failed for the image nr. " + i.ToString() + " with the status: " + status.ToString() + vbCrLf

                    End If

                Next

               If oGdPicturePDFDest.SaveToFile("destination.pdf") = GdPictureStatus.OK Then

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

                Else

                    message = message + "The SaveToFile() method has failed with the status: " + oGdPicturePDFDest.GetStat().ToString()

                End If

                MessageBox.Show(message, "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Hand)

            Else

                MessageBox.Show("The NewPDF() method has failed with the status: " + oGdPicturePDFDest.GetStat().ToString(), "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Error)

            End If

           oGdPicturePDFDest.Dispose()

        Else

            If status = GdPictureStatus.OK Then

                MessageBox.Show("The first page doesn't contain any image.", "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Information)

            Else

                MessageBox.Show("The GetPageImageCount() method has failed with the status: " + status.ToString(), "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Error)

            End If

        End If

    Else

        If status = GdPictureStatus.OK Then

           MessageBox.Show("This file doesn't contain any page.", "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Information)

        Else

            MessageBox.Show("The GetPageCount() method has failed with the status: " + status.ToString(), "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Error)

       End If

    End If

Else

    MessageBox.Show("The file can't be loaded.", "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Error)

End If

oGdPicturePDFSrc.Dispose()
    Disposing image resources.
    Copy Code 
    //We assume that GdPicture has been correctly installed and unlocked.

GdPicturePDF oGdPicturePDFSrc = new GdPicturePDF();

// the source PDF document

if (oGdPicturePDFSrc.LoadFromFile("source.pdf", false) == GdPictureStatus.OK)

{

    int pageCount = oGdPicturePDFSrc.GetPageCount();

    GdPictureStatus status = oGdPicturePDFSrc.GetStat();

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

    {

        // the first page is automatically selected as the current page

        int imageCount = oGdPicturePDFSrc.GetPageImageCount();

        status = oGdPicturePDFSrc.GetStat();

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

        {

            GdPicturePDF oGdPicturePDFDest = new GdPicturePDF();

            // the destination PDF document

            if (oGdPicturePDFDest.NewPDF() == GdPictureStatus.OK)

            {

                string message = "";

                int imageID = 0;

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

                {

                    // extracting the image from the source PDF document

                    imageID = oGdPicturePDFSrc.ExtractPageImage(i);

                    status = oGdPicturePDFSrc.GetStat();

                    if (status == GdPictureStatus.OK)

                    {

                        // drawing the extracted image on the newly created page in the destination PDF document

                        string res_name = oGdPicturePDFDest.AddImageFromGdPictureImage(imageID, PdfAdvancedImageCompression.PdfAdvancedImageCompressionMRC);

                        status = oGdPicturePDFSrc.GetStat();

                        if (status == GdPictureStatus.OK)

                            message = message + "The image nr. " + i.ToString() + " has been successfully drawn.\n";

                        else

                            message = message + "The AddImageFromGdPictureImage() method has failed for the image nr. " + i.ToString() + " with the status: " + status.ToString() + "\n";

                       // releasing already used image

                        if (GdPictureDocumentUtilities.DisposeImage(imageID) != GdPictureStatus.OK)

                            message = message + "The DisposeImage() method has failed for the image nr. " + i.ToString() + " with the status: " + status.ToString() + "\n";

                    }

                    else

                        message = message + "The ExtractPageImage() method has failed for the image nr. " + i.ToString() + " with the status: " + status.ToString() + "\n";

                }

                if (oGdPicturePDFDest.SaveToFile("destination.pdf") == GdPictureStatus.OK)

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

                else

                    message = message + "The SaveToFile() method has failed with the status: " + oGdPicturePDFDest.GetStat().ToString();

                MessageBox.Show(message, "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Hand);

            }

            else

                MessageBox.Show("The NewPDF() method has failed with the status: " + oGdPicturePDFDest.GetStat().ToString(), "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Error);

            oGdPicturePDFDest.Dispose();

        }

        else

        {

            if (status == GdPictureStatus.OK)

                MessageBox.Show("The first page doesn't contain any image.", "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Information);

            else

                MessageBox.Show("The GetPageImageCount() method has failed with the status: " + status.ToString(), "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Error);

        }

    }

    else

    {

        if (status == GdPictureStatus.OK)

            MessageBox.Show("This file doesn't contain any page.", "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Information);

        else

            MessageBox.Show("The GetPageCount() method has failed with the status: " + status.ToString(), "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Error);

    }

}

else

    MessageBox.Show("The file can't be loaded.", "Releasing images", MessageBoxButtons.OK, MessageBoxIcon.Error);

oGdPicturePDFSrc.Dispose();

    As you can see, we used the static GdPictureDocumentUtilities.DisposeImage() method on each drawn image once we finished using it.

 Closing multipage files, PDF documents and TWAIN sources

It is really important to close TWAIN sources and to close multipage files (if there is a need to, depends on the saving mechanism used, for more information, please review the TiffSaveAsMultiPageFile method documentation). As for PDF documents, it is important to close them in order to release their memory. If you work with images as a part of your files or documents, you have to release them separately (see the section above). Closing and disposing of files or documents do not release used images. So here is an example of creating a searchable PDF from an existing PDF.

Closing active files and documents.
Copy Code 
'We assume that GdPicture has been correctly installed and unlocked.

Dim oGdPicturePDF As New GdPicturePDF()

'Loading a PDF document.

Dim status As GdPictureStatus = oGdPicturePDF.LoadFromFile("C:\input.pdf", False)

'If loading was successful, let's continue.

If status = GdPictureStatus.OK Then

    Dim pageCount As Integer = oGdPicturePDF.GetPageCount()

    'loop through document pages

    For i As Integer = 1 To pageCount

       'select the page

       oGdPicturePDF.SelectPage(i)

       'ocr the page and check for error

       If oGdPicturePDF.OcrPage("eng", "C:\Program Files (x86)\GdPicture.NET 14\Redist\OCR", "", 200) <> GdPictureStatus.OK Then

           MessageBox.Show("OCR problem occurred on the page nr." + i.ToString() + ". Error: " + oGdPicturePDF.GetStat().ToString())

       End If

    Next

    'save to a different file

    status = oGdPicturePDF.SaveToFile("C:\output.pdf", True)

    'close and release source document

    oGdPicturePDF.CloseDocument()

Else

    MessageBox.Show("The file can't be loaded. Status: " + status.ToString())

End If

oGdPicturePDF.Dispose()
Closing active files and documents.
Copy Code 
//We assume that GdPicture has been correctly installed and unlocked.

GdPicturePDF oGdPicturePDF = new GdPicturePDF();

//Loading a PDF document.

GdPictureStatus status = oGdPicturePDF.LoadFromFile("C:\\input.pdf", false);

//If loading was successful, let's continue.

if (status == GdPictureStatus.OK)

{

    int pageCount = oGdPicturePDF.GetPageCount();

    //loop through document pages

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

    {

       //select the page

       oGdPicturePDF.SelectPage(i);

       //ocr the page and check for error

       if (oGdPicturePDF.OcrPage("eng", "C:\\Program Files (x86)\\GdPicture.NET 14\\Redist\\OCR", "", 200) != GdPictureStatus.OK)

       {

           MessageBox.Show("OCR problem occurred on the page nr." + i.ToString() + ". Error: " + oGdPicturePDF.GetStat().ToString());

       }

    }

    //save to a different file

    status = oGdPicturePDF.SaveToFile("C:\\output.pdf", true);

    //close and release source document

    oGdPicturePDF.CloseDocument();

}

else

{

    MessageBox.Show("The file can't be loaded. Status: " + status.ToString());

}

oGdPicturePDF.Dispose();
 Closing displayed documents in GdViewer

It is always a best practice to close the displayed document in GdViewer using the GdViewer.CloseDocument() method before you display a new one. If this document exists in another class, let's say an image in GdPictureImaging class, you also have to release it using the GdPictureImaging.ReleaseGdPictureImage() method if you are done using it.

 TWAIN issues

TWAIN is a massive protocol. Problems arise from the fact that different manufacturers have to support it individually for their machinery. To handle those issues, we have created a step by step protocol for you to follow in order to figure out the source of your problem. 95% of cases are solved by following the steps described here: TWAIN Acquisition Issues