javax.media.jai.operator
Class MosaicDescriptor

java.lang.Object
  extended byjavax.media.jai.OperationDescriptorImpl
      extended byjavax.media.jai.operator.MosaicDescriptor
All Implemented Interfaces:
OperationDescriptor, RegistryElementDescriptor, Serializable

public class MosaicDescriptor
extends OperationDescriptorImpl

An OperationDescriptor describing the "Mosaic" operation in the rendered mode.

The "Mosaic" operation creates a mosaic of two or more source images. This operation could be used for example to assemble a set of overlapping geospatially rectified images into a contiguous image. It could also be used to create a montage of photographs such as a panorama.

All source images are assumed to have been geometrically mapped into a common coordinate space. The origin (minX, minY) of each image is therefore taken to represent the location of the respective image in the common coordinate system of the source images. This coordinate space will also be that of the destination image.

All source images must have the same data type and sample size for all bands. The destination will have the same data type, sample size, and number of bands and color components as the sources.

The destination layout may be specified by an ImageLayout hint provided via a RenderingHints supplied to the operation. If this hint contains a setting for the image bounds (origin and dimensions), it will be used even if it does not intersect the union of the bounds of the sources; otherwise the image bounds will be set to the union of all source image bounds. If the data type or sample size specified by the layout hint do not match those of the sources, then this portion of the hint will be ignored.

It is permissible that the number of source images be initially zero. In this case a non-null ImageLayout must be supplied with valid width and height and a non-null SampleModel. The destination data type, sample size, number of bands, and image bounds will all be determined by the ImageLayout.

If sourceAlpha is non-null, then any non- null elements of the array must be single-band images with the same data type and sample size as the sources.

The source threshold array parameter has maximum dimensions as double[NUM_SOURCES][NUM_BANDS]. Default values of the thresholds actually used are defined as follows:

The background value array parameter has maximum dimensions as double[NUM_BANDS]. Default values of the background actually used are defined as follows:

The default behavior therefore is to set the background to zero.

If a given destination position (x, y) is within the bounds of M source images, then the destination pixel value D(x, y) is computed using an algorithm selected on the basis of the mosaicType parameter value. If the destination position is not within any source image, then the destination pixel value is set to the specified background value.

If the mosaicType parameter value is MOSAIC_TYPE_BLEND, then the destination pixel value is computed as:

 double[][][] s; // source pixel values
 double[][][] w; // derived source weight values
 double[][] d;   // destination pixel values

 double weightSum = 0.0;
 for(int i = 0; i < M; i++) {
     weightSum += w[i][x][y];
 }

 if(weightSum != 0.0) {
     double sourceSum = 0.0;
     for(int i = 0; i < M; i++) {
         sourceSum += s[i][x][y]*w[i][x][y];
     }
     d[x][y] = sourceSum / weightSum;
 } else {
     d[x][y] = background;
 }
 
where the index i is over the sources which contain (x, y). The destination pixel value is therefore a blend of the source pixel values at the same position.

If the mosaicType parameter value is MOSAIC_TYPE_OVERLAY, then the destination pixel value is computed as:

 d[x][y] = background;
 for(int i = 0; i < M; i++) {
     if(w[i][x][y] != 0.0) {
         d[x][y] = s[i][x][y];
         break;
     }
 }
 
The destination pixel value is therefore the value of the first source pixel at the same position for which the derived weight value at the same position is non-zero.

The derived weight values for the ith source are determined from the corresponding sourceAlpha, sourceROI, and sourceThreshold parameters as follows where for illustration purposes it is assumed that any alpha values range over [0.0, 1.0] with 1.0 being opaque:

 // Set flag indicating whether to interpret alpha values as bilevel.
 boolean isAlphaBitmask =
     !(mosaicType.equals(MOSAIC_TYPE_BLEND) &&
       sourceAlpha != null &&
       !(sourceAlpha.length < NUM_SOURCES));
 if(!isAlphaBitmask) {
     for(int i = 0; i < NUM_SOURCES; i++) {
         if(sourceAlpha[i] == null) {
             isAlphaBitmask = true;
             break;
         }
     }
 }

 // Derive source weights from the supplied parameters.
 w[i][x][y] = 0.0;
 if(sourceAlpha != null && sourceAlpha[i] != null) {
     w[i][x][y] = sourceAlpha[i][x][y];
     if(isAlphaBitmask && w[i][x][y] > 0.0) {
         w[i][x][y] = 1.0;
     }
 } else if(sourceROI != null && sourceROI[i] != null &&
           sourceROI[i].contains(x,y)) {
     w[i][x][y] = 1.0;
 } else if(s[i][x][y] >= sourceThreshold[i]) { // s[i][x][y] = source value
     w[i][x][y] = 1.0;
 }
 

