ImageUtilities (Geotools modules 28-SNAPSHOT API)

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 Summary

Fields
Modifier and Type	Field and Description
`static RenderingHints`	`BORDER_EXTENDER_HINTS`
`static BorderExtender`	`DEFAULT_BORDER_EXTENDER`
`static String`	`DIRECT_KAKADU_PLUGIN`
`static RenderingHints`	`DONT_REPLACE_INDEX_COLOR_MODEL` `RenderingHints` used to prevent `JAI` operations from expanding `IndexColorModel`s.
`static RenderingHints`	`EXTEND_BORDER_BY_COPYING` Cached instance of a `RenderingHints` for controlling border extension on `JAI` operations.
`static RenderingHints`	`EXTEND_BORDER_BY_REFLECT` Cached instance of a `RenderingHints` for controlling border extension on `JAI` operations.
`static String[]`	`INTERPOLATION_NAMES` List of valid names.
`static int[]`	`INTERPOLATION_TYPES` Interpolation types (provided by Java Advanced Imaging) for `INTERPOLATION_NAMES`.
`static RenderingHints`	`NN_INTERPOLATION_HINT` `RenderingHints` for requesting Nearest Neighbor intepolation.
`static RenderingHints`	`NOCACHE_HINT` `RenderingHints` for avoiding caching of `JAI` `RenderedOp`s.
`static float`	`RATIONAL_TOLERANCE`
`static RenderingHints`	`REPLACE_INDEX_COLOR_MODEL` `RenderingHints` used to force `JAI` operations to expand `IndexColorModel`s.
`static double[][]`	`RGB_TO_GRAY_MATRIX`
`static double[][]`	`RGBA_TO_GRAY_MATRIX`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and 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 `RenderedImage`s 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)` Builds a `ReferencedEnvelope` from a `GeographicBoundingBox`.
`static RenderingHints`	`getRenderingHints(RenderedImage image)` Suggests a set of `RenderingHints` for the specified image.
`static ReferencedEnvelope`	`getWGS84ReferencedEnvelope(GeneralEnvelope coverageEnvelope)` Builds a `ReferencedEnvelope` in WGS84 from a `GeneralEnvelope`.
`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
```
  - DIRECT_KAKADU_PLUGIN
```
public static final String DIRECT_KAKADU_PLUGIN
```
    See Also:
    
    Constant Field Values
  - RATIONAL_TOLERANCE
```
public static final float RATIONAL_TOLERANCE
```
    See Also:
    
    Constant Field Values
- 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 . 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)
```
  - 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(GeneralEnvelope coverageEnvelope)
```
    Builds a ReferencedEnvelope in WGS84 from a GeneralEnvelope.
    
    Parameters:
    
    coverageEnvelope - the GeneralEnvelope 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

Class ImageUtilities

Field Summary

Method Summary

Methods inherited from class Object

Field Detail

RGB_TO_GRAY_MATRIX

RGBA_TO_GRAY_MATRIX

DONT_REPLACE_INDEX_COLOR_MODEL

REPLACE_INDEX_COLOR_MODEL

NN_INTERPOLATION_HINT

NOCACHE_HINT

EXTEND_BORDER_BY_COPYING

EXTEND_BORDER_BY_REFLECT

INTERPOLATION_NAMES

INTERPOLATION_TYPES

DEFAULT_BORDER_EXTENDER

BORDER_EXTENDER_HINTS

DIRECT_KAKADU_PLUGIN

RATIONAL_TOLERANCE

Method Detail

getImageLayout

getRenderingHints

toTileSize

createIntersection

toInterpolation

getInterpolationName

tileImage

fill

isMediaLibAvailable

disposePlanarImageChain

maskColor

cloneImageReadParam

layoutHelper

getReferencedEnvelopeFromGeographicBoundingBox

getWGS84ReferencedEnvelope

getDimension

checkEmptySourceRegion

getBackgroundValues

disposeImage

disposeSinglePlanarImage

getDatabufferTypeName

applyRescaling