Module is.codion.plugin.imagepanel
Package is.codion.plugin.imagepanel

Class NavigableImagePanel

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
is.codion.plugin.imagepanel.NavigableImagePanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class NavigableImagePanel extends JPanel
NavigableImagePanel is a lightweight container displaying an image that can be zoomed in and out and panned with ease and simplicity, using an adaptive rendering for high quality display and satisfactory performance.

Image

An image is loaded either via a constructor:

 NavigableImagePanel panel = new NavigableImagePanel(image);
or using a setter: 
 NavigableImagePanel panel = new NavigableImagePanel();
 panel.setImage(image);
When an image is set, it is initially painted centered in the component, at the largest possible size, fully visible, with its aspect ratio is preserved. This is defined as 100% of the image size and its corresponding zoom level is 1.0.

Zooming

Zooming can be controlled interactively, using either the mouse scroll wheel (default) or the mouse two buttons, or programmatically, allowing the programmer to implement other custom zooming methods. If the mouse does not have a scroll wheel, set the zooming device to mouse buttons: 
 panel.setZoomDevice(ZoomDevice.MOUSE_BUTTON);
The left mouse button works as a toggle switch between zooming in and zooming out modes, and the right button zooms an image by one increment (default is 20%). You can change the zoom increment value by: 
 panel.setZoomIncrement(newZoomIncrement);
If you intend to provide programmatic zoom control, set the zoom device to none to disable both the mouse wheel and buttons for zooming purposes: 
 panel.setZoomDevice(ZoomDevice.NONE);
and use setZoom() to change the zoom level. Zooming is always around the point the mouse pointer is currently at, so that this point (called a zooming center) remains stationary ensuring that the area of an image we are zooming into does not disappear off the screen. The zooming center stays at the same location on the screen and all other points move radially away from it (when zooming in), or towards it (when zooming out). For programmatically controlled zooming the zooming center is either specified when setZoom() is called: 
 panel.setZoom(newZoomLevel, newZoomingCenter);
or assumed to be the point of an image which is the closest to the center of the panel, if no zooming center is specified: 
 panel.setZoom(newZoomLevel);
There are no lower or upper zoom level limits.

Navigation

NavigableImagePanel does not use scroll bars for navigation, but relies on a navigation image located in the upper left corner of the panel. The navigation image is a small replica of the image displayed in the panel. When you click on any point of the navigation image that part of the image is displayed in the panel, centered. The navigation image can also be zoomed in the same way as the main image.

In order to adjust the position of an image in the panel, it can be dragged with the mouse, using the left button. For programmatic image navigation, disable the navigation image: 

 panel.setNavigationImageEnabled(false)
and use getImageOrigin() and setImageOrigin() to move the image around the panel.

Rendering

NavigableImagePanel uses the Nearest Neighbor interpolation for image rendering (default in Java). When the scaled image becomes larger than the original image, the Bilinear interpolation is applied, but only to the part of the image which is displayed in the panel. This interpolation change threshold can be controlled by adjusting the value of HIGH_QUALITY_RENDERING_SCALE_THRESHOLD.

http://today.java.net/pub/a/today/2007/03/27/navigable-image-panel.html Included with permission.

See Also:

  • Field Details

    • ZOOM_LEVEL_CHANGED_PROPERTY

      public static final String ZOOM_LEVEL_CHANGED_PROPERTY

      Identifies a change to the zoom level.

      See Also:

    • ZOOM_INCREMENT_CHANGED_PROPERTY

      public static final String ZOOM_INCREMENT_CHANGED_PROPERTY

      Identifies a change to the zoom increment.

      See Also:

    • IMAGE_CHANGED_PROPERTY

      public static final String IMAGE_CHANGED_PROPERTY

      Identifies that the image in the panel has changed.

      See Also:

  • Constructor Details

    • NavigableImagePanel

      public NavigableImagePanel()

      Creates a new navigable image panel with no default image and the mouse scroll wheel as the zooming device.

    • NavigableImagePanel

      public NavigableImagePanel(BufferedImage image)

      Creates a new navigable image panel with the specified image and the mouse scroll wheel as the zooming device.

      Parameters:
      image - the default image
      Throws:
      IllegalArgumentException - in case the image height and/or width is zero

  • Method Details

    • readImage

      public static BufferedImage readImage(String imagePath) throws IOException
      Reads an image from the given path
      Parameters:
      imagePath - the path, either file or http
      Returns:
      the loaded image
      Throws:
      IOException - in case of an exception

    • getImageWidth

      public final int getImageWidth()
      Returns:
      the image width

    • getImageHeight

      public final int getImageHeight()
      Returns:
      the image height

    • setZoomDevice

      public final void setZoomDevice(NavigableImagePanel.ZoomDevice newZoomDevice)

      Sets a new zoom device.

      Parameters:
      newZoomDevice - specifies the type of the new zoom device.

    • getZoomDevice

      public final NavigableImagePanel.ZoomDevice getZoomDevice()

      Gets the current zoom device.

      Returns:
      the ZoomDevice

    • centerImage

      public final void centerImage(Point2D.Double imagePoint)
      Centers the image on the given image point
      Parameters:
      imagePoint - the image point on which to center the image

    • centerImage

      public final void centerImage(Point panelPoint)
      Centers the image on the given point on the panel, if it is within the image boundaries.
      Parameters:
      panelPoint - the point on which to center the image

    • isWithinImage

      public final boolean isWithinImage(Point panelPoint)
      Tests whether a given point in the panel falls within the image boundaries.
      Parameters:
      panelPoint - the point on the panel
      Returns:
      true if an image is available and the given point is within the image

    • setImage

      public final void setImage(BufferedImage image)

      Sets an image for display in the panel.

      Parameters:
      image - an image to be set in the panel
      Throws:
      IllegalArgumentException - in case the image height and/or width is zero

    • getImage

      public final BufferedImage getImage()
      Returns:
      the image being displayed, null if none

    • getScale

      public final double getScale()
      Returns:
      the zoom scale

    • resetView

      public final void resetView()
      Resets the view so the image fits the panel

    • panelToImagePoint

      public final Point2D.Double panelToImagePoint(Point panelPoint)
      Converts this panel's point into the original image point
      Parameters:
      panelPoint - the panel point
      Returns:
      the image point

    • imageToPanelPoint

      public final Point2D.Double imageToPanelPoint(Point2D.Double imagePoint)
      Converts the original image point into this panel's point
      Parameters:
      imagePoint - the image point
      Returns:
      the panel point

    • isHighQualityRenderingEnabled

      public final boolean isHighQualityRenderingEnabled()

      Indicates whether the high quality rendering feature is enabled.

      Returns:
      true if high quality rendering is enabled, false otherwise.

    • setHighQualityRenderingEnabled

      public final void setHighQualityRenderingEnabled(boolean enabled)

      Enables/disables high quality rendering.

      Parameters:
      enabled - enables/disables high quality rendering

    • isNavigationImageEnabled

      public final boolean isNavigationImageEnabled()

      Indicates whether navigation image is enabled.

      Returns:
      true when navigation image is enabled, false otherwise.

    • setNavigationImageEnabled

      public final void setNavigationImageEnabled(boolean enabled)

      Enables/disables navigation with the navigation image.

      Navigation image should be disabled when custom, programmatic navigation is implemented.

      Parameters:
      enabled - true when navigation image is enabled, false otherwise.

    • isMoveImageEnabled

      public final boolean isMoveImageEnabled()

    • setMoveImageEnabled

      public final void setMoveImageEnabled(boolean moveImageEnabled)

    • getZoom

      public final double getZoom()

      Gets the current zoom level.

      Returns:
      the current zoom level

    • setZoom

      public final void setZoom(double newZoom)

      Sets the zoom level used to display the image.

      This method is used in programmatic zooming. The zooming center is the point of the image closest to the center of the panel. After a new zoom level is set the image is repainted.

      Parameters:
      newZoom - the zoom level used to display this panel's image.

    • setZoom

      public final void setZoom(double newZoom, Point zoomingCenter)

      Sets the zoom level used to display the image, and the zooming center, around which zooming is done.

      This method is used in programmatic zooming. After a new zoom level is set the image is repainted.

      Parameters:
      newZoom - the zoom level used to display this panel's image.
      zoomingCenter - the zooming center

    • getZoomIncrement

      public final double getZoomIncrement()

      Gets the current zoom increment.

      Returns:
      the current zoom increment

    • setZoomIncrement

      public final void setZoomIncrement(double newZoomIncrement)

      Sets a new zoom increment value.

      Parameters:
      newZoomIncrement - new zoom increment value

    • getImageOrigin

      public final Point getImageOrigin()

      Gets the image origin.

      Image origin is defined as the upper, left corner of the image in the panel's coordinate system.

      Returns:
      the point of the upper, left corner of the image in the panel's coordinates system.

    • setImageOrigin

      public final void setImageOrigin(int x, int y)

      Sets the image origin.

      Image origin is defined as the upper, left corner of the image in the panel's coordinate system. After a new origin is set, the image is repainted. This method is used for programmatic image navigation.

      Parameters:
      x - the x coordinate of the new image origin
      y - the y coordinate of the new image origin

    • setImageOrigin

      public final void setImageOrigin(Point newOrigin)

      Sets the image origin.

      Image origin is defined as the upper, left corner of the image in the panel's coordinate system. After a new origin is set, the image is repainted. This method is used for programmatic image navigation.

      Parameters:
      newOrigin - the value of a new image origin

    • paintComponent

      protected void paintComponent(Graphics g)
      Paints the panel and its image at the current zoom level, location, and interpolation method dependent on the image scale.
      Overrides:
      paintComponent in class JComponent
      Parameters:
      g - the Graphics context for painting