Spatial DataBlade
JAVA API v8.21

com.ibm.spatial.geom
Class IfxGeometry

java.lang.Object
  extended by com.ibm.spatial.geom.IfxGeometry
All Implemented Interfaces:
Geometry, java.lang.Cloneable
Direct Known Subclasses:
IfxMultiCoord, IfxPoint

public abstract class IfxGeometry
extends java.lang.Object
implements Geometry, java.lang.Cloneable

IfxGeometry partially implements the Geometry interface. Several convenience methods for retrieving coordinate data are also implemented in this class.

IfxGeometry is the root class of a geometry objects hierarchy. It is an abstract class.


Field Summary
static int COORD_M
          M values are copied into the destination buffer.
static int COORD_XY
          X and Y coordinates are copied into the destination buffer.
static int COORD_Z
          Z coordinates are copied into the destination buffer.
 
Method Summary
 double area()
          Returns the area of this object, as measured in the spatial reference system of this object.
 java.io.ByteArrayOutputStream asBinary()
          Exports this geometry to a specific well-known binary representation.
 java.lang.String asText()
          Exports this geometry to a specific well-known text representation.
 Geometry boundary()
          This implementation throws UnsupportedOperationException.
 Geometry buffer(double distance)
          This implementation throws UnsupportedOperationException.
 java.lang.Object clone()
          Return a copy of this object.
 boolean contains(Geometry geometry)
          Returns whether or not this object completely contains the geometry argument.
 Geometry convexHull()
          This implementation throws UnsupportedOperationException.
 boolean crosses(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 Geometry difference(Geometry geometry)
          This implementation throws UnsupportedOperationException.
abstract  int dimension()
          Returns the dimension of this geometry object.
 boolean disjoint(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 double distance(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 Geometry envelope()
          Returns a Geometry that represents this object's envelope.
 boolean envelopesIntersect(Geometry geometry)
          Returns true if the envelope of this geometry object intersects the envelope of the argument.
 boolean equals(java.lang.Object anObject)
          Compares this IfxGeometry to the specified object.
 Envelope extent()
          Returns an Envelope object that represents this geometry's envelope.
 Geometry exterior()
          This implementation throws UnsupportedOperationException.
 java.lang.String geometryType()
          Gets the most appropriate OGC geometry interface type for this object.
 int getCoordinateDimension()
          Gets the dimension of the coordinates that define this geometry, which must be the same as the coordinate dimension of the spatial reference system for this geometry.
 int getDimensionality()
          Gets the dimensionality of this geometry, which might be different from the coordinate dimension of the spatial reference system for this geometry.
 CoordPoint getLabelPoint()
          Returns a label point for this geometry.
 void getLabelPoint(CoordPoint point)
          Returns a label point for this geometry.
 java.lang.Class getOGCType()
          Gets the most appropriate OGC geometry interface type for this object.
 Geometry interior()
          This implementation throws UnsupportedOperationException.
 Geometry intersection(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 boolean intersects(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 boolean is3D()
          Tests whether or not this geometry object has three-dimensional coordinates.
 boolean isEmpty()
          Tests whether this geometry object is empty.
 boolean isMeasured()
          Tests whether or not this geometry object has measures.
 boolean isSimple()
          Tests whether this geometry object is simple (has no anomalous geometric points, such as self intersection or self tangency).
 boolean isValid()
          This implementation throws UnsupportedOperationException.
 double length()
          Returns the length of this object.
 Geometry locateAlong(double measure)
          This implementation throws UnsupportedOperationException.
 Geometry locateBetween(double fromMeasure, double toMeasure)
          This implementation throws UnsupportedOperationException.
abstract  int numParts()
          Returns the number of parts of this object.
abstract  int numPoints()
          Returns the number of points in this geometry.
abstract  int numPoints(int part, int subPart)
          Returns the number of points in the specified part and subpart.
abstract  int numSubParts(int part)
          Returns the number of subparts in the specified part.
 boolean overlaps(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 double perimeter()
          Returns the perimeter of this object, as measured in the spatial reference system of this object.
 int srid()
          Returns this object's spatial reference system identifier.
 Geometry symmetricDiff(Geometry geometry)
          This implementation throws UnsupportedOperationException.
abstract  int toCoordArray(double[] buf, int destOffset, int coordType, int srcOffset, int part, int subPart)
          Gets the coordinates of up to count points from the specified part and subpart of this object, starting with the position specified by index.
abstract  int toPointArray(CoordPoint[] pointArray, int destOffset, int srcOffset, int part, int subPart)
          Copies up to count points from the specified part and subpart of this object, starting with the point at the position specified by index (relative to the current subpart beginning position), into pointArray.
 java.lang.String toString()
          Returns a String object representing this object's modified WKT representation.
 boolean touches(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 Geometry union(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 boolean within(Geometry geometry)
          This implementation throws UnsupportedOperationException.
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COORD_XY

public static final int COORD_XY
X and Y coordinates are copied into the destination buffer.

See Also:
toCoordArray(double[], int, int, int, int, int), Constant Field Values

COORD_Z

public static final int COORD_Z
Z coordinates are copied into the destination buffer.

See Also:
toCoordArray(double[], int, int, int, int, int), Constant Field Values

COORD_M

public static final int COORD_M
M values are copied into the destination buffer.

See Also:
toCoordArray(double[], int, int, int, int, int), Constant Field Values
Method Detail

dimension

public abstract int dimension()

Returns the dimension of this geometry object. A geometry's dimension can be:

Specified by:
dimension in interface Geometry
Returns:
The dimension of this geometry.

asBinary

public java.io.ByteArrayOutputStream asBinary()
Exports this geometry to a specific well-known binary representation.

This implementation throws UnsupportedOperationException.

Specified by:
asBinary in interface Geometry
Returns:
The well-known binary (WKB) representation of this geometry object.

asText

public java.lang.String asText()
Exports this geometry to a specific well-known text representation.

Specified by:
asText in interface Geometry
Returns:
The well-known text (WKT) representation of this geometry object.

isSimple

public boolean isSimple()

Tests whether this geometry object is simple (has no anomalous geometric points, such as self intersection or self tangency).

For example, a LineString is simple if it does not intersect its interior. A MultiPoint is simple if none of its elements occupy the same coordinate space. A MultiLineString is simple if none of its element's interiors intersect.

This implementation throws UnsupportedOperationException.

Specified by:
isSimple in interface Geometry
Returns:
true if this geometry object is simple; otherwise, returns false

envelope

public Geometry envelope()

Returns a Geometry that represents this object's envelope.

The envelope of a geometry is the bounding geometry formed by the minimum and maximum (x,y) coordinates. The envelopes of most geometries form a boundary rectangle; however, the envelope of a point is the point itself, since its minimum and maximum coordinates are the same, and the envelope of a horizontal or vertical linestring is a linestring represented by the endpoints of the source linestring.

Specified by:
envelope in interface Geometry
Returns:
The envelope of this object

extent

public Envelope extent()

Returns an Envelope object that represents this geometry's envelope.

The envelope of a geometry is the bounding geometry formed by the minimum and maximum (x,y) coordinates. The envelopes of most geometries form a boundary rectangle; however, the envelope of a point is the point itself, since its minimum and maximum coordinates are the same, and the envelope of a horizontal or vertical linestring is a linestring represented by the endpoints of the source linestring.

Specified by:
extent in interface Geometry
Returns:
The envelope of this object

envelopesIntersect

public boolean envelopesIntersect(Geometry geometry)
Returns true if the envelope of this geometry object intersects the envelope of the argument.

Specified by:
envelopesIntersect in interface Geometry
Parameters:
geometry - The geometry tested for envelope intersection
Returns:
true if this geometry's envelope intersects the envelope of the argument; otherwise, it returns false

srid

public int srid()
Returns this object's spatial reference system identifier.

Specified by:
srid in interface Geometry
Returns:
The spatial reference ID of this geometry object.

isEmpty

public boolean isEmpty()
Tests whether this geometry object is empty.

Specified by:
isEmpty in interface Geometry
Returns:
true if this geometry object is empty; otherwise, returns false

numPoints

public abstract int numPoints()
Returns the number of points in this geometry.

Specified by:
numPoints in interface Geometry
Returns:
the number of points in this geometry

contains

public boolean contains(Geometry geometry)

Returns whether or not this object completely contains the geometry argument. The boundary and interior of the argument geometry are not allowed to intersect the exterior of this object.

This function returns the opposite result of within.

This implementation throws UnsupportedOperationException.

Specified by:
contains in interface Geometry
Parameters:
geometry - The geometry tested for inclusion.
Returns:
true if this Geometry contains the argument object; false otherwise.
See Also:
within(Geometry)

crosses

public boolean crosses(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
crosses in interface Geometry
Returns:
true if this Geometry crosses the argument object; false otherwise.
See Also:
Geometry.crosses(com.ibm.spatial.geom.Geometry)

disjoint

public boolean disjoint(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
disjoint in interface Geometry
Parameters:
geometry - The geometry tested for non-intersection.
Returns:
true if this geometry does not intersect the argument geometry; otherwise, it returns false.
See Also:
Geometry.disjoint(com.ibm.spatial.geom.Geometry)

intersects

public boolean intersects(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
intersects in interface Geometry
Parameters:
geometry - The geometry tested for intersection
Returns:
true if the intersection of this geometry object and the argument doesn't result in an empty set; otherwise, returns false.
See Also:
Geometry.intersects(com.ibm.spatial.geom.Geometry)

overlaps

public boolean overlaps(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
overlaps in interface Geometry
Parameters:
geometry - The geometry to test for overlapping
Returns:
true if this geometry object and the argument overlap; otherwise, returns false
See Also:
Geometry.overlaps(com.ibm.spatial.geom.Geometry)

touches

public boolean touches(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
touches in interface Geometry
Parameters:
geometry - The geometry to test for touching
Returns:
true if this geometry object and the argument touch; otherwise, returns false
See Also:
Geometry.touches(com.ibm.spatial.geom.Geometry)

within

public boolean within(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
within in interface Geometry
Parameters:
geometry - The geometry to test for within
Returns:
true if this geometry object is completely within the argument; otherwise, returns false
See Also:
Geometry.within(com.ibm.spatial.geom.Geometry)

boundary

public Geometry boundary()
This implementation throws UnsupportedOperationException.

Specified by:
boundary in interface Geometry
Returns:
The boundary of this object.
See Also:
Geometry.boundary()

buffer

public Geometry buffer(double distance)
This implementation throws UnsupportedOperationException.

Specified by:
buffer in interface Geometry
Parameters:
distance - The distance at which the encircling geometry is generated.
Returns:
The buffer geometry.
See Also:
Geometry.buffer(double)

convexHull

public Geometry convexHull()
This implementation throws UnsupportedOperationException.

Specified by:
convexHull in interface Geometry
Returns:
The convex hull geometry.
See Also:
Geometry.convexHull()

difference

public Geometry difference(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
difference in interface Geometry
Parameters:
geometry - The geometry tested for inclusion.
Returns:
The difference between this geometry and the argument.
See Also:
Geometry.difference(com.ibm.spatial.geom.Geometry)

distance

public double distance(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
distance in interface Geometry
Parameters:
geometry - The geometry to which the distance is calculated.
Returns:
The distance between this object and the argument.
See Also:
Geometry.distance(com.ibm.spatial.geom.Geometry)

intersection

public Geometry intersection(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
intersection in interface Geometry
Parameters:
geometry - The geometry to intersect with
Returns:
true if the intersection of this geometry
See Also:
Geometry.intersection(com.ibm.spatial.geom.Geometry)

symmetricDiff

public Geometry symmetricDiff(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
symmetricDiff in interface Geometry
Parameters:
geometry - The second operand of the symmetric difference
Returns:
A geometry representing the result of the symmetric difference operation
See Also:
Geometry.symmetricDiff(com.ibm.spatial.geom.Geometry)

union

public Geometry union(Geometry geometry)
This implementation throws UnsupportedOperationException.

Specified by:
union in interface Geometry
Parameters:
geometry - The second operand of the union
Returns:
Returns a geometry object that is the union of this object and the argument.
See Also:
Geometry.union(com.ibm.spatial.geom.Geometry)

is3D

public boolean is3D()
Tests whether or not this geometry object has three-dimensional coordinates.

Specified by:
is3D in interface Geometry
Returns:
true if this object has three-dimensional coordinates; otherwise, returns false

isMeasured

public boolean isMeasured()
Tests whether or not this geometry object has measures.

Specified by:
isMeasured in interface Geometry
Returns:
true if this object has measures; otherwise, returns false

isValid

public boolean isValid()
This implementation throws UnsupportedOperationException.

Specified by:
isValid in interface Geometry
Returns:
true if this geometry object is valid; otherwise, returns false
See Also:
Geometry.isValid()

exterior

public Geometry exterior()
This implementation throws UnsupportedOperationException.

Specified by:
exterior in interface Geometry
Returns:
the exterior of a geometry
See Also:
Geometry.exterior()

interior

public Geometry interior()
This implementation throws UnsupportedOperationException.

Specified by:
interior in interface Geometry
Returns:
the interior of a geometry
See Also:
Geometry.interior()

locateAlong

public Geometry locateAlong(double measure)
This implementation throws UnsupportedOperationException.

Specified by:
locateAlong in interface Geometry
Returns:
the set of points having the measure specified by measure
See Also:
Geometry.locateAlong(double)

locateBetween

public Geometry locateBetween(double fromMeasure,
                              double toMeasure)
This implementation throws UnsupportedOperationException.

Specified by:
locateBetween in interface Geometry
Returns:
the set of points or paths having measures between fromMeasure and toMeasure
See Also:
Geometry.locateBetween(double, double)

equals

public boolean equals(java.lang.Object anObject)
Compares this IfxGeometry to the specified object. The result is true if and only if the argument is not null and is a IfxGeometry object that represents the same sequence of coordinates as this object.

Note that only the srid's of the coordinate references of the two objects are compared for equality.

Specified by:
equals in interface Geometry
Overrides:
equals in class java.lang.Object
Parameters:
anObject - the object to compare this IfxGeometry against.
Returns:
true if the IfxGeometrys are equal; false otherwise.

getCoordinateDimension

public int getCoordinateDimension()
Gets the dimension of the coordinates that define this geometry, which must be the same as the coordinate dimension of the spatial reference system for this geometry.

Returns:
dimension of the coordinates that define this geometry

getDimensionality

public int getDimensionality()
Gets the dimensionality of this geometry, which might be different from the coordinate dimension of the spatial reference system for this geometry. For example, the user may store non-spatial values such as measurement, which make the dimensionality of geometry higher than that of the spatial reference system.

Returns:
the dimensionality of this geometry

geometryType

public java.lang.String geometryType()
Gets the most appropriate OGC geometry interface type for this object.

Returns:
a string that identifies the OGC interface related to this geometry

getOGCType

public java.lang.Class getOGCType()
Gets the most appropriate OGC geometry interface type for this object.

Returns:
a Class object that identifies the OGC interface related to this geometry

getLabelPoint

public CoordPoint getLabelPoint()
                         throws SpatialException
Returns a label point for this geometry. This method calculates a reasonable point location somewhere within this geometry that can be used for labeling.

Returns:
a 2D CoordPoint holding the coordinates of a label point for this geometry
Throws:
SpatialException - if an error occurs during the calculation of the label point coordinates

getLabelPoint

public void getLabelPoint(CoordPoint point)
                   throws SpatialException
Returns a label point for this geometry. This method calculates a reasonable point location somewhere within this geometry that can be used for labeling.

Parameters:
point - a CoordPoint object to be filled with the coordinates of the label point
Throws:
SpatialException - if an error occurs during the calculation of the label point coordinates

area

public double area()
Returns the area of this object, as measured in the spatial reference system of this object. Objects with dimension 0 or 1 have an area equal to zero.

Note: this implementation does not compute the area of a given geometry; instead it merely returns an area value which was previously associated with this object. For example, if we call area() on an object read from the database, we get the correct answer only if the database server calculated this value and sent it to the client together with the coordinate data. If called on a geometry created locally (using a geometry factory, for example) this method will return 0.

Returns:
the area of this object in double precision

perimeter

public double perimeter()
Returns the perimeter of this object, as measured in the spatial reference system of this object. Objects with dimension 0 or 1 have a perimeter equal to zero. Note: this implementation does not compute the perimeter of a given geometry; instead it merely returns the perimeter value previously associated with this object. For example, if we call perimeter() on an object read from the database, we get the correct answer only if the database server calculated this value and sent it to the client together with the coordinate data. If called on a geometry created locally (using a geometry factory, for example) this method will return 0.

Returns:
the perimeter of this object

length

public double length()
Returns the length of this object. Objects with dimension 0 or 2 have a length equal to zero. Note: this implementation does not compute the length of a given geometry; instead it merely returns the length value previously associated with this object. For example, if we call length() on an object read from the database, we get the correct answer only if the database server calculated this value and sent it to the client together with the coordinate data. If called on a geometry created locally (using a geometry factory, for example) this method will return 0.

Returns:
Returns the length of this object in its associated spatial reference.

numParts

public abstract int numParts()
Returns the number of parts of this object.

A IfxGeometry object is structured in parts. Each part can contain one or more subparts. Here is the part/subpart structure of instantiatiable subtypes:

Geometry TypePartsSubparts
Point 1 1
LineString 1 1
Polygon 1 N (subpart <==> ring)
MultiPoint 1 1
MultiLineString N 1
MultiPolygon N N

Returns:
the number of parts

numSubParts

public abstract int numSubParts(int part)
Returns the number of subparts in the specified part.

Parameters:
part - part index
Returns:
the number of subparts in the specified part
Throws:
java.lang.IndexOutOfBoundsException - for non-empty geometries, if the given part index is out of range (part < 0 || part >= numParts()).
See Also:
numParts()

numPoints

public abstract int numPoints(int part,
                              int subPart)
Returns the number of points in the specified part and subpart.

Parameters:
part - part index
subPart - subpart index
Returns:
the number of points in the specified part and subpart
Throws:
java.lang.IndexOutOfBoundsException - for non-empty geometries, if the given part and subpart indexes are out of range (part < 0 || part >= numParts()) || (subPart < 0 || subPart >= numSubParts(part)).
See Also:
numParts(), numSubParts(int)

toCoordArray

public abstract int toCoordArray(double[] buf,
                                 int destOffset,
                                 int coordType,
                                 int srcOffset,
                                 int part,
                                 int subPart)

Gets the coordinates of up to count points from the specified part and subpart of this object, starting with the position specified by index. The value of index is relative to the beginning of the current subpart. The order in which the coordinates are returned is described by coordType:

The number of points read count is equal to the smaller of buf.length and numPoints(part, subpart)-index. If count is positive, then coordinates of the points starting with position index through index+count-1 are copied into buf. The value count is returned.

If the array buf is reused for several calls, this method may be used to save allocation costs.

Below is an usage example. Looping through geometries with the same (known) type may help to further optimize the code:

  IfxGeometry geo;
  double buf[] = new double[1000];
  ...
  for(int part = 0; part < geo.numParts(); part++) {
      for(int subpart = 0; subpart < geo.numSubParts(part); subpart++) {
          int position = 0, read = 0;
          for (int points = geo.numPoints(part, subpart);
              points > 0;
              points -= read) {

              read = geo.toCoordArray(buf, 0, IfxGeometry.COORD_XY,
                          position, part, subpart);
              if (read == 0) break;

              // display coordinates
              ...
              // update position of the next point to read
              position += read;
          }
      }
  }
In case of geometries with more than one point, if coordType only equals one of the flag values, then the coordinate values are copied into the buffer in the manner performed by System.arraycopy.

If a coordinate type is specified that this object does not hold (for example, if COORD_Z is specified for a Polygon M), this method returns 0 without copying any coordinate.

Parameters:
buf - the array of double where point coordinates are returned. If buffer is null, an error is reported
destOffset - the starting position in the destination buffer where coordinates are written
coordType - specifies which coordinates are returned. It may be any combination of the flag values COORD_XY, COORD_Z, and COORD_M.
srcOffset - the position of the first point whose coordinates are copied into the destination buffer
part - the current part (see numParts)
subPart - the current subpart (see numParts)
Returns:
the number of points actually read from this object
Throws:
java.lang.IndexOutOfBoundsException - if case of non-empty geometries, if an attempt is made to write past the destination array boundaries or the given part and subpart indexes are out of range (part < 0 || part >= numParts()) || (subPart < 0 || subPart >= numSubParts(part)).
See Also:
COORD_XY, COORD_Z, COORD_M

toPointArray

public abstract int toPointArray(CoordPoint[] pointArray,
                                 int destOffset,
                                 int srcOffset,
                                 int part,
                                 int subPart)

Copies up to count points from the specified part and subpart of this object, starting with the point at the position specified by index (relative to the current subpart beginning position), into pointArray.

The number of points read count is equal to the smaller of pointArray.length and numPoints(part, subpart)-index. If count is positive, then points starting with position index through index+count-1 are copied into buf. The value count is returned.

If pointArray is reused for several calls, this method may be used to save allocation costs.

Below is an usage example. Looping through geometries with the same (known) type may help to further optimize the code:

  IfxGeometry geo;
  CoordPoint buf[] = new CoordPoint.Double[1000];

  for(int part = 0; part < geo.numParts(); part++) {
      for(int subpart = 0; subpart < geo.numSubParts(part); subpart++) {
          int read = 0;
          int position = 0;
          for (int points = geo.numPoints(part, subpart);
              points > 0;
              points -= read) {

              read = geo.toPointArray(buf, 0, position, part, subpart);
              if (read == 0) break;

              // display vertices ...

              // update position of the next point to read
              position += read;
          }
      }
  }

Parameters:
pointArray - the array of CoordPoints where point coordinates are returned.
destOffset - start position in the destination array pointArray
srcOffset - the position of the first point whose coordinates are copied, relative to the beginning of the specified part / subpart
part - the current geometry part (see numParts)
subPart - the current subpart (see numParts)
Returns:
the number of points actually read from this object
Throws:
java.lang.IndexOutOfBoundsException - if case of non-empty geometries, if an attempt is made to write past the destination array boundaries or the given part and subpart indexes are out of range (part < 0 || part >= numParts()) || (subPart < 0 || subPart >= numSubParts(part)).

toString

public java.lang.String toString()

Returns a String object representing this object's modified WKT representation.

This representation is compatible with the representation defined by the IBM Informix Spatial DataBlade, used for loading text strings directly into geometry columns without filtering the string through one of the Spatial DataBlade text functions.

Examples:

1 Point zm(10.98 29.91 10.2 9.1)

By placing the SRID in front of the text description, this representation may be used to insert data directly into a spatial column. Also, the load statement in the IBM Informix DB-Access utility reads text files generated with this format and inserts the modified well-known text representation into the geometry columns.

Overrides:
toString in class java.lang.Object
Returns:
a String object representing this object's modified WKT representation
See Also:
asText()

clone

public java.lang.Object clone()
Return a copy of this object.

Overrides:
clone in class java.lang.Object
Returns:
a copy of this object.

Spatial DataBlade
JAVA API v8.21


Licensed Materials - Property of IBM
Copyright IBM Corp. 2002, 2012 All Rights Reserved.