Technical FAQs for "ImageGear .NET"

Question

I am trying to perform OCR on a PDF created from a scanned document. I need to rasterize the PDF page before importing the page into the recognition engine. When rasterizing the PDF page I want to set the bit depth of the generated page to be equal to the bit depth of the embedded image so I may use better compression methods for 1-bit and 8-bit images.

ImGearPDFPage.DIB.BitDepth will always return 24 for the bit depth of a PDF. Is there a way to detect the bit depth based on the PDF’s embedded content?

Answer

To do this:

  1. Use the ImGearPDFPage.GetContent() function to get the elements stored in the PDF page.
  2. Then loop through these elements and check if they are of the type ImGearPDEImage.
  3. Convert the image to an ImGearPage and find it’s bit depth.
  4. Use the highest bit depth detected from the images as the bit depth when rasterizing the page.

The code below demonstrates how to do detect the bit depth of a PDF page for all pages in a PDF document, perform OCR, and save the output while using compression.

private static void Recognize(ImGearRecognition engine, string sourceFile, ImGearPDFDocument doc)
    {
        using (ImGearPDFDocument outDoc = new ImGearPDFDocument())
        {
            // Import pages
            foreach (ImGearPDFPage pdfPage in doc.Pages)
            {
                int highestBitDepth = 0;
                ImGearPDEContent pdeContent = pdfPage.GetContent();
                int contentLength = pdeContent.ElementCount;
                for (int i = 0; i < contentLength; i++)
                {
                    ImGearPDEElement el = pdeContent.GetElement(i);
                    if (el is ImGearPDEImage)
                    {
                        //create an imGearPage from the embedded image and find its bit depth
                        int bitDepth = (el as ImGearPDEImage).ToImGearPage().DIB.BitDepth; 
                        if (bitDepth > highestBitDepth)
                        {
                            highestBitDepth = bitDepth;
                        }
                    }
                }
                if(highestBitDepth == 0)
                {
                    //if no images found in document or the images are embedded deeper in containers we set to a default bitDepth of 24 to be safe
                    highestBitDepth = 24;
                }
                ImGearRasterPage rasterPage = pdfPage.Rasterize(highestBitDepth, 200, 200);
                using (ImGearRecPage recogPage = engine.ImportPage(rasterPage))
                {
                    recogPage.Image.Preprocess();
                    recogPage.Recognize();
                    ImGearRecPDFOutputOptions options = new ImGearRecPDFOutputOptions() { VisibleImage = true, VisibleText = false, OptimizeForPdfa = true, ImageCompression = ImGearCompressions.AUTO, UseUnicodeText = false };
                    recogPage.CreatePDFPage(outDoc, options);
                }
            }
            outDoc.SaveCompressed(sourceFile + ".result.pdf");
        }
    }

For the compression type, I would recommend setting it to AUTO. AUTO will set the compression type depending on the image’s bit depth. The compression types that AUTO uses for each bit depth are: 

  • 1 Bit Per Pixel – ImGearCompressions.CCITT_G4
  • 8 Bits Per Pixel – ImGearCompressions.DEFLATE
  • 24 Bits Per Pixel – ImGearCompressions.JPEG

Disclaimer: This may not work for all PDF documents due to some PDF’s structure. If you’re unfamiliar with how PDF content is structured, we have an explanation in our documentation. The above implementation of this only checks one layer into the PDF, so if there were containers that had images embedded in them, then it will not detect them.

However, this should work for documents created by scanners, as the scanned image should be embedded in the first PDF layer. If you have more complex documents, you could write a recursive function that goes through the layers of the PDF to find the images.

The above code will set the bit depth to 24 if it wasn’t able to detect any images in the first layer, just to be on the safe side.

Question

In ImageGear .NET, I am receiving error “API_HARDTIMEOUT_ERR” when using Recognize() to OCR a document. What is happening and how can I fix it?

Sample case: I have a large PDF I was processing page-by-page. The first 15 pages took six minutes, but the 16th page took three minutes and produced that error.

Answer

API_HARDTIMEOUT_ERR can occur when ImageGear has taken too long to process your document. This tends to happen when the OCR process is spending too much time on things it thinks are characters (very common in bitonal documents), such as, scan artifacts in damaged documents, visual marks (e.g, the distortion of a camera picture of a computer monitor), or other marks that the recognition engine would waste time on because it thinks they’re letters. See the bottom of this page for an example.

For scanned bitonal documents, running a Despeckle operation on the page can help reduce the amount of noise obstructing the OCR process.

ImGearRasterPage igRasterPage = p.Rasterize(1, 300, 300);
if (ImGearRasterProcessing.Verifier.CanApplyDespeckle(igRasterPage))
    ImGearRasterProcessing.Despeckle(igRasterPage, 3, 3);

Also, if converting documents to bitonal is part of the document process, ImageGear .NET has reducing methods that may make for a less damaged document, such as our Reduce method with configurable parameters. Alternately, the color document could be OCR’d instead with likely better results.

