Class ImageUtilities
*Factory
classes for creating those objects).- Since:
- 1.1
- Version:
- 1.2
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
Approximate size of the buffer to use for copying data from/to a raster, in bits.static final int
Default width and height of tiles, in pixels.private static final byte[]
The values to be returned bytoNumberEnum(int)
.static final int
Suggested size for a tile cache in number of tiles.private static final String[]
Names ofDataBuffer
types. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic short[]
bandNames
(ColorModel cm, SampleModel sm) Returns names of bands based on inspection of the sample model and color model.static void
clipBounds
(RenderedImage image, Rectangle aoi) Clips the given rectangle to the bounds of the given image.static int
Returns the data type of bands in rasters that use the given sample model.static Rectangle
getBounds
(RenderedImage image) Returns the bounds of the given image as a new rectangle.static String
Returns the name of theDataBuffer
type used by the given sample model.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.static short
Returns the key of a localizable text that describes the transparency.static int
getVisibleBand
(RenderedImage image) If the given image is showing only one band, returns the index of that band.static boolean
isIntegerType
(int dataType) Returnstrue
if the given data buffer type is an integer type.static boolean
Returnstrue
if the given sample model use an integer type.static boolean
isLosslessConversion
(SampleModel source, SampleModel target) Returns whether samples values stored usingsource
model can be converted totarget
model without data lost.static boolean
Returnstrue
if the type of sample values is an unsigned integer type.static Rectangle
pixelsToTiles
(RenderedImage image, Rectangle pixels) Converts pixel coordinates to pixel indices.static int
pixelToTileX
(RenderedImage image, int x) Converts a x pixel coordinates to a tile index.static int
pixelToTileY
(RenderedImage image, int y) Converts a y pixel coordinates to a tile index.static int
prepareTransferRegion
(Rectangle bounds, int dataType) Suggests the height of a transfer region for a tile of the given size.static boolean
If scale and shear coefficients are close to integers, replaces their current values by their rounded values.static Rectangle
tilesToPixels
(RenderedImage image, Rectangle tiles) Converts tile indices to pixel coordinate inside the tiles.static int
tileToPixelX
(RenderedImage image, int tileX) Converts a tile column index to smallest x pixel coordinate inside the tile.static int
tileToPixelY
(RenderedImage image, int tileY) Converts a tile row index to smallest y pixel coordinate inside the tile.static byte
toNumberEnum
(int dataType) Converts aDataBuffer
enumeration value toNumbers
enumeration value.
-
Field Details
-
DEFAULT_TILE_SIZE
public static final int DEFAULT_TILE_SIZEDefault width and height of tiles, in pixels.- See Also:
-
SUGGESTED_TILE_CACHE_SIZE
public static final int SUGGESTED_TILE_CACHE_SIZESuggested 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 byComputedImage
.- See Also:
-
BUFFER_SIZE
private static final int BUFFER_SIZEApproximate 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
Names ofDataBuffer
types. -
NUMBER_ENUMS
private static final byte[] NUMBER_ENUMSThe values to be returned bytoNumberEnum(int)
.
-
-
Constructor Details
-
ImageUtilities
private ImageUtilities()Do not allow instantiation of this class.
-
-
Method Details
-
getBounds
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
Clips the given rectangle to the bounds of the given image. Note thatRectangle.width
and/orRectangle.width
results may be negative. Consequently, the caller should testRectangle.isEmpty()
on the returned value.- Parameters:
image
- the image.aoi
- a region of interest to clip to the image bounds.
-
getNumBands
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, ornull
.- Returns:
- number of bands in the specified image, or 0 if the image or its sample model is null.
- See Also:
-
getVisibleBand
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, ornull
.- Returns:
- index of the visible band, or -1 if there is none or more than one.
-
getBandType
Returns the data type of bands in rasters that use the given sample model. If each band is stored in its ownDataBuffer
element, then this method returns the same value asSampleModel.getDataType()
. But if multiple sample values are packed in a single data element (SinglePixelPackedSampleModel
orMultiPixelPackedSampleModel
), 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 aBandedSampleModel
.- Parameters:
sm
- the sample model for which to get the band type, ornull
.- Returns:
- the data type, or
DataBuffer.TYPE_UNDEFINED
if unknown. - See Also:
-
getDataTypeName
Returns the name of theDataBuffer
type used by the given sample model.- Parameters:
sm
- the sample model for which to get the data type name, ornull
.- Returns:
- name of the given constant, or
null
if unknown.
-
getTransparencyDescription
Returns the key of a localizable text that describes the transparency. This method returns one of the following values:Resources.Keys.ImageAllowsTransparency
Resources.Keys.ImageHasAlphaChannel
Resources.Keys.ImageIsOpaque
- 0 if the transparency is unknown.
- Parameters:
cm
- the color model from which to get the transparency, ornull
.- Returns:
- a
Resources.Keys
value for the transparency, or 0 if unknown.
-
bandNames
Returns names of bands based on inspection of the sample model and color model. The bands are identified byVocabulary.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, ornull
if unknown.sm
- the image sample model (cannot be null).- Returns:
Vocabulary.Keys
identifying the bands.
-
toNumberEnum
public static byte toNumberEnum(int dataType) Converts aDataBuffer
enumeration value toNumbers
enumeration value. This method ignores whether the type is signed or unsigned.- Parameters:
dataType
- theDataBuffer
enumeration value.- Returns:
- the
Numbers
enumeration value.
-
isIntegerType
public static boolean isIntegerType(int dataType) Returnstrue
if the given data buffer type is an integer type. Returnsfalse
if the type is a floating point type or in case of doubt (e.g. forDataBuffer.TYPE_UNDEFINED
).- Parameters:
dataType
- one ofDataBuffer
constants.- Returns:
- whether the given constant is for an integer type.
-
isIntegerType
Returnstrue
if the given sample model use an integer type. Returnsfalse
if the type is a floating point type or in case of doubt (e.g. forDataBuffer.TYPE_UNDEFINED
).- Parameters:
sm
- the sample model, ornull
.- Returns:
- whether the given sample model is for integer values.
-
isUnsignedType
Returnstrue
if the type of sample values is an unsigned integer type. Returnsfalse
if the type is a floating point type or in case of doubt (e.g. forDataBuffer.TYPE_UNDEFINED
).- Parameters:
sm
- the sample model, ornull
.- Returns:
- whether the given sample model provides unsigned sample values.
-
isLosslessConversion
Returns whether samples values stored usingsource
model can be converted totarget
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
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
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
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
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
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
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
Suggests the height of a transfer region for a tile of the given size. The given region should be contained insideRaster.getBounds()
. This method modifiesRectangle.height
in-place. TheRectangle.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 ofDataBuffer
constant. It is okay if an unknown constant is used since this information is used only as a hint for adjusting theBUFFER_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
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).
-