cpselect

Control Point Selection tool

Syntax

cpselect(moving,fixed)

cpselect(moving,fixed,initialMovingPoints,initialFixedPoints)

cpselect(moving,fixed,cpstruct_in)

h = cpselect(___)

h = cpselect(___,"Wait",false)

[selectedMovingPoints,selectedFixedPoints] = cpselect(___,"Wait",true)

Description

The Control Point Selection tool enables you to select and modify control points in a pair of 2-D images interactively.

cpselect(moving,fixed) starts the Control Point Selection tool that enables you to select control points in two related images. moving is the image to be warped, which brings it into the coordinate system of the fixed image.

When the Control Point Selection tool is open, you can add, move, and delete control points interactively with the mouse. When you are done modifying the control points, export them to the workspace by selecting Export Points to Workspace from the File menu. The tool can return the coordinates of valid selected pairs of moving and fixed control points in two numeric vectors. The tool can also return all selected control points and indexing information in a cpstruct structure that saves the state of the tool so that you can restart the tool later. For more information about using the tool, see Select Matching Control Point Pairs.

cpselect(moving,fixed,initialMovingPoints,initialFixedPoints) starts the Control Point Selection tool with an initial set of valid moving and fixed control point pairs, initialMovingPoints and initialFixedPoints.

cpselect(moving,fixed,cpstruct_in) starts the Control Point Selection tool with an initial set of control points and indexing information that are stored in cpstruct_in. Use this syntax to restart the Control Point Selection tool from a previously saved state.

h = cpselect(___) returns a handle h to the Control Point Selection tool. You can use the close(h) command to close the tool from the command line.

h = cpselect(___,"Wait",false) returns a handle h to the Control Point Selection tool. You can use the close(h) syntax to close the tool from the command line. In contrast to setting "Wait" as true, this syntax lets you run cpselect at the same time as you run other programs in MATLAB^®.

[selectedMovingPoints,selectedFixedPoints] = cpselect(___,"Wait",true) takes control of the MATLAB command line until you finish selecting control points. When you have finished selecting control points, return to the workspace by closing the tool. cpselect returns the coordinates of valid selected pairs of moving and fixed control points in selectedMovingPoints and selectedFixedPoints.

Examples

Start Control Point Selection Tool with Saved Images

Read the image westconcordorthophoto.png into the workspace. This image is an orthophoto that has already been registered to the ground.

fixed = imread('westconcordorthophoto.png');

Read the image westconcordaerial.png into the workspace. This image was taken from an airplane and is distorted relative to the orthophoto.

moving = imread('westconcordaerial.png');

Call cpselect, specifying the names of the image you want to register and the reference image. You can now add, move, and delete control points interactively with the mouse. When you are done adding control points, export them to the workspace by selecting Export Points to Workspace from the File menu.

cpselect('westconcordaerial.png','westconcordorthophoto.png');

Open Control Point Selection Tool with Predefined Control Points

Create a sample reference image. This image is the fixed image.

I = checkerboard;

Create a rotated and stretched copy of the sample image. This image is the moving image to be aligned with the fixed image.

J = imresize(I,'Scale',[1 1.3]);
moving = imrotate(J,30);

Specify the (x,y) coordinates of three corresponding control points for the fixed and moving images.

fixedPoints = [10.7 30.6; 40.5 50.6; 20.6 10.7];
movingPoints = [21.6 64.2; 71.1 70.3; 28.7 48.3];

Open the Control Point Selection tool, specifying the sample fixed and moving images and the two sets of saved control points. You can now continue adding, moving, and deleting control points interactively with the mouse. When you are done modifying the control points, export them to the workspace by selecting Export Points to Workspace from the File menu.

h = cpselect(moving,I,movingPoints,fixedPoints);

Close the Control Point Selection tool programmatically by using the close function.

close(h)

Input Arguments

moving — Input image to be aligned

grayscale image | truecolor image | binary image | character vector | string

Input image to be aligned, specified as a grayscale, truecolor, or binary image, or a character vector or string that specifies the file name of an image of those types.

