org.jaitools.media.jai.maskedconvolve
Class MaskedConvolveDescriptor

java.lang.Object
  javax.media.jai.OperationDescriptorImpl
      org.jaitools.media.jai.maskedconvolve.MaskedConvolveDescriptor

All Implemented Interfaces:

Serializable, javax.media.jai.OperationDescriptor, javax.media.jai.RegistryElementDescriptor

public class MaskedConvolveDescriptor
extends javax.media.jai.OperationDescriptorImpl

The "MaskedConvolve" operation extends JAI's convolve operator by providing the option to select which source and or destination pixels are included in processing using an associated ROI object.

Two masking options are provided:

• source masking, in which the ROI is used to constrain which source image pixels contribute to the kernel calculation;
• destination masking in which the convolution kernel will only be placed over pixels that are within the ROI.

The two options may be used together. If neither masking option is required it is better to use the standard "Convolve" operator as it will be faster.

With this operator, a given destination pixel will have a nil result if any of the following are true:

• The pixel was not included in a destination mask.
• The pixel had no kernel values included in a source mask.
• The requirement for the minimum number of unmasked source image values was not met (explained below in relation to the minCells parameter).

A flag value is returned for such pixels which you can specify with the nilValue parameter (the default is 0).

You can specify the minimum number of non-zero kernel cells that must be positioned over unmasked source image pixels for convolution to be performed via the minCells parameter. If there are NO_DATA values defined (see nodata parameter below) then this parameter refers to the number of unmasked source image pixels with data. Any of the following are accepted:

1. "ANY" (case-insensitive) (or the constant MIN_CELLS_ANY). With this option, convolution will be performed if there is at least one unmasked source image value in the pixel neighbourhood. This is the default.
2. "ALL" (case-insensitive) (or the constant MIN_CELLS_ALL). Convolution will only be performed if all source image pixels in the neighbourhood are unmasked.
3. A Number with value between one and the number of non-zero kernel cells (inclusive).
4. A String representing a numeric value.

Example of use:

 RenderedImage img = ...
 
 float[] kernelData = new float[]{  // for neighbourhood sum
      0, 0, 1, 0, 0,
      0, 1, 1, 1, 0,
      1, 1, 1, 1, 1,
      0, 1, 1, 1, 0,
      0, 0, 1, 0, 0,
 };
       
 KernelJAI kernel = new KernelJAI(5, 5, kernelData);
 ROI roi = new ROI(img, thresholdValue);
 
 ParameterBlockJAI pb = new ParameterBlockJAI("maskedconvolve");
 pb.setSource("source0", op0);
 pb.setParameter("kernel", kernel);
 pb.setParameter("roi", roi);
 pb.setParameter("nilValue", Integer.valueOf(-1));
 
 // no need to set masksource and maskdest params if we want to
 // use their default values (TRUE)
 
 BorderExtender extender = BorderExtender.createInstance(BorderExtender.BORDER_ZERO);
 RenderingHints hints = new RenderingHints(JAI.KEY_BORDER_EXTENDER, extender);

 RenderedOp dest = JAI.create("maskedconvolve", pb, hints);

Summary of parameters:

Name	Class	Default	Description
kernel	KernelJAI	No default	Kernel defining the convolution neighbourhood
roi	ROI	No default	ROI to use for source and/or destination masking
maskSource	Boolean	true	Whether to apply source masking
maskDest	Boolean	true	Whether to apply destination masking
nilValue	Number	0	Value to return for pixels with no convolution result
minCells	See note above	MIN_CELLS_ANY	Minimun number of non-zero kernel cells over unmasked source image pixels for convolution to be performed
nodata	Collection	null	Values to be treated as NO_DATA. A value can be either a Number or a Range (mixtures of both are permitted).
strictNodata	Boolean	false	If true, convolution will no be performed for a target pixel with any NODATA values in its neighbourhood (non-zero kernel cells); if false convolution can occur, subject to masking and minCells criteria, with NODATA values being ignored.

Since:

1.0

Version:

$Id$

Author:

Michael Bedward

See Also:

KernelFactory, Serialized Form

Field Summary

static Number	DEFAULT_NIL_VALUE Default value for nilValue parameter (0)
static String	MIN_CELLS_ALL Constant that can be used for the minCells parameter to require all non-zero kernel cells to overlap with unmasked source image cells for convolution to be performed for a terget cell
static String	MIN_CELLS_ANY Constant that can be used for the minCells parameter to specify convolution will be performed for a terget cell if any non-zero kernel cells overlap with unmasked source image cells.

Fields inherited from class javax.media.jai.OperationDescriptorImpl

resources, sourceNames, supportedModes

Fields inherited from interface javax.media.jai.OperationDescriptor

NO_PARAMETER_DEFAULT

Constructor Summary

MaskedConvolveDescriptor()
Constructor.

Method Summary

protected boolean

validateParameters(String modeName, ParameterBlock pb, StringBuffer msg) Validates the supplied parameters.

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, validateRenderableArguments, validateRenderableSources, validateSources, validateSources

Methods inherited from class java.lang.Object

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

Field Detail

MIN_CELLS_ANY

public static final String MIN_CELLS_ANY

Constant that can be used for the minCells parameter to specify convolution will be performed for a terget cell if any non-zero kernel cells overlap with unmasked source image cells. This is the default parameter value.

See Also:

Constant Field Values

MIN_CELLS_ALL

public static final String MIN_CELLS_ALL

Constant that can be used for the minCells parameter to require all non-zero kernel cells to overlap with unmasked source image cells for convolution to be performed for a terget cell

See Also:

Constant Field Values

DEFAULT_NIL_VALUE

public static final Number DEFAULT_NIL_VALUE

Default value for nilValue parameter (0)

Constructor Detail

MaskedConvolveDescriptor

public MaskedConvolveDescriptor()

Constructor.

Method Detail

validateParameters

protected boolean validateParameters(String modeName,
                                     ParameterBlock pb,
                                     StringBuffer msg)

Validates the supplied parameters.

Overrides:

validateParameters in class javax.media.jai.OperationDescriptorImpl

Parameters:

modeName - the rendering mode

pb - the input parameters

msg - a StringBuffer instance to receive error messages

Returns:

true if parameters are valid; false otherwise