Main Content

cpselect

Control Point Selection tool

Description

example

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 Control Point Selection Procedure.

example

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

collapse all

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');

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

collapse all

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

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

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 by exporting points from the Control Point Selection tool, described in Export Control Points to the Workspace.

Data Types: struct

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

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

collapse all

Control Point Selection tool, returned as a handle.

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.

Data Types: double

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.

Data Types: double

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.

Algorithms

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.

Introduced before R2006a