Gselect
Purpose
Selects objects in a figure (various selection styles).
Synopsis
- [selected,y] = gselect(mode,command,options)
- selected = gselect(mode,TargetHandle,options)
- [x,y] = gselect(mode,TargetHandle,options)
Description
GSELECT is a general utility which allows user-selection of plotted objects (points, line segments, areas of images, etc.). A variety of selection modes can be used on various types of plots. Each mode allows the user to select an area or range of the current axes. After selection is complete, the function returns a cell array that contains one cell for each line or image object on the axes. These cells contain a binary (true/false) array representing the selected points of each object.
The input mode is a string representing the selection mode. This governs how GSELECT selects objects in a figure. mode can be one of the following strings {default = 'rbbox'}:
- 'x': select a single x-axis position (snaps-to line x-data),
- 'y': select a single y-axis position (snaps-to line y-data),
- 'xs': select range of x-axis positions (snaps-to line x-data),
- 'ys': select range of y-axis positions (snaps-to line y-data),
- 'rbbox': select points inside a standard rubber-band box {default },
- 'polygon': select points inside a polygon (user selects corners),
- 'circle': select points inside a circle,
- 'ellipse': select points inside an ellipse,
- 'lasso': select points inside a lasso,
- 'paint': drag a broad line across points for selection,
- 'nearest': select single nearest point,
- 'nearests': select multiple single (nearest) points,
- 'all': selects all points (no user interaction required), and
- 'none': selects no points (no user interaction required).
TargetHandle specifies object to use to determine points and inclusion {default is all lines, patches, surfaces, and images}. If TargetHandle is empty, then selected will be the raw shape information of the selected item (e.g. the polygon or rbbox verticies or x/y positions).
The output is a cell array selection. Each cell in selection will be equal in length to the data used to create the corresponding object. For example, if a vector containing 30 points was plotted, the resulting cell will be a vector of 30 binary values. Each selected point on that object will be represented by a value of 1 (one) in the cell, unselected objects by a value of 0 (zero).
If two outputs [x,y] are requested, GSELECT does not test objects for selection and simply returns the x and y points defining the selected area.
Options
- options = a structure array with the following fields:
- modal: [ {'Flase'} | 'True' ] Governs window's "modal" nature. Note that some systems will not allow modal windows.
- btndown: [ {'Flase'} | 'True' ] Should button be considered "down" at start?
- demo: [ {'Flase'} | 'True' ] Is this a demo call to gselect? (do not wait to exit)
- poslabel: [ 'none' | {'xy'} ] Governs what kind of axis position labels will be shown.
- helpbox: [ 'off' | {'on'} ] Governs display of the helpbox.
- helptextpre: [ '' ] Specifies text to prepend to helpbox message.
- helptextpost: [ '' ] Specifies text to append to end of helpbox message.
- helptext: [ '' ] Specifies alternate text to replace default helpbox message.
- modalwindow = optional flag which can be passed in place of "options" input. Controls window modal setting during the selection process (Keeps other windows from interrupting process) A value of 1 sets options.modal to 'true'.
Examples
Example 1. Plot a vector of 10 random values and let the user select from these points using the standard rubber-band box.
plot(randn(10,3), randn(10,3), '.'); slct = gselect('rbbox')
The output will be something like:
slct =
[1x10 uint8]
>> slct{1}
ans =
0 0 0 0 1 1 0 1 0 0
>> find(slct{1})
ans =
5 6 8
indicating that points 5, 6 and 8 were selected by the user.
Example 2. Plot a small image and let the user select a sub-range using the polygon tool.
imagesc(randn(6,6)); slct = gselect('polygon')
The output will be something like:
slct =
[6x6 uint8]
>> slct{1}
ans =
0 0 0 0 0 0
0 1 0 0 0 0
0 1 1 1 0 0
0 1 1 1 0 0
0 1 0 1 1 0
0 1 0 1 0 0
indicating the "n" shaped region selected by the user.