In the past, some users have found some success adjusting some of the time-based parameters in the recognition engine. ImGearRecTradeoff and DecompMethod can be modified to trade-off accuracy for speed during the actual OCR process, and Locate can be used to identify existing text before recognition.

First Google Images result for "Badly Scanned Document"

Question

During the installation of ImageGear for .NET (v23.4 and above), the installer reaches out to Microsoft’s site to download the VC++ redistributable and .NET packages. Which one(s) does it download?

Answer

The ImageGear for .NET installer places the following redistributables onto a system:

In addition to this, the following .NET framework versions are installed:

  • Microsoft .NET Framework 2.x
  • Microsoft .NET Framework 3.0
  • Microsoft .NET Framework 3.5
  • Microsoft .NET Framework 4.0

So, if a system already has all of these installed on it, this should prevent the installer from trying to reach out to download them.

Question

My service is crashing in IIS, and I see an error saying w3wp.exe has crashed in my Event Viewer. Why is my service crashing?

Answer

Normally, when there is an error in the Event Viewer saying that w3wp.exe has crashed, this means that your application pool has crashed. So, by extension, anything running on IIS will stop working. There are many reasons why this could happen, so to find out the root cause, there are a few things that you can do:

  1. Look at the dump file generated by the Event Viewer
    that is tied to this specific error.
  2. Run this file through WinDbg to get a stack trace of the
    error.

These two things should give you the information you need to determine the root cause of the problem. Below is an online article explaining in more detail how to get these two things and possible causes of the crash.

http://blog.whitesites.com/Debugging-Faulting-Application-w3wp-exe-Crashes__634424707278896484_blog.htm

Question

My service is crashing in IIS, and I see an error saying w3wp.exe has crashed in my Event Viewer. Why is my service crashing?

Answer

Normally, when there is an error in the Event Viewer saying that w3wp.exe has crashed, this means that your application pool has crashed. So, by extension, anything running on IIS will stop working. There are many reasons why this could happen, so to find out the root cause, there are a few things that you can do:

  1. Look at the dump file generated by the Event Viewer
    that is tied to this specific error.
  2. Run this file through WinDbg to get a stack trace of the
    error.

These two things should give you the information you need to determine the root cause of the problem. Below is an online article explaining in more detail how to get these two things and possible causes of the crash.

http://blog.whitesites.com/Debugging-Faulting-Application-w3wp-exe-Crashes__634424707278896484_blog.htm

Question

Why do I get a “File Format Unrecognized” exception when trying to load a PDF document in ImageGear .NET?

Answer

You will need to set up your project to include PDF support if you want to work with PDF documents. Add a reference to ImageGear24.Formats.Pdf (if you’re using another version of ImageGear, make sure you’re adding the correct reference). Add the following line of code where you specify other resources:

using ImageGear.Formats.PDF;

Add the following lines of code before you begin working with PDFs:

ImGearFileFormats.Filters.Insert(0, ImGearPDF.CreatePDFFormat());
ImGearPDF.Initialize();

The documentation page linked here shows how to add PDF support to a project.

Question

How do I remove XMP Data from my image using ImageGear .NET?

Answer

When removing XMP data in ImageGear, the simplest way to do this is to set the XMP Metadata node to null, like so:

ImGearSimplifiedMetadata.Initialize(); 
doc.Metadata.XMP = new ImGearXMPMetadataRoot();

Or, you can traverse through the metadata tree and remove each node from the tree:

// Example code. Not thoroughly tested
private static void RemoveXmp(ImGearMetadataTree tree)
{
ArrayList toRemove = new ArrayList();
foreach (ImGearMetadataNode node in tree.Children)
{
    if (node is ImGearMetadataTree)
        RemoveXmp((ImGearMetadataTree)node);

    if (node.Format != ImGearMetadataFormats.XMP)
        continue;

    toRemove.Add(node);
}

foreach (ImGearMetadataNode node in toRemove)
    tree.Children.Remove(node);
}
Question

We are saving files to the PDF/A standard and are running into a few cases where the file cannot be saved as PDF/A by ImageGear .NET. Why is this, and how do we do it properly?

Answer

First, determine whether a PDF document can be converted to PDF/A by creating an ImGearPDFPreflight object from your document, and generating an ImGearPDFPreflightReport object from it:

using (ImGearPDFPreflight preflight = new ImGearPDFPreflight((ImGearPDFDocument)igDocument))
{
    report = preflight.VerifyCompliance(ImGearPDFPreflightProfile.PDFA_1A_2005, 0, -1);
}

The first argument of the VerifyCompliance() method is the standard of PDF/A you want to use. ImageGear .NET is currently able to convert documents to adhere to the PDF/A-1A and PDF/A-1B standards:

PDF/A-1 Standard

ImageGear and PDF/A

There are parts of the PDF/A-2 and PDF/A-3 standards which may allow for more documents to be converted, but ImageGear .NET currently does not support those. This could possibly be why your document cannot be converted in ImageGear .NET.

Once the report is generated, you can access its Status, which will tell you if the document is fixable. You can also access its Code which will let you know if it’s a fixed page or if it has issues; it will return Success if fixed, or some error code otherwise. You can check these conditions to determine whether it’s worth attempting to convert the document:

// If the document is not already PDFA-1a compliant but can be converted
if ((report.Code == ImGearPDFPreflightReportCodes.SUCCESS) ||
(report.Status == ImGearPDFPreflightStatusCode.Fixable))
{
    ImGearPDFPreflightConvertOptions pdfaOptions = new ImGearPDFPreflightConvertOptions(ImGearPDFPreflightProfile.PDFA_1A_2005, 0, -1);
    ImGearPDFPreflight preflight = new ImGearPDFPreflight((ImGearPDFDocument)igDocument);
    preflight.Convert(pdfaOptions);
    saveFile(outputPath, igDocument);
}

// Create error message if document was not converted.
else if (report.Status != ImGearPDFPreflightStatusCode.Fixed)
{
    printAllRecordDescriptions(report);
    throw new ApplicationException("Given PDF document cannot be converted to PDFA-1a standard.");
}

If you want more information on why a document may not be convertible, you can access the preflight report for its records and codes. A preflight’s "Records" member is a recursive list of preflight reports. A preflight report will have a list of reports under Records, and each of those reports may have more reports, etc. You can recursively loop through them as seen below to output every reason a document is not convertible:

    private static void printAllRecordDescriptions(StreamWriter file, ImGearPDFPreflightReport report)
    {
        foreach (ImGearPDFPreflightReport rep in report.Records)
        {
            file.WriteLine(rep.Description);
            file.WriteLine(rep.Code.ToString() + "\r\n");
            printAllRecordDescriptions(file, rep);
        }
    }

Ultimately, the failure of a document to convert to PDF/A is non-deterministic. While some compliance failures can be corrected, in combination they may not be correctable. Therefore, the unfortunate answer is that to determine if it can be converted, conversion must be attempted.

Question

How do I use a Network Drive path for Image and ART storage in my ImageGear .NET web application?

Answer

In an ImageGear .NET web application, you have to define the location of the images and annotations directory in the storageRootPath and artStorageRootPath configuration property.
In the current version of ImageGear .NET, the storageRootPath and artStorageRootPath do not work with a network drive path \\SERVER-NAME\sharefilename.

The workaround for this would be to create a Symbolic link from a local directory to the network drive directory.

  • To create a symbolic link: Open “Command Prompt” as Administrator and type in > mklink /d "local path" \\SERVER-NAME\sharefilename
  • Pass in the path of the symbolic link as image or art storage root path in your web.config: storageRootPath="local path" artStorageRootPath="local path"
Question

I want to re-arrange the page order of a PDF. I’ve tried the following…

var page = imGearDocument.Pages[indx].Clone();

imGearDocument.Pages.RemoveAt(indx); //// Exception: "One or more pages are in use and could not be deleted."

imGearDocument.Pages.Insert(newIndx, page);

But an exception is thrown. Somehow, even though the page was cloned, the exception states that the page can’t be removed because it’s still in use.

What am I doing wrong here?

Answer

If you’re using an older version of ImageGear .NET, you may run into this exception when you clone the page. Some of the resources between the original and the clone are still shared, which is why this happens.

Starting with ImageGear .NET v24.8, this no longer happens, and the above code should work fine.

If you still need to use the earlier version, you can use the InsertPages method instead.

Question

ImageGear .NET v24.6 added support for viewing PDF documents with XFA content. I’m using v24.8, and upon trying to open an XFA PDF, I get a SEHException for some reason…

SEHException

Why might this be happening?

Answer

One reason could be because you need to execute the following lines after initializing the PDF component, and prior to loading an XFA PDF:

// Allow opening of PDF documents that contain XFA form data.
IImGearFormat pdfFormat = ImGearFileFormats.Filters.Get(ImGearFormats.PDF);
pdfFormat.Parameters.GetByName("XFAAllowed").Value = true;

This will enable XFA PDFs to be opened by the ImageGear .NET toolkit.

Question

For ImageGear .NET, what are the feature differences between an OCR Standard license, an OCR Plus license, and an OCR Asian license?

https://www.accusoft.com/products/imagegear-collection/imagegear-dot-net/#pricing

Answer

ImageGear’s OCR library has three different functionality options that you can choose for your website or application. The primary difference between the three options is the output formats created by the OCR engine. The options for your development are as follows:

  1. OCR Standard:
    The standard edition creates output formats for Western languages such as English. The standard edition outputs text only files and generates a PDF. The file formats it includes are searchable text PDFs and text documents.

  2. OCR Plus:
    The standard plus edition creates formatted outputs for Western languages like English. The formatted output is created with recognition technology that identifies font detail, locates image zones, and recognizes table structure in order to create a representation of the original document. The file formats it includes are Word, Excel, HTML, searchable PDF, and text documents.

  3. OCR Asian:
    The Asian edition creates a formatted output for Asian languages like Chinese, Japanese, and Korean. This formatted output is created with the same recognition technology as the Standard Plus that identifies font detail, locates image zones, and recognizes table structure. It also creates a representation of the original file. Formats include Word, Excel, HTML, searchable PDF, and text documents.