# Feature Finding Task

The Feature Finding task acquires images of a part and locates the features on the part. It has the subtasks shown in the image below. This task could be executed during train-time or run-time. During train-time the task could be executed to locate part feature locations at train-time and/or set train-time gripper positions. During run-time the task is executed to locate run-time part feature locations. Some of the command keys that can be encoded in the command string are TA/TT/TTA commands, used during train-time, or LF/LFA used during run-time.

The following are the commands that the user can send to the feature finder task for an application that acquires images of a single part at two positions. The application is one where the gripper of the robot is to be aligned to the part:

Command Index | Command Key | Position Index | Description
--- | --- | --- | ---
1 | TA | 0 | Acquire images at position 0 at train-time
2 | TA | 1 | Acquire image and process image at position 1 at train-time
3 | TTR | 1 | Save gripper's train time pose
4 | LF/LFA | 0 | Acquire images at position 0 at run-time
5 | LF/LFA | 1 | Acquire image and process image at position 1 at run-time

## Command

When a command string is received by the CommandHandler script, an equivalent CommandArgs object is created. This object contains all the data that is needed to execute the target task. Command subtask is the interface to receive CommandArgs object from task scheduler which makes the object available to current task as an output pin and a public tag.

There are four properties in the CommandArgs object that controls the work flow of feature finding task: ExecutionMode, PositionIndex, AlignmentOperation and SavePoseDuringTraining. ExecutionMode decides which sub tasks should got executed. PositionIndex specifies which position cameras should acquire images at. AlignmentOperation specifies whether it's train time or run time fro feature finding. SavePoseDuringTraining indicates whether motion device's train time pose should be save or not.

### Execution Mode

- ExecutionMode: Acquire

  When cameras are not at their last acquisition position, feature finding task shall only acquire images when it's called. Therefore, the ExecutionMode should be set as Acquire in this case, and accordingly, the task will only run Acquisition, Image Saver2 and Raw Image Display subtasks to acquire, accumulate, and display raw images at current position.

- ExecutionMode: AcquireAndProcessImage

  When cameras are at their last acquisition position, feature finding task should acquire images and run feature finding when it's called. In this case, ExecutionMode here should be set as AcquireAndProcessImage, and the task will run Acquisition, Corrector, Feature Extractor, L-Check, Result Publisher subtasks sequentially to finish image acquisition, image correction, feature extraction, feature length check and publish results. It also save images to image files if image saving function is enabled and generates raw image records in case user wants to show raw images on image display. The work flow below shows all its subtasks and their execution sequence.

## Acquisition

Running condition: [ExecutionMode = Acquire || AcquireAndProcessImage]

Acquisition subtask acquires images of the part at the position index encoded in the encodedID.

For a shuttling camera application that uses two cameras that shuttle to two positions, the feature finder task is executed twice. The first using a command string with an encodedID that encodes the first position and with execution mode set to Acquire. The second using a command string with an encodedID that encodes the second position and with execution mode set to AcquireAndProcessImage. Both the executions execute the Acquisition subtask.

Command | ExecutionMode | Position Index | Image Item | Before Acquisition | Acquisition at Pos0 | Acquisition at Pos1
--- | --- | --- | --- | --- | --- | ---
1 | Acquire | 0 | Cam0Pos0 | Null |  | /
0 | Cam1Pos0 | Null |  | /
2 | AcquireAndProcessImage | 1 | Cam0Pos1 | Null | Null |
1 | Cam1Pos1 | Null | Null |

For non-shuttling camera applications, a single command string with an encodedID that encodes the execution mode to AcquireAndProcessImage is used to acquire the image.

Command | ExecutionMode | Position Index | Image Item | Before Acquisition | Acquisition at Pos0
--- | --- | --- | --- | --- | ---
1 | AcquireAndProcessImage | 0 | Cam0Pos0 | Null |
0 | Cam1Pos0 | Null |

## Corrector

Running condition: [ExecutionMode = ProcessImage || AcquireAndProcessImage]

The corrector subtask uses image correctors for removing non-linear imaging distortion. All Cognex vision tools assume an affine relationship between the image and the world. By removing non-linear distortion image correctors ensure the vision tools work accurately. The output of this task is a list of corrected images.

## Feature Extractor

Running condition: [ExecutionMode = ProcessImage || AcquireAndProcessImage]

Feature extractor sub task extract features from corrected images using feature finders set by user in Alignment setup interface for locating train-time and run-time features. The output of this sub task are train time and/or run time command, train time and/or run time features, and their graphics.

- Train Time

  At train time, when TA/TT command string is sent to vision system, CommandHandler will set AlignmentOperation of current command as Train. Within Feature Extractor subtask, it will first run feature extraction, then update train time features in its publisher. It will also update train time graphics.

  When TTR command string is sent to vision system, CommandHandler will set as True , and the Feature Extractor subtask will save train time command(motion device's train time X, Y, Theta are included) into its publisher.

- Run Time

  At train time, when LF/LFA command string is sent to vision system, CommandHandler will set AlignmentOperation of current command as Align. Within Feature Extractor subtask, it will first run feature extraction, then update run time command(motion device's current X, Y, Theta are included) and run time features so that they will be save in their publishers. It will also update run time features to VproRecords so that corresponding image display will be updated.

## L-Check

Running condition: [ExecutionMode = ProcessImage || AcquireAndProcessImage]

L-Check subtask checks if the distance between pairs of features are within specification. The outputs of this sub task are measured lengths and if the lenghts meet the specification.

## Result Publisher

Running condition: [ExecutionMode = ProcessImage || AcquireAndProcessImage]

The Result Publisher subtask publishes all train-time, offset camera centers, and run-time feature locations for other tasks in the applications to consume. It also publishes the CommandArgs object that was received at train-time. Other tasks consume the object to get the train-time gripper position. Result publisher subtask also outputs overall OK/NG signal based on feature finding OK/NG signal, L-Check OK/NG signal and customized OK/NG signal. The customized OK/NG signal is from on open input pin, it will be ignored for overall OK/NG judgement if it's not implemented.

## Display Recorder Generator

Running condition: [ExecutionMode = ProcessImage || AcquireAndProcessImage]

Display Recorder Generator sub task merges VisionPro records from feature extractor subtask with customized VisionPro records for image displays.

## Image Saving

Feature finding task can save all raw images in TIF files for user to playback feature finding process. It also supports screenshots saving in JPG files for user to manually review feature extraction results.

### Image Saver2

Running condition: Always run.

Image Saver2 subtask accumulates raw images and their corresponding commands every time when current task acquires images. The accumulates images and commands would get cleared when Image Saver2 Sync Trigger subtask is called at the end of the task.

### Image Saver2 Sync Trigger

Running condition:[ExecutionMode = ProcessImage || AcquireAndProcessImage]

Image Saver2 Sync Trigger subtask saves all accumulated raw images and their commands from Image Saver2 subtask into TIF files if current task's raw image saving function is enabled. It also saves image records into JPG files when screenshot saving function is enabled. See how to enable raw image saving and screenshot saving in Image Saving

## Raw Image Display

Running condition:[ExecutionMode = ProcessImage || AcquireAndProcessImage]

Raw Image Display subtask generates raw image records(images without graphics) for image display. Those records will be shown on task's image display page if "Display Raw Image" is selected in functional panel below navigation tree. See more information at Show Graphics in Multiple Display.