jwo.landserf.structure
Class GISVector

java.lang.Object
  jwo.landserf.structure.SpatialObject
      jwo.landserf.structure.GISVector

All Implemented Interfaces:

Serializable, SpatialModel

public class GISVector
extends SpatialObject

Models a GIS vector object such as a single point, line or area. Objects can contain more than 1 'subpath' allowing discontinuities, holes and islands to be represented.

Version:

2.3, 7th September, 2008.

Author:

Jo Wood

See Also:

Serialized Form

Field Summary

Fields inherited from interface jwo.landserf.structure.SpatialModel

ADJACENT, AREA, CONTOUR, ENCLOSES, INTERSECTION, LINE, MATCHES, MSN, NO_VALUE, OUT_OF_BOUNDS, OVERLAPS, POINT, RASTER_2D, RASTER_3D, SEPARATE, TIN, UNDEFINED, UNION, UNKNOWN, UNKNOWN_MODEL, VECTOR_2D, VECTOR_3D, VOLUME, WITHIN

Constructor Summary

GISVector()
Creates an empty GIS vector object.

GISVector(float[] xCoords, float[] yCoords, int type, float attrib)
Creates the GIS vector object with the given x and y coordinates.

GISVector(float easting, float northing, float attribute)
Creates a GIS vector point object with given coordinates and attribute.

GISVector(float n, float s, float e, float w)
Creates a bounding box with the given north, south, east and west coordinates.

GISVector(Footprint fp)
Creates a bounding box from the given footprint.

GISVector(GISVector oldVector)
Creates a clone of the given GIS Vector.

Method Summary

void	addCoords(Footprint footprint) Adds the given footprint to the vector's coordinates and updates the bounding area.
boolean	combine(GISVector otherVector) Combines the given GIS Vector with this one to form a composite object.
int	compare(SpatialModel other) Makes a spatial comparison between this vector and a given spatial object's MER.
Vector	findLineIntersections(GISVector otherVector) Reports the intersections between this and the given vector.
Vector	findLineIntersections(GISVector otherVector, boolean interior) Reports the intersections between this and the given vector.
Vector	findObjectIntersections(GISVector otherVector) Reports the intersection object(s) of this one and the given one.
float	getAttribute() Reports the numeric attribute associated with the GIS vector.
float	getAttribute(Footprint fp) Reports the attribute at the given point location.
float	getAttribute(Footprint fp, float snappingDistance) Reports the attribute at the given point location.
Footprint	getCentroid() Finds the centroid of this object.
GeneralPath	getCoords() Returns a drawable set of coordinates representing vector object.
boolean	getCoords(float[] x, float[] y) Fills the given coordinate arrays with coordinates representing the GIS vector.
float	getDistance(Footprint fp) Reports the closest distance to the given point location.
void	getImage(int[] img, int imgWidth) Converts the GIS vector into colour image for display.
float	getMaxAttribute() Reports the maximum attribute value of the object.
float	getMinAttribute() Reports the minimum attribute value of the object.
int	getNumCoords() Reports the number of coordinates in this GIS vector.
int	getNumSubpaths() Reports the number of sub-paths represented by this object.
float	getSize() Reports the size of the object.
String	getSizeText() Reports a message giving length/area of the object.
Vector	getSubpaths() Returns a collection of separate GISVectors, each representing a separate subpath.
int	getType() Reports the type of vector.
float[]	getZCoords() Returns a set of z coordinates matching each (x,y) pair.
boolean	isOpenPolygon() Reports whether this object is a polygon that contains at least one ring whose first and last coordinates are not identical.
void	reverse() Reverses the order of coordinates making up the object.
void	setAttribute(float attrib) Sets the attribute of the GIS vector.
void	setCoords(float[] xCoords, float[] yCoords) Sets the coordinates of the vector object from the given arrays.
void	setCoords(GeneralPath coords) Sets the coordinates of the vector object from the given general path.
void	setType(int type) Sets the type of vector.
boolean	setZCoords(float[] zCoords) Adds an array of z-coordinates to match each (x,y pair).
Vector	split(GISVector otherVector) Splits this object into two new ones around the given object.
SpatialModel	subset(Footprint clipRect) Subsets this GIS vector by clipping to the given rectangle.
void	updateBounds() Updates the bounding rectangle of this object by examining coordinates that make up the feature.
void	updateNumSubpaths() Calculates the number of sub-paths represented by this object.

