com.bbn.openmap.layer.shape
Class SpatialIndex

java.lang.Object
  extended bycom.bbn.openmap.layer.shape.ShapeUtils
      extended bycom.bbn.openmap.layer.shape.SpatialIndex
All Implemented Interfaces:
ShapeConstants
Direct Known Subclasses:
LinkSpatialIndex

public class SpatialIndex
extends ShapeUtils

A Spatial Index is a variation on a Shape Index, adding the bounding box of the shape to the index.

The file has a 100 byte header identical to a Shape Index followed by n records.

The record layout of the spatial index is as follows:

Position Field Value Type Byte Order
Byte 0 Offset Offset Integer Big
Byte 4 Content Length Content Length Integer Big
Byte 8 Bounding Box Xmin Double Little
Byte 16 Bounding Box Ymin Double Little
Byte 24 Bounding Box Xmax Double Little
Byte 32 Bounding Box Ymax Double Little

Usage

java com.bbn.openmap.layer.shape.SpatialIndex -d file.ssx
Dumps spatial index information, excluding bounding boxes to stdout. Useful for comparing to a shape index.

java com.bbn.openmap.layer.shape.SpatialIndex -d -b file.ssx
Dumps spatial index information including bounding boxes to stdout.

java com.bbn.openmap.layer.shape.SpatialIndex -c file.ssx file.shp
Creates spatial index file.ssx from shape file file.shp.

Notes

When reading the Shape file, the content length is the length of the record's contents, exclusive of the record header (8 bytes). So the size that we need to read in from the Shape file is actually denoted as ((contentLength * 2) + 8). This converts from 16bit units to 8 bit bytes and adds the 8 bytes for the record header.

To Do

Version:
$Revision: 1.6.2.6 $ $Date: 2007/06/21 21:41:38 $
Author:
Tom Mitchell
See Also:
ShapeIndex

Nested Class Summary
static class SpatialIndex.Entry
           
 
Field Summary
protected  ESRIBoundingBox bounds
          The bounds of all the shapes in the shape file.
protected  DbfHandler dbf
          The handler for dbf file information.
static int DEFAULT_SHAPE_RECORD_SIZE
          Default size for shape record buffer.
protected  java.util.List entries
          A cached list of the SpatialIndex file entries, for repeated reference.
protected  javax.swing.ImageIcon pointIcon
          The icon to use for point objects.
static int SHAPE_FILE_HEADER_LENGTH
          Size of a shape file header in bytes.
static int SHAPE_RECORD_HEADER_LENGTH
          Size of a shape file record header in bytes.
protected  BinaryBufferedFile shp
          The shape file.
protected  java.lang.String shpFileName
          The file name for the shape file, for opening/reopening.
static int SPATIAL_INDEX_HEADER_LENGTH
          Size of the spatial index header in bytes.
static int SPATIAL_INDEX_RECORD_LENGTH
          Size of the spatial index record in bytes.
protected  BinaryBufferedFile ssx
          The spatial index file.
protected  java.lang.String ssxFileName
          The file name for the spatial index file, for opening/reopening.
 
Fields inherited from interface com.bbn.openmap.dataAccess.shape.ShapeConstants
DBF_ATTRIBUTE, DBF_CHARACTER, DBF_DATE, DBF_LOGICAL, DBF_MEMO, DBF_NUMERIC, DBF_TYPE_CHARACTER, DBF_TYPE_DATE, DBF_TYPE_LOGICAL, DBF_TYPE_MEMO, DBF_TYPE_NUMERIC, PARAM_DBF, PARAM_SHP, PARAM_SHX, SHAPE_BOUNDS_ATTRIBUTE, SHAPE_DBF_DASHPATTERN, SHAPE_DBF_DASHPHASE, SHAPE_DBF_DESCRIPTION, SHAPE_DBF_FILLCOLOR, SHAPE_DBF_INFO_ATTRIBUTE, SHAPE_DBF_LINECOLOR, SHAPE_DBF_LINEWIDTH, SHAPE_DBF_SELECTCOLOR, SHAPE_FILE_RECORD_HEADER_LENGTH, SHAPE_INDEX_ATTRIBUTE, SHAPE_MAX_MEASURE_ATTRIBUTE, SHAPE_MAX_Z_ATTRIBUTE, SHAPE_MEASURE_ATTRIBUTE, SHAPE_MIN_MEASURE_ATTRIBUTE, SHAPE_MIN_Z_ATTRIBUTE, SHAPE_TYPE_ARC, SHAPE_TYPE_MULTIPATCH, SHAPE_TYPE_MULTIPOINT, SHAPE_TYPE_MULTIPOINTM, SHAPE_TYPE_MULTIPOINTZ, SHAPE_TYPE_NULL, SHAPE_TYPE_POINT, SHAPE_TYPE_POINTM, SHAPE_TYPE_POINTZ, SHAPE_TYPE_POLYGON, SHAPE_TYPE_POLYGONM, SHAPE_TYPE_POLYGONZ, SHAPE_TYPE_POLYLINE, SHAPE_TYPE_POLYLINEM, SHAPE_TYPE_POLYLINEZ, SHAPE_Z_ATTRIBUTE
 