As illustrated above, the interpretation of the alpha values will vary depending on the values of the parameters supplied to the operation. If and only if mosaicType equals MOSAIC_TYPE_BLEND and an alpha mask is available for each source will the alpha values be treated as arbitrary values as for Transparency.TRANSLUCENT. In all other cases the alpha values will be treated as bilevel values as for Transparency.BITMASK.

It should be remarked that the MOSAIC_TYPE_BLEND algorithm applied when the weights are treated as bilevel values is equivalent to averaging all non-transparent source pixels at a given position. This in effect intrinsically provides a third category of mosaicking. The available categories are summarized in the following table.

Mosaic Categories
Mosaic Type Transparency Type Category
MOSAIC_TYPE_BLEND BITMASK Average
MOSAIC_TYPE_BLEND TRANSLUCENT Alpha Blend
MOSAIC_TYPE_OVERLAY BITMASK || TRANSLUCENT Superposition

Resource List
Name Value
GlobalName Mosaic
LocalName Mosaic
Vendor com.sun.media.jai
Description Creates a mosaic of two or more rendered images.
DocURL http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/MosaicDescriptor.html
Version 1.0
arg0Desc Mosaicking type.
arg1Desc Source alpha masks.
arg2Desc Source region of interest masks.
arg3Desc Source threshold values.
arg4Desc Destination background value.

Parameter List
Name Class Type Default Value
mosaicType javax.media.jai.operator.MosaicType MOSAIC_TYPE_OVERLAY
sourceAlpha javax.media.jai.PlanarImage[] null
sourceROI javax.media.jai.ROI[] null
sourceThreshold double[][] double[][] {{1.0}}
backgroundValues double[] double[] {0.0}

Since:
JAI 1.1.2
See Also:
Serialized Form

Field Summary
static MosaicType MOSAIC_TYPE_BLEND
          Destination pixel equals alpha blend of source pixels.
static MosaicType MOSAIC_TYPE_OVERLAY
          Destination pixel equals first opaque source pixel.
 
Fields inherited from class javax.media.jai.OperationDescriptorImpl
sourceNames, supportedModes
 
Fields inherited from interface javax.media.jai.OperationDescriptor
NO_PARAMETER_DEFAULT
 
Constructor Summary
MosaicDescriptor()
          Constructor.
 
Method Summary
static RenderedOp create(RenderedImage[] sources, MosaicType mosaicType, PlanarImage[] sourceAlpha, ROI[] sourceROI, double[][] sourceThreshold, double[] backgroundValues, RenderingHints hints)
          Creates a mosaic of two or more rendered images.
 
Methods inherited from class javax.media.jai.OperationDescriptorImpl
arePropertiesSupported, getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamMaxValue, getParamMinValue, getParamNames, getPropertyGenerators, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isImmediate, isModeSupported, isRenderableSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateArguments, validateParameters, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MOSAIC_TYPE_BLEND

public static final MosaicType MOSAIC_TYPE_BLEND
Destination pixel equals alpha blend of source pixels.


MOSAIC_TYPE_OVERLAY

public static final MosaicType MOSAIC_TYPE_OVERLAY
Destination pixel equals first opaque source pixel.

Constructor Detail

MosaicDescriptor

public MosaicDescriptor()
Constructor.

Method Detail

create

public static RenderedOp create(RenderedImage[] sources,
                                MosaicType mosaicType,
                                PlanarImage[] sourceAlpha,
                                ROI[] sourceROI,
                                double[][] sourceThreshold,
                                double[] backgroundValues,
                                RenderingHints hints)
Creates a mosaic of two or more rendered images.

Creates a ParameterBlockJAI from all supplied arguments except hints and invokes JAI.create(String,ParameterBlock,RenderingHints).

Parameters:
sources - RenderedImage sources.
mosaicType - Mosaicking type. May be null.
sourceAlpha - May be null.
sourceROI - Source region of interest masks. May be null.
sourceThreshold - Source threshold values. May be null.
backgroundValues - Destination background value. May be null.
hints - The RenderingHints to use. May be null.
Returns:
The RenderedOp destination.
Throws:
IllegalArgumentException - if any source is null.
See Also:
JAI, ParameterBlockJAI, RenderedOp