Class ComputedImage
- All Implemented Interfaces:
- RenderedImage,- Disposable
- Direct Known Subclasses:
- ResampledImage
ComputedImage may have an arbitrary number of source images, including zero.
 A TileObserver is automatically registered to all sources that are instances of
 WritableRenderedImage. If one of those sources sends a change event, then all
 ComputedImage tiles that may be impacted by that change are marked as dirty
 and will be computed again when needed.
When this ComputedImage is garbage collected, all cached tiles are discarded
 and the above-cited TileObserver is automatically removed from all sources.
 This cleanup can be requested without waiting for garbage collection by invoking the
 dispose() method, but that call should be done only if the caller is certain
 that this ComputedImage will not be used anymore.
Pixel coordinate system
Default implementation assumes that the pixel in upper-left left corner is located at coordinates (0,0). This assumption is consistent withGridCoverage.render(GridExtent)
 contract, which produces an image located at (0,0) when the image region matches the GridExtent.
 However, subclasses can use a non-zero origin by overriding the methods documented in the
 Sub-classing section below.
 If this ComputedImage does not have any WritableRenderedImage source, then there is
 no other assumption on the pixel coordinate system. But if there is writable sources, then the default
 implementation assumes that source images occupy the same region as this ComputedImage:
 all pixels at coordinates (x, y) in this ComputedImage depend on pixels
 at the same (x, y) coordinates in the source images,
 possibly shifted or expanded to neighborhood pixels as described in SOURCE_PADDING_KEY.
 If this assumption does not hold, then subclasses should override the
 sourceTileChanged(RenderedImage, int, int) method.
Sub-classing
Subclasses need to implement at least the following methods:
- RenderedImage.getWidth()— the image width in pixels.
- RenderedImage.getHeight()— the image height in pixels.
- computeTile(int, int, WritableRaster)— invoked when a requested tile is not in the cache or needs to be updated.
If pixel coordinates or tile indices do not start at zero, then subclasses shall also override the following methods:
- PlanarImage.getMinX()— the minimum x coordinate (inclusive) of the image.
- PlanarImage.getMinY()— the minimum y coordinate (inclusive) of the image.
- PlanarImage.getMinTileX()— the minimum tile index in the x direction.
- PlanarImage.getMinTileY()— the minimum tile index in the y direction.
Writable computed images
ComputedImage can itself be a WritableRenderedImage if subclasses decide so.
 A writable computed image is an image which can retro-propagate sample value changes to the source images.
 This class provides hasTileWriters(), getWritableTileIndices(), isTileWritable(int, int)
 and markTileWritable(int, int, boolean) methods for WritableRenderedImage implementations convenience.
 Apache SIS does not yet define a synchronization policy
 between getTile(…) method and WritableRenderedImage.getWritableTile/releaseWritableTile(…) methods.
 For example if a call to getTile(tileX, tileY) is followed by a call to getWritableTile(tileX, tileY)
 in another thread, there is no guarantee about whether or not the sample values seen in the Raster would be
 isolated from the write operations done concurrently in the WritableRaster.
 A future SIS version may define a policy (possibly based on ReadWriteLock).
Note that despite above-cited issue, all methods in this ComputedImage class are thread-safe.
 What is not thread-safe is writing into a WritableRaster from outside the computeTile(…) method, or reading a Raster after it became dirty
 if the change to dirty state happened after the call to getTile(…).
