Package org.geotools.image.util

Class ImageUtilities

Object
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

  • Field Details

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

    • 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

    • DIRECT_KAKADU_PLUGIN

      public static final String DIRECT_KAKADU_PLUGIN
      See Also:

    • RATIONAL_TOLERANCE

      public static final float RATIONAL_TOLERANCE
      See Also:

  • Method Details

    • 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 ImageN are active or not.
      Returns:
      false in case the ImageN 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)

    • getReferencedEnvelopeFromGeographicBoundingBox

      public static ReferencedEnvelope getReferencedEnvelopeFromGeographicBoundingBox(GeographicBoundingBox geographicBBox)
      Builds a ReferencedEnvelope from a GeographicBoundingBox. This is useful in order to have an implementation of BoundingBox from a GeographicBoundingBox which strangely does implement GeographicBoundingBox.
      Parameters:
      geographicBBox - the GeographicBoundingBox to convert.
      Returns:
      an instance of ReferencedEnvelope.

    • getWGS84ReferencedEnvelope

      public static ReferencedEnvelope getWGS84ReferencedEnvelope(GeneralBounds coverageEnvelope)
      Builds a ReferencedEnvelope in WGS84 from a GeneralBounds.
      Parameters:
      coverageEnvelope - the GeneralBounds to convert.
      Returns:
      an instance of ReferencedEnvelope in WGS84 or null in case a problem during the conversion occurs.

    • 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

    • setSubsamplingFactors

      public static void setSubsamplingFactors(ImageReadParam readParameters, double[] requestedRes, double[] selectedRes, int rasterWidth, int rasterHeight)
      Computes and applies suitable subsampling factors on the given ImageReadParam.

      The method determines integer subsampling factors based on the ratio between the requested resolution and the selected overview resolution, and applies several adjustments to ensure both quality and seamless rendering:

      • Uses floor(ratio + epsilon) to derive the base subsampling factor, avoiding oversampling and rounding errors.
      • Optionally increases the factor by +1 if this provides a closer match to the requested resolution and the relative error remains within a configurable tolerance (default 3%). This reduces the number of pixels read, improving performance with negligible quality loss.
      • Clamps the factors so they are never less than 1 or greater than the raster width/height.
      • If a source region is defined, aligns its x/y/width/height to multiples of the subsampling factors. This prevents “whiteline” artifacts (seams) by ensuring no partial rows/columns are skipped during read. Negative x/y are not expected at this stage (they would be rejected by ImageReadParam), but clipping to ≥0 is performed defensively.
      Parameters:
      readParameters - the read parameters on which to set the source region and subsampling
      requestedRes - the resolution requested by the client (x,y)
      selectedRes - the resolution of the selected overview (x,y)
      rasterWidth - full width of the raster
      rasterHeight - full height of the raster