Constructor Summary
SpatialIndex(java.lang.String ssxFilename)
          Opens a spatial index file for reading.
SpatialIndex(java.lang.String ssxFilename, java.lang.String shpFilename)
          Opens a spatial index file and it's associated shape file.
 
Method Summary
 boolean close(boolean done)
           
static void createIndex(java.lang.String inFile, java.lang.String outFile)
          Creates a spatial index for a shape file.
 void dumpIndex(boolean showBounds)
          Displays the contents of this index.
 java.util.Iterator entryIterator()
          Provides an iterator over the SpatialIndex entries.
 java.util.Iterator entryIterator(GeoCoordTransformation dataTransform)
          Provides an iterator over the SpatialIndex entries.
 ESRIBoundingBox getBounds()
          Get the box boundary containing all the shapes.
 DbfHandler getDbf()
           
 EsriGraphicFactory getFactory()
          The factory is used to filter and create OMGraphics from a shape file.
 OMGraphic getOMGraphicAtOffset(int byteOffset, DrawingAttributes drawingAttributes)
          Skips the BinaryFile for the shp data to the offset and reads the record data there, creating an OMGraphic from that data.
 OMGraphicList getOMGraphics(double xmin, double ymin, double xmax, double ymax, OMGraphicList list, DrawingAttributes drawingAttributes, Projection mapProj, GeoCoordTransformation dataProj)
          Locates OMGraphics in the shape file that intersect with the given rectangle.
 javax.swing.ImageIcon getPointIcon()
          Get the icon used for general point objects.
protected static void indexNulls(java.io.InputStream is, long ptr, java.io.OutputStream os)
          Writes the spatial index for a null shape file.
protected static void indexPoints(java.io.InputStream is, long ptr, java.io.OutputStream os)
          Writes the spatial index for a point shape file.
protected static void indexPolygons(java.io.InputStream is, long ptr, java.io.OutputStream os)
          Writes the spatial index for a polygon shape file.
protected static boolean intersects(double xmin1, double ymin1, double xmax1, double ymax1, double xmin2, double ymin2, double xmax2, double ymax2)
          Determines if two rectangles intersect.
static SpatialIndex locateAndSetShapeData(java.lang.String shapeFileName)
          Create a SpatialIndex object with just a shape file name.
static SpatialIndex locateAndSetShapeData(java.lang.String shapeFileName, java.lang.String spatialIndexFileName)
           
static java.lang.String locateFile(java.lang.String name)
          Locate file 'fileName' in classpath, if it is not an absolute file name.
 ESRIRecord[] locateRecords(double xmin, double ymin, double xmax, double ymax)
          Locates records in the shape file that intersect with the given rectangle.
static void main(java.lang.String[] argv)
          The driver for the command line interface.
 ESRIRecord makeESRIRecord(int shapeType, byte[] b, int off)
          Creates a record instance from the shape file data.
static void printUsage(java.io.PrintStream out)
          Prints a usage statement describing how to use this class from the command line.
protected  java.util.List readIndexFile(ESRIBoundingBox bounds)
           
protected  java.util.List readIndexFile(ESRIBoundingBox bounds, GeoCoordTransformation dataTransform)
           
 void resetBounds()
          Reset the bounds so they will be recalculated the next time a file is read.
 void setDbf(DbfHandler dbf)
           
 void setFactory(EsriGraphicFactory factory)
           
 void setPointIcon(javax.swing.ImageIcon ii)
          Set the icon to use for point objects, in general.
 
Methods inherited from class com.bbn.openmap.layer.shape.ShapeUtils
readBEInt, readBox, readLEDouble, readLEInt, readLEInt, readLELong, readPoint, writeBEInt, writeBox, writeLEDouble, writeLEInt, writeLELong, writePoint
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SHAPE_FILE_HEADER_LENGTH

public static final int SHAPE_FILE_HEADER_LENGTH
Size of a shape file header in bytes.

See Also:
Constant Field Values

SHAPE_RECORD_HEADER_LENGTH

public static final int SHAPE_RECORD_HEADER_LENGTH
Size of a shape file record header in bytes.

See Also:
Constant Field Values

SPATIAL_INDEX_HEADER_LENGTH

public static final int SPATIAL_INDEX_HEADER_LENGTH
Size of the spatial index header in bytes.

See Also:
Constant Field Values

SPATIAL_INDEX_RECORD_LENGTH

public static final int SPATIAL_INDEX_RECORD_LENGTH
Size of the spatial index record in bytes.

