SpatialIndex (OpenMap API)
Date: 2016-12-09

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

    java.lang.Object
      com.bbn.openmap.dataAccess.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. Usage

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

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

     Creates spatial index file.ssx from shape file.shp
     java com.bbn.openmap.layer.shape.SpatialIndex -c 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.

Version:
  $Revision: 1.19 $ $Date: 2009/02/25 22:34:04 $
Author:
  Tom Mitchell
See Also:
  `ShapeIndex`

Nested Class Summary
`static class` | `SpatialIndex.Entry` The spatial information for each shp entry is held in one of these.
`static class` | `SpatialIndex.FileIndex`
`static class` | `SpatialIndex.MemoryIndex`

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<SpatialIndex.Entry>` | `entries` A cached list of the SpatialIndex file entries, for repeated reference.
`static java.util.logging.Logger` | `logger`
`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 BinaryFile` | `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.

Fields inherited from interface com.bbn.openmap.dataAccess.shape.ShapeConstants
`DBF_ATTRIBUTE, DBF_AUTOINCREMENT, DBF_BINARY, DBF_CHARACTER, DBF_DATE, DBF_DOUBLE, DBF_FLOAT, DBF_LOGICAL, DBF_LONG, DBF_MEMO, DBF_NUMERIC, DBF_OLE, DBF_TIMESTAMP, DBF_TYPE_AUTOINCREMENT, DBF_TYPE_BINARY, DBF_TYPE_CHARACTER, DBF_TYPE_DATE, DBF_TYPE_DOUBLE, DBF_TYPE_FLOAT, DBF_TYPE_LOGICAL, DBF_TYPE_LONG, DBF_TYPE_MEMO, DBF_TYPE_NUMERIC, DBF_TYPE_OLE, DBF_TYPE_TIMESTAMP, 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 shpFilename)` Opens a spatial index file for reading based on the location of the provided shp file.
`SpatialIndex(java.lang.String ssxFilename, java.lang.String shpFilename)` Deprecated. ssx file is figured based on the shp file path

Method Summary
`boolean` | `close(boolean done)`
`static java.lang.String` | `dbf(java.lang.String shpFileName)` Figures out the dbf file name from the shp file name.
`void` | `dumpIndex(boolean showBounds)` Displays the contents of this index.
`java.util.Iterator<SpatialIndex.Entry>` | `entryIterator()` Provides an iterator over the SpatialIndex entries.
`java.util.Iterator<SpatialIndex.Entry>` | `entryIterator(GeoCoordTransformation dataTransform)` Provides an iterator over the SpatialIndex entries.
`OMGraphic` | `evaluate(OMGraphic omg, OMGraphicList labels, Projection mapProj)` Evaluates the OMGraphic against the DbfHandler rules.
`OMGraphicList` | `evaluateDbf(OMGraphicList retList, Projection mapProj)` Takes the contents of the list and evaluates them against the information contained in the DbfHandler set in this SpatialIndex class.
`OMGraphicList` | `getAllOMGraphics(OMGraphicList retList, DrawingAttributes drawingAttributes, Projection mapProj, GeoCoordTransformation dataProj)` Retrieves all OMGraphics in the shape file.
`ESRIBoundingBox` | `getBounds()` Get the box boundary containing all the shapes.
`ESRIBoundingBox` | `getBounds(GeoCoordTransformation coordTransform)` Returns the bounds of the shape file.
`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 BinaryFile` | `getShpFile(java.lang.String shapeFileName)` Method that can be overridden to adjust how the BinaryFile is created for shp files.
`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 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<SpatialIndex.Entry>` | `readIndexFile(ESRIBoundingBox bounds)`
`protected java.util.List<SpatialIndex.Entry>` | `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.
`static java.lang.String` | `ssx(java.lang.String shpFileName)` Figures out the ssx file name from the shp file name.

Methods inherited from class com.bbn.openmap.dataAccess.shape.ShapeUtils
`getStringForType, 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

### logger

    public static java.util.logging.Logger logger

### 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

### shp

    protected BinaryFile 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.

### entries

    protected java.util.List<SpatialIndex.Entry> entries

  A cached list of the SpatialIndex file entries, for repeated reference.

Constructor Detail

### SpatialIndex

    public SpatialIndex(java.lang.String shpFilename)
                 throws java.io.IOException

  Opens a spatial index file for reading based on the location of the provided shp file.

  Parameters:
    `shpFilename` - 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

  Deprecated. ssx file is figured based on the shp file path

  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

