L_AnnCalibrateRuler

#include "l_bitmap.h"

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

HANNOBJECT hObject;	/* handle to an ANNOBJECT_RULER object */
L_DOUBLE dCalibrateLength;	/* length to assign to the ruler */
L_UINT uCalibrateUnit;	/* units of the length */
L_DOUBLE dDpiRatioXtoY;	/* ratio of dpiX to dpiY */

Calibrates an ANNOBJECT_RULER annotation object. This function is available in the Document/Medical Toolkits.

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.
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 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.

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

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.

Platforms

Windows 95 / 98 / Me, Windows 2000 / XP.

See Also

Functions:	L_AnnGetBitmapDpiX, L_AnnGetBitmapDpiY, L_AnnSetBitmapDpiX, L_AnnSetBitmapDpiY, L_AnnSetUnit, L_AnnGetUnit, L_AnnGetDistance, L_AnnGetDistance2, L_AnnSetOptions, L_AnnGetOptions
Topics:	Calibrating Annotation Ruler Objects
	Annotation Functions:Getting and Setting Ruler Properties
	New Annotation Features of Version 14.5

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 of type ANNOBJECT_RULER
// It then sets this calibration to ALL ruler objects
// (ANNOBJECT_RULER, ANNOBJECT_POLYRULER, ANNOBJECT_CROSSPRODUCT, ANNOBJECT_PROTRACTOR)
// in the container.
L_VOID ExampleAnnCalibrateRuler(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;

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

   MessageBox(NULL, "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.", "Error", MB_OK);

   L_AnnGetBitmapDpiX (hObjectRuler, &dDpiX);
   L_AnnGetBitmapDpiY (hObjectRuler, &dDpiY);

   // Match calibration to existing objects in container
   L_AnnSetBitmapDpiX(hContainer, dDpiX, ANNFLAG_RECURSE);
   L_AnnSetBitmapDpiY(hContainer, dDpiY, ANNFLAG_RECURSE);

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