Image Type	Supported Data Types
Grayscale	uint8, uint16, int16, single, or double
Truecolor	uint8, uint16, single, or double
Binary	logical

Data Types: single | double | int16 | uint8 | uint16 | logical | char | string

fixed — Reference image

grayscale image | truecolor image | binary image | character vector | string

Reference image, specified as a grayscale, truecolor, or binary image, or a character vector or string that specifies the file name of an image of those types.

Image Type	Supported Data Types
Grayscale	uint8, uint16, int16, single, or double
Truecolor	uint8, uint16, single, or double
Binary	logical

Data Types: single | double | int16 | uint8 | uint16 | logical | char | string

cpstruct_in — Preselected control points

cpstruct structure

Preselected control points, specified as a cpstruct structure. cpstruct_in contains information about x- and y-coordinates of all control points in the moving and fixed images, including unpaired and predicted control points. cpstruct_in also contains indexing information that allows the Control Point Selection tool to restore the state of the control points.

Create a cpstruct structure by exporting points from the Control Point Selection tool, described in Select Matching Control Point Pairs.

Data Types: struct

initialMovingPoints — Preselected control points on moving image

m-by-2 numeric array

Preselected control points on the moving image, specified as an m-by-2 numeric array. The two columns represent the x- and y-coordinates of the control points.

Data Types: double

initialFixedPoints — Preselected control points on fixed image

m-by-2 numeric array

Preselected control points on the fixed image, specified as an m-by-2 numeric array. The two columns represent the x- and y-coordinates of the control points.

Data Types: double

Output Arguments

h — Control Point Selection tool

handle

Control Point Selection tool, returned as a handle.

selectedMovingPoints — Selected control points on moving image

p-by-2 numeric array

Selected control points on the moving image, specified as a p-by-2 numeric array. The two columns represent the x- and y-coordinates of the control points, respectively, in the intrinsic coordinate system of the image.

Data Types: double

selectedFixedPoints — Selected control points on fixed image

p-by-2 numeric array

Selected control points on the fixed image, specified as a p-by-2 numeric array. The two columns represent the x- and y-coordinates of the control points, respectively, in the intrinsic coordinate system of the image.

Data Types: double

More About

Layout of the Control Point Selection Tool

The Control Point Selection tool consists of three primary components:

• Detail windows—The two windows displayed at the top of the tool are called the Detail windows. These windows show a close-up view of a portion of the images you are working with. The moving image is on the left and the fixed image is on the right.

• Overview windows—The two windows displayed at the bottom of the tool are called the Overview windows. These windows show the images in their entirety, at the largest scale that fits the window. The moving image is on the left and the fixed image is on the right. You can control whether the Overview window appears by using the View menu.

• Detail rectangles—Superimposed on the images displayed in the two Overview windows is a rectangle, called the Detail rectangle. This rectangle controls the part of the image that is visible in the Detail window. By default, at startup, the detail rectangle covers one quarter of the entire image and is positioned over the center of the image. You can move the Detail rectangle to change the portion of the image displayed in the Detail windows.

The figure shows these components of the Control Point Selection tool.

For more information about selecting control points, see Select Matching Control Point Pairs.

Control Point Prediction

cpselect uses the following general procedure for control-point prediction.

1. Find all valid pairs of control points.

2. Infer a spatial transformation between moving and fixed control points using a method that depends on the number of valid control point pairs.

   Transformation Type	Minimum Number of Control Point Pairs
   Nonreflective similarity	2
   Affine	3
   Projective	4

3. Apply the spatial transformation to the new point. This transformation generates the predicted point.

4. Display the predicted point.

Tips

• When calling cpselect in a script, specify the 'Wait' option as true. The 'Wait' option causes cpselect to block the MATLAB command line until control points have been selected and returned. If you do not use the 'Wait' option, cpselect returns control immediately and your script continues without allowing time for control point selection. Additionally, without the 'Wait' option, cpselect does not return the control points as return values.

Version History

Introduced before R2006a