## com.bbn.openmap.layer.shape
Class SpatialIndex

    java.lang.Object
      com.bbn.openmap.layer.shape.ShapeUtils
          com.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

- index arcs
- index multipoints

Version:
  $Revision: 1.6.2.6 $ $Date: 2007/06/21 21:41:38 $
Author:
  Tom Mitchell <tmitchell@bbn.com>
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