com.luciad.imaging

LuciadLightspeedClass ALcdImagingEngine

java.lang.Object

com.luciad.imaging.ALcdImagingEngine

All Implemented Interfaces:

ILcdDisposable, AutoCloseable

public abstract class ALcdImagingEngine
extends Object
implements ILcdDisposable

Provides methods for reading pixel values out of an ALcdBasicImage.

Engine creation

This class should not be implemented by the user; implementations can be instantiated using the provided factory methods.

An imaging engine should be considered a heavy-weight object. It can hold system resources that are expensive to initialize or of which there are only a limited amount available. So an application should typically re-use a single engine multiple times. It should not create a engine for each individual processing request. Note that care should also be taken to dispose the engine when it is no longer needed.

Usage example

The following code snippet adds two images and then reads pixel values for the first tile out of the result:

 ALcdImagingEngine engine = ALcdImagingEngine.createEngine();
 try {
   ALcdBasicImage input1 = ...;
   ALcdBasicImage input2 = ...;
   ALcdBasicImage output = (ALcdBasicImage) TLcdBinaryOp.binaryOp(input1, input2, ADD);
   Rectangle region = output.getConfiguration().getTilePixelBounds(0, 0);
   Raster outputData = engine.getImageDataReadOnly(output, region);
   float[] pixel = new float[1]; // Assuming a single band image with float pixel data
   for (int y=0; y < region.height; y++) {
     for (int x=0; x < region.width; x++) {
       outputData.getPixel(outputData.getMinX() + x, outputData.getMinY() + y, pixel);
       System.out.println("Pixel at " + x + "," + y + ":" + pixel[0]);
     }
   }
 }
 finally {
   engine.dispose();
 }
 

Instances of this class are thread-safe.

Since:

2014.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ALcdImagingEngine.Descriptor Describes the capabilities and execution environment of an ALcdImagingEngine.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ALcdImagingEngine() This class is not intended to be implemented by users.

Method Summary

Modifier and Type	Method and Description
abstract ColorModel	createCompatibleColorModel(ALcdBasicImage aImage) Creates a ColorModel that is compatible with the specified image.
protected abstract SampleModel	createCompatibleSampleModel(ALcdBasicImage aImage, int aWidth, int aHeight) Creates a SampleModel that is compatible with the specified image.
abstract WritableRaster	createCompatibleWritableRaster(ALcdBasicImage aImage, Rectangle aRegion) Creates a WritableRaster that is compatible with the specified image.
static ALcdImagingEngine	createEngine() Creates a new imaging engine.
static ALcdImagingEngine	createEngine(ALcdImagingEngine.Descriptor aDescriptor) Creates a new imaging engine based on the given descriptor.
abstract BufferedImage	getBufferedImage(ALcdBasicImage aImage, Rectangle aRegion) Reads a rectangular block of data out of a given image.
abstract ALcdImagingEngine.Descriptor	getDescriptor() Returns the descriptor of this imaging engine.
static Collection<ALcdImagingEngine.Descriptor>	getEngineDescriptors() Enumerates all available imaging engine implementations.
abstract WritableRaster	getImageData(ALcdBasicImage aImage, Rectangle aRegion) Reads a rectangular block of data out of a given image.
abstract void	getImageData(ALcdBasicImage aImage, WritableRaster aOutputRasterSFCT) Reads a rectangular block from a given image into a given raster.
abstract Raster	getImageDataReadOnly(ALcdBasicImage aImage, Rectangle aRegion) Reads a rectangular block of data out of a given image.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.luciad.util.ILcdDisposable

close, dispose

Constructor Detail

ALcdImagingEngine

protected ALcdImagingEngine()

This class is not intended to be implemented by users.

Method Detail

createEngine

public static ALcdImagingEngine createEngine()

Creates a new imaging engine. Searches through the available implementations and uses the first one that is hardware-accelerated. If no such engine is available, a CPU-based fallback is used. You can also create an engine for a specific descriptor.

Returns:

a new imaging engine

createEngine

public static ALcdImagingEngine createEngine(ALcdImagingEngine.Descriptor aDescriptor)

Creates a new imaging engine based on the given descriptor. Descriptors for all available imaging engine implementations can be obtained using getEngineDescriptors().

Parameters:

aDescriptor - the engine descriptor

Returns:

a new imaging engine

getEngineDescriptors

public static Collection<ALcdImagingEngine.Descriptor> getEngineDescriptors()

