Proximal Topology (raster) — program to generate,using a raster based algorithm, polygon distances to neighbouring polygons.



ca.spatial.gis.raster.ProximalTopology {cover} {dist} {outputfile}

ca.spatial.gis.raster.ProximalTopology {cover} {cellsize} {column} {dist} {outputfile}


covername of a polygon coverage or shapefileNone
distmaximum search distance for neighbouring polygons None
cellsizeraster resolution to use when processing polygon coverages None
columnattribute column within the polygon coverage that provides the polygon name None
outputfilename of the output file to hold the neighbour distances None


The ProximalTopology program will generate a table of distances from each polygon to every neighbouring polygon within the specified threshold search distance. The output of this program is a table containing pairs of polygon numbers, the distance between the polygons, and the length edge distance that is shared between the two polygons. Polygons that exceed the threshold search distance apart will be ignored.

The edge distance will only be recorded for polygons that share a common boundary. Polygons that do not touch, but are within the search threshold will have a shared edge length of zero.

Distances between polygons are symetric (the distance from A to B is the same as the distance from B to A), and values are only recorded once. The output table is sorted first by the lowered ordered polygon label, and then by the neighbouring polygon number.

The algorithn converts polygons to rasters on the fly and scans for touching neighbours based on a 4-way touching rule. Distances to non-touching neighbours is based on straightline distances from the closest edges or corners. Polygons that touch at corners will have a distance of zero but no shared edge.

Polygon coverages are rasterized on-the-fly using a centroid method into the specified grid cell size. The raster will cover the entire extent of the polygon coverage, and the starting X and Y offsets will be rounded down to an even multiple of the cell size. An extra row of cells is added around the entire coverage in order to allow calculation of shared edge to the outside of the map boundary. Raster cells that fall outside of the coverage will be given a no-data value of "-9999".

Polygons that are too small to be censused by a grid cell are treated specially. They are considered to have the same neighbours as the closest censused polygon, but no shared edge.

The distance matrix is written to standard output after all cells have been processed.



The name of an ascii format raster file, in ESRI format. This is the format that results from the Arc/Info GRIDASCII command or from exporting a grid file from ArcView. This program supports extensions to this format included alphanumeric cell values and run length encoded values.


The name of a polygon coverage or shapefile. This file will be rasterized on-the-fly using a centroid method.


The maximum threshold distance to use to search for neighbouring polygons. The search for neighbouring polygons will not extend beyond this distance. The units are the same as the map coordinates.


The raster cell size to use when converting polygon coverages. Coverages will be rasterized on-the-fly using the centroid method. The units are the same as the map coordinates.


The name of the column in the polygon coverage that should be used to identify the polygon. This value behaves similarly to a dissolve column. Polygons with the same value in this attribute will be considered the same when calculating neighbours. This also specifies the polygon label to be used in the output file.


The name of the file that will hold the distance table. The file contents are in CSV format so it is appropriate to use a CSV extension on the file name.

Processing Notes

This program requires about 100Mb of virtual memory.

Processing times are influenced by the coverage size, the cell size and by the search distance. Processing time increases by 2**2 with search distance, and by 2**4 with cell size.

See Also




java -Xmx100M -jar patchworks.jar ca.spatial.gis.raster.ProximalTopology \
              block.shp 10 BLOCK 100 topology.csv

In this example, a polygon shape file named 'block.shp' is used with a search threshold of 100. The polygons are rasterized on-the-fly using a cell-size of 10. The results are stored in a file named 'topology.csv'.