L_AnnCalibrateRulerSuccessive

#include "l_bitmap.h"

L_LTANN_API L_INT L_AnnCalibrateRulerSuccessive (hObject, dCalibrateLength, uCalibrateUnit)

HANNOBJECT hObject;

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

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

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

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 2000 / XP/Vista.

See Also

Functions:

L_AnnCalibrateRuler 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

 

Annotation Features

Example

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 set to have a length of 2 inches. The second calibration is vertical, 200 pixels in length, and set to have a legnth of 1 inch. This result is that the horizizontal resolution of 100, and a vertical resolution of 200.

 L_INT AnnCalibrateRulerSuccessiveExample(HANNOBJECT hContainer,
                                                         HANNOBJECT hAutomation)
{
   L_INT    nRet = SUCCESS;
   HANNOBJECT hRuler = 0;
   WCHAR szMsg[200];

   // 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;

   wsprintf(szMsg, TEXT("Resulting horizontal resolution: %d -- it should be 100"), (int)dDpiX);
   MessageBox(NULL, szMsg,TEXT("Error"), MB_OK); 

   wsprintf(szMsg, TEXT("Resulting vertical  resolution: %d -- it should be 200"), (int)dDpiY);
   MessageBox(NULL, szMsg,TEXT("Error"), MB_OK); 

   MessageBox(NULL, TEXT("Now all existing and newly created ruler objects will be matched to this calibration."), TEXT("Error"), 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;
}