- Since:
- 1.1
Defined in the sis-feature module
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected final SampleModelThe sample model shared by all tiles in this image.static final StringThe property for declaring the amount of additional source pixels needed on each side of a destination pixel.Fields inherited from class PlanarImageGRID_GEOMETRY_KEY, MASK_KEY, POSITIONAL_ACCURACY_KEY, SAMPLE_RESOLUTIONS_KEY, STATISTICS_KEY
- 
Constructor SummaryConstructorsModifierConstructorDescriptionprotectedComputedImage(SampleModel sampleModel, RenderedImage... sources) Creates an initially empty image with the given sample model.
- 
Method SummaryModifier and TypeMethodDescriptionprotected booleanclearErrorFlags(Rectangle tiles) Clears the error status of all tiles in the given range of indices.protected abstract RastercomputeTile(int tileX, int tileY, WritableRaster previous) Invoked when a tile need to be computed or updated.protected WritableRastercreateTile(int tileX, int tileY) Creates an initially empty tile at the given tile grid position.voiddispose()Advises this image that its tiles will no longer be requested.Returns the sample model associated with this image.protected final RenderedImagegetSource(int index) Returns the source at the given index.Returns the immediate sources of image data for this image (may benull).final RastergetTile(int tileX, int tileY) Returns a tile of this image, computing it when needed.intReturns the height of tiles in this image.intReturns the width of tiles in this image.Point[]Returns the indices of all tiles under computation or checked out for writing, ornullif none.booleanReturns whether any tile is under computation or is checked out for writing.booleanisTileWritable(int tileX, int tileY) Returns whether the specified tile is currently under computation or checked out for writing.protected booleanmarkDirtyTiles(Rectangle tiles) Marks all tiles in the given range of indices as in need of being recomputed.protected booleanmarkTileWritable(int tileX, int tileY, boolean writing) Sets or clears whether a tile is checked out for writing.protected DisposableNotifies this image that tiles will be computed soon in the given region.protected voidsourceTileChanged(RenderedImage source, int tileX, int tileY) Invoked when a tile of a source image has been updated.Methods inherited from class PlanarImagecopyData, getBounds, getData, getData, getMinTileX, getMinTileY, getMinX, getMinY, getNumXTiles, getNumYTiles, getProperty, getPropertyNames, getTileGridXOffset, getTileGridYOffset, toString, verifyMethods inherited from class Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods inherited from interface RenderedImagegetColorModel, getHeight, getWidth
- 
Field Details- 
SOURCE_PADDING_KEYThe property for declaring the amount of additional source pixels needed on each side of a destination pixel. This property can be used for calculations that require only a fixed rectangular source region around a source pixel in order to compute each destination pixel. A given destination pixel (x, y) may be computed from the neighborhood of source pixels beginning at (x -Insets.left, y -Insets.top) and extending to (x +Insets.right, y +Insets.bottom) inclusive. Thoseleft,top,rightandbottomattributes can be positive, zero or negative, but their sums shall be positive with (left+right) ≥ 0 and (top+bottom) ≥ 0.The property value shall be an instance of InsetsorInsets[]. The array form can be used when a different padding is required for each source image. In that case, the image source index is used as the index for accessing theInsetselement in the array. Null or undefined elements mean that no padding is applied. If the array length is shorter than the number of source images, missing elements are considered as null.
- 
sampleModelThe sample model shared by all tiles in this image. The sample model width determines this image tile width, and the sample model height determines this image tile height.Design note:ComputedImagerequires the sample model to have exactly the desired tile size otherwise tiles created bycreateTile(int, int)will consume more memory than needed.
 
- 
- 
Constructor Details- 
ComputedImageCreates an initially empty image with the given sample model. The default tile size will be the width and height of the given sample model (this default setting minimizes the amount of memory consumed bycreateTile(int, int)). This constructor automatically registers aTileObserverfor all sources that areWritableRenderedImageinstances.- Parameters:
- sampleModel- the sample model shared by all tiles in this image.
- sources- sources of this image (may be an empty array), or a null array if unknown.
 
 
- 
- 
Method Details- 
getSourceReturns the source at the given index.- Parameters:
- index- index of the desired source.
- Returns:
- source at the given index.
- Throws:
- IndexOutOfBoundsException- if the given index is out of bounds.
 
- 
getSourcesReturns the immediate sources of image data for this image (may benull). This method returns all sources specified at construction time.- Specified by:
- getSourcesin interface- RenderedImage
- Overrides:
- getSourcesin class- PlanarImage
- Returns:
- the immediate sources, or an empty vector is none, or nullif unknown.
 
- 
getSampleModelReturns the sample model associated with this image. All rasters returned from this image will have this sample model. InComputedImageimplementation, the sample model determines the tile size (this is not necessarily true for allRenderedImageimplementations).- Specified by:
- getSampleModelin interface- RenderedImage
- Returns:
- the sample model of this image.
 
- 
getTileWidthpublic int getTileWidth()Returns the width of tiles in this image. The default implementation returnsSampleModel.getWidth().Note: a raster can have a smaller width than its sample model, for example when a raster is a view over a subregion of another raster. But this is not recommended in the particular case of thisComputedImageclass, because it would causecreateTile(int, int)to consume more memory than necessary.- Specified by:
- getTileWidthin interface- RenderedImage
- Returns:
- the width of this image in pixels.
 
