LEADTOOLS Image File Support (Leadtools.Codecs assembly) Send comments on this topic. | Back to Introduction - All Topics | Help Version 17.0.3.29
CodecsRasterizeDocumentLoadOptions Class
See Also  Members  
Leadtools.Codecs Namespace : CodecsRasterizeDocumentLoadOptions Class



Contains set options for loading a document file as a raster image (rasterization).

Object Model

CodecsRasterizeDocumentLoadOptions Class

Syntax

Visual Basic (Declaration) 
Public Class CodecsRasterizeDocumentLoadOptions
Visual Basic (Usage)Copy Code
Dim instance As CodecsRasterizeDocumentLoadOptions
C# 
public class CodecsRasterizeDocumentLoadOptions
C++/CLI 
public ref class CodecsRasterizeDocumentLoadOptions

Example

For an example, refer to CodecsPdfOptions.

This example will load a PDF document using different rasterize document options and show its effect on the result raster image width, height and resolution.

Visual BasicCopy Code
Public Sub RasterizeDocumentExample()
      ' Unlock support for loading raster PDF files
      RasterSupport.Unlock(RasterSupportType.PdfRead, "Your key here")
      ' Initialize the RasterCodecs object to use
      Dim codecs As New RasterCodecs()

      ' Enable using the RasterizeDocumentOptions
      Dim rasterizeDocumentLoadOptions As CodecsRasterizeDocumentLoadOptions = codecs.Options.RasterizeDocument.Load
      rasterizeDocumentLoadOptions.Enabled = True

      ' No margins (only used with RTF and TXT files)
      rasterizeDocumentLoadOptions.LeftMargin = 0
      rasterizeDocumentLoadOptions.TopMargin = 0
      rasterizeDocumentLoadOptions.RightMargin = 0
      rasterizeDocumentLoadOptions.BottomMargin = 0

      ' The PDF file we are testing. This could be an XPS, RTF, TXT or XLS file as well
      Dim imageFileName As String = Path.Combine(LEAD_VARS.ImagesDir, "Leadtools.pdf")

      ' Show the file information
      Using imageInfo As CodecsImageInfo = codecs.GetInformation(imageFileName, True)
         Dim documentImageInfo As CodecsDocumentImageInfo = imageInfo.Document

         ' If this is a document file, show the document information
         If documentImageInfo.IsDocumentFile Then
            Console.WriteLine("Document file")
            Console.WriteLine("  Original size is: {0} by {1} {2}", _
               documentImageInfo.PageWidth, documentImageInfo.PageHeight, documentImageInfo.Unit)

            Console.WriteLine("  Using current rasterization, load size will be: {0} by {1} pixels at {2} by {3}", _
               imageInfo.Width, imageInfo.Height, imageInfo.XResolution, imageInfo.YResolution)
         Else
            ' Regular raster image, show the image information
            Console.WriteLine("Raster file")
            Console.WriteLine("  Original size is: {0} by {1} pixels at {2} by {3}", _
               imageInfo.Width, imageInfo.Height, imageInfo.XResolution, imageInfo.YResolution)
         End If
      End Using

      ' Example 1. Load at original document size at 300 DPI
      rasterizeDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.None
      rasterizeDocumentLoadOptions.XResolution = 300
      rasterizeDocumentLoadOptions.YResolution = 300

      Using image As RasterImage = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1)
         ShowResult(codecs, image)
      End Using

      ' Example 2. Fit the document at 640 by 480 pixels at 96 DPI keeping the aspect ratio
      rasterizeDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.Fit
      rasterizeDocumentLoadOptions.PageWidth = 640
      rasterizeDocumentLoadOptions.PageHeight = 480
      rasterizeDocumentLoadOptions.Unit = CodecsRasterizeDocumentUnit.Pixel
      rasterizeDocumentLoadOptions.XResolution = 96
      rasterizeDocumentLoadOptions.YResolution = 96

      Using image As RasterImage = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1)
         ShowResult(codecs, image)
      End Using

      ' Example 3. Fit the document at 8.5 by 11 inches at 96 DPI keeping the aspect ratio
      rasterizeDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.Fit
      rasterizeDocumentLoadOptions.PageWidth = 8.5
      rasterizeDocumentLoadOptions.PageHeight = 11
      rasterizeDocumentLoadOptions.Unit = CodecsRasterizeDocumentUnit.Inch
      rasterizeDocumentLoadOptions.XResolution = 300
      rasterizeDocumentLoadOptions.YResolution = 300

      Using image As RasterImage = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1)
         ShowResult(codecs, image)
      End Using

      ' Example 4. Stretch the image to always be 4 by 4 inches at 150 DPI. Aspect ratio may differ
      rasterizeDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.Stretch
      rasterizeDocumentLoadOptions.PageWidth = 4
      rasterizeDocumentLoadOptions.PageHeight = 4
      rasterizeDocumentLoadOptions.Unit = CodecsRasterizeDocumentUnit.Inch
      rasterizeDocumentLoadOptions.XResolution = 150
      rasterizeDocumentLoadOptions.YResolution = 150

      Using image As RasterImage = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1)
         ShowResult(codecs, image)
      End Using

      codecs.Dispose()
   End Sub

   Private Shared Sub ShowResult(ByVal codecs As RasterCodecs, ByVal image As RasterImage)
      Dim rasterizeDocumentLoadOptions As CodecsRasterizeDocumentLoadOptions = codecs.Options.RasterizeDocument.Load

      Console.WriteLine("Showing result..")
      Console.WriteLine("  Current rasterization options:")
      Console.WriteLine("    Size mode is: {0}", rasterizeDocumentLoadOptions.SizeMode)
      Console.WriteLine("    Page size is {0} by {1} {2}", _
         rasterizeDocumentLoadOptions.PageWidth, rasterizeDocumentLoadOptions.PageHeight, rasterizeDocumentLoadOptions.Unit)
      Console.WriteLine("    Resolution is {0} by {1}", _
         rasterizeDocumentLoadOptions.XResolution, rasterizeDocumentLoadOptions.YResolution)

      Console.WriteLine("  Loaded raster image size is: {0} by {1} at {2} by {3}", _
         image.ImageWidth, image.ImageHeight, image.XResolution, image.YResolution)

      ' Code to verify our results

      ' Get the suggested page width and height in pixels
      Dim pageWidthInPixels As Double
      Dim pageHeightInPixels As Double

      Select Case rasterizeDocumentLoadOptions.Unit
         Case CodecsRasterizeDocumentUnit.Inch
            pageWidthInPixels = rasterizeDocumentLoadOptions.PageWidth * rasterizeDocumentLoadOptions.XResolution
            pageHeightInPixels = rasterizeDocumentLoadOptions.PageHeight * rasterizeDocumentLoadOptions.YResolution

         Case CodecsRasterizeDocumentUnit.Millimeter
            pageWidthInPixels = rasterizeDocumentLoadOptions.PageWidth * rasterizeDocumentLoadOptions.XResolution * 25.400000025908
            pageHeightInPixels = rasterizeDocumentLoadOptions.PageHeight * rasterizeDocumentLoadOptions.YResolution * 25.400000025908

         Case CodecsRasterizeDocumentUnit.Pixel
            pageWidthInPixels = rasterizeDocumentLoadOptions.PageWidth
            pageHeightInPixels = rasterizeDocumentLoadOptions.PageHeight
      End Select

      ' Verify
      Select Case rasterizeDocumentLoadOptions.SizeMode
         Case CodecsRasterizeDocumentSizeMode.Fit, CodecsRasterizeDocumentSizeMode.FitAlways
            ' The image width/height must not be greater than suggested page width/height
            Console.WriteLine("Image width/height must be less than or equal to page width/height")
            System.Diagnostics.Debug.Assert(image.ImageWidth <= pageWidthInPixels)
            System.Diagnostics.Debug.Assert(image.ImageHeight <= pageHeightInPixels)

         Case CodecsRasterizeDocumentSizeMode.FitWidth
            ' The image width must be equal to the suggested page width
            Console.WriteLine("Image width must be equal to page width")
            System.Diagnostics.Debug.Assert(image.ImageWidth = pageWidthInPixels)

         Case CodecsRasterizeDocumentSizeMode.Stretch
            ' The image width/height must be equal to the suggested page width/height
            Console.WriteLine("Image width/height must be equal to suggested page width/height")
            System.Diagnostics.Debug.Assert(image.ImageWidth = pageWidthInPixels)
            System.Diagnostics.Debug.Assert(image.ImageHeight = pageHeightInPixels)

         Case CodecsRasterizeDocumentSizeMode.None
            Console.WriteLine("Loading at original document page size")
            ' No checking
      End Select
   End Sub

