Web-based Visualization - Homework 3

Alain Ledon <alain.ledon@db.com>
Alex Gleyzer <alex@boylesoftware.com>
Jayasree Tangirala <jsreet@hotmail.com>
Kirill Karpelson <Kirill.Karpelson@morganstanley.com>


1. BASIC OBJECTS

Baisic objects include;

	Point2 - 2d point
	Line - collection of points 
	LineList - collection of lines
	Box - basic rectangle class with methods like 
		contains(Box&) - returns true if this box contains the
		parameter
		intersection(float dx, float dy) - returns list of boxes
		that will be created if this box was intersected with
		translated itself - used in finding invalid regions
	State - line list and two points representing min and max coordinates
	Country - is a state that is a collection of states



2. COUNTRY & STATE

Since our input data is broken in files by state, we can load not the
entire country but only selected states. Internally we're still
loading the states individually then adding them into country object
which will adjust its min and max points. Country also keeps list of
state objects.


		
3. LINEFINDER CLASS HIERARCHY 

To simplify development, LineFinder class hierarchy is
used. LineFinder itself is an abstract class that defines two abstract
methods:
	Box getBoundaries();	// returns box represening min and max
			 	// points of the country
	
	LineList *findLines(Box&);	// returns list of lines that are
					// cross parameter box

This is all that OpenGL display code needs to display the
country. Then we have multiple implementations of line finder:

SimpleLineFinder - implements a very naive line-searching algorithm -
linearly going through all lines and checking their points. This was
implemented so we could proceed with development of other pieces of
code using LineFinders.

SmartLineFinder - is supposed to implement some better algorithm with
a special data structure. This part is not implemented yet. 

NetworkLineFinder - is a networked implementation that will talk to
the server to get boundaries and lines, while the server can use
another type line (preferrably SmartLineFinder) finder to execute the
queries.

CachedLineFinder - is an implementation which acts as a caching proxy
to another LineFinder. It keeps a cache of recent results of line
queries, so if a request comes that can be satisfied by the data in
cache, it will return it, otherwise it will call the "real"
LineFinder, and store its results in cache. 



4. PIXMAP 

Pixmap drawing is implemented by classes in Pixmap.h, which are pretty
much the same as the ones given in the pixmap examples, with some
misc. cleanup.



5. NETWORK PROTOCOL

Network protocol is accomplished by sending data in ascii format. This
way it can be easily debugged. The server supports two kind of
requests, which correspond to two methods in LineFinder:

	BOX - returns min and max points for the whole country

	LINES - returns all lines which are within given min and max
	points, the result is returned as ascii lines one geometrical
	line per one text line, similarly to the input files.
	

6. PROBLEMS

a. Caching algorithm is not very good. b. The networked version seems
   to choke when all 50 states + territories are loadded, however it
   seems to work ok on a selection of east coast states.

b. When drawing invalid polygons next to translated pixmap buffer,
   sometimes weird side-effects show up - gray seam lines, or when the
   lines are re-drawn they don't exactly match their parts that were
   stored in the pixmap buffer.

c. We're still missing smart orthogonal query algorithm.

d. It appears that there are some issues with network protocol on
   cygwin, on linux it works fine.



7. COMPILATION 

   To compile standalone version:

   make standalone

   To compile networked version:

   make client server



8. EXECUTION
  
   To execute standalone version, run it passing names of the data
   files as parameters. 

   To load NJ only:

   ./standalone ./data/NJChains.txt 
   
   To load all files:	

   ./standalone ./data/*

   To run the networked version, you need to start the server first,
   specifying port number as first argument:

   ./server 8080 ./data/NJChains.txt

   And then start client, passing hostname and port number of the server:

   ./client localhost 8080

   A shell script "run" can be used to start both client and server
   with some east-coast states, loading entire US map seems to break
   the network protocol.

