UseDpi Property

get_useDpi();
set_useDpi(value);
Object.defineProperty('useDpi');

Property Value

Changing the value of this property will fire the PropertyChanged and TransformChanged events.

The physical resolution of an image is measured in dots per inch (DPI). The values of ImageDpiX, ImageDpiY, ScreenDpiX and ScreenDpiY are used when calculating how to display the image if the value of UseDpi is set to true.

For example, a typical A4 document image is 8.5 by 11 inches. Which could be 2550 by 3300 pixels if the image has a resolution of 300 by 300. Most document viewer applications will try to display this image in its original size. i.e. the image will take 8.5 inches of screen horizontal space and 11 inches of screen vertical space. If you do not use the UseDpi property for this control, you are required to do the calculations yourself as follows:

            viewer.set_useDpi(false);
            viewer.set_scaleFactor = screenResolution / imageResolution;
            

In the case of the image above, this will be 96 (typical screen resolution) divided by 300. Or, you can set the UseDpi value to true and the control will use the above formula internally keeping the ScaleFactor set to 1 as follows:

            viewer.set_useDpi(true);
            viewer.set_scaleFactor = 1;
            

This code will produce the same results as the first code snippet.

The viewer will not automatically set the values of ImageDpiX, ImageDpiY, ScreenDpiX and ScreenDpiY to the current image and screen resolution, instead, these values will all be set to the default value of 96. You must set these values to the correct values if the UseDpi is to be used correctly.

For the image resolution (ImageDpiX and ImageDpiY), Use the LEADTOOLS REST services to obtain this value, refer to the LEADTOOLS HTML 5 Viewer Demo for an example.

For the screen resolution (ScreenDpiX and ScreenDpiY), there is no easy way to get these values in JavaScript/HTML. You must instruct the user to enter these values manually or use the default values of 96.

When UseDpi is set to false, the values of ImageSize and RealImageSize will be the same (the size of the image in pixels). When UseDpi is set to true, the values of ImageSize and RealImageSize might not be the same as the image or screen DPI. ImageSize will have the original size in pixels while RealImageSize will contain the size multiplied by a ratio between screen and image sizes.

Start with the ImageViewer example, remove all the code inside the example function (search for the "// TODO: add example code here" comment) and insert the following code:

Open the HTML page in your browser, now as you click the Example button, the UseDpi value will be flipped and the image size and real image size values are shown. Note that if you replace PngImage.png with a typical 8.5 by 11 at 300 DPI document image (such as Ocr1.tif), and use it in the demo, then you will see that when UseDpi is true, the image will be exactly 8.5 by 11 inches when displayed in a desktop browser (if the screen resolution is the default value of 96).

example: function SiteLibrary_DefaultPage$example(viewer) {
   var exampleLabel = document.getElementById("exampleLabel");

   // Check if UseDpi is set to true
   if(!viewer.get_useDpi()) {
      // No, set it to true
      // Also set the image DPI to 300 and the screen DPI to 96
      viewer.beginUpdate();
      viewer.set_imageDpiX(300);
      viewer.set_imageDpiY(300);
      viewer.set_screenDpiX(96);
      viewer.set_screenDpiY(96);
      viewer.set_useDpi(true);
      viewer.endUpdate();
   } else {
      // Yes, set it back to false
      viewer.set_useDpi(false);
   }

   // Show the image and real image sizes
   var imageSize = viewer.get_imageSize();
   var realImageSize = viewer.get_realImageSize();

   var content = "UseDPI: " + viewer.get_useDpi();
   content += " Image size: " + imageSize.get_width() + ", " + imageSize.get_height();
   content += " Real image size: " + realImageSize.get_width() + ", " + realImageSize.get_height();
   exampleLabel.textContent = content;
},