- 
getTileHeightpublic int getTileHeight()Returns the height of tiles in this image. The default implementation returnsSampleModel.getHeight().Note: a raster can have a smaller height than its sample model, for example when a raster is a view over a subregion of another raster. But this is not recommended in the particular case of thisComputedImageclass, because it would causecreateTile(int, int)to consume more memory than necessary.- Specified by:
- getTileHeightin interface- RenderedImage
- Returns:
- the height of this image in pixels.
 
- 
getTileReturns a tile of this image, computing it when needed. This method performs the first of the following actions that apply:- If the requested tile is present in the cache and is not dirty, then that tile is returned immediately.
- Otherwise if the requested tile is being computed in another thread,
       then this method blocks until the other thread completed its work and returns its result.
       If the other thread failed to compute the tile, an ImagingOpExceptionis thrown.
- Otherwise this method computes the tile and caches the result before to return it.
       If an error occurred, an ImagingOpExceptionis thrown.
 Race conditions with write operationsIf this image implements theWritableRenderedImageinterface, then a user may acquire the same tile for a write operation after this method returned. In such case there is no consistency guarantee on sample values: the tile returned by this method may show data in an unspecified stage during the write operation. A synchronization policy may be defined in a future Apache SIS version.- Specified by:
- getTilein interface- RenderedImage
- Parameters:
- tileX- the column index of the tile to get.
- tileY- the row index of the tile to get.
- Returns:
- the tile at the given index (never null).
- Throws:
- IndexOutOfBoundsException- if a given tile index is out of bounds.
- ImagingOpException- if an error occurred while computing the image.
 
