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)