Applying Actions

Actions are processes that can be applied to the images attached to cells within the container/image viewer. LEADTOOLS supports several standard or "built-in" actions and custom or "user-defined" actions.

Features of Version 16 and above:

General

Support has been added for the following built-in actions:

Nudge tool region: expands the region border using the mouse. Also serves as a region painter.
Shrink tool region: shrinks the region border using the mouse.

Action Behaviors

Nudge tool: Click and drag to expand the region.
Shrink tool: Click and drag to shrink the region.

Window Levels

Set default values either by using L_DispContainerGetDefaultWindowLevelValues or have them calculated internally when the images are first set in the control using either L_DispContainerSetCellBitmapList or L_DispContainerSetRequestedImage (when the low memory usage feature is enabled). For more information about the low memory usage feature, refer to the L_DispContainerEnableCellLowMemoryUsage function. To reset the window level values to the default values call L_DispContainerResetWindowLevelValues.

To get the default window level values, call L_DispContainerSetDefaultWindowLevelValues.

To get the current window level values call L_DispContainerGetActionProperties. To set the current window level values call L_DispContainerSetActionProperties.

Fitting an Image to a Cell

Currently, there are two ways to fit an image to a cell. One is by setting the bIsFit value of the DISPCELLPROPERTIES structure to true (also remembering to set the corresponding uMask value), and then send this structure to the function L_DispContainerSetCellProperties. The other method is by using the L_DispContainerGetCellScale and L_DispContainerSetCellScale functions. If using these make sure that bIsFit is set to FALSE.

To set the scale of a cell or sub-cell call L_DispContainerSetCellScale, and to set the properties of the scale action use the L_DispContainerSetActionProperties function. To retrieve the properties of the scale action use the L_DispContainerGetActionProperties function. To set the scale mode of a cell or sub-cell call the L_DispContainerSetCellScaleMode function and to get it call L_DispContainerGetCellScaleMode.

Low Memory Usage

Take advantage of the viewers low memory usage feature by calling L_DispContainerEnableCellLowMemoryUsage. When enabled, the viewer only loads the frames that are currently visible on the cell at runtime, instead of all of the frames. Call L_DispContainerGetLowMemoryUsageCallBack to get a callback function which will be fired every time the control requests a new frame when the low memory usage feature is enabled. When frames are requested, send them to the control by using L_DispContainerSetRequestedImage. Call L_DispContainerSetLowMemoryUsageCallBack to set the current frames request callback function. To set the values necessary for the medical viewer to function properly when the low memory usage feature is enabled, call L_DispContainerSetBitmapListInfo.

Features of Version 15 and above:

Built-in Actions

LEADTOOLS supports the following built-in actions:

Window Leveling: Maps grayscale intensities using a user defined color map (LUT).
Alpha: A window-leveling factor used when the window leveling lookup table is not linear.
Scale: Increases or decreases the size of the image in the cell.
Offset: Changes the offset of the image within the cell.
Magnifying Glass: Magnifies the image in the cell.
Stack: Scrolls the images within the cell.
Annotation ruler: adds a ruler object to the cell.
Annotation rectangle: adds a rectangular object to the cell.
Annotation ellipse: adds an elliptical object to the cell.
Annotation angle: adds an angle object to the cell.
Annotation highlight: adds a highlight object to the cell.
Annotation arrow: adds an arrow object to the cell.
Annotation text: adds a text object to the cell.
Rectangle region: adds a rectangular region to the cell.
Square region: adds a square region to the cell.
Elliptical region: adds an elliptical region to the cell.
Circular region: adds a circular region to the cell.
Free hand region: adds a free hand region to the cell.
Polygon region: adds a polygonal region to the cell.
Magic Wand region: sets a region based on the color at a selected point, growing outward in all directions from that point. Dragging increases the deviation allowed from the selected color..
Color Range region: adds a color range region to the cell.

Custom Actions

Custom actions are completely controlled by the user, including any mouse movement and keystroke association. These are handled through a DISPCONTAINERACTIONCALLBACK callback function. This callback function must be set by calling L_DispContainerSetActionCallback. To determine the current callback being used to handle custom actions, call L_DispContainerGetActionCallback.

Adding Actions

Regardless of whether the action is built-in or custom, any action first must be added to a container before it can be used. To add an action to a container, call L_DispContainerAddAction, and pass the desired action ID. Since the Image Viewer supports custom actions, there is no limit on how many actions a container can have. However, the same action cannot be added to a container twice. To determine how many actions are currently in a particular container, call L_DispContainerGetActionCount.

Next, assign a mouse button or a keyboard key to the action. To assign a mouse button to the action, call L_DispContainerSetAction, and pass the action and associated mouse button values together. For example, if the Window Level action is assigned to the left mouse button, when the user clicks and hold the mouse button, then drags in any direction, the brightness and contrast of gray image will be changed according to the direction of drag. An action can only be assigned to one mouse button.

To assign a keyboard shortcut to the action use the function L_DispContainerSetKeyboardAction. This allows you to set a keystroke to imitate the mouse movement in any of four ordinal directions. For example, assign the key Shift + Left to initiate the same effect as dragging the mouse to the left. To get the current keystroke combination associated with a specific action, call L_DispContainerGetKeyboardAction.

