LAnnotation::CalibrateRuler

#include "ltwrappr.h"

L_INT LAnnotation::CalibrateRuler(dCalibrateLength, uCalibrateUnit, dDpiRatioXtoY)

L_DOUBLE dCalibrateLength;

calibrated ruler length

L_UINT uCalibrateUnit;

unit of measurement

L_DOUBLE dDpiRatioXtoY;

ratio of dpiX to dpiY

Calibrates an LAnnRuler annotation object.

Parameter Description
dCalibrateLength Length to be assigned to the ruler.
uCalibrateUnit Unit of measurement. 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.
dDpiRatioXtoY The ratio of the horizontal resolution (dots per inch or DPI) to the vertical resolution. It must be in the range of 1/100 to 100 inclusive. For most images, the ratio is 1.

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

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

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

This function must be enabled by passing OPTIONS_NEW_ CALIBRATE_RULER to the LAnnotation::SetOptions function before calling LAnnotation::CalibrateRuler. For more information, refer to Key Annotation Features.

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 LAnnRuler objects, it can be used indirectly to calibrate any or all ruler objects, including LAnnPolyRuler, LAnnProtractor, and LAnnCrossProduct. To do this, calibrate an LAnnRuler object, get the resulting resolutions, and assign this resolution to all objects in the container. The example illustrates how to do this.

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

Required DLLs and Libraries

LTANN

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

Note to the documentation team: Using Rulers in Annotation Objects is a fairly new programming topic (the edits adding this topic were completed in May of this year.)

Platforms

Win32, x64.

See Also

Functions:

LAnnAutomation::GetBitmapDpiX, LAnnAutomation::GetBitmapDpiY, LAnnAutomation::SetBitmapDpiX, LAnnAutomation::SetBitmapDpiY, LAnnRuler::SetUnit, LAnnRuler::GetUnit, LAnnRuler::GetDistance, LAnnRuler::GetDistance2, LAnnotation::GetOptions, LAnnotation::SetOptions

Topics:

Calibrating Annotation Ruler Objects

 

Annotation Functions: Getting and Setting the Ruler Properties

 

Using Rulers in Annotation Objects

 

Key Annotation Features

Example

L_INT LAnnotation_CalibrateRulerExample(LAnnContainer anncont, LAnnAutomation  annauto, LAnnRuler annruler) 
{ 
   // This example calibrates a ruler object 
   // so that it measures 10 inches with a DPI ratio of 1:1 
   // Note that ruler object must be of type LAnnRuler 
   L_INT nRet = SUCCESS; 
   L_UINT uObjectType = 0; 
   L_DOUBLE dDpiX = 0; 
   L_DOUBLE dDpiY = 0; 
   UNREFERENCED_PARAMETER(dDpiY); 
   UNREFERENCED_PARAMETER(dDpiX); 
   uObjectType = annruler.GetType(); 
   if (uObjectType < ANNOBJECT_CONTAINER) 
      return FAILURE; 
   if (uObjectType!= ANNOBJECT_RULER) 
   { 
      MessageBox(NULL, TEXT("Error: CalibrateRuler  only works on ANNOBJECT_RULER objects"), TEXT("Error"), MB_OK); 
      return FAILURE ; 
   } 
   nRet = annruler.CalibrateRuler(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("Error"), MB_OK); 
   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++ Class Library Help
Introduction
Version History
Getting Started
LEADTOOLS Raster Imaging Features
Redistributables/Files To Be Included With Your Application
Quick Reference
Tutorials
Classes and Member Functions
Call Back Functions
Summary of Features