Public NotInheritable Class LEAD_VARS
   Public Const ImagesDir As String = "C:\Users\Public\Documents\LEADTOOLS Images"
End Class
C#Copy Code
public void RasterizeDocumentExample()
   {
      // Unlock support for loading raster PDF files
      RasterSupport.Unlock(RasterSupportType.PdfRead, "Your key here");
      // Initialize the RasterCodecs object to use
      RasterCodecs codecs = new RasterCodecs();

      // Enable using the RasterizeDocumentOptions
      CodecsRasterizeDocumentLoadOptions rasterizeDocumentLoadOptions = codecs.Options.RasterizeDocument.Load;
      rasterizeDocumentLoadOptions.Enabled = true;

      // No margins (only used with RTF and TXT files)
      rasterizeDocumentLoadOptions.LeftMargin = 0;
      rasterizeDocumentLoadOptions.TopMargin = 0;
      rasterizeDocumentLoadOptions.RightMargin = 0;
      rasterizeDocumentLoadOptions.BottomMargin = 0;

      // The PDF file we are testing. This could be an XPS, RTF, TXT or XLS file as well
      string imageFileName = Path.Combine(LEAD_VARS.ImagesDir,"Leadtools.pdf");

      // Show the file information
      using(CodecsImageInfo imageInfo = codecs.GetInformation(imageFileName, true))
      {
         CodecsDocumentImageInfo documentImageInfo = imageInfo.Document;

         // If this is a document file, show the document information
         if(documentImageInfo.IsDocumentFile)
         {
            Console.WriteLine("Document file");
            Console.WriteLine("  Original size is: {0} by {1} {2}",
               documentImageInfo.PageWidth, documentImageInfo.PageHeight, documentImageInfo.Unit);

            Console.WriteLine("  Using current rasterization, load size will be: {0} by {1} pixels at {2} by {3}",
               imageInfo.Width, imageInfo.Height, imageInfo.XResolution, imageInfo.YResolution);
         }
         else
         {
            // Regular raster image, show the image information
            Console.WriteLine("Raster file");
            Console.WriteLine("  Original size is: {0} by {1} pixels at {2} by {3}",
               imageInfo.Width, imageInfo.Height, imageInfo.XResolution, imageInfo.YResolution);
         }
      }

      // Example 1. Load at original document size at 300 DPI
      rasterizeDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.None;
      rasterizeDocumentLoadOptions.XResolution = 300;
      rasterizeDocumentLoadOptions.YResolution = 300;

      using(RasterImage image = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1))
      {
         ShowResult(codecs, image);
      }

      // Example 2. Fit the document at 640 by 480 pixels at 96 DPI keeping the aspect ratio
      rasterizeDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.Fit;
      rasterizeDocumentLoadOptions.PageWidth = 640;
      rasterizeDocumentLoadOptions.PageHeight = 480;
      rasterizeDocumentLoadOptions.Unit = CodecsRasterizeDocumentUnit.Pixel;
      rasterizeDocumentLoadOptions.XResolution = 96;
      rasterizeDocumentLoadOptions.YResolution = 96;

      using(RasterImage image = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1))
      {
         ShowResult(codecs, image);
      }

      // Example 3. Fit the document at 8.5 by 11 inches at 96 DPI keeping the aspect ratio
      rasterizeDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.Fit;
      rasterizeDocumentLoadOptions.PageWidth = 8.5;
      rasterizeDocumentLoadOptions.PageHeight = 11;
      rasterizeDocumentLoadOptions.Unit = CodecsRasterizeDocumentUnit.Inch;
      rasterizeDocumentLoadOptions.XResolution = 300;
      rasterizeDocumentLoadOptions.YResolution = 300;

      using(RasterImage image = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1))
      {
         ShowResult(codecs, image);
      }

      // Example 4. Stretch the image to always be 4 by 4 inches at 150 DPI. Aspect ratio may differ
      rasterizeDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.Stretch;
      rasterizeDocumentLoadOptions.PageWidth = 4;
      rasterizeDocumentLoadOptions.PageHeight = 4;
      rasterizeDocumentLoadOptions.Unit = CodecsRasterizeDocumentUnit.Inch;
      rasterizeDocumentLoadOptions.XResolution = 150;
      rasterizeDocumentLoadOptions.YResolution = 150;

      using(RasterImage image = codecs.Load(imageFileName, 0, CodecsLoadByteOrder.BgrOrGray, 1, 1))
      {
         ShowResult(codecs, image);
      }

      codecs.Dispose();
   }

   private static void ShowResult(RasterCodecs codecs, RasterImage image)
   {
      CodecsRasterizeDocumentLoadOptions rasterizeDocumentLoadOptions = codecs.Options.RasterizeDocument.Load;

      Console.WriteLine("Showing result..");
      Console.WriteLine("  Current rasterization options:");
      Console.WriteLine("    Size mode is: {0}", rasterizeDocumentLoadOptions.SizeMode);
      Console.WriteLine("    Page size is {0} by {1} {2}",
         rasterizeDocumentLoadOptions.PageWidth, rasterizeDocumentLoadOptions.PageHeight, rasterizeDocumentLoadOptions.Unit);
      Console.WriteLine("    Resolution is {0} by {1}",
         rasterizeDocumentLoadOptions.XResolution, rasterizeDocumentLoadOptions.YResolution);

      Console.WriteLine("  Loaded raster image size is: {0} by {1} at {2} by {3}",
         image.ImageWidth, image.ImageHeight, image.XResolution, image.YResolution);

      // Code to verify our results

      // Get the suggested page width and height in pixels
      double pageWidthInPixels;
      double pageHeightInPixels;

      switch(rasterizeDocumentLoadOptions.Unit)
      {
         case CodecsRasterizeDocumentUnit.Inch:
            pageWidthInPixels = rasterizeDocumentLoadOptions.PageWidth * rasterizeDocumentLoadOptions.XResolution;
            pageHeightInPixels = rasterizeDocumentLoadOptions.PageHeight * rasterizeDocumentLoadOptions.YResolution;
            break;

         case CodecsRasterizeDocumentUnit.Millimeter:
            pageWidthInPixels = rasterizeDocumentLoadOptions.PageWidth * rasterizeDocumentLoadOptions.XResolution * 25.400000025908000026426160026955;
            pageHeightInPixels = rasterizeDocumentLoadOptions.PageHeight * rasterizeDocumentLoadOptions.YResolution * 25.400000025908000026426160026955;
            break;

         case CodecsRasterizeDocumentUnit.Pixel:
         default:
            pageWidthInPixels = rasterizeDocumentLoadOptions.PageWidth;
            pageHeightInPixels = rasterizeDocumentLoadOptions.PageHeight;
            break;
      }

      // Verify
      switch(rasterizeDocumentLoadOptions.SizeMode)
      {
         case CodecsRasterizeDocumentSizeMode.Fit:
         case CodecsRasterizeDocumentSizeMode.FitAlways:
            // The image width/height must not be greater than suggested page width/height
            Console.WriteLine("Image width/height must be less than or equal to page width/height");
            System.Diagnostics.Debug.Assert(image.ImageWidth <= pageWidthInPixels);
            System.Diagnostics.Debug.Assert(image.ImageHeight <= pageHeightInPixels);
            break;

         case CodecsRasterizeDocumentSizeMode.FitWidth:
            // The image width must be equal to the suggested page width
            Console.WriteLine("Image width must be equal to page width");
            System.Diagnostics.Debug.Assert(image.ImageWidth == pageWidthInPixels);
            break;

         case CodecsRasterizeDocumentSizeMode.Stretch:
            // The image width/height must be equal to the suggested page width/height
            Console.WriteLine("Image width/height must be equal to suggested page width/height");
            System.Diagnostics.Debug.Assert(image.ImageWidth == pageWidthInPixels);
            System.Diagnostics.Debug.Assert(image.ImageHeight == pageHeightInPixels);
            break;

         case CodecsRasterizeDocumentSizeMode.None:
         default:
            Console.WriteLine("Loading at original document page size");
            // No checking
            break;
      }
   }