See Also:
Constant Field Values

DEFAULT_SHAPE_RECORD_SIZE

public static final int DEFAULT_SHAPE_RECORD_SIZE
Default size for shape record buffer.

See Also:
Constant Field Values

ssx

protected BinaryBufferedFile ssx
The spatial index file.


shp

protected BinaryBufferedFile shp
The shape file.


dbf

protected DbfHandler dbf
The handler for dbf file information.


pointIcon

protected javax.swing.ImageIcon pointIcon
The icon to use for point objects.


bounds

protected ESRIBoundingBox bounds
The bounds of all the shapes in the shape file.


shpFileName

protected java.lang.String shpFileName
The file name for the shape file, for opening/reopening.


ssxFileName

protected java.lang.String ssxFileName
The file name for the spatial index file, for opening/reopening.


entries

protected java.util.List entries
A cached list of the SpatialIndex file entries, for repeated reference.

Constructor Detail

SpatialIndex

public SpatialIndex(java.lang.String ssxFilename)
             throws java.io.IOException
Opens a spatial index file for reading.

Parameters:
ssxFilename - the name of the spatial index file
Throws:
java.io.IOException - if something goes wrong opening the file

SpatialIndex

public SpatialIndex(java.lang.String ssxFilename,
                    java.lang.String shpFilename)
             throws java.io.IOException
Opens a spatial index file and it's associated shape file.

Parameters:
ssxFilename - the name of the spatial index file
shpFilename - the name of the shape file
Throws:
java.io.IOException - if something goes wrong opening the files
Method Detail

getBounds

public ESRIBoundingBox getBounds()
Get the box boundary containing all the shapes.


resetBounds

public void resetBounds()
Reset the bounds so they will be recalculated the next time a file is read.


makeESRIRecord

public ESRIRecord makeESRIRecord(int shapeType,
                                 byte[] b,
                                 int off)
                          throws java.io.IOException
Creates a record instance from the shape file data. Calls the appropriate record constructor based on the shapeType, and passes the buffer and offset to that constructor.

Parameters:
shapeType - the shape file's shape type, enumerated in ShapeUtils
b - the buffer pointing to the raw record data
off - the offset of the data starting point in the buffer
Throws:
java.io.IOException - if something goes wrong reading the file
See Also:
ShapeUtils

locateRecords

public ESRIRecord[] locateRecords(double xmin,
                                  double ymin,
                                  double xmax,
                                  double ymax)
                           throws java.io.IOException,
                                  FormatException
Locates records in the shape file that intersect with the given rectangle. The spatial index is searched for intersections and the appropriate records are read from the shape file.

Parameters:
xmin - the smaller of the x coordinates
ymin - the smaller of the y coordinates
xmax - the larger of the x coordinates
ymax - the larger of the y coordinates
Returns:
an array of records that intersect the given rectangle
Throws:
java.io.IOException - if something goes wrong reading the files
FormatException

getFactory

public EsriGraphicFactory getFactory()
The factory is used to filter and create OMGraphics from a shape file. This accessor is provided in order to allow you to modify the data projection it uses, or the line type.

Returns:

setFactory

public void setFactory(EsriGraphicFactory factory)

getOMGraphics

public OMGraphicList getOMGraphics(double xmin,
                                   double ymin,
                                   double xmax,
                                   double ymax,
                                   OMGraphicList list,
                                   DrawingAttributes drawingAttributes,
                                   Projection mapProj,
                                   GeoCoordTransformation dataProj)
                            throws java.io.IOException,
                                   FormatException
Locates OMGraphics in the shape file that intersect with the given rectangle. The spatial index is searched for intersections and the appropriate OMGraphics are created from the shape file.

Parameters:
xmin - the smaller of the x coordinates
ymin - the smaller of the y coordinates
xmax - the larger of the x coordinates
ymax - the larger of the y coordinates
list - OMGraphicList to add OMGraphics to and return, if null one will be created.
drawingAttributes - DrawingAttributes to set on the OMGraphics.
mapProj - the Map Projection for the OMGraphics so they can be generated right after creation.
dataProj - for preprojected data, a coordinate translator for the data's projection to use to translate the coordinates to decimal degree lat/lon. Can be null to leave the coordinates untouched.
Returns:
an OMGraphicList containing OMGraphics that intersect the given rectangle
Throws:
java.io.IOException - if something goes wrong reading the files
FormatException

getOMGraphicAtOffset

public OMGraphic getOMGraphicAtOffset(int byteOffset,
                                      DrawingAttributes drawingAttributes)
                               throws java.io.IOException,
                                      FormatException
Skips the BinaryFile for the shp data to the offset and reads the record data there, creating an OMGraphic from that data.

Parameters:
drawingAttributes -
Returns:
Throws:
java.io.IOException
FormatException

