dd.sim
Class Map

java.lang.Object
  dd.sim.SimObject
      dd.sim.Map

All Implemented Interfaces:

java.io.Serializable

public class Map

extends SimObject

The current geographic region of interest. In the disaster simulation, the map is the core simulation object. The map represents the region that is currently being simulated. The map is divided geographically into smaller hexagonal regions called MapCells, and is conceptually divided into Layers. Although the map is two-dimensional, layers may be used to add three-dimensional information to each cell. The map is responsible for keeping track of cells and layers.

There are several ways to refer to locations within the Map. Internally, a Map consists of rows and columns. Rows refer to the height of the map and the vertical (north/south) distance. Columns refer to the width of the map and horizontal (east/west) distance. Row and column refer to the internal map coordinate numbering system, whereas X and Y or latitude and longitude refer to the geographic coordinates in which cells of the map live.

Author:

Eric Scharff

See Also:

Serialized Form

Field Summary

static java.lang.String	CELL
static java.lang.String	EUCLIDEAN

Fields inherited from class dd.sim.SimObject

attributes

Constructor Summary

Map()
Create a new (empty) map.

Map(int rows, int columns)
Creates a new map of specified size.

Method Summary

void	addLayer(Layer layer) Adds a layer to the map.
int	cDistanceBetweenCells(MapCell cell1, MapCell cell2) Computes the cell distance between two cells.
MapCell	cellAt(int row, int column) Returns the cell at the specified internal coordinates.
MapCell	cellAt(java.lang.String cellName) Returns the cell at the internal coordinates specified by name in the form "".
java.util.Collection	cellsWithin(MapCell cell, int distance) Returns all the cells within a radius of the cell specified.
void	copyLayer(java.lang.String sourceLayerName, java.lang.String targetLayerName) Duplicates a layer by giving it a new name.
Layer	createLayer(java.lang.String layerName) Creates and adds a layer to the map.
double	distanceBetweenCells(MapCell cell1, MapCell cell2, java.lang.String type)
double	eDistanceBetweenCells(MapCell cell1, MapCell cell2) Computes the Euclidean distance between two cells.
float	getAttribute(java.lang.String layerName, MapCell cell, java.lang.String attributeName) Retrieves the value of an attribute for a specific layer and specific cell.
float	getAttribute(java.lang.String layerName, MapCell cell, java.lang.String attributeName, float defaultValue) Retrieves the value of an attribute for a specific layer and specific cell.
java.util.Collection	getCells() Returns all the cells in the map.
java.util.ArrayList	getCells(java.lang.String[] sites) Returns an ArrayList containing the mapCells specified by name (in the form "") in the given array.
Layer	getLayer(java.lang.String layerName) Returns the layer with the name specified.
java.util.Collection	getLayers() Returns all layers on this map.
int	getMapHeight() Returns the height of the map.
int	getMapWidth() Returns the width of the map.
java.util.Collection	getNeighbors(MapCell cell) Returns a collection of neighbors of the specified cell.
java.lang.Object	getObjectAttribute(java.lang.String layerName, MapCell cell, java.lang.String attributeName) Retrieves the value of an attribute for a specific layer and specific cell.
int	luCount(java.lang.String landuse) As luCount(landuse, layer), on the "landuse" layer.
int	luCount(java.lang.String landuse, java.util.Collection c) As luCount(landuse, collection, layer), on the "landuse" layer.
int	luCount(java.lang.String landuse, java.util.Collection c, Layer layer) As luCount(landuse, cell, layer), but summeed over all the MapCells specified in the given Collection.
int	luCount(java.lang.String landuse, Layer layer) As luCount(landuse, cell, layer), but summed over the entire Map.
int	luCount(java.lang.String landuse, MapCell cell) As luCount(landuse, cell, layer), on the "landuse" layer.
int	luCount(java.lang.String landuse, MapCell cell, Layer layer) Returns the number of landuses (count of luArray items equal to landuse) in the given Cell on the given Layer of the Map.
static void	main(java.lang.String[] args) Runs a test of Map functionality.
void	makeCache() Creates the cell cache.
MapCell	northEastOf(MapCell cell) Returns the cell northeast of the cell specified.
MapCell	northOf(MapCell cell) Returns the cell north of the cell specified.
MapCell	northWestOf(MapCell cell) Returns the cell northwest of the cell specified.
void	setAttribute(java.lang.String layerName, MapCell cell, java.lang.String attributeName, float value) Sets the attribute associated with a specified layer and cell.
void	setCellAt(int row, int column, MapCell cell) Adds a cell to the map at the specified coordinates.
MapCell	southEastOf(MapCell cell) Returns the cell southeast of the cell specified.
MapCell	southOf(MapCell cell) Returns the cell south of the cell specified.
MapCell	southWestOf(MapCell cell) Returns the cell southwest of the cell specified.