### ssx

    public static java.lang.String ssx(java.lang.String shpFileName)

  Figures out the ssx file name from the shp file name.

  Parameters:
    `shpFileName` -
  Returns:
    ssx file name from shape file name

### dbf

    public static java.lang.String dbf(java.lang.String shpFileName)

  Figures out the dbf file name from the shp file name.

  Parameters:
    `shpFileName` -
  Returns:
    dbf file name created from shp file name.

### getBounds

    public ESRIBoundingBox getBounds()

  Get the box boundary containing all the shapes.

### getShpFile

    protected BinaryFile getShpFile(java.lang.String shapeFileName)
                             throws java.io.IOException

  Method that can be overridden to adjust how the BinaryFile is created for shp files.

  Parameters:
    `shapeFileName` - The path to shape file, absolute, relative or URL
  Returns:
    BinaryFile
  Throws:
    `java.io.IOException` - if the shapeFileName can't be found.

### getBounds

    public ESRIBoundingBox getBounds(GeoCoordTransformation coordTransform)

  Returns the bounds of the shape file. If bounds don't exist, they are read from the shape file header.

  Parameters:
    `coordTransform` -
  Returns:
    null if bounds can't been read, otherwise ESRIBoundingBox.

### 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. Not really used anymore, except for old code. Use EsriGraphicList or EsriGraphicFactory instead.

  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:
    EsriGraphicFactory being used to create EsriGraphics from shape file.

### 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 pre-projected 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`

### getAllOMGraphics

    public OMGraphicList getAllOMGraphics(OMGraphicList retList,
                                          DrawingAttributes drawingAttributes,
                                          Projection mapProj,
                                          GeoCoordTransformation dataProj)
                                   throws java.io.IOException,
                                          FormatException

  Retrieves all OMGraphics in the shape file.

  Parameters:
    `retList` - 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. This will also be used by the DbfHandler, to determine if some OMGraphics should not be returned based on attribute settings.
    `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`

### evaluateDbf

    public OMGraphicList evaluateDbf(OMGraphicList retList,
                                     Projection mapProj)

  Takes the contents of the list and evaluates them against the information contained in the DbfHandler set in this SpatialIndex class.

  Parameters:
    `retList` - the list of OMGraphics to evaluate.
    `mapProj` - the current map projection to be used by the DbfHandler to determine if some OMGraphics should be visible.
  Returns:
    OMGraphicList containing OMGraphics modified/passing evaluations rules in the DbfHandler.

### evaluate

    public OMGraphic evaluate(OMGraphic omg,
                              OMGraphicList labels,
                              Projection mapProj)

  Evaluates the OMGraphic against the DbfHandler rules.

  Parameters:
    `omg` - the OMGraphic to evaluate.
    `labels` - for DbfHandler label rules. Assumes that you are managing display of the labels list.
    `mapProj` - for DbfHandler scale rules.
  Returns:
    OMGraphic if it passes the rules.

### 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:
    `byteOffset` - , usually gotten from an Entry object.
    `drawingAttributes` -
  Returns:
    OMGraphic from entry object.
  Throws:
    `java.io.IOException`
    `FormatException`

### entryIterator

    public java.util.Iterator<SpatialIndex.Entry> entryIterator()
                                                         throws java.io.IOException,
                                                                FormatException

  Provides an iterator over the SpatialIndex entries.

  Returns:
    iterator over entries
  Throws:
    `java.io.IOException`
    `FormatException`

### entryIterator

    public java.util.Iterator<SpatialIndex.Entry> entryIterator(GeoCoordTransformation dataTransform)
                                                         throws java.io.IOException,
                                                                FormatException

  Provides an iterator over the SpatialIndex entries.

  Parameters:
    `dataTransform` - GeoCoordTransform for pre-projected data.
  Returns:
    iterator over entries, data transformed.
  Throws:
    `java.io.IOException`
    `FormatException`

### readIndexFile

    protected java.util.List<SpatialIndex.Entry> readIndexFile(ESRIBoundingBox bounds)
                                                        throws java.io.IOException,
                                                               FormatException

  Parameters:
    `bounds` - if not null, add min/max values to them.
  Returns:
    list of entries.
  Throws:
    `java.io.IOException`
    `FormatException`

### readIndexFile

    protected java.util.List<SpatialIndex.Entry> 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:
    list of entries
  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

### 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.

### 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)

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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