Once the action has been added, it is considered "active". To determine whether a specific action is active, call L_DispContainerIsActionActive. To check whether the button or the flag is valid to be assigned to the specific action, use the function L_DispContainerIsButtonValid.

The L_DispContainerSetAction function also lets the user decide whether the applied action will affect one cell, selected cells, or all cells in the container, and whether the action is applied during mouse movement or after mouse button release. You can also retrieve the assigned mouse button and flags to the specified action by calling the function L_DispContainerGetActionButton.

Window Levels

Set default values either by using L_DispContainerSetDefaultWindowLevelValues or have them calculated internally when the images are first set in the control using either L_DispContainerSetCellBitmapList or L_DispContainerSetRequestedImage (when the low memory usage feature is enabled). For more information about the low memory usage feature, refer to the function L_DispContainerEnableCellLowMemoryUsage. To reset the window level values to the default values call L_DispContainerResetWindowLevelValues.

To get the default window level values, call L_DispContainerSetDefaultWindowLevelValues.

To get the current window level values call L_DispContainerGetActionProperties. To set the current window level values call L_DispContainerSetActionProperties.

Action Properties

Each action has both general and specific properties. The general properties, like the cursor, are common to all cells within the container. These are applied at the container level. Specific properties, such as the width used by the window level action, are used to manually change values used by the action. These are applied at the cell level. The properties used by each action are contained in an action-specific structure.

Action properties that apply to the entire container can be found in the DISPCONTAINERACTIONPROPS structure. Each of the action-specific structures also contains a DISPCONTAINERACTIONPROPS structure, as well as other properties, related to the specific action. Some of the additional properties related to the specific properties are also applied at the container level and are therefore "general" properties, while others are applied at the cell level and are therefore "specific" properties.

The current properties associated with a specific action can be retrieved by calling L_DispContainerGetActionProperties. To change the properties for a specific action, call L_DispContainerSetActionProperties. When an action is no longer needed in a container, it can be removed by calling L_DispContainerRemoveAction.

Action Behaviors

Window level
- Click and hold the mouse to start the effect. Releasing the assigned mouse button ends the action.
- Dragging the mouse to the left decreases the center parameter.
- Dragging the mouse to the right increases the center parameter.
- Dragging the mouse upward decreases the width parameter.
- Dragging the mouse downward increases the width parameter.
Alpha
- Click and hold the mouse to start the effect. Releasing the assigned mouse button ends the action.
- Dragging the mouse to the left increases the alpha factor.
- Dragging the mouse to the right decreases the alpha factor.
Scale
- Click and hold the mouse to start the effect. Releasing the assigned mouse button ends the action.
- Dragging the mouse downward enlarges the image.
- Dragging the mouse upward shrinks the image.
Magnifying Glass
- Click and hold the mouse to start the effect. The magnifying glass will appear. Releasing the assigned mouse button ends the action.
- Dragging the mouse causes the magnifying glass to move with the cursor.
Stack
- Click and hold the mouse to start the effect. Releasing the assigned mouse button ends the action. It is better to assign the mouse wheel to the stack action. So whether the user wheels up or down, the stack action will take effect.
- Dragging the mouse downward shows the next frame.
- Dragging the mouse upward shows the previous frame.
Offset
- Click and hold the mouse to start the effect. Releasing the assigned mouse button ends the action.
- Dragging the mouse to the left moves the image to the left.
- Dragging the mouse to the right moves the image to the right.
- Dragging the mouse upward moves the image up.
- Dragging the mouse downward moves the image down.
Rectangle region: Click and drag to create a rectangular region.
Ellipse region: Click and drag to create an elliptical region.
Square region: Click and drag to create a square region.
Circle region: Click and drag to create a circular region.
Polygon region: Click at the start point and intermediate points to create a polygonal region. After finishing the shape, double-click to end the action and to complete the region.
Free hand region: Click and drag to create a custom region.
Magic wand region
- Click and hold the mouse to start the effect and to assign the starting point and color. The region will grow outwards from the selected point to the boundaries of that color. Releasing the assigned mouse button ends the action.
- Dragging the mouse downward increases the threshold of variation allowed from the selected color.
- Dragging the mouse upward decreases the threshold of variation allowed from the selected color.
Color range region
- Click and hold the mouse to start the effect. When the user releases the assigned mouse button, the action will end.
- Dragging the mouse left/right increases/decreases the lower tolerance.
- Dragging the mouse left/right increases/decreases the upper tolerance.
Rectangle Annotation: Click and drag to create a rectangular annotation object.
Ellipse Annotation: Click and drag to create an elliptical annotation object.
Arrow Annotation: Click and drag to create the arrow annotation object.
Text Annotation
- Click on the area where the text object must be placed, type the text, and then press Enter to finish.
- Pressing Ctrl + Enter causes the editor to create a new line.
Angle Annotation: Click three times to create the angle annotation object: first click to create the angle base, the second to create the angle apex, and the third to create the angle end.
Ruler annotation: Click and drag to create the ruler annotation object.
Highlight annotation: Click and drag to create the highlight annotation object.