static class LEAD_VARS
{
   public const string ImagesDir = @"C:\Users\Public\Documents\LEADTOOLS Images";
}
SilverlightCSharpCopy Code


SilverlightVBCopy Code


 
            
            
Remarks
LEADTOOLS provides support for loading a document as a raster image. Documents formats such as PDF, XPS, XLS, RTF and Text do not contain physical width, height or resolution. It is up to the loader (in this case, the RasterCodecs object) to specify the transformation from logical coordinates to physical pixels through a process called rasterization.



Rasterization is the process of converting a document to a raster image. To check if a certain file on disk (or in a .NET stream) contains a document file rather than a regular raster image, call the RasterCodecs.GetInformation o RasterCodecs.GetInformationAsync method and check the CodecsDocumentImageInfo.IsDocumentFile property. Here is a code snippet:





    



             CodecsImageInfo imageInfo = rasterCodecsInstance.GetInformation(fileName, true);
             if(imageInfo.Document.IsDocumentFile)
             {
                // A document file (PDF, XPS, rtc), show the original document size:
                Console.WriteLine("Document file, original size is {0} by {1} {2}",
                   imageInfo.Document.PageWidth, imageInfo.Document.PageHeight, imageInfo.Document.Unit);
            
                // Your code specific to rasterization based on the original document size goes here
             }
             




  







