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

    Author: Slav Boleslawski http://today.java.net/pub/a/today/2007/03/27/navigable-image-panel.html

    See Also:
    Serialized Form
    • Field Detail

      • ZOOM_LEVEL_CHANGED_PROPERTY

        public static final String ZOOM_LEVEL_CHANGED_PROPERTY

        Identifies a change to the zoom level.

        See Also:
        Constant Field Values
      • ZOOM_INCREMENT_CHANGED_PROPERTY

        public static final String ZOOM_INCREMENT_CHANGED_PROPERTY

        Identifies a change to the zoom increment.

        See Also:
        Constant Field Values
      • IMAGE_CHANGED_PROPERTY

        public static final String IMAGE_CHANGED_PROPERTY

        Identifies that the image in the panel has changed.

        See Also:
        Constant Field Values
    • Constructor Detail

      • 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 Detail

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