Gselect: Difference between revisions

From Eigenvector Research Documentation Wiki
Jump to navigation Jump to search
imported>Jeremy
(Importing text file)
imported>Jeremy
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
===Purpose===
===Purpose===


===Selects objects in a figure (various selection styles).===
Selects objects in a figure (various selection styles).


===Synopsis===
===Synopsis===


:selected = gselect(mode,''TargetHandle'',''options'')
:selected = gselect(mode,''TargetHandle'',''options'')
 
:[x,y] = gselect(mode,''TargetHandle'',''options'')
:[x,y]   = gselect(mode,''TargetHandle'',''options'')


===Description===
===Description===
Line 44: Line 42:
* ''''none'''': selects no points (no user interaction required).
* ''''none'''': selects no points (no user interaction required).


Optional input ''TargetHandle'' is the handle or handles of objects to test for selection. The default is all lines, patches, surfaces, and images.  
''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).
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).
Line 60: Line 58:
* '''demo''': [ {'Flase'} | 'True' ] Is this a demo call to gselect? (do not wait to exit)
* '''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.
* '''poslabel''': [ 'none' | 'insidexy' | {'xy'} ] Governs what kind of axis position labels will be shown.
::''' 'none' ''' : show no labels
::''' 'insidexy' ''' : show xy labels inside of axes
::''' 'xy' ''' : show xy labels outside of axes


* '''helpbox''': [ 'off' | {'on'} ] Governs display of the helpbox.
* '''helpbox''': [ 'off' | {'on'} ] Governs display of the helpbox.


* '''helptextpre''': [ '' ] Specifies text to prepend to helpbox message.
* '''helptextpre''': [ <nowiki>''</nowiki> ] Specifies text to prepend to helpbox message.
 
* '''helptextpost''': [ <nowiki>''</nowiki> ] Specifies text to append to end of helpbox message.


* '''helptextpost''': [ '' ] Specifies text to append to end of helpbox message.
* '''helptext''': [ <nowiki>''</nowiki> ] Specifies alternate text to replace default  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'.
'''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===
===Examples===
Line 76: Line 78:
Example 1. Plot a vector of 10 random values and let the user select from these points using the standard rubber-band box.
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')
<pre>plot(randn(10,3), randn(10,3), '.'); slct = gselect('rbbox')</pre>


The output will be something like:
The output will be something like:


:slct =  
<pre>slct =  


:    [1x10 uint8]
    [1x10 uint8]


:>> slct{1}
>> slct{1}


:ans =
ans =


:    0    0    0    0    1    1    0    1    0    0
    0    0    0    0    1    1    0    1    0    0


:>> find(slct{1})
>> find(slct{1})


:ans =
ans =


:    5    6    8
    5    6    8</pre>


indicating that points 5, 6 and 8 were selected by the user.
indicating that points 5, 6 and 8 were selected by the user.
Line 100: Line 102:
Example 2. Plot a small image and let the user select a sub-range using the polygon tool.
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')
<pre>imagesc(randn(6,6)); slct = gselect('polygon')</pre>


The output will be something like:
The output will be something like:


:slct =  
<pre>slct =  


:    [6x6 uint8]
    [6x6 uint8]


:>> slct{1}
>> slct{1}


:ans =
ans =


:    0    0    0    0    0    0
    0    0    0    0    0    0


:    0    1    0    0    0    0
    0    1    0    0    0    0


:    0    1    1    1    0    0
    0    1    1    1    0    0


:    0    1    1    1    0    0
    0    1    1    1    0    0


:    0    1    0    1    1    0
    0    1    0    1    1    0


:    0    1    0    1    0    0
    0    1    0    1    0    0</pre>


indicating the "n" shaped region selected by the user.
indicating the "n" shaped region selected by the user.

Latest revision as of 14:59, 22 February 2013

Purpose

Selects objects in a figure (various selection styles).

Synopsis

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' | 'insidexy' | {'xy'} ] Governs what kind of axis position labels will be shown.
'none'  : show no labels
'insidexy'  : show xy labels inside of axes
'xy'  : show xy labels outside of axes
  • 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.

See Also

plotgui