Class ImageUtilities


  • public final class ImageUtilities
    extends Object
    A set of static methods working on images. Some of those methods are useful, but not really rigorous. This is why they do not appear in any "official" package, but instead in this private one.

    Do not rely on this API!

    It may change in incompatible way in any future version.

    Since:
    2.0
    Author:
    Martin Desruisseaux (IRD), Simone Giannecchini, GeoSolutions
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static RenderedImage applyRescaling​(Double[] scales, Double[] offsets, RenderedImage image, Hints hints)
      Applies values rescaling if either the scales or the offsets array is non null, or has any value that is not a default (1 for scales, 0 for offsets)
      static boolean checkEmptySourceRegion​(ImageReadParam readParameters, Rectangle dimensions)
      Checks that the provided dimensions when intersected with the source region used by the provided ImageReadParam instance does not result in an empty Rectangle.
      static ImageReadParam cloneImageReadParam​(ImageReadParam param)  
      static ImageLayout createIntersection​(ImageLayout layout, List<RenderedImage> sources)
      Computes a new ImageLayout which is the intersection of the specified ImageLayout and all RenderedImages in the supplied list.
      static void disposeImage​(RenderedImage inputImage)
      Allow to dispose this image, as well as the related image sources, readers, stream, ROI.
      static void disposePlanarImageChain​(PlanarImage pi)
      Dispose an image with all its ancestors.
      static void disposeSinglePlanarImage​(PlanarImage planarImage)
      Disposes the specified image, without recursing back in the sources
      static void fill​(WritableRenderedImage image, Number value)
      Sets every samples in the given image to the given value.
      static Number[] getBackgroundValues​(SampleModel sampleModel, double[] backgroundValues)
      Build a background values array using the same dataType of the input SampleModel (if available) and the values provided in the input array.
      static String getDatabufferTypeName​(int dataType)
      Transform a data type into a representative String.
      static Rectangle getDimension​(int imageIndex, ImageInputStream inStream, ImageReader reader)
      Retrieves the dimensions of the RenderedImage at index imageIndex for the provided ImageReader and ImageInputStream.
      static ImageLayout getImageLayout​(RenderedImage image)
      Suggests an ImageLayout for the specified image.
      static String getInterpolationName​(Interpolation interp)
      Returns the interpolation name for the specified interpolation object.
      static ReferencedEnvelope getReferencedEnvelopeFromGeographicBoundingBox​(GeographicBoundingBox geographicBBox)
      static RenderingHints getRenderingHints​(RenderedImage image)
      Suggests a set of RenderingHints for the specified image.
      static ReferencedEnvelope getWGS84ReferencedEnvelope​(GeneralBounds coverageEnvelope)
      Builds a ReferencedEnvelope in WGS84 from a GeneralBounds.
      static boolean isMediaLibAvailable()
      Tells me whether or not the native libraries for JAI are active or not.
      static Rectangle2D layoutHelper​(RenderedImage source, float scaleX, float scaleY, float transX, float transY, Interpolation interp)  
      static RenderedImage maskColor​(Color transparentColor, RenderedImage image)
      Relies on the ImageWorker to mask a certain color from an image.
      static RenderedOp tileImage​(RenderedOp image)
      Tiles the specified image.
      static Interpolation toInterpolation​(Object type)
      Casts the specified object to an object.
      static Dimension toTileSize​(Dimension size)
      Suggests a tile size for the specified image size.
      • Methods inherited from class Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • RGB_TO_GRAY_MATRIX

        public static final double[][] RGB_TO_GRAY_MATRIX
      • RGBA_TO_GRAY_MATRIX

        public static final double[][] RGBA_TO_GRAY_MATRIX
      • DONT_REPLACE_INDEX_COLOR_MODEL

        public static final RenderingHints DONT_REPLACE_INDEX_COLOR_MODEL
        RenderingHints used to prevent JAI operations from expanding IndexColorModels.
      • REPLACE_INDEX_COLOR_MODEL

        public static final RenderingHints REPLACE_INDEX_COLOR_MODEL
        RenderingHints used to force JAI operations to expand IndexColorModels.
      • NN_INTERPOLATION_HINT

        public static final RenderingHints NN_INTERPOLATION_HINT
        RenderingHints for requesting Nearest Neighbor intepolation.
      • NOCACHE_HINT

        public static final RenderingHints NOCACHE_HINT
        RenderingHints for avoiding caching of JAI RenderedOps.
      • EXTEND_BORDER_BY_COPYING

        public static final RenderingHints EXTEND_BORDER_BY_COPYING
        Cached instance of a RenderingHints for controlling border extension on JAI operations. It contains an instance of a BorderExtenderCopy.
      • EXTEND_BORDER_BY_REFLECT

        public static final RenderingHints EXTEND_BORDER_BY_REFLECT
        Cached instance of a RenderingHints for controlling border extension on JAI operations. It contains an instance of a BorderExtenderReflect.
      • INTERPOLATION_NAMES

        public static final String[] INTERPOLATION_NAMES
        List of valid names. Note: the "Optimal" type is not implemented because currently not provided by JAI.
      • INTERPOLATION_TYPES

        public static final int[] INTERPOLATION_TYPES
        Interpolation types (provided by Java Advanced Imaging) for INTERPOLATION_NAMES.
      • DEFAULT_BORDER_EXTENDER

        public static final BorderExtender DEFAULT_BORDER_EXTENDER
      • BORDER_EXTENDER_HINTS

        public static final RenderingHints BORDER_EXTENDER_HINTS
    • Method Detail

      • getImageLayout

        public static ImageLayout getImageLayout​(RenderedImage image)
        Suggests an ImageLayout for the specified image. All parameters are initially set equal to those of the given RenderedImage, and then the tile size is updated according the image size. This method never returns null.
      • getRenderingHints

        public static RenderingHints getRenderingHints​(RenderedImage image)
        Suggests a set of RenderingHints for the specified image. The rendering hints may include the following parameters:
        • JAI.KEY_IMAGE_LAYOUT with a proposed tile size.
        This method may returns null if no rendering hints is proposed.
      • toTileSize

        public static Dimension toTileSize​(Dimension size)
        Suggests a tile size for the specified image size. On input, size is the image's size. On output, it is the tile size. This method write the result directly in the supplied object and returns size for convenience.

        This method it aimed to computing a tile size such that the tile grid would have overlapped the image bound in order to avoid having tiles crossing the image bounds and being therefore partially empty. This method will never returns a tile size smaller than 256. If this method can't suggest a size, then it left the corresponding size field (width or height) unchanged.

        The width and height fields are processed independently in the same way. The following discussion use the width field as an example.

        This method inspects different tile sizes close to the default tile size. Lets width be the default tile width. Values are tried in the following order: width, width+1, width-1, width+2, width-2, width+3, width-3, etc. until one of the following happen:

        • A suitable tile size is found. More specifically, a size is found which is a dividor of the specified image size, and is the closest one of the default tile size. The Dimension field (width or height) is set to this value.
        • An arbitrary limit (both a minimum and a maximum tile size) is reached. In this case, this method may set the Dimension field to a value that maximize the remainder of image size / tile size (in other words, the size that left as few empty pixels as possible).
      • createIntersection

        public static ImageLayout createIntersection​(ImageLayout layout,
                                                     List<RenderedImage> sources)
        Computes a new ImageLayout which is the intersection of the specified ImageLayout and all RenderedImages in the supplied list. If the minX, minY, width and height properties are not defined in the layout, then they will be inherited from the first source for consistency with OpImage constructor.
        Parameters:
        layout - The original layout. This object will not be modified.
        sources - The list of sources RenderedImage.
        Returns:
        A new ImageLayout, or the original layout if no change was needed.
      • toInterpolation

        public static Interpolation toInterpolation​(Object type)
                                             throws IllegalArgumentException
        Casts the specified object to an object.
        Parameters:
        type - The interpolation type as an Interpolation or a CharSequence object.
        Returns:
        The interpolation object for the specified type.
        Throws:
        IllegalArgumentException - if the specified interpolation type is not a know one.
      • getInterpolationName

        public static String getInterpolationName​(Interpolation interp)
        Returns the interpolation name for the specified interpolation object. This method tries to infer the name from the object's class name.
        Parameters:
        interp - The interpolation object, or null for "nearest" (which is an other way to say "no interpolation").
      • tileImage

        public static RenderedOp tileImage​(RenderedOp image)
                                    throws IOException
        Tiles the specified image.
        Throws:
        IOException - If an I/O operation were required (in order to check if the image were tiled on disk) and failed.
        Since:
        2.3
      • fill

        public static void fill​(WritableRenderedImage image,
                                Number value)
        Sets every samples in the given image to the given value. This method is typically used for clearing an image content.
        Parameters:
        image - The image to fill.
        value - The value to to given to every samples.
      • isMediaLibAvailable

        public static boolean isMediaLibAvailable()
        Tells me whether or not the native libraries for JAI are active or not.
        Returns:
        false in case the JAI native libs are not in the path, true otherwise.
      • disposePlanarImageChain

        public static void disposePlanarImageChain​(PlanarImage pi)
        Dispose an image with all its ancestors.
        Parameters:
        pi - the PlanarImage to dispose.
      • maskColor

        public static RenderedImage maskColor​(Color transparentColor,
                                              RenderedImage image)
                                       throws IllegalStateException
        Relies on the ImageWorker to mask a certain color from an image.
        Parameters:
        transparentColor - the Color to make transparent
        image - the RenderedImage to work on
        Returns:
        a new RenderedImage where the provided Color has turned into transparent.
        Throws:
        IllegalStateException
      • cloneImageReadParam

        public static ImageReadParam cloneImageReadParam​(ImageReadParam param)
      • layoutHelper

        public static Rectangle2D layoutHelper​(RenderedImage source,
                                               float scaleX,
                                               float scaleY,
                                               float transX,
                                               float transY,
                                               Interpolation interp)
      • getDimension

        public static Rectangle getDimension​(int imageIndex,
                                             ImageInputStream inStream,
                                             ImageReader reader)
                                      throws IOException
        Retrieves the dimensions of the RenderedImage at index imageIndex for the provided ImageReader and ImageInputStream.

        Notice that none of the input parameters can be null or a NullPointerException will be thrown. Morevoer the imageIndex cannot be negative or an IllegalArgumentException will be thrown.

        Parameters:
        imageIndex - the index of the image to get the dimensions for.
        inStream - the ImageInputStream to use as an input
        reader - the ImageReader to decode the image dimensions.
        Returns:
        a Rectangle that contains the dimensions for the image at index imageIndex
        Throws:
        IOException - in case the ImageReader or the ImageInputStream fail.
      • checkEmptySourceRegion

        public static final boolean checkEmptySourceRegion​(ImageReadParam readParameters,
                                                           Rectangle dimensions)
        Checks that the provided dimensions when intersected with the source region used by the provided ImageReadParam instance does not result in an empty Rectangle.

        Input parameters cannot be null.

        Parameters:
        readParameters - an instance of ImageReadParam for which we want to check the source region element.
        dimensions - an instance of Rectangle to use for the check.
        Returns:
        true if the intersection is not empty, false otherwise.
      • getBackgroundValues

        public static Number[] getBackgroundValues​(SampleModel sampleModel,
                                                   double[] backgroundValues)
        Build a background values array using the same dataType of the input SampleModel (if available) and the values provided in the input array.
      • disposeImage

        public static void disposeImage​(RenderedImage inputImage)
        Allow to dispose this image, as well as the related image sources, readers, stream, ROI.
        Parameters:
        inputImage - the image to be disposed.
      • disposeSinglePlanarImage

        public static void disposeSinglePlanarImage​(PlanarImage planarImage)
        Disposes the specified image, without recursing back in the sources
      • getDatabufferTypeName

        public static String getDatabufferTypeName​(int dataType)
        Transform a data type into a representative String.
        Returns:
        a representative String.
      • applyRescaling

        public static RenderedImage applyRescaling​(Double[] scales,
                                                   Double[] offsets,
                                                   RenderedImage image,
                                                   Hints hints)
        Applies values rescaling if either the scales or the offsets array is non null, or has any value that is not a default (1 for scales, 0 for offsets)
        Parameters:
        scales - The scales array
        offsets - The offsets array
        image - The image to be rescaled
        hints - The image processing hints, if any (can be null)
        Returns:
        The original image, or a rescaled image