L_AnnCalibrateRuler

#include "l_bitmap.h"

L_LTANN_API L_INT L_AnnCalibrateRuler (hObject, dCalibrateLength, uCalibrateUnit, dDpiRatioXtoY)

Calibrates an ANNOBJECT_RULER annotation object.

Returns

Comments

Call this function to calibrate an ANNOBJECT_RULER object. This function is used to assign any existing ANNOBJECT_RULER object to a specific length.

Note that this function only works on ANNOBJECT_RULER objects, but can be used to indirectly calibrate other objects.

Calibrating the ANNOBJECT_RULER annotation object can be accomplished in two different ways:

1. Specifying one ruler length and a DPI ratio.  This is accomplished by calling L_AnnCalibrateRuler. For more on the DPI ratio, see the comments below.

2. Specifying two ruler lengths.  This is accomplished first by calling L_AnnCalibrateRuler (specifying 1.0 for the dDpiRatioXtoY parameter), changing the orientation of the ruler, and then calling L_AnnCalibrateRulerSuccessive.  Typically, this method is used when a user wants to calibrate a ruler by a horizontal calibration, followed by a vertical calibration.  For details, see L_AnnCalibrateRulerSuccessive.

The dDpiRatioXtoY is the ratio of the horizontal resolution of the image (dots per inch or DPI) to the vertical resolution of the image. For most images, the horizontal resolution and the vertical resolution are the same, so this value will be 1.0. However for some fax images, the horizontal resolution is twice the vertical resolution (this would correspond to a dDpiRatioXtoY of 2.0). The dDpiRatioXtoY must be between (1/100) and 100 inclusive.

While this function only works on ANNOBJECT_RULER objects, it can be used indirectly to calibrate any or all ruler objects, including ANNOBJECT_POLYRULER, ANNOBJECT_CROSSPRODUCT, and ANNOBJECT_POLYRULER. To do this, calibrate an ANNOBJECT_RULER object, get the resulting resolutions, and assign this resolution to all objects in the container. The example illustrates how to do this.

If you passed a negative value to the dDpiRatioXtoY parameter, the ERROR_INV_PARAMETER error will be returned.

Required DLLs and Libraries

Platforms

Win32, x64.

See Also

Example

This example calibrates a ruler object (hObject) so that it measures 10 inches with a DPI ratio of 1:1. Note that hObject must be an ANNOBJECT_RULER type. It then sets this calibration to ALL ruler objects (ANNOBJECT_RULER, ANNOBJECT_POLYRULER, ANNOBJECT_CROSSPRODUCT, and ANNOBJECT_PROTRACTOR) in the container.

 L_INT AnnCalibrateRulerExample(HANNOBJECT hContainer,
                                               HANNOBJECT hAutomation,
                                               HANNOBJECT hObjectRuler)
{
   L_INT    nRet = SUCCESS;
   L_UINT   uObjectType = 0;
   L_DOUBLE dDpiX = 0;
   L_DOUBLE dDpiY = 0;

   nRet = L_AnnGetType(hObjectRuler, &uObjectType);
   if (nRet != SUCCESS) 
      return nRet; 

   if (uObjectType!= ANNOBJECT_RULER) 
   {
      MessageBox(NULL, TEXT(" Error:  L_AnnCalibrateRuler only works on ANNOBJECT_RULER objects"), TEXT("Error"), MB_OK); 
      return 0; 
   }
   nRet = L_AnnCalibrateRuler(hObjectRuler, 10, ANNUNIT_INCHES, 1.0); 
   if (nRet != SUCCESS) 
      return nRet; 

   MessageBox(NULL, TEXT("Ruler has been calibrated to have a length of 10 inches.  Now all existing and newly created ruler objects will be matched to this calibration."), TEXT("Notice"), MB_OK); 


   nRet = L_AnnGetBitmapDpiX (hObjectRuler, &dDpiX); 
   if(nRet != SUCCESS)
      return nRet;
   nRet = L_AnnGetBitmapDpiY (hObjectRuler, &dDpiY); 
   if(nRet != SUCCESS)
      return nRet;

   // Match calibration to existing objects in container
   nRet = L_AnnSetBitmapDpiX(hContainer, dDpiX, ANNFLAG_RECURSE); 
   if(nRet != SUCCESS)
      return nRet;
   nRet = L_AnnSetBitmapDpiY(hContainer, dDpiY, ANNFLAG_RECURSE); 
   if(nRet != SUCCESS)
      return nRet;

   // Set automation defaults so that all newly created objects have this calibration
   nRet = L_AnnSetBitmapDpiX(hAutomation, dDpiX, ANNFLAG_RECURSE); 
   if(nRet != SUCCESS)
      return nRet;
   nRet = L_AnnSetBitmapDpiY(hAutomation, dDpiY, ANNFLAG_RECURSE); 
   if(nRet != SUCCESS)
      return nRet;
   return SUCCESS;
}