imscrollpanel (Image Processing Toolbox User's Guide)

Image Processing Toolbox User's Guide

Scroll panel for interactive image navigation

Syntax

hpanel = imscrollpanel(hparent, himage)

Description

hpanel = imscrollpanel(hparent, himage) creates a scroll panel containing the target image (the image to be navigated).. himage is a handle to the target image. hparent is a handle to the figure or uipanel that will contain the new scroll panel. hpanel is the handle to the scroll panel, which is a uipanel object.

A scroll panel makes an image scrollable. If the size or magnification makes an image too large to display in a figure on the screen, 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.

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.

API functions

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.

Scroll Panel API Function
Description

setMagnification

Sets the magnification in units of screen pixels per image pixel.

mag = api.getMagnification(new_mag)

where new_mag is a scalar magnification factor.

getMagnification

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

mag = api.getMagnification()

Multiply mag by 100 to convert to percentage. For example if mag=2, that's equivalent to 200% magnification.

setMagnificationAndCenter

Changes the magnification and makes the point cx,cy appear in the center of the scroll panel. This operation is equivalent to a simultaneous zoom and recenter.

api.setMagnificationAndCenter(mag,cx,cy)

findFitMag

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

mag = api.findFitMag()

setVisibleLocation

Moves the target image so that the specified location is visible. Scrollbars update.

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

getVisibleLocation

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

loc = api.getVisibleLocation()

where loc is a vector [xmin ymin].

getVisibleImageRect

Returns the current visible portion of the image.

r = api.getVisibleImageRect()

where r is a rectangle [xmin ymin width height].

addNewMagnificationCallback

Adds 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)

where mag is a scalar magnification factor.

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

removeNewMagnificationCallback

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

api.removeNewMagnificationCallback(id)

where id is the identifier returned by addNewMagnificationCallback.

addNewLocationCallback

Adds 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)

where loc is [xmin ymin].

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

removeNewLocationCallback

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

api.removeNewLocationCallback(id)

where id is the identifier returned by addNewLocationCallback.

Scroll Panel API Function	Description
`setMagnification`	Sets the magnification in units of screen pixels per image pixel. mag = api.getMagnification(new_mag) where `new_mag` is a scalar magnification factor.
`getMagnification`	Returns the current magnification factor in units of screen pixels per image pixel. `mag = api.getMagnification()` Multiply `mag` by 100 to convert to percentage. For example if `mag=2`, that's equivalent to 200% magnification.
`setMagnificationAndCenter`	Changes the magnification and makes the point `cx,cy` appear in the center of the scroll panel. This operation is equivalent to a simultaneous zoom and recenter. `api.setMagnificationAndCenter(mag,cx,cy)`
`findFitMag`	Returns the magnification factor that would make the image just fit in the scroll panel. `mag = api.findFitMag()`
`setVisibleLocation`	Moves the target image so that the specified location is visible. Scrollbars update. `api.setVisibleLocation(xmin,ymin)api.setVisibleLocation([xmin ymin])`
`getVisibleLocation`	Returns the location of the currently visible portion of the target image. `loc = api.getVisibleLocation()` where `loc` is a vector `[xmin ymin]`.
`getVisibleImageRect`	Returns the current visible portion of the image. `r = api.getVisibleImageRect()` where `r` is a rectangle `[xmin ymin width height]`.
`addNewMagnificationCallback`	Adds 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)` where `mag` is a scalar magnification factor. The return value, `id`, is used only with `removeNewMagnificationCallback`.
`removeNewMagnificationCallback`	Removes the corresponding function from the new-magnification callback list. `api.removeNewMagnificationCallback(id)` where id is the identifier returned by `addNewMagnificationCallback`.
`addNewLocationCallback`	Adds 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)` where `loc` is `[xmin ymin]`. The return value, `id`, is used only with `removeNewLocationCallback`.
`removeNewLocationCallback`	Removes the corresponding function from the new-location callback list. `api.removeNewLocationCallback(id)` where `id` is the identifier returned by `addNewLocationCallback`.

Note

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 hpanel 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.

Example

This example creates a scroll panel with a magnification box and an overview tool.

Create a scroll panel

hFig = figure('Toolbar','none',...
              'Menubar','none');
hIm = imshow('saturn.png');
hSP = imscrollpanel(hFig,hIm);
set(hSP,'Units','normalized',...
        'Position',[0 .1 1 .9])

Add a magnification box and an overview tool.

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

Get the scroll panel API to programmatically control the view.

```
api = iptgetapi(hSP);
```

Get the current magnification and position.

mag = api.getMagnification() 
r = api.getVisibleImageRect()

View the top left corner of the image.

```
api.setVisibleLocation(0.5,0.5)
```

Change the magnification to the value that just fits.

api.setMagnification(api.findFitMag())

Zoom in to 1600% on the dark spot.

api.setMagnificationAndCenter(16,306,800)

imrotate imshow