Package org.apache.sis.internal.coverage.j2d

Class ImageUtilities

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.internal.coverage.j2d.ImageUtilities
public final class ImageUtilities extends Static
Utility methods related to images and their color model or sample model. Those methods only fetch information, they do not create new rasters or sample/color models (see *Factory classes for creating those objects).
Since:
1.1
Version:
1.2

  • Field Details

    • DEFAULT_TILE_SIZE

      public static final int DEFAULT_TILE_SIZE
      Default width and height of tiles, in pixels.
      See Also:

    • SUGGESTED_TILE_CACHE_SIZE

      public static final int SUGGESTED_TILE_CACHE_SIZE
      Suggested size for a tile cache in number of tiles. This value can be used for very simple caching mechanism, keeping the most recently used tiles up to 10 Mb of memory. This is not for sophisticated caching mechanism; instead the "real" caching should be done by ComputedImage.
      See Also:

    • BUFFER_SIZE

      private static final int BUFFER_SIZE
      Approximate size of the buffer to use for copying data from/to a raster, in bits. The actual buffer size may be smaller or larger, depending on the actual tile size. This value does not need to be very large. The current value is 8 kb.
      See Also:

    • TYPE_NAMES

      private static final String[] TYPE_NAMES
      Names of DataBuffer types.

    • NUMBER_ENUMS

      private static final byte[] NUMBER_ENUMS
      The values to be returned by toNumberEnum(int).

  • Constructor Details

    • ImageUtilities

      private ImageUtilities()
      Do not allow instantiation of this class.

  • Method Details

    • getBounds

      public static Rectangle getBounds(RenderedImage image)
      Returns the bounds of the given image as a new rectangle.
      Parameters:
      image - the image for which to get the bounds.
      Returns:
      the bounds of the given image.
      See Also:

    • clipBounds

      public static void clipBounds(RenderedImage image, Rectangle aoi)
      Clips the given rectangle to the bounds of the given image. Note that Rectangle.width and/or Rectangle.width results may be negative. Consequently, the caller should test Rectangle.isEmpty() on the returned value.
      Parameters:
      image - the image.
      aoi - a region of interest to clip to the image bounds.

    • getNumBands

      public static int getNumBands(RenderedImage image)
      Returns the number of bands in the given image, or 0 if the image or its sample model is null.
      Parameters:
      image - the image for which to get the number of bands, or null.
      Returns:
      number of bands in the specified image, or 0 if the image or its sample model is null.
      See Also:

    • getVisibleBand

      public static int getVisibleBand(RenderedImage image)
      If the given image is showing only one band, returns the index of that band. Otherwise returns 0. Image showing only one band are SIS-specific (usually an image show all its bands).
      Parameters:
      image - the image for which to get the visible band, or null.
      Returns:
      index of the visible band, or -1 if there is none or more than one.

    • getBandType

      public static int getBandType(SampleModel sm)
      Returns the data type of bands in rasters that use the given sample model. If each band is stored in its own DataBuffer element, then this method returns the same value as SampleModel.getDataType(). But if multiple sample values are packed in a single data element (SinglePixelPackedSampleModel or MultiPixelPackedSampleModel), then this method returns a smaller data type. As a general rule, this method returns the smallest data type capable to store all sample values with a BandedSampleModel.
      Parameters:
      sm - the sample model for which to get the band type, or null.
      Returns:
      the data type, or DataBuffer.TYPE_UNDEFINED if unknown.
      See Also:

    • getDataTypeName

      public static String getDataTypeName(SampleModel sm)
      Returns the name of the DataBuffer type used by the given sample model.
      Parameters:
      sm - the sample model for which to get the data type name, or null.
      Returns:
      name of the given constant, or null if unknown.

    • getTransparencyDescription

      public static short getTransparencyDescription(ColorModel cm)
      Returns the key of a localizable text that describes the transparency. This method returns one of the following values:
      Parameters:
      cm - the color model from which to get the transparency, or null.
      Returns:
      a Resources.Keys value for the transparency, or 0 if unknown.

    • bandNames

      public static short[] bandNames(ColorModel cm, SampleModel sm)
      Returns names of bands based on inspection of the sample model and color model. The bands are identified by Vocabulary.Keys values for red, green, blue, cyan, magenta, yellow, black, gray, etc. If a band cannot be identified, then its corresponding value is 0.
      Parameters:
      cm - the color model for which to get band names, or null if unknown.
      sm - the image sample model (cannot be null).
      Returns:
      Vocabulary.Keys identifying the bands.

    • toNumberEnum

      public static byte toNumberEnum(int dataType)
      Converts a DataBuffer enumeration value to Numbers enumeration value. This method ignores whether the type is signed or unsigned.
      Parameters:
      dataType - the DataBuffer enumeration value.
      Returns:
      the Numbers enumeration value.

    • isIntegerType

      public static boolean isIntegerType(int dataType)
      Returns true if the given data buffer type is an integer type. Returns false if the type is a floating point type or in case of doubt (e.g. for DataBuffer.TYPE_UNDEFINED).
      Parameters:
      dataType - one of DataBuffer constants.
      Returns:
      whether the given constant is for an integer type.

    • isIntegerType

      public static boolean isIntegerType(SampleModel sm)
      Returns true if the given sample model use an integer type. Returns false if the type is a floating point type or in case of doubt (e.g. for DataBuffer.TYPE_UNDEFINED).
      Parameters:
      sm - the sample model, or null.
      Returns:
      whether the given sample model is for integer values.

    • isUnsignedType

      public static boolean isUnsignedType(SampleModel sm)
      Returns true if the type of sample values is an unsigned integer type. Returns false if the type is a floating point type or in case of doubt (e.g. for DataBuffer.TYPE_UNDEFINED).
      Parameters:
      sm - the sample model, or null.
      Returns:
      whether the given sample model provides unsigned sample values.

    • isLosslessConversion

      public static boolean isLosslessConversion(SampleModel source, SampleModel target)
      Returns whether samples values stored using source model can be converted to target model without data lost. This method verifies the number of bands and the size of data in each band.
      Parameters:
      source - model of sample values to convert.
      target - model of converted sample values.
      Returns:
      whether the conversion from source model to target model is lossless.

    • pixelToTileX

      public static int pixelToTileX(RenderedImage image, int x)
      Converts a x pixel coordinates to a tile index.
      Parameters:
      image - the image containing tiles.
      x - the pixel coordinate for which to get tile index.
      Returns:
      tile index for the given pixel coordinate.

    • pixelToTileY

      public static int pixelToTileY(RenderedImage image, int y)
      Converts a y pixel coordinates to a tile index.
      Parameters:
      image - the image containing tiles.
      y - the pixel coordinate for which to get tile index.
      Returns:
      tile index for the given pixel coordinate.

    • tileToPixelX

      public static int tileToPixelX(RenderedImage image, int tileX)
      Converts a tile column index to smallest x pixel coordinate inside the tile. The returned value is a coordinate of the pixel in upper-left corner.
      Parameters:
      image - the image containing tiles.
      tileX - the tile index for which to get pixel coordinate.
      Returns:
      smallest x pixel coordinate inside the tile.

    • tileToPixelY

      public static int tileToPixelY(RenderedImage image, int tileY)
      Converts a tile row index to smallest y pixel coordinate inside the tile. The returned value is a coordinate of the pixel in upper-left corner.
      Parameters:
      image - the image containing tiles.
      tileY - the tile index for which to get pixel coordinate.
      Returns:
      smallest y pixel coordinate inside the tile.

    • pixelsToTiles

      public static Rectangle pixelsToTiles(RenderedImage image, Rectangle pixels)
      Converts pixel coordinates to pixel indices. This method does not clip the rectangle to image bounds.
      Parameters:
      image - the image containing tiles.
      pixels - the pixel coordinates for which to get tile indices.
      Returns:
      tile indices that fully contain the pixel coordinates.

    • tilesToPixels

      public static Rectangle tilesToPixels(RenderedImage image, Rectangle tiles)
      Converts tile indices to pixel coordinate inside the tiles. Tiles will be fully included in the returned range of pixel indices. This method does not clip the rectangle to image bounds.
      Parameters:
      image - the image containing tiles.
      tiles - the tile indices for which to get pixel coordinates.
      Returns:
      pixel coordinates that fully contain the tiles.

    • prepareTransferRegion

      public static int prepareTransferRegion(Rectangle bounds, int dataType)
      Suggests the height of a transfer region for a tile of the given size. The given region should be contained inside Raster.getBounds(). This method modifies Rectangle.height in-place. The Rectangle.width value is never modified, so caller can iterate on all raster rows without the need to check if the row is incomplete.
      Parameters:
      bounds - on input, the region of interest. On output, the suggested transfer region bounds.
      dataType - one of DataBuffer constant. It is okay if an unknown constant is used since this information is used only as a hint for adjusting the BUFFER_SIZE value.
      Returns:
      the maximum y value plus 1. This can be used as stop condition for iterating over rows.
      Throws:
      ArithmeticException - if the maximum y value overflows 32 bits integer capacity.
      RasterFormatException - if the given bounds is empty.

    • roundIfAlmostInteger

      public static boolean roundIfAlmostInteger(AffineTransform tr)
      If scale and shear coefficients are close to integers, replaces their current values by their rounded values. The scale and shear coefficients are handled in a "all or nothing" way; either all of them or none are rounded. The translation terms are handled separately, provided that the scale and shear coefficients have been rounded.

      This rounding is useful in order to accelerate some rendering operations. In particular Java2D has an optimization when drawing RenderedImage: if the transform has only a translation (scale factors are equal to 1) and if that translation is integer, then Java2D will fetch only tiles that are required for the area to draw. Otherwise Java2D fetches a copy of the whole image.

      This method assumes that the given argument is a transform from something to display coordinates in pixel units, or other kind of measurements usually expressed as integer values. In particular this method assumes that if the scale and shear factors are integers, then translation terms should also be integer. Be careful to not use this method with transforms where the translation terms may have a 0.5 offset (e.g. for mapping pixel centers).

      Parameters:
      tr - the transform to round in place. Target coordinates should be integer measurements such as pixels.
      Returns:
      whether the transform has integer coefficients (possibly after rounding applied by this method).