Enumerates all available imaging engine implementations. Returns a list of engine descriptors which can be used to instantiate a particular engine.

Returns:

a list of descriptors for all available imaging engine implementations

See Also:

createEngine(ALcdImagingEngine.Descriptor)

createCompatibleWritableRaster

public abstract WritableRaster createCompatibleWritableRaster(ALcdBasicImage aImage,
                                                              Rectangle aRegion)

Creates a WritableRaster that is compatible with the specified image.

The raster can be used with getImageData(ALcdBasicImage, java.awt.image.WritableRaster).

Parameters:

aImage - the image

aRegion - the rectangle

Returns:

the writable raster

createCompatibleSampleModel

protected abstract SampleModel createCompatibleSampleModel(ALcdBasicImage aImage,
                                                           int aWidth,
                                                           int aHeight)

Creates a SampleModel that is compatible with the specified image.

Parameters:

aImage - the image

aWidth - the width of the sample model

aHeight - the height of the sample model

Returns:

the sample model

createCompatibleColorModel

public abstract ColorModel createCompatibleColorModel(ALcdBasicImage aImage)

Creates a ColorModel that is compatible with the specified image.

The result is null if the image pixels do not represent a color. The color model can for example be used to create a BufferedImage. It is also required when getting one from the imaging engine.

Parameters:

aImage - the image

Returns:

the color model or null

See Also:

createCompatibleWritableRaster(ALcdBasicImage, java.awt.Rectangle), getBufferedImage(ALcdBasicImage, java.awt.Rectangle)

getBufferedImage

public abstract BufferedImage getBufferedImage(ALcdBasicImage aImage,
                                               Rectangle aRegion)

Reads a rectangular block of data out of a given image. This is a convenience method which delegates to getImageData(ALcdBasicImage, java.awt.Rectangle). It can be used in cases where an image is easier to work with than a WritableRaster (e.g. when performing Graphics2D operations).

Note that this method can only be used with an image that contains color data.

Parameters:

aImage - the image

aRegion - the requested region

Returns:

an image containing the requested data

Throws:

IllegalArgumentException - if the region is invalid, the image does not contain color data or the image is not supported

See Also:

createCompatibleColorModel(ALcdBasicImage)

getImageDataReadOnly

public abstract Raster getImageDataReadOnly(ALcdBasicImage aImage,
                                            Rectangle aRegion)

Reads a rectangular block of data out of a given image.

This method is potentially more efficient than getImageData(com.luciad.imaging.ALcdBasicImage, java.awt.Rectangle), especially if no processing is necessary to produce the data. To benefit from this performance improvement, the requested region must coincide with a tile in the image. You can compute the region for a tile using ALcdBasicImage.Configuration.getTilePixelBounds(int, int).

Parameters:

aImage - the image

aRegion - the requested region

Returns:

a raster containing the requested data

Throws:

IllegalArgumentException - if the region is invalid or the image is not supported

Since:

2015.0

See Also:

getImageData(ALcdBasicImage, java.awt.Rectangle)

getImageData

public abstract WritableRaster getImageData(ALcdBasicImage aImage,
                                            Rectangle aRegion)

Reads a rectangular block of data out of a given image.

Parameters:

aImage - the image

aRegion - the requested region

Returns:

a raster containing the requested data

Throws:

IllegalArgumentException - if the region is invalid or the image is not supported

See Also:

getImageDataReadOnly(ALcdBasicImage, java.awt.Rectangle)

getImageData

public abstract void getImageData(ALcdBasicImage aImage,
                                  WritableRaster aOutputRasterSFCT)

Reads a rectangular block from a given image into a given raster.

Note that aOutputRasterSFCT also indicates which block of data from the image should be copied to it.

Parameters:

aImage - the image

aOutputRasterSFCT - the raster to write the result into

Throws:

IllegalArgumentException - if the output raster is invalid or the image is not supported

See Also:

createCompatibleWritableRaster(ALcdBasicImage, java.awt.Rectangle)

getDescriptor

public abstract ALcdImagingEngine.Descriptor getDescriptor()

Returns the descriptor of this imaging engine. Descriptors of all available engine implementations can be enumerated using getEngineDescriptors(). An engine can be created by using a descriptor with createEngine(ALcdImagingEngine.Descriptor). This method returns the descriptor that was used to create this engine.

Returns:

the engine descriptor