Methods inherited from class dd.sim.SimObject

addPropertyChangeListener, addPropertyChangeListener, debug, duplicate, error, fatal, filter, filter, firePropertyChange, getAttribute, getAttribute, getAttributes, getGlobalAttribute, getObjectAttribute, getObjectAttribute, incrementAttribute, incrementAttribute, isSet, log, out, readFromXML, readFromXML, removeAttribute, removePropertyChangeListener, setAttribute, setAttribute, setAttribute, setAttributes, setGlobalAttribute, warning, writeText, writeXML, writeXML

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EUCLIDEAN

public static final java.lang.String EUCLIDEAN

See Also:

Constant Field Values

CELL

public static final java.lang.String CELL

See Also:

Constant Field Values

Constructor Detail

Map

public Map()

Create a new (empty) map. The map adopts a default width and height.

Map

public Map(int rows,
           int columns)

Creates a new map of specified size. The rows and columns determine the height and width of the map, respectively.

Parameters:

rows - number of cells tall the resulting map should be

columns - number of cells wide the resulting map should be

Method Detail

getMapWidth

public int getMapWidth()

Returns the width of the map. This is the number of cells from the east to the west edges of the map.

Returns:

the width of the map, in terms of number of cells

getMapHeight

public int getMapHeight()

Returns the height of the map. This is the number of cells from the north to the south edges of the map.

Returns:

the height of the map, in terms of number of cells

makeCache

public void makeCache()

Creates the cell cache. The cell cache is an internal structure that accelerates access to cells in the map. If the map dimensions change or cells are added, removed, or replaced, the cell cache must be recreated using this method.

createLayer

public Layer createLayer(java.lang.String layerName)

Creates and adds a layer to the map. If the map already has a layer with the specified name, that existing layer is returned. If not, a new layer is created and properly initialized. This method properly handles sets up all of the dependencies between Maps, MapCells, and layers. This is the preferred way to create layers, rather than calling the Layer constructor directly.

Parameters:

layerName - name of the layer to create

Returns:

the newly created and initialized layer (if the layer did not exist), or the existing layer with the given name

copyLayer

public void copyLayer(java.lang.String sourceLayerName,
                      java.lang.String targetLayerName)

Duplicates a layer by giving it a new name. This effectively copies a layer by creating a new layer with all the same attributes of the current layer.

Parameters:

sourceLayerName - name of the layer to copy

targetLayerName - name of the new layer to create

addLayer

public void addLayer(Layer layer)

Adds a layer to the map. This method takes a layer and adds it to the current map, creating dependencies between the layer, map, and cells. If a layer with the same name as the layer passed to this method already existed on the map, it is replaced with this new layer. It is usually desirable to avoid calling this method directly and instead to use the createLayer method.

Parameters:

layer - layer to add to the map

getCells

public java.util.Collection getCells()

Returns all the cells in the map. This method returns a list of cells, suitable (for example) to iterate over all cells in the map. There is no guarantee to the order in which the cells are returned.

Returns:

a collection of MapCell objects that make up the map

getLayers

public java.util.Collection getLayers()

Returns all layers on this map. This method returns a list of Layer objects that have been added to the map. Note that it is possible (though perhaps not desirable) that this will not return all layers within the simulation, since it is possible to add a layer directly to a cell without also adding it to the Map.

Returns:

a collection of Layer objects that have been added to the map

cellAt

public MapCell cellAt(int row,
                      int column)

Returns the cell at the specified internal coordinates. The row and column provided refer to cell coordinates in the map internal coordinate system. This internal coordinate system may change at any time, and it is usually desirable to use the geographic querying mechanisms.

Parameters:

row - row (in internal Map coordinates) of the cell

column - column (in internal Map coordinates) of the cell

Returns:

the cell at the specified coordinates, null if the coordinates are invalid or there is no cell at that location

cellAt

public MapCell cellAt(java.lang.String cellName)

Returns the cell at the internal coordinates specified by name in the form "". (This is a convenience method that parses the string and calls cellAt(row, col).)

getCells

public java.util.ArrayList getCells(java.lang.String[] sites)

