This topic contains the following sections.
The Copy Region tool edit control provides a graphical user interface to the CogCopyRegionTool tool, which you use to copy a portion of an input image to a new output image, copy a portion of an input image into an existing destination image, or fill a portion of an input region with a constant grey value. See the topic Copy Region Tool for more information on how to use a Copy Region tool.
The Copy Region tool accepts all supported image types including 16-bit encoded images, allowing you to use and generate images with a bit depth of 8-bits, 10-bits, 12-bit, 14-bits and 16-bits.
Note: The output image's coordinate space tree is adjusted to preserve the relationship between root space and image features.
The following figure shows the Copy Region tool edit control:
The edit control offers the following features:
- A row of control buttons at the top left provide access to the most common operations.
- A set of function tabs allow you to choose whether to copy pixels from the input image or fill an output image with a constant value (greyscale or color), determine the type of input region you want to use, and select an alignment that controls how the input image maps to the output image.
- An image display window displays acquired images and the output image the Copy Region tool generates.
When you add a new Copy Region tool to a QuickBuild application, it appears with the input terminals for the input image, the destination image, and the output image, as shown in the following figure:
To include the edit control in your custom vision application, you must first add it to your Visual Studio.NET development environment. See the topic Adding Edit Controls to Visual Studio for more information.
The following table describes the function of each button:
| Button | Description | Function |
 | Run | Generate an output image based on the dimensions of the input region and current parameters. |
 | Electric mode | Toggle electric mode, where the Copy Region tool executes automatically when particular configuration parameters change. In electric mode, a lightning bolt appears next to every electric property. |
 | Local image display | Open or close the local image display window. A Copy Region tool supports the following image buffers:
|
 | Floating image display | Open a floating image window, which supports the same image buffers as the local image display window. |
 | Open | Open a VisionPro persistence (.vpp) file that contains a set of saved properties for this vision tool object type. VisionPro reports an error if you try to open a .vpp file for another object type. |
 | Save | Save the current properties of the vision tool to a VisionPro persistence (.vpp) file. The edit control allows you to choose between saving the vision tool with or without its image buffers and tool results. |
 | Save As | Save the current properties of the vision tool to a new VisionPro persistence (.vpp) file. |
 | Reset | Reset the vision tool to its default state. The tool gives you a choice between resetting to the default-constructed state, which is appropriate when you are using it in a Visual Studio.NET application, or its template-initialized state, which is appropriate for QuickBuild applications. |
 | Show ToolTips | Enable or disable the display of tooltips for individual items in the edit control. |
 | Help | Open this VisionPro online help file. |
This section contains the following subsections.
Use the Settings tab to determine whether the output image contains pixels from the input image or a constant greyscale or color value, and how the tool handles pixels outside the input region but within the borders of the region bounding box. The following figure shows the default Settings tab:
Use the following options to determine whether the output image contains pixels from the input image or a constant grey value:
| Parameter | Description |
| FillRegion | Take pixels from the input region of the input image for copying to the output image. |
Fill the output image with a constant greyscale or color value, based on the input region you use as well as the format of the input image. If you are using greyscale images, specify the FillRegionValue. If you are using color images, specify values for FillRegionPlane0Value, FillRegionPlane1Value, and FillRegionPlane2Value, which correspond to separate planes for Red, Green and Blue in RGB images, or Hue, Saturation and Intensity in HSI images. |
Specify the type of DefaultOutputImageType you want to generate when you choose to fill in pixels of the input region with a constant greyscale or color value.
Use the following options to configure how the tool handles pixels outside a circular, elliptical, or affine rectangle region of interest but within an enclosing rectangle and you are using a region mode of Pixel Aligned Bounding Box Adjust Mask:
| Parameter | Description |
If you are not using a destination image, this option fills pixels outside the region but within the enclosing bounding box with uninitialized values. If you are using a destination image, however, this option allows the pixels outside the region to retain the values of the underlying destination image. | |
Fill in pixels outside the region but within the bounding box with a constant greyscale or color value, based on the input region you use as well as the format of the input image. If you are using greyscale images, specify the FillBoundingBoxValue. If you are using color images, specify values for FillBoundingBoxPlane0Value, FillBoundingBoxPlane1Value, and FillBoundingBoxPlane2Value, which correspond to separate planes for Red, Green and Blue in RGB images, or Hue, Saturation and Intensity in HSI images. |
Use the Region tab to select the shape of the input region. The following figure shows the Region tab:
Use the following options to configure the input region:
| Feature | Description |
Defines one of the following types of input regions:
| |
| Region Shape | The shape of the copy region. Selecting "None=Use entire image" means that the entire input image becomes the region. The set of region-defining parameters depends on the selected Region Shape. |
| SelectedSpaceName | The coordinate space in which the copy region is interpreted. For more information, see Coordinate Space Names. |
| Select Mode | Available when Region Shape is cogRectangle or cogRectangleAffine. Selects the set of parameters that define the rectangle. If CogRectangleAffine is chosen, note that the angles of rotation and skew can be specified in degrees or radians, although the underlying tool keeps the measurements in radians. |
| FitToImage | Centers the copy region within Current.InputImage. |
The Copy Region tool allows you to copy the input region of the input image and paste it into the contents of some destination image. By default, the input image and the destination image align themselves at the top-left corner of each image, at image coordinate (0,0) in the current coordinate space. This alignment causes the input region to be placed in the destination image at the same location it uses in the input image.
Use the Alignment tab of the Copy Region edit control to specify a different alignment between the two images. For example, if you specify a coordinate of (25, 25) for the input image and leave the alignment point on the destination image at (0, 0), then the tool aligns the input image at point (25, 25) with the point (0, 0) in the destination image. This, in turn, causes the input region to appear in the destination image offset with respect to its location in the input image.
The settings in this tab have no effect if you do not provide the tool with a destination image. The following figure shows the default Alignment tab:
Use the following parameters to align the images:
| Parameter | Description |
| ImageAlignmentEnabled | Enable a particular alignment of the input image with the destination image. By default, the tool aligns the images at coordinate (0, 0) of each image. |
Input Image Alignment | Use the InputImageAlignmentX and InputImageAlignmentY fields to specify the point in the input image you want to use to align the images. Click the Fit In Input Image button to move the alignment point to the center of the input image. |
Destination Image Alignment | Use the DestinationImageAlignmentX and DestinationImageAlignmentY fields to specify the point in the destination image you want to use to align the images. Click the Fit In Destination Image button to move the alignment point to the center of the destination image. |
This section contains the following subsections.
Use the Graphics tab to specify the graphics that the tool generates and displays. The following figure shows the Graphics tab:
Enable either of the following options:
| Option | Description |
| Show Output Image | You can choose not to generate an image record for the LastRun.OutputImage. |
| Show Destination Region | You can enable a graphic in the LastRun.OutputImage representing the region of the image that was overwritten by the tool, based on the input region and alignment settings. |
Enable any of the following options:
| Option | Description |
| Show Input Image | Determine whether or not the input image is recorded as part of the diagnostic record, and whether the image is copied to the record or saved in the record as a reference. |
| Show Source Region | Enable a graphic representing the input region for the LastRun.InputImage. |
| Show Image Alignment Points | Enable graphics for the input region and the point of alignment over the destination image for the LastRun.InputImage and the LastRun.OutputImage. These are visible only if alignment is enabled.. |