#include "l_bitmap.h"

L_LTANN_API L_INT L_AnnCalibrateRulerSuccessive (hObject, dCalibrateLength, uCalibrateUnit)


handle to an ANNOBJECT_RULER object

L_DOUBLE dCalibrateLength;

length to assign to the ruler

L_UINT uCalibrateUnit;

units of the length

Calibrates an ANNOBJECT_RULER annotation object.

Parameter Description
hObject Handle to an ANNOBJECT_RULER object.
dCalibrateLength Length to be assigned to the ruler.
uCalibrateUnit Units of the length. Possible values are:
  Value Meaning
  ANNUNIT_INCHES [0] Inches.
  ANNUNIT_FEET [1] Feet.
  ANNUNIT_YARDS [2] Yards.
  ANNUNIT_MICROMETERS [3] Micrometers.
  ANNUNIT_MILLIMETERS [4] Millimeters.
  ANNUNIT_CENTIMETERS [5] Centimeters.
  ANNUNIT_METERS [6] Meters.



The function was successful.

< 1

An error occurred. Refer to Return Codes.


Use this function in conjunction with L_AnnCalibrateRuler 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 L_AnnCalibrateRuler.

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.  Note that when using this method, the two ruler calibrations can be on ruler(s) of ANY angle.  The only requirement the two calibrations must be on rulers that do not have the same orientation (angle between the ruler and the X-axis).

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.

Required DLLs and Libraries


For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.


Win32, x64.

See Also


L_AnnCalibrateRuler L_AnnGetBitmapDpiX, L_AnnGetBitmapDpiY, L_AnnSetBitmapDpiX, L_AnnSetBitmapDpiY, L_AnnSetUnit, L_AnnGetUnit, L_AnnGetDistance, L_AnnGetDistance2, L_AnnSetOptions, L_AnnGetOptions


Calibrating Annotation Ruler Objects


Annotation Functions:Getting and Setting Ruler Properties


Annotation Features


This example calibrates all annotation ruler objects without specifying a DPI Ratio. This is done by calibrating a ruler twice. The first calibration is horizontal, 200 pixels in length, and with the width set to 2 inches. The second calibration is vertical, 200 pixels in length, and with the width set to have a length of 1 inch. The resulting rulers have a horizontal resolution of 100, and a vertical resolution of 200.

L_INT AnnCalibrateRulerSuccessiveExample(HANNOBJECT hContainer, 
HANNOBJECT hAutomation) 
   L_INT    nRet = SUCCESS; 
   HANNOBJECT hRuler = 0; 
   // Create the ruler -- set it horizontal, length of 200 pixels 
   L_AnnCreate(ANNOBJECT_RULER, &hRuler); 
   ANNPOINT aptH[2] = {100,100, 300, 100}; 
   L_AnnSetPoints(hRuler, aptH, 2); 
   L_AnnInsert(hContainer, hRuler, FALSE); 
   // Calibrate the horizontal ruler for a length of two inches 
   L_AnnCalibrateRuler(hRuler, 2, ANNUNIT_INCHES, 1.0);  // it does not matter what is passed for the last argument 
   // Move the ruler so that it is vertical 
   ANNPOINT aptV[2] = {100,100,100,300}; 
   L_AnnSetPoints(hRuler, aptV, 2); 
   // Calibrate the vertical ruler for a length of one inch 
   L_AnnCalibrateRulerSuccessive(hRuler, 1, ANNUNIT_INCHES);  // it does not matter what is passed for the last argument 
   L_DOUBLE dDpiX = 0; 
   L_DOUBLE dDpiY = 0; 
   nRet = L_AnnGetBitmapDpiX (hRuler, &dDpiX); 
   if(nRet != SUCCESS) 
      return nRet; 
   nRet = L_AnnGetBitmapDpiY (hRuler, &dDpiY); 
   if(nRet != SUCCESS) 
      return nRet; 
   MessageBox(NULL, TEXT("Now all existing and newly created ruler objects will be matched to this calibration."), TEXT("Notice"), MB_OK); 
   // 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; 

Help Version 19.0.2017.10.27
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.
LEADTOOLS Raster Imaging C API Help