entryIterator

public java.util.Iterator entryIterator()
                                 throws java.io.IOException,
                                        FormatException
Provides an iterator over the SpatialIndex entries.

Returns:
Throws:
java.io.IOException
FormatException

entryIterator

public java.util.Iterator entryIterator(GeoCoordTransformation dataTransform)
                                 throws java.io.IOException,
                                        FormatException
Provides an iterator over the SpatialIndex entries.

Parameters:
dataTransform - GeoCoordTransform for pre-projected data.
Returns:
Throws:
java.io.IOException
FormatException

readIndexFile

protected java.util.List readIndexFile(ESRIBoundingBox bounds)
                                throws java.io.IOException,
                                       FormatException
Parameters:
bounds - if not null, add min/max values to them.
Returns:
Throws:
java.io.IOException
FormatException

readIndexFile

protected java.util.List readIndexFile(ESRIBoundingBox bounds,
                                       GeoCoordTransformation dataTransform)
                                throws java.io.IOException,
                                       FormatException
Parameters:
bounds - if not null, add min/max values to them.
dataTransform - GeoCoordTransform for pre-projected data.
Returns:
Throws:
java.io.IOException
FormatException

intersects

protected static final boolean intersects(double xmin1,
                                          double ymin1,
                                          double xmax1,
                                          double ymax1,
                                          double xmin2,
                                          double ymin2,
                                          double xmax2,
                                          double ymax2)
Determines if two rectangles intersect. Actually, this method determines if two rectangles don't intersect, and then returns a negation of that result. But the bottom line is the same.

Parameters:
xmin1 - the small x of rectangle 1
ymin1 - the small y of rectangle 1
xmax1 - the big x of rectangle 1
ymax1 - the big y of rectangle 1
xmin2 - the small x of rectangle 2
ymin2 - the small y of rectangle 2
xmax2 - the big x of rectangle 2
ymax2 - the big y of rectangle 2
Returns:
true if the rectangles intersect, false if they do not

dumpIndex

public void dumpIndex(boolean showBounds)
               throws java.io.IOException
Displays the contents of this index.

Parameters:
showBounds - true to show bounding box, false to skip it
Throws:
java.io.IOException - if something goes wrong reading the file

indexPolygons

protected static void indexPolygons(java.io.InputStream is,
                                    long ptr,
                                    java.io.OutputStream os)
Writes the spatial index for a polygon shape file.

Parameters:
is - the shape file input stream
ptr - the current position in the file
os - the spatial index file output stream

indexPoints

protected static void indexPoints(java.io.InputStream is,
                                  long ptr,
                                  java.io.OutputStream os)
Writes the spatial index for a point shape file.

Parameters:
is - the shape file input stream
ptr - the current position in the file
os - the spatial index file output stream

indexNulls

protected static void indexNulls(java.io.InputStream is,
                                 long ptr,
                                 java.io.OutputStream os)
Writes the spatial index for a null shape file.

Parameters:
is - the shape file input stream
ptr - the current position in the file
os - the spatial index file output stream

createIndex

public static void createIndex(java.lang.String inFile,
                               java.lang.String outFile)
Creates a spatial index for a shape file. Reads the records from the shape file, writing appropriate index records to the spatial index file.

Parameters:
inFile - the shape file
outFile - the spatial index file

printUsage

public static void printUsage(java.io.PrintStream out)
Prints a usage statement describing how to use this class from the command line.

Parameters:
out - The output stream to use for output

locateFile

public static java.lang.String locateFile(java.lang.String name)
Locate file 'fileName' in classpath, if it is not an absolute file name.

Returns:
absolute name of the file as a string if found, null otherwise.

locateAndSetShapeData

public static SpatialIndex locateAndSetShapeData(java.lang.String shapeFileName)
Create a SpatialIndex object with just a shape file name. If the shape file is local, this method will attempt to build the spatial index file and place it next to the shape file.


locateAndSetShapeData

public static SpatialIndex locateAndSetShapeData(java.lang.String shapeFileName,
                                                 java.lang.String spatialIndexFileName)

main

public static void main(java.lang.String[] argv)
                 throws java.io.IOException
The driver for the command line interface. Reads the command line arguments and executes appropriate calls.

See the file documentation for usage.

Parameters:
argv - the command line arguments
Throws:
java.io.IOException - if something goes wrong reading or writing the file

setPointIcon

public void setPointIcon(javax.swing.ImageIcon ii)
Set the icon to use for point objects, in general.

Parameters:
ii - ImageIcon to use for icon.

getPointIcon

public javax.swing.ImageIcon getPointIcon()
Get the icon used for general point objects.

Returns:
ImageIcon, null if not set.

close

public boolean close(boolean done)

getDbf

public DbfHandler getDbf()

setDbf

public void setDbf(DbfHandler dbf)


Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details