Methods inherited from class jwo.landserf.structure.SpatialObject

getAttributeTable, getBounds, getColourTable, getComparisonText, getHeader, getIntersectionMER, getProjection, getTypeName, getTypeName, getUnionMER, move, setAttributeTable, setBounds, setColourTable, setHeader, setProjection, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

GISVector

public GISVector()

Creates an empty GIS vector object.

GISVector

public GISVector(GISVector oldVector)

Creates a clone of the given GIS Vector.

Parameters:

oldVector - Vector to clone.

GISVector

public GISVector(float easting,
                 float northing,
                 float attribute)

Creates a GIS vector point object with given coordinates and attribute.

Parameters:

easting - x-coordinate of point.

northing - y-coordinate of point.

attribute - Attribute of point.

GISVector

public GISVector(float n,
                 float s,
                 float e,
                 float w)

Creates a bounding box with the given north, south, east and west coordinates.

Parameters:

n - y-coordinate of northern bounds.

s - y-coordinate of southern bounds.

e - x-coordinate of eastern bounds.

w - x-coordinate of western bounds.

GISVector

public GISVector(Footprint fp)

Creates a bounding box from the given footprint.

Parameters:

fp - Footprint representing bounding box.

GISVector

public GISVector(float[] xCoords,
                 float[] yCoords,
                 int type,
                 float attrib)

Creates the GIS vector object with the given x and y coordinates.

Parameters:

xCoords - Array holding x-coordinates of object.

yCoords - Array holding y-coordinates of object.

type - Type of vector object (POINT, LINE, AREA, VOLUME).

attrib - Attribute associated with this GIS vector.

Method Detail

addCoords

public void addCoords(Footprint footprint)

Adds the given footprint to the vector's coordinates and updates the bounding area.

Parameters:

footprint - Coordinates to add.

setZCoords

public boolean setZCoords(float[] zCoords)

Adds an array of z-coordinates to match each (x,y pair). Note that the z coordinates are not saved if this object is serialized.

Parameters:

zCoords - Array of z coordinates.

Returns:

True if size of array matches number of coordinates.

combine

public boolean combine(GISVector otherVector)

Combines the given GIS Vector with this one to form a composite object. Both must be of the same type (e.g AREA with AREA, or LINE with LINE) and must not be points. Both GIS vectors must also have the same attribute for the combination to be valid. If they are not, consider adding both GIS Vectors to the same vector map. If both objects are areas and one intersects with the other it is assumed to represent either a hole or an island. If either vector does not contain z values, the combined vector will not have z coordinates.

Parameters:

otherVector - GIS Vector to combine with this one.

Returns:

True if objects combined successfully.

subset

public SpatialModel subset(Footprint clipRect)

Subsets this GIS vector by clipping to the given rectangle. The footprint provided must be a rectangle, or no clipping will take place. Note that if object contained z values and it intersects with the clip rectangle these will be reset during clipping.

Specified by:

subset in interface SpatialModel

Specified by:

subset in class SpatialObject

Parameters:

clipRect - Clipping rectangle.

Returns:

Clipped GIS Vector or null if clipped object is empty.

getImage

public void getImage(int[] img,
                     int imgWidth)

Converts the GIS vector into colour image for display. This is an empty method required by the SpatialModel interface, so in this case, no image is generated. To generate image, place GISVector inside a VectorMap and call its getImage() method.

Specified by:

getImage in interface SpatialModel

Specified by:

getImage in class SpatialObject

Parameters:

img - Image array to store colours (unchanged by this method).

imgWidth - Image width (ignored).

findLineIntersections

public Vector findLineIntersections(GISVector otherVector)

Reports the intersections between this and the given vector. This is a 2d operation that ignores the z values of both objects. Attribute of any returned objects will be identical to the attributes of this object. Treats all areas as (boundary) lines. If either vector is a point, then this will always return null. To compare points, use compare(). To make a full point/line/area comparison use findObjectIntersections.

Parameters:

otherVector - GIS vector with which to make comparison.

Returns:

A list of GIS vectors representing intersection, or null if no intersection.

See Also:

compare(jwo.landserf.structure.SpatialModel), findObjectIntersections(GISVector)

findLineIntersections

public Vector findLineIntersections(GISVector otherVector,
                                    boolean interior)

Reports the intersections between this and the given vector. This is a 2d operation that ignores the z values of both objects. Attribute of any returned objects will be identical to the attributes of this object. Treats all areas as (boundary) lines. If either vector is a point, then this will always return null. To compare points, use compare(). To make a full point/line/area comparison use findObjectIntersections.

Parameters:

otherVector - GIS vector with which to make comparison.

interior - Ignores end points of lines if true.

Returns:

A list of GIS vectors representing intersection, or null if no intersection.

See Also:

compare(jwo.landserf.structure.SpatialModel), findObjectIntersections(GISVector)

split

public Vector split(GISVector otherVector)

Splits this object into two new ones around the given object. Note, this currently only works if this object is a line, and the given object is a point. Will split line at nearest vertex to point.

Parameters:

otherVector - GIS Vector (point) about which to split.

Returns:

The split GIS vectors.

reverse

public void reverse()

Reverses the order of coordinates making up the object. This can be used by processes that need to store vector objects with a given direction.

compare

public int compare(SpatialModel other)

Makes a spatial comparison between this vector and a given spatial object's MER. If the given spatial object is a GISVector, consider using findLineIntersections() to identify crossing lines etc.

Specified by:

compare in interface SpatialModel

Overrides:

compare in class SpatialObject

Parameters:

other - Spatial model with which to make a comparison.

Returns:

One of five topological relations (WITHIN, MATCHES, OVERLAPS, ENCLOSES, or SEPARATE).

See Also:

findLineIntersections(GISVector), findObjectIntersections(GISVector)

findObjectIntersections

public Vector findObjectIntersections(GISVector otherVector)

Reports the intersection object(s) of this one and the given one. Generally, this is most useful if at least one of the objects is a polygon. If both are points, only identical points can result in an object being returned. If both objects are lines, one or more points may be returned if intersection occurs. If one object a line, and the other a point, only one point can be returned if it is on the line. Any intersecting objects will have the same attribute as this GISVector. To look for boundary intersections only, consider using findLineIntersections.

Parameters:

otherVector - GIS vector to compare with this one.

Returns:

Set of GIS vectors representing intersecting objects. Will be null if no intersections occur.

See Also:

findLineIntersections(GISVector)

updateBounds

public void updateBounds()

Updates the bounding rectangle of this object by examining coordinates that make up the feature.

Specified by:

updateBounds in class SpatialObject

updateNumSubpaths

public void updateNumSubpaths()

Calculates the number of sub-paths represented by this object. A single object can contain multiple sub-paths if it has discontinuities such as islands, holes or truncated lines.

getCoords

public GeneralPath getCoords()

Returns a drawable set of coordinates representing vector object.

Returns:

coordinates of the vector.

getZCoords

public float[] getZCoords()

Returns a set of z coordinates matching each (x,y) pair. If no z coordinates have been defined, this will return null. Note that z coordinates are not saved when this object is serialized.

Returns:

Z coordinates of the vector or null if not currently defined.

getCoords

public boolean getCoords(float[] x,
                         float[] y)

Fills the given coordinate arrays with coordinates representing the GIS vector. Note that this version will not distinguish between subpaths. This means that subpaths will appear joined with line. To collect separate subpath coordinates first separate them using getSubPaths().

Parameters:

x - Array to be filled with x coordinates.

y - Array to be filled with y coordinates.

Returns:

True if array length matches number of coordinates.

isOpenPolygon

public boolean isOpenPolygon()

Reports whether this object is a polygon that contains at least one ring whose first and last coordinates are not identical. This method can be used to identify implicitly closed polygons, or complex polygons with implicitly closed rings. Note that this is quite an expensive operation as it has to iterate through all polygon coordinates, so should not be called unnecessarily.

Returns:

True if this is a polygon that contains at least one ring whose first and last coordinates are not identical.

getSubpaths

public Vector getSubpaths()

Returns a collection of separate GISVectors, each representing a separate subpath. For most GISVectors, which consist of 1 subpath only, this method simply returns a Java Vector containing this object alone.