Returns an ArrayList containing the mapCells specified by name (in the form "") in the given array. The ArrayList has the same ordering as the given array.

setCellAt

public void setCellAt(int row,
                      int column,
                      MapCell cell)

Adds a cell to the map at the specified coordinates. If there is already a cell in the map at the location specified, it is replaced by this this new cell. Note that it is necessary to recreate the cell cache after all of the cells have been added.

Parameters:

row - row (in internal Map coordinates) of the cell

column - column (in internal Map coordinates) of the cell

cell - cell to be added to the map

See Also:

makeCache()

northOf

public MapCell northOf(MapCell cell)

Returns the cell north of the cell specified. This method returns the cell geographically north of the one provided, regardless of the internal coordinates used in the cell.

Parameters:

cell - cell whose neighbor should be retrieved

Returns:

the cell north of the cell provided, null if it does not exist.

southOf

public MapCell southOf(MapCell cell)

Returns the cell south of the cell specified. This method returns the cell geographically south of the one provided, regardless of the internal coordinates used in the cell.

Parameters:

cell - cell whose neighbor should be retrieved

Returns:

the cell north of the cell provided, null if it does not exist.

northEastOf

public MapCell northEastOf(MapCell cell)

Returns the cell northeast of the cell specified. This method returns the cell geographically northeast of the one provided, regardless of the internal coordinates used in the cell.

Parameters:

cell - cell whose neighbor should be retrieved

Returns:

the cell northeast of the cell provided, null if it does not exist.

northWestOf

public MapCell northWestOf(MapCell cell)

Returns the cell northwest of the cell specified. This method returns the cell geographically northwest of the one provided, regardless of the internal coordinates used in the cell.

Parameters:

cell - cell whose neighbor should be retrieved

Returns:

the cell northwest of the cell provided, null if it does not exist.

southEastOf

public MapCell southEastOf(MapCell cell)

Returns the cell southeast of the cell specified. This method returns the cell geographically southeast of the one provided, regardless of the internal coordinates used in the cell.

Parameters:

cell - cell whose neighbor should be retrieved

Returns:

the cell southeast of the cell provided, null if it does not exist.

southWestOf

public MapCell southWestOf(MapCell cell)

Returns the cell southwest of the cell specified. This method returns the cell geographically southwest of the one provided, regardless of the internal coordinates used in the cell.

Parameters:

cell - cell whose neighbor should be retrieved

Returns:

the cell southwest of the cell provided, null if it does not exist.

getNeighbors

public java.util.Collection getNeighbors(MapCell cell)

Returns a collection of neighbors of the specified cell. In the hexagonal coordinate system, a cell has at most six neighbors to the north, northeast, southeast, south, southwest, and northwest. A cell may have less neighbors if it is on the edge of the map. This method returns a list of these neighbors. The order of the neighbors is unspecified.

Parameters:

cell - cell whose neighbors should be retrieved

Returns:

a collection of MapCell objects that are adjacent to the cell specified.

eDistanceBetweenCells

public double eDistanceBetweenCells(MapCell cell1,
                                    MapCell cell2)

Computes the Euclidean distance between two cells. This is the straight-line distance between the centers of the cells, based on their Cartesian coordinates, which are initialized in makeMap() with the assumption that hexes have a unit side-length.

Parameters:

cell1 - origin to compare distance

cell2 - destination to compute distance

Returns:

the distance between the centers of cell1 and cell2

cDistanceBetweenCells

public int cDistanceBetweenCells(MapCell cell1,
                                 MapCell cell2)

Computes the cell distance between two cells. This is the number of cell boundaries you have to cross to travel from one cell to another following an optimal path. This corresponds to hexagonal taxicab distance, and also what your instinctive notion of distance is for moving on a hexagonal grid.

Parameters:

cell1 - origin to compare distance

cell2 - destination to compute distance

Returns:

the distance between the centers of cell1 and cell2

distanceBetweenCells

public double distanceBetweenCells(MapCell cell1,
                                   MapCell cell2,
                                   java.lang.String type)

cellsWithin

public java.util.Collection cellsWithin(MapCell cell,
                                        int distance)

Returns all the cells within a radius of the cell specified. Similar to querying neighbors, this method returns all the cells that are within a specific geographic distance of the cell provided.

Parameters:

cell - center cell

distance - geographic (Cartesian) distance to the furthest cell

Returns:

a collection of MapCell objects that that are at most distance units away from the center cell

See Also:

