Main Content

imscrollpanel

Scroll panel for interactive image navigation

collapse all in page

Syntax

hPanel = imscrollpanel(hParent,hImage)

Description

Use the imscrollpanel function to add a scroll panel to an image. If the size or magnification makes an image too large to display in a figure on the screen, then the scroll panel displays a portion of the image at 100% magnification (one screen pixel represents one image pixel). The scroll panel adds horizontal and vertical scroll bars to enable navigation around the image.

hPanel = imscrollpanel(hParent,hImage) creates a scroll panel hPanel that enables scrolling image hImage. The scroll panel is added to the parent figure or panel hParent.

example

Examples

collapse all

Open Live Script

Display an image in a figure. The example suppresses the standard toolbar and menubar in the figure window because these do not work with the scroll panel.

hFig = figure(Toolbar="none",Menubar="none",Name="Saturn");
hIm = imshow("saturn.png");

Figure Saturn contains an axes object. The hidden axes object contains an object of type image.

Create a scroll panel to contain the image.

hSP = imscrollpanel(hFig,hIm);
set(hSP,Units="normalized",Position=[0 .1 1 .9])

Add a Magnification Box and an Overview tool to the figure.

hMagBox = immagbox(hFig,hIm);
pos = get(hMagBox,"Position");
set(hMagBox,Position=[0 0 pos(3) pos(4)])

Figure Saturn contains an axes object and other objects of type uipanel, uicontrol. The hidden axes object contains an object of type image.

imoverview(hIm)

Figure Overview (Saturn) contains an axes object and other objects of type uipanel, uitoolbar, uimenu. The hidden axes object contains 8 objects of type line, patch, image.

Get the scroll panel API so that you can control the view programmatically.

api = iptgetapi(hSP);

Get the current magnification and position.

mag = api.getMagnification()
mag = 
1

r = api.getVisibleImageRect()
r = 1×4

  219.0000  380.8000  763.0000  739.4000

Use the scroll panel object API function setVisibleLocation to view the top left corner of the image.

api.setVisibleLocation(0.5,0.5)

Figure Saturn contains an axes object and other objects of type uipanel, uicontrol. The hidden axes object contains an object of type image.

Figure Overview (Saturn) contains an axes object and other objects of type uipanel, uitoolbar, uimenu. The hidden axes object contains 8 objects of type line, patch, image.

Change the magnification of the image so that the image fits entirely in the scroll panel. In the following figure, note that the scroll bars are no longer visible.

api.setMagnification(api.findFitMag())

Figure Saturn contains an axes object and other objects of type uipanel, uicontrol. The hidden axes object contains an object of type image.

Figure Overview (Saturn) contains an axes object and other objects of type uipanel, uitoolbar, uimenu. The hidden axes object contains 8 objects of type line, patch, image.

Zoom in to 1600% on the dark spot.

api.setMagnificationAndCenter(16,306,800)

Figure Saturn contains an axes object and other objects of type uipanel, uicontrol. The hidden axes object contains an object of type image.

Figure Overview (Saturn) contains an axes object and other objects of type uipanel, uitoolbar, uimenu. The hidden axes object contains 8 objects of type line, patch, image.

Input Arguments

collapse all

Parent of the scroll panel, specified as a Figure or Panel object.

Image, specified as an Image object.

Output Arguments

collapse all

Scroll panel, returned as a Panel object.

More About

collapse all

Scroll Panel API Structure

A scroll panel contains a structure of function handles, called an API. You can use the functions in this API to manipulate the scroll panel. To retrieve this structure, use the iptgetapi function, as in the following example.

api = iptgetapi(hPanel)

This table lists the scroll panel API functions, in the order they appear in the structure.

Function

Description

setMagnification

Set the magnification of the target image in units of screen pixels per image pixel.

mag = api.setMagnification(new_mag)

new_mag is a scalar magnification factor.

getMagnification

Return the current magnification factor of the target image in units of screen pixels per image pixel.

mag = api.getMagnification()

Multiply mag by 100 to convert to percentage. For example if mag is 2, then the magnification is 200%.

setMagnificationAndCenter

Change the magnification and make the point with (x,y) coordinate (cx,cy) in the target image appear in the center of the scroll panel. This operation is equivalent to a simultaneous zoom and recenter.

api.setMagnificationAndCenter(mag,cx,cy)

findFitMag

Return the magnification factor that would make the target image just fit in the scroll panel.

mag = api.findFitMag()

setVisibleLocation

Move the target image so that the specified location is visible, and update the scroll bars.

api.setVisibleLocation(xmin, ymin) 
api.setVisibleLocation([xmin ymin])

getVisibleLocation

Return the location of the currently visible portion of the target image.

loc = api.getVisibleLocation()

loc is a vector [xmin ymin].

getVisibleImageRect

Return the current visible portion of the image.

r = api.getVisibleImageRect()

r is a rectangle [xmin ymin width height].

addNewMagnificationCallback

Add the function handle fcn to the list of new-magnification callback functions.

id = api.addNewMagnificationCallback(fcn)

Whenever the scroll panel magnification changes, each function in the list is called with the syntax:

fcn(mag)

mag is a scalar magnification factor.

The return value, id, is used only with removeNewMagnificationCallback.

removeNewMagnificationCallback

Remove the corresponding function from the new-magnification callback list.

api.removeNewMagnificationCallback(id)

id is the identifier returned by addNewMagnificationCallback.

addNewLocationCallback

Add the function handle fcn to the list of new-location callback functions.

id = api.addNewLocationCallback(fcn)

Whenever the scroll panel location changes, each function in the list is called with the syntax:

fcn(loc)

loc is [xmin ymin].

The return value, id, is used only with removeNewLocationCallback.

removeNewLocationCallback

Remove the corresponding function from the new-location callback list.

api.removeNewLocationCallback(id)

id is the identifier returned by addNewLocationCallback.

replaceImage

api.replaceImage(...,PARAM1,VAL1,PARAM2,VAL2,...) replaces the image displayed in the scroll panel. 

api.replaceImage(I)
api.replaceImage(BW)
api.replaceImage(RGB)
api.replaceImage(I,MAP)
api.replaceImage(filename)

By default, the new image data is displayed centered, at 100% magnification. The image handle is unchanged.

The parameters you can specify include many of the parameters supported by imshow, including 'Colormap', 'DisplayRange', and 'InitialMagnification'. In addition, you can use the 'PreserveView' parameter to preserve the current magnification and centering of the image during replacement. Specify the logical scalar True to preserve current centering and magnification.

Tips

  • imscrollpanel changes the object hierarchy of the target image. Instead of the familiar figure→axes→image object hierarchy, imscrollpanel inserts several uipanel and uicontrol objects between the figure and the axes object.

  • Scrollbar navigation as provided by imscrollpanel is incompatible with the default MATLAB® figure navigation buttons (pan, zoom in, zoom out). The corresponding menu items and toolbar buttons should be removed in a custom GUI that includes a scrollable uipanel created by imscrollpanel.

  • When you run imscrollpanel, it appears to take over the entire figure because, by default, an uipanel object has 'Units' set to 'normalized' and 'Position' set to [0 0 1 1]. If you want to see other children of hparent while using your new scroll panel, you must manually set the 'Position' property of hpanel.

Version History

Introduced before R2006a

See Also

| | | |

Topics