To rasterize a document file, set the properties of the CodecsRasterizeDocumentLoadOptions to the required value. For example, the following code snippet will instruct LEADTOOLS to fit any document files into 8.5 by 11 inches at 300 paper size. Every document file loaded with the RasterCodecs.Load or RasterCodecs.LoadAsync methods will have width/height of no more than 2550 by 3300 pixels with a resolution of 300 by 300:





    



             CodecsRasterizeDocumentLoadOptions rasterDocumentLoadOptions = rasterCodecsInstance.Options.RasterizeDocument.Load;
             // Enable rasterization
             rasterDocumentLoadOptions.Enabled = true;
             // Set the size mode, we want to fit
             rasterDocumentLoadOptions.SizeMode = CodecsRasterizeDocumentSizeMode.Fit;
             // Set the page size
             rasterDocumentLoadOptions.PageWidth = 8.5;
             rasterDocumentLoadOptions.PageHeight = 11;
             rasterDocumentLoadOptions.Unit = CodecsRasterizeDocumentUnit.Inch;
             // And the resolution
             rasterDocumentLoadOptions.XResolution = 300;
             rasterDocumentLoadOptions.YResolution = 300;
            
             // Load the image
             RasterImage image = rasterCodecsInstance.Load(fileName);
            
             // Show its pixel size, it should be less than or equal to
             // 2550 by 3300 pixels (8.5 * 300 by 11 * 300)
             Console.WriteLine("Loaded image size: {0} by {1} pixels at {2} by {3}",
             image.ImageWidth, image.ImageHeight, image.XResolution, image.YResolution);
             




  







