created August 12, 2004 by addie m. beseda


GEO3D PROGRAMMERS' README FILE

This file is intended to give current and future programmers of Geo3D an overview of the inner
mechanics of the project without requiring coders to search around the code themselves to understand
how the program works and how all the classes / file folders are interrelated.  It should give
coders a greater level of comfort with jumping into certain portions of the project, and a greater
sense of control over the entirety of the project itself, since the scope can often be daunting.  
It should also provide a framework for future expansions and additions to Geo3D.

If you are a coder and have made significant changes to the Geo3D code, I would highly recommend
that you document the code in the appropriate section of this readme file so future programmers
can understand how it fits into the rest of the project.

If you have any additions, suggestions or corrections please email me at
abeseda@gladstone.uoregon.edu.

Last updated: August 12, 2004 by a.m.b.

Contents:
1.0 - Basic file / folder organization details
	1.1 - gui folder
	1.2 - mod folder
	1.3 - plugins folder
	1.4 - tools folder
2.0 - What Geo3D does at every load
3.0 - Globeview functionality
4.0 - Dataset handling
5.0 - Plugin architecture
6.0 - Style and documentation notes

+----------------------------------------------------------------------------------------+
	SECTION 1.0 - Basic file / folder organization details
+----------------------------------------------------------------------------------------+

	The Geo3D source code is currently located in the folder
		geo3d --> PROJ-INF --> src --> org  --> scec --> geo3d
	Within this folder, all source code has been organized into the following folders:
		gui - code in this folder is the backbone of the Geo3D user interface.
		mod - code in this folder manages datasets and catalogs.
		plugins - code in this folder belongs to plugins, which are additional functionality
			built into the Geo3D program, but not hard-coded.
		tools - code in this folder is hard-coded functionality of the Geo3D program,
			including plugin management and error handling.
	This folder also contains this readme file and the Geo3d.java file, which contains
		the main() method used to run the program.
		
	+---------------------------------------------------------------------------------+
	 	SECTION 1.1 - gui folder
	+---------------------------------------------------------------------------------+
	
	+---------------------------------------------------------------------------------+
	 	SECTION 1.2 - mod folder
	+---------------------------------------------------------------------------------+
	
	+---------------------------------------------------------------------------------+
	 	SECTION 1.3 - plugins folder
	+---------------------------------------------------------------------------------+
	
	+---------------------------------------------------------------------------------+
	 	SECTION 1.4 - tools folder
	+---------------------------------------------------------------------------------+
	


+----------------------------------------------------------------------------------------+
	SECTION 2.0 - What Geo3D does at every load
+----------------------------------------------------------------------------------------+

	Program execution begins in the source file Geo3D.java, located in the geo3d folder (see
	section 1.0).  
	
	Geo3D.java (written by SCEC EIT interns):
		1. Initializes Torque (?)
		2. Sets the GUI look-and-feel
		3. Loads all plugins using PluginHandler
		4. Initializes a MainWindow frame
		
	PluginHandler.java (written by Scott Callaghan):
		1. Creates a PluginLoader
		2. The program's plugin directory (geo3d --> PROJ-INF --> lib --> plugins) is
			searched and all .jar files in the directory are returned.
		3. Each .jar file is loaded as a class with the PluginLoader.
		
			PluginLoader.java (written by Scott Callaghan)
			1. Loads in a class from a .jar file, mostly using functionality from inherited
				URLClassLoader.
	
	MainWindow.java (written by Andrew Hart, additional work by Julia Reynolds)
		1. The base interface of Geo3D is a JDesktopPane.
		2. Menus are added to this JDesktopPane that provide access to the rest of the
			program's functionality.
		
	Once this loading has finished control of the program is passed to the user. 
	
	Choosing Display -> New View -> New View or Display -> New View -> Clone Current View
			will open a GlobeView window.  Functionality of the program - such as display of
			faults and earthquakes - is all done through the GlobeView window.
				
		
		
+-----------------------------------------------------------------------------------------+
	SECTION 3.0 - Globeview Functionality
+-----------------------------------------------------------------------------------------+

+-----------------------------------------------------------------------------------------+
	SECTION 4.0 - Dataset handling
+-----------------------------------------------------------------------------------------+

	+-------------------------------------------------------------------------------------+
		SECTION 4.1 - Earthquake catalogs
	+-------------------------------------------------------------------------------------+
	
	All earthquake catalogs brought into Geo3D are in XML format.  Users do not need to
	know XML formatting; the CatAdapter (by Derek Desens) will take any catalog of any format 
	and convert it to XML for the user.  
	
	..blah blah blah suckas..
	
+-----------------------------------------------------------------------------------------+
	SECTION 5.0 - Plugin Architecture
+-----------------------------------------------------------------------------------------+

+-----------------------------------------------------------------------------------------+
	SECTION 6.0 - Style and Documentation notes
+-----------------------------------------------------------------------------------------+
	
	First and foremost - DOCUMENT AS MUCH AS POSSIBLE! 
	
	Create a readme file in the folder you are working on, comment well, etc.
	
	Or else some foolio will pick up your project, not understand where you were going with
	it, and undo your work like some hat an old woman just knitted
	
	It will be a tragedy of the umpteenth degree
	
	ALSO - name your variables well, or ELSE
	
	
	pp