cDistanceBetweenCells(MapCell,MapCell)

getLayer

public Layer getLayer(java.lang.String layerName)

Returns the layer with the name specified. This method is similar to createLayer but does not create a new layer if it does not already exist.

Parameters:

layerName - name of the layer to retrieve from the map

Returns:

the layer with the specified name, null if the map does not have a cell with this layer.

getAttribute

public float getAttribute(java.lang.String layerName,
                          MapCell cell,
                          java.lang.String attributeName)

Retrieves the value of an attribute for a specific layer and specific cell. This is a convenience method for querying attributes without already having the layer or cell. This is a convenience method for the more general-purpose getObjectAttribute method, which shares the same variables. This method is equivalent to cell.getAttribute(attributeName, this.getLayer(layerName))

Parameters:

layerName - the layer on which the attribute is stored

cell - the cell in which the attribute is stored

attributeName - the name of the attribute to return

Returns:

the value of that attribute in this cell on the layer specified

Throws:

java.util.NoSuchElementException - if there is no attribute with that name associated with that layer.

getAttribute

public float getAttribute(java.lang.String layerName,
                          MapCell cell,
                          java.lang.String attributeName,
                          float defaultValue)

Retrieves the value of an attribute for a specific layer and specific cell. This is a convenience method for querying attributes without already having the layer or cell. This is a convenience method for the more general-purpose getObjectAttribute method, which shares the same variables. This method is equivalent to cell.getAttribute(attributeName, this.getLayer(layerName), defaultValue)

Parameters:

layerName - the layer on which the attribute is stored

cell - the cell in which the attribute is stored

attributeName - the name of the attribute to return

defaultValue - default if the attribute does not exist

Returns:

the value of that attribute in this cell on the layer specified

getObjectAttribute

public java.lang.Object getObjectAttribute(java.lang.String layerName,
                                           MapCell cell,
                                           java.lang.String attributeName)

Retrieves the value of an attribute for a specific layer and specific cell. This is a convenience method for querying attributes without already having the layer or cell.

Parameters:

layerName - the layer on which the attribute is stored

cell - the cell in which the attribute is stored

attributeName - the name of the attribute to return

Returns:

the value of that attribute in this cell on the layer specified, null if the attribute does not exist

setAttribute

public void setAttribute(java.lang.String layerName,
                         MapCell cell,
                         java.lang.String attributeName,
                         float value)

Sets the attribute associated with a specified layer and cell. This creates a new attribute (or overwrites an existing attribute) associated with the name, layer, and cell specified. This has the effect of associating a value with the current cell with the current name on the current layer. An appropriate property change event is fired when the attribute is set.

Parameters:

layerName - layer on which the attribute should exist

cell - the cell into which the attribute should be stored

attributeName - name of the attribute to set

value - value to which the attribute should be set

See Also:

PropertyChangeEvent

luCount

public int luCount(java.lang.String landuse,
                   Layer layer)

As luCount(landuse, cell, layer), but summed over the entire Map.

luCount

public int luCount(java.lang.String landuse,
                   java.util.Collection c,
                   Layer layer)

As luCount(landuse, cell, layer), but summeed over all the MapCells specified in the given Collection.

Parameters:

c - a Collection of MapCells to total landuse over.

luCount

public int luCount(java.lang.String landuse,
                   MapCell cell,
                   Layer layer)

Returns the number of landuses (count of luArray items equal to landuse) in the given Cell on the given Layer of the Map. Although this is a hurricance-scenario specific function, it's going here in Map because it will generalize usefully one we rescale the map. Invalid landuses are okay; they will return 0.

Parameters:

landuse - the landuse to tally. In addition to the normal landuses, the pseudo-landuse "all" is overloaded to return the sum of house, hotel, store, and condo landuses. Yeah, it's hacky, but it's useful until the general cleanup of rescaling happens.

luCount

public int luCount(java.lang.String landuse)

As luCount(landuse, layer), on the "landuse" layer.

luCount

public int luCount(java.lang.String landuse,
                   java.util.Collection c)

As luCount(landuse, collection, layer), on the "landuse" layer.

luCount

public int luCount(java.lang.String landuse,
                   MapCell cell)

As luCount(landuse, cell, layer), on the "landuse" layer.

main

public static void main(java.lang.String[] args)

Runs a test of Map functionality. This basic test creates and initializes a number of cells and layers and then queries and manipulates their values. There is also some code to test XML reading and writing of state.

Parameters:

args - command-line arguments, currently ignored