Returns:

Collection of GISVectors, each one representing a separate subpath.

getNumCoords

public int getNumCoords()

Reports the number of coordinates in this GIS vector.

Returns:

Number of coordinates representing the GIS vector.

getNumSubpaths

public int getNumSubpaths()

Reports the number of sub-paths represented by this object. A single object can contain multiple sub-paths if it has discontinuities such as islands, holes or truncated lines.

Returns:

Number of sub-paths (1 for simple objects).

getType

public int getType()

Reports the type of vector.

Specified by:

getType in interface SpatialModel

Overrides:

getType in class SpatialObject

Returns:

Type of vector (POINT, LINE, AREA or VOLUME).

getAttribute

public float getAttribute()

Reports the numeric attribute associated with the GIS vector. Note that this method will not use the attribute table, but will always use the numeric 'id' associated with the object. To get the 'active attribute' associated with an attribute table, get the attribute table from this vector's VectorMap.getAttributeTable() method, then call the table's getAttribute() method, supplying the id provided by this method.

Returns:

Attribute associated with the GIS vector.

getAttribute

public float getAttribute(Footprint fp)

Reports the attribute at the given point location. The larger of the width/height of footprint is used to define a snapping distance within which the attribute value of points and lines will be reported. If no width or height defined, a snapping distance of 0.1 is used.

Specified by:

getAttribute in interface SpatialModel

Specified by:

getAttribute in class SpatialObject

Parameters:

fp - Location and snapping distance to query.

Returns:

Attribute associated with the GIS vector if given location is close to or within object, otherwise OUT_OF_BOUNDS.

getAttribute

public float getAttribute(Footprint fp,
                          float snappingDistance)

Reports the attribute at the given point location.

Parameters:

fp - Location to query.

snappingDistance - Tolerance of query location for points and lines.

Returns:

Attribute associated with the GIS vector if given location is close to or within object, otherwise OUT_OF_BOUNDS.

getDistance

public float getDistance(Footprint fp)

Reports the closest distance to the given point location.

Parameters:

fp - Location to query.

Returns:

Shortest distance between this object and the given location.

getCentroid

public Footprint getCentroid()

Finds the centroid of this object. If this is a point, the point location is returned. If this is a line, the midpoint is returned. If it is a polygon, the area centroid is returned.

Returns:

Footprint representing centroid of object.

getMinAttribute

public float getMinAttribute()

Reports the minimum attribute value of the object. Since GIS vectors can only have a single attribute, this value will always be equal to the attribute associated with this object. For flow lines etc, use getZCoords() to retrieve multiple values.

Specified by:

getMinAttribute in class SpatialObject

Returns:

Minimum attribute value.

getMaxAttribute

public float getMaxAttribute()

Reports the maximum attribute value of the object. Since GIS vectors can only have a single attribute, this value will always be equal to the attribute associated with this object. For flow lines etc, use getZCoords() to retrieve multiple values.

Specified by:

getMaxAttribute in class SpatialObject

Returns:

Maximum attribute value.

getSizeText

public String getSizeText()

Reports a message giving length/area of the object. If a line, this will return its length in geographical units. If a polygon, will return its area in squared geographical units. Any other types of object return an empty string. Useful for information messages.

Returns:

Message reporting the length or area of object.

getSize

public float getSize()

Reports the size of the object. If a point, this will always return 0, if a line, this will return its length in geographical units, if an area, will return its area in squared geographical units. Note that this makes little sense for longitude/latitude projected data.

Returns:

Length or area of object.

setType

public void setType(int type)

Sets the type of vector.

Parameters:

type - Type of vector (POINT, LINE, AREA or VOLUME).

setAttribute

public void setAttribute(float attrib)

Sets the attribute of the GIS vector.

Parameters:

attrib - Attribute of the GIS vector.

setCoords

public void setCoords(float[] xCoords,
                      float[] yCoords)

Sets the coordinates of the vector object from the given arrays.

Parameters:

xCoords - Array holding x coordinates.

yCoords - Array holding y coordinates.

setCoords

public void setCoords(GeneralPath coords)

Sets the coordinates of the vector object from the given general path.

Parameters:

coords - General path containing coordinates.