1. Data Files
Geo Relocation takes as its input 3 text files: A vectorized Map (VEC), a list of object descriptions (CSV), and a list of square matrices that denote the numeric relationship between all objects for any given time period (DAT). The vectorized map (VEC) is then drawn in the interface, annotated using descriptions from (CSV), and populated with data from (DAT).
1.1 The VEC file and The Vectorizer (vectorizer.jar)
A [geographic] map consists of primitive shapes (polygons), each of which is filled with some color. In the figure above, the map consists of city blocks (brown), and different shapes (circles, rectangles, and other polygons) each filled with a different color (red, green, etc.) and outlined in black. The Vectorizer (vectorizer.jar) attempts to convert this bitmap image into vector polygons for more efficient and effective display in the interface. The most important properties of any map used in the interface are:
- Descriptive objects (shapes) must be colored uniquely: Every unique color in a map is mapped to a descriptor in the CSV file. This relationship allows the interface to distinguish between descriptive objects and provides the necessary link to the data from (DAT).
- Non-descriptive objects (shapes) can be colored with any color that has not been assigned to a descriptive object. City blocks, in the example of a geographic map, are non-descriptive objects that serve only to retain context of the buildings in it.
- Every object (shape) must be outlined in black (RGB = 0,0,0). This outline is used to recognize the shapes, whereas the fill color is used to map the object to the descriptor.
- The color from descriptive objects is replaced with a pre-defined color in the interface; colors of non-descriptive objects are retained. (Colors for descriptive objects are really just used to provide the mapping between objects, descriptors and data.)
- The vectorizer converts each polygon into the following form: POLY,R,G,B,x1,y1,x2,y2,...,xn,yn where POLY is a keyword, R,G,B is the fill color of the polygon, and x1,y1,...,xn,yn are the coordinates of the shape.
Note that the vectorizer is not perfect - there do exist shapes that are not well recognized if their outline is not minimally closed. This means that a closed outline of thickness 1 is more likely to be vectorized correctly than an outline of thickness > 1. In the near future the vectorizer will be updated so that black outlines are no longer necessary, and so that shapes are better recognized altogether.
1.2 The CSV descriptor file
This file enumerates the fill color for each descriptive object and maps it to the name of the object: R,G,B,description of object. Object descriptions are used in the interface for mouse roll-overs and summary cards.
1.3 Relocation matrices (DAT file)
This file enumerates, for each time period, a square matrix that maps relocations from building X to building Y in terms of some numeric value. Given a square matrix with rows and columns, a relocation FROM building X TO building Y with some numeric value V appears in row X and column Y, i.e. matrix(X,Y) = matrix(row,col) = V denotes relocations from building X to building Y.
This file is structured as follows:
- The first line enumerates all of the descriptors' colors in the same order they appear in the matrix: COUNT,R1,G1,B1,R2,G2,B2,...,Rn,Gn,Bn, where COUNT is the total number of objects, i.e. the number of rows (and number of columns), R1,G1,B1 is the color for object in row 1 and column 1, R2,G2,B2 is the color for object in row 2 and column 2, etc.
- Each following line describes a relocation matrix for one time period in the format MM/DD/YYYY,MM/DD/YYYY,ROWS,COLS,m11,m12,...,m1n,m21,m22,...,m2n,...,mn1,mn2,...,mnn, where the first MM/DD/YYYY is this period's start date, the second MM/DD/YYYY is this period's end date, ROWS is the number of rows, COLS is the number of columns (ROWS must be equals to COLS), and m11,...,mnn is the relocation matrix merged into one line, such that matrix m = [row1, row2, ..., rowN].