The CodecsRasterizeDocumentLoadOptions class contains the following properties:




    
        

            Property

            Description
        


        

            Enabled

            
                
Enable or disable using the current CodecsRasterizeDocumentLoadOptions properties when loading document files. You must set the value of this property to true before using the other members of this class.

            		
        


        

            PageWidth and PageHeight

            
                
The result page width and height (in Unit). The value of the result raster image width and height in pixels depends on the current resolution and size mode values.

            		
        


        

            LeftMargin, TopMargin, RightMargin and BottomMargin

            
                
The size of the margins to leave from the left, top, right and bottom in Unit. Currently, only RTF and TXT documents support margins.

            		
        


        

            Unit

            
                
The units to use for the PageWidth, PageHeight, LeftMargin, TopMargin, RightMargin and BottomMargin values.

            		
        


        

            XResolution and YResolution

            
                
The resolution to use when rasterization the document files. A value of 0 means using the current screen resolution (usually 96). The resolution controls the pixel density of the result raster image. For example, if you specify 8.5 by 11 inches page width and height and a resolution of 96, the result image will have a pixel width and height of (8.5 * 96 = 816) and (11 * 96 = 1056) pixels. This is suitable for viewing at a 100 percent zoom but when you start zooming in, the image will get pixelated. Pixelation may also occur if you send the raster image to a printer, since printers usually have much higher resolution than a screen.


                
If zooming in or high quality printing is a requirement in your code, then a higher resolution value must be specified, for example 300 by 300. For an 8.5 by 11 inch document, this results in a raster image size if (8.5 * 300 = 2550) and (11 * 300 = 3300) pixels. More than suitable for printing or zooming in. Keep in mind that increasing the resolution will increase the memory used to hold the image data. Finding the right balance between pixel density and memory consumption depends on your application needs.

            		
        


        

            SizeMode

            
                
Controls the transformation used when converting the logical size specified in page width and height to the physical raster image size. Refer to CodecsRasterizeDocumentSizeMode for more information.

            		
        

    




The value of CodecsRasterizeDocumentLoadOptions.Enabled is set to false by default in the current version of LEADTOOLS. This is done for backward compatibility and means the current CodecsRasterizeDocumentLoadOptions will not be used when rasterization a document image. You must set the value of this property to true first, before using the rest of the properties of this class. A convenient way of doing this is after instantiating the RasterCodecs object, set enabled property to true:





             RasterCodecs codecs = new RasterCodecs();
             //Use the new RasterizeDocumentOptions
             codecs.Options.RasterizeDocument.Load.Enabled = true;
             







LEADTOOLS will set the default value of CodecsRasterizeDocumentLoadOptions.Enabled to true in the next version so it is recommended you start porting your code to use the new options.



Refer to the C# and VB Rasterize Document Demo that ships with your version of LEADTOOLS for an interactive demonstration of CodecsRasterizeDocumentLoadOptions.

            
Inheritance Hierarchy
System.Object
   Leadtools.Codecs.CodecsRasterizeDocumentLoadOptions
 
            
Requirements
Target Platforms: Silverlight, Windows XP, Windows Server 2003 family, Windows Server 2008 family, Windows Vista, Windows 7, MAC OS/X (Intel Only) 

            
            
See Also