- 
computeTileprotected abstract Raster computeTile(int tileX, int tileY, WritableRaster previous) throws Exception Invoked when a tile need to be computed or updated. This method is invoked bygetTile(int, int)when the requested tile is not in the cache, or when a writable source notified us that its data changed. The returned tile will be automatically cached.A typical implementation is as below: @Override protected Raster computeTile(int tileX, int tileY, WritableRaster tile) { if (tile == null) { tile = createTile(tileX, tileY); } // Do calculation here and write results in tile. return tile; }Error handlingIf this method throws an exception or returnsnull, thengetTile(…)will set an error flag on the tile and throw anImagingOpExceptionwith the exception thrown bycomputeTile(…)as its cause. Future invocations ofgetTile(tileX, tileY)with the same tile indices will cause anImagingOpExceptionto be thrown immediately without invocation ofcompute(tileX, tileY). If the error has been fixed, then users can invokeclearErrorFlags(Rectangle)for allowing the tile to be computed again.- Parameters:
- tileX- the column index of the tile to compute.
- tileY- the row index of the tile to compute.
- previous- if the tile already exists but needs to be updated, the tile to update. Otherwise- null.
- Returns:
- computed tile for the given indices. May be the previoustile after update but cannot be null.
- Throws:
- Exception- if an error occurred while computing the tile.
 
- 
createTileCreates an initially empty tile at the given tile grid position. This is a helper method forcomputeTile(int, int, WritableRaster)implementations.- Parameters:
- tileX- the column index of the tile to create.
- tileY- the row index of the tile to create.
- Returns:
- initially empty tile for the given indices (cannot be null).
 
- 
prefetchNotifies this image that tiles will be computed soon in the given region. This method is invoked byImageProcessor.prefetch(RenderedImage, Rectangle)before to request (potentially in multi-threads) all tiles in the area of interest. If the returnedDisposableis non-null,ImageProcessorguarantees that theDisposable.dispose()method will be invoked after the prefetch operation completed, successfully or not.The default implementation does nothing. Subclasses can override this method if they need to allocate and release resources once for a group of tiles. - Parameters:
- tiles- indices of the tiles which will be prefetched.
- Returns:
- handler on which to invoke dispose()after the prefetch operation completed (successfully or not), ornullif none.
- Since:
- 1.2
 
- 
hasTileWriterspublic boolean hasTileWriters()Returns whether any tile is under computation or is checked out for writing. There is two reasons why this method may returntrue:- At least one computeTile(…)call is running in another thread.
- There is at least one call to markTileWritable(tileX, tileY, true)call without matching call tomarkTileWritable(tileX, tileY, false). This second case may happen if thisComputedImageis also aWritableRenderedImage.
 - Returns:
- whether any tiles are under computation or checked out for writing.
- See Also:
 
- At least one 
- 
isTileWritablepublic boolean isTileWritable(int tileX, int tileY) Returns whether the specified tile is currently under computation or checked out for writing. There is two reasons why this method may returntrue:- computeTile(tileX, tileY, …)is running in another thread.
- There is at least one call to markTileWritable(tileX, tileY, true)call without matching call tomarkTileWritable(tileX, tileY, false). This second case may happen if thisComputedImageis also aWritableRenderedImage.
 - Parameters:
- tileX- the X index of the tile to check.
- tileY- the Y index of the tile to check.
- Returns:
- whether the specified tile is under computation or checked out for writing.
- See Also:
 
- 
getWritableTileIndicesReturns the indices of all tiles under computation or checked out for writing, ornullif none. This method lists all tiles for which the condition documented inisTileWritable(int, int)istrue.- Returns:
- an array containing the indices of tiles that are under computation or checked out for writing,
         or nullif none.
- See Also:
 
- 
markTileWritableprotected boolean markTileWritable(int tileX, int tileY, boolean writing) Sets or clears whether a tile is checked out for writing. This method is provided for subclasses that implement theWritableRenderedImageinterface. This method can be used as below:class MyImage extends ComputedImage implements WritableRenderedImage { // Constructor omitted for brevity. @Override public WritableRaster getWritableTile(int tileX, int tileY) { WritableRaster raster = ...; // Get the writable tile here. markTileWritable(tileX, tileY, true); return raster; } @Override public void releaseWritableTile(int tileX, int tileY) { markTileWritable(tileX, tileY, false); // Release the raster here. } }- Parameters:
- tileX- the x index of the tile to acquire or release.
- tileY- the y index of the tile to acquire or release.
- writing-- truefor acquiring the tile, or- falsefor releasing it.
- Returns:
- trueif the tile goes from having no writers to having one writer (may happen if- writingis- true), or goes from having one writer to no writers (may happen if- writingis- false).
- See Also:
 
- 
markDirtyTilesMarks all tiles in the given range of indices as in need of being recomputed. The tiles will not be recomputed immediately, but only on next invocation ofgetTile(tileX, tileY)if the(tileX, tileY)indices are contained if the specified rectangle.Subclasses can invoke this method when the tiles in the given range depend on source data that changed, typically (but not necessarily) source images. Note that there is no need to invoke this method if the source images are instances of WritableRenderedImage, becauseComputedImagealready hasTileObserverfor them.- Parameters:
- tiles- indices of tiles to mark as dirty.
- Returns:
- trueif at least one tile has been marked dirty.
 
- 
clearErrorFlagsClears the error status of all tiles in the given range of indices. Those tiles will be marked as dirty and recomputed next time the thegetTile(int, int)method is invoked. The status of valid tiles is unchanged by this method call.- Parameters:
- tiles- indices of tiles for which to clear the error status.
- Returns:
- trueif at least one tile got its error flag cleared.
- See Also:
 
- 
sourceTileChangedInvoked when a tile of a source image has been updated. This method should mark as dirty all tiles of thisComputedImagethat depend on the updated tile.The default implementation assumes that source images use pixel coordinate systems aligned with this ComputedImagein such a way that all pixels at coordinates (x, y) in thesourceimage are used for calculation of pixels at the same (x, y) coordinates in thisComputedImage, possibly expanded to neighborhood pixels if the "org.apache.sis.SourcePadding" property is defined. If this assumption does not hold, then subclasses should override this method and invokemarkDirtyTiles(Rectangle)themselves.- Parameters:
- source- the image that own the tile which has been updated.
- tileX- the x index of the tile that has been updated.
- tileY- the y index of the tile that has been updated.
 
- 
disposepublic void dispose()Advises this image that its tiles will no longer be requested. This method removes all tiles from the cache and stops observation ofWritableRenderedImagesources. This image should not be used anymore after this method call.Note: keep in mind that this image may be referenced as a source of other images. In case of doubt, it may be safer to rely on the garbage collector instead of invoking this method. - Specified by:
- disposein interface- Disposable
 
 
-