Using Rulers in Annotation Objects

(Document and Medical Imaging toolkits)

The following annotation objects utilize one or more rulers as part of the annotation:

ANNOBJECT_CROSSPRODUCT

ANNOBJECT_POLYRULER

ANNOBJECT_PROTRACTOR

ANNOBJECT_RULER

In addition, the Automation object (ANNOBJECT_AUTOMATION) stores default ruler settings along with the other object default settings.

To determine the unit of measure for each ruler as well as its precision, call the L_AnnGetUnit function. The default unit of measure for ruler, polyruler, and crossproduct objects is smart English. With the smart units, the unit changes with the length. For example, if the length is 11 inches (assuming the default precision of 2 is being used), "11.00 in" displays whereas if the length is 15 inches, "1 ft 3.00 in" displays. Call the L_AnnSetUnit function to set the unit of measurement and its precision for the ruler. The precision indicates how many digits to display to the right of the decimal point in the length.

There are two functions that can be used to get the length of a ruler: the L_AnnGetDistance function and the L_AnnGetDistance2 function. The L_AnnGetDistance function can be used with up to 2 rulers, whereas the L_AnnGetDistance2 function can be used on any of the ruler objects. Call the L_AnnGetDistance2 function to get the length of all the rulers in an ANNOBJECT_POLYRULER object. If the annotation object is type ANNOBJECT_CROSSPRODUCT, ANNOBJECT_PROTRACTOR or ANNOBJECT_POLYRULER, the L_AnnGetDistance2 function provides more information on the length of each ruler, the number of rulers, the unit of measure of each ruler and the total length of all rulers. The L_AnnGetDistance2 function is meant to replace the L_AnnGetDistance function, which is being phased out.

At each end of the ruler is a perpendicular line called a gauge. Use the L_AnnSetGaugeLength function to set the length of the gauge. The length is expressed in pixels, not in points. The length extends from one end point of the gauge, through the end point of the ruler, to the other end point of the gauge. Use the L_AnnGetGaugeLength function to get the length of the gauge.

There are two functions that can be used to calibrate a ruler: L_AnnCalibrateRuler and L_AnnCalibrateRulerSuccessive. For more information, refer to Calibrating Annotation Ruler Objects.

Along the length of the ruler are tic marks. The tic marks are the perpendicular lines that measure the units. The length of these tick marks can be set using the L_AnnSetTicMarkLength function The length of the tic mark is expressed in pixels, not in points. Call the L_AnnGetShowFlags function to determine how the rulers are being displayed. Call the L_AnnSetShowFlags function to set whether ruler length, gauge and tic marks will be displayed.

Please note that when loading or pasting Automation objects or any objects that use rulers from the clipboard, it is necessary to call the L_AnnSetBitmapDpiY function and set the vertical Bitmap DPI value to the bitmap's Y resolution. Likewise, call the L_AnnSetBitmapDpiX function and set the horizontal Bitmap DPI value to the bitmap's X resolution. Doing so ensures that the distances shown by the ruler objects will be accurate.