org.jaitools.media.jai.maskedconvolve
Class MaskedConvolveDescriptor

java.lang.Object
  extended by javax.media.jai.OperationDescriptorImpl
      extended by 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:

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:

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


Copyright © 2009-2013. All Rights Reserved.