Repast Simphony's GIS support is based on the Geography projection. A Geography is essentially a space in which agents are associated with a spatial geometry (polygon, point, etc.. Agents are stored by type in layers within the Geography and agents of the same type must have the same geometry. The geography can be queried spatially to return all the agents within some particular area. When a geography is displayed the agents are displayed in typical GIS fashion and represented by their associated geometries.

Repast Simphony uses Geotoolsand the Java Topology Suiteextensively for its GIS support.

 Creating a Geography

Creating a geography in repast simphony is similar to creating the other projections.  Your agents must exist in the context in order to exist in the geography, and you want to create the geograhy using a factory to make sure that it is initialized properly.

GeographyParameters<Object> params = new GeographyParameters<Object>();
GeographyFactory factory = GeographyFactoryFinder.createGeographyFactory(null);
Geography geography = factory.createGeography("GeograhpyName", context, params);

This should be fairly straightforward. We create a GeographyFactory and the create the Geography with that, passing the name of the Geography, the associated context, and the GeographyParameters.

GeographyParameters

GeographyParameters can be used to set the "adder" and the CoordinateReferenceSystem for a Geography.

Adders

The adder controls how any agent added to the context is added to the Geography. The default is a SimpleAdder which although it makes the Geography aware of the agent, it does not move the agent into the Geography by associating it with some Geometry. Custom adders can be created by implementing the GISAdder interface. A typical custom adder would call Geography.move to move an agent into the Geography and associate it with a Geometry in some model specific manner.

CoordinateReferenceSystem

Using GeographyParameters, you can define the CoordinateReferenceSystem for the created Geography. In the absence of any user supplied CRS, the default is WGS84 as defined by Geotools'  DefaultGeographicCRS.WGS84. That CRS uses (longitude, latitude) coordinates with longitude values increasing East and latitude values increasing North. Angular units are degrees and prime meridian is Greenwich.

Moving in a Geography

Moving a Geography is typically accomplished using the following method

move(T agent, Geometry geom)

The first time this is called for an agent that agent is moved into the Geography and associated with the specific geometry. The specific geometry establishes the agent's location in the geographical space and subsequent queries of the Geography will make use of that Geometry. If this is the first time an agent of this Class has been move in the Geography that type of agent will become associated with that Geometry type. For example, if the agent's type is the Java class anl.model.Truck, and the Geometry is a Point, then all Trucks are considered to be Points and any Truck moved in the Geography must have a Point geometry.

An agent's current Geometry (i.e. its location) can be retrieved with:

Geometry getGeometry(Object agent);

This returned Geometry can be used to move the agent without recreating a Geometry and passing that new Geometry to the move method. For example, where "this" refers to an agent,

Geometry geom = geography.getGeometry(this);
Coordinate coord = geom.getCoordinate();
coord.x += .005;
coord.y += .005;
geography.move(this, geom);

 In this case, we know the Geometry is a Point and so it has a single coordinate whose x and y values we can change. Note that its important to call move here to register the move with the Geography.

Geography has additional move methods that can move by displacement etc.:

/**
   * Displaces the specified object by the specified lon and lat amount.
   *
   * @param object the object to move
   * @param lonShift the amount to move longitudinaly
   * @param latShift the amount to move latitudinaly
   * @return the new geometry of the object
   */
  Geometry moveByDisplacement(T object, double lonShift, double latShift);

/**
   * Moves the specified object the specified distance along the specified angle.
   *
   * @param object the object to move
   * @param distance the distance to move
   * @param unit the distance units. This must be convertable to meters
   * @param angleInRadians the angle along which to move
   *
   * @return the geometric location the object was moved to
   */
  Geometry moveByVector(T object, double distance, Unit unit,  double angleInRadians);

/**
   * Moves the specified object the specified distance along the specified angle.
   *
   * @param object the object to move
   * @param distance the distance to move in meters
   * @param angleInRadians the angle along which to move
   *
   * @return the geometric location the object was moved to
   */
  Geometry moveByVector(T object, double distance,  double angleInRadians);

Queries

A Geography can also be queried spatially to return the objects within a particular envelope.

 /**
   * Gets an iterable over all the objects within the specified envelope.
   *
   * @param envelope the bounding envelope
   * @return an iterable over all the objects within the specified location.
   */
  Iterable<T> getObjectsWithin(Envelope envelope);

Additional queries are available for getting agents that  intersect another agent or geometry, for getting the agents that touch another agent or geometry, and so on. See the classes in the repast.simphony.query.space.gis package for more information.