org.jaitools.media.jai.vectorize
Class VectorizeDescriptor

java.lang.Object
  javax.media.jai.OperationDescriptorImpl
      org.jaitools.media.jai.vectorize.VectorizeDescriptor

All Implemented Interfaces:

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

public class VectorizeDescriptor
extends javax.media.jai.OperationDescriptorImpl

Traces the boundaries of regions with uniform data and returns them as vector polygons. The source image passes through to thedestination unchanged, similar to a JAI statistics operator, while the vectors are returned as an image property.

 // Vectorize regions using default parameter settings
 RenderedImage image = ...
 ParameterBlockJAI pb = new ParameterBlockJAI("Vectorize");
 pb.setSource("source0", image);
 RenderedOp dest = JAI.create("Vectorize", pb);
 
 // retrieve the vectors
 Collection<Polygon> polys = (Collection<Polygon>) dest.getProperty(
         VectorizeDescriptor.VECTOR_PROPERTY_NAME);
 

The vectors are JTS Polygon objects. Each polygon holds the value of its source image region as a Double (regardless of the source image data type) as a user data attribute.

 // report source image region value and area (expressed as pixel units)
 Collection<Polygon> polys = (Collection<Polygon>) dest.getProperty(
         VectorizeDescriptor.VECTOR_PROPERTY_NAME);
 
 System.out.println("Region value  Perimeter       Area");
 for (Polygon poly : polys) {
     Double value = (Double) poly.getUserData();
     double perimeter = poly.getLength();
     double area = poly.getArea();
     System.out.printf("%12.2f %10.2f %10.2f\n", value, perimeter, area);
 }
 

Optionally, polygons below a threshold area can be filtered from the output by simple deletion, or by merging with a neighbour (where possible). A neighbouring polygon is one that shares one or more boundary segments with the target polygon (ie. lineal intersection). Two polygons that only touch at a single vertex are not considered neighbours.

 ParameterBlockJAI pb = new ParameterBlockJAI("Vectorize");
 pb.setSource("source0", myImage);
 
 // Filter polygons with area up to 5 pixels by merging
 // them with the largest neighbouring polygon. Where no neighbour
 // exists (e.g. small region surrounded by NODATA) the polygon
 // will be discarded.
 pb.setParameter("filterThreshold", 5.1);
 pb.setParameter("filterMethod", VectorizeDescriptor.FILTER_MERGE_LARGEST);
 

While the Vectorize parameters allow substantial control over the polygons generated from a source image, sometimes it is not possible to avoid generating unwanted polygons. An example is where the same pixel value is used for a target region in one part of the image, but is treated as an outside value in other parts of the image. Generally it will be straightforward to identify such unwanted polygons and filter them from the result set.

The following parameters control the vectorizing process:

Name	Class	Default	Description
roi	ROI	null	An optional ROI to define the vectorizing area.
band	Integer	0	The source image band to process.
outsideValues	Collection	empty	Values to treat as NODATA.
insideEdges	Boolean	Boolean.TRUE	Whether to vectorize boundaries between data regions. Setting this to false results in only the boundaries between NODATA and data regions being returned.
removeCollinear	Boolean	Boolean.TRUE	Whether to simplify polygons by removing collinear vertices.
filterThreshold	Double	0	The area (pixel units) below which a polygon will be filtered from the output by merging or deletion.
filterMethod	Integer	FILTER_MERGE_LARGEST	The method used to filter small polygons when filterThreshold > 0. Must be one of: FILTER_MERGE_LARGEST FILTER_MERGE_RANDOM FILTER_DELETE

Since:

1.1

Version:

$Id$

Author:

Michael Bedward

See Also:

Polygon, org.jaitools.media.jai.regionalizeRegionalizeDescriptor, RangeLookupDescriptor, Serialized Form

Field Summary

static int	FILTER_DELETE Filter small polygons by simple deletion.
static int	FILTER_MERGE_LARGEST Filter small polygons by merging each with its largest (area) neighbour.
static int	FILTER_MERGE_RANDOM Filter small polygons by merging each with a randomly chosen neighbour.
static String	VECTOR_PROPERTY_NAME Name used to access the vectorized region boundaries as a destination image property.

Fields inherited from class javax.media.jai.OperationDescriptorImpl

resources, sourceNames, supportedModes

Fields inherited from interface javax.media.jai.OperationDescriptor

NO_PARAMETER_DEFAULT

Constructor Summary

VectorizeDescriptor()
Constructor.

Method Summary

protected boolean

validateParameters(String modeName, ParameterBlock pb, StringBuffer msg) Validates 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

VECTOR_PROPERTY_NAME

public static final String VECTOR_PROPERTY_NAME

Name used to access the vectorized region boundaries as a destination image property.

See Also:

Constant Field Values

FILTER_MERGE_LARGEST

public static final int FILTER_MERGE_LARGEST

Filter small polygons by merging each with its largest (area) neighbour. This is the default.

See Also:

Constant Field Values

FILTER_MERGE_RANDOM

public static final int FILTER_MERGE_RANDOM

Filter small polygons by merging each with a randomly chosen neighbour.

See Also:

Constant Field Values

FILTER_DELETE

public static final int FILTER_DELETE

Filter small polygons by simple deletion.

See Also:

Constant Field Values

Constructor Detail

VectorizeDescriptor

public VectorizeDescriptor()

Constructor.

Method Detail

validateParameters

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

Validates supplied parameters.

Overrides:

validateParameters in class javax.media.jai.OperationDescriptorImpl

Parameters:

modeName - the rendering mode

pb - the parameter block

msg - a StringBuffer to receive error messages

Returns:

true if parameters are valid; false otherwise