org.jaitools.media.jai.vectorize
Class VectorizeDescriptor

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


Copyright © 2009-2013. All Rights Reserved.