-------------------------------------------------------------------------
  Module:    TGLOBE

  Comment:   Displays an Interactive 3D Globe or mercator projection of 
             the World.

  Author:    Graham knight
  Email:     GKnight@Helmstone.co.uk
  Version:   0.93
  Date:      June 1997

 Copyright (c) 1997 Graham Knight. All rights reserved.

-------------------------------------------------------------------------


TGLOBE displays a three-dimensional globe or mercator projection of the world 
and allows you to interact with the countries and objects displayed.
The globe can be rotated and zoomed into to display a close-up of any region
of the Earth.

This component will definitely benefit from a fast Pentium machine and a fast
Video card. It was built on a P166 with 32M of Ram.

This component is still in it's early days and so I'm not releasing the source
for the unit or the format of the external datafiles until things have had a
chance to stabilise.


Any comments or suggestions welcome.


See end of this file for registration details.

============================= Version Control ============================
0.93	16 bit version withdrawn due to compatability problems, if there is
	enough interest in the 16 bit version I will look at it again.
	Modified Demo program to show realtime updating.
	Fixed Delphi 3 package.
	Add LineLLToLL method to draw lines on the surface of the Globe.
	Added LLtoDeviceXY method to convert Long/Lat coords to XY coords.
	Changed the Parameters to DeviceXYtoLL for consistancy.
	Opened up the OnPaint event.
	Added ScaleFactor property for scaling of objects.
	Fixed Clipping of Objects.

0.92	Allocates working array from heap not static data.
	Included compiled version for Delphi 3.0.
	Added Projection property.
	Added OnZoomed event.
	Added GlobeColor property.

0.91	Cleaned up the globe data file, remove a number of duplicates.
	Moved text to Layer 4 in datafile.
	Fixed Scrollbar Thumb positioning.
	Added LocateObject() method.
	Fixed bug with rendering of countries.

0.90	First public release.

========================== Important Information =========================
The TGLOBE component must be installed before compiling and running the
Demo application.  If not you will receive errors.

Component Installation.

The components for the Delphi 2 IDE comprise of the following files:

	globe32.dcu
	globe32.dcr

and the delphi 3 IDE :

	globe.dpl


Copy these files to the installation to directory of your choice then install
the components into your IDE before attempting to compile and run the Demo
program.

The rest of the files are required to build and run the Demo program.  The
GLOBE.DAT file should be placed in the same directory as the Demo program so
that is can be loaded on startup.

Installing the TGLOBE component in the Delphi 2 IDE:

To install the component:
	Select Options | Install Components from Delphi's menu.
	Click the Add button to open the Add Module dialog box.
	Click the Browse button to open the Add Module file selection dialog box.
	Select the full drive and directory name path to the globe32.dcu for 
	the Delphi 2 IDE and click the OK button.

The Globe Component installs itself onto the Samples Pallete.

To install under the Delphi 3 IDE:
	Select Component | Install Packages from Delphi's menu.
	Click the Add button to open the Open Package dialog box.
	Select the full drive and directory name path to the globe.dpl and click
	the open button. Ensure the checkbox next to the TGlobe Component Package
	is selected.


----------------
TGLOBE Component
----------------

For TGLOBE the following are defined:

	EarthRadius = 3437.7;  { in minutes of a degree or nautical miles }
	iEarthRadius = 3438;   { in minutes of a degree or nautical miles }
	MAXPOINTS = 10000;     { Maximum number of points in an object }
	MAXLAYERS = 255;       { maximum number of layers on globe }

	TSmallPoint = record   { An X,Y point using 16 bit integers }
		X,Y : SmallInt;
	end;

	{ Array of Small points used to create new objects }
	TPointLLArray = array [0..MAXPOINTS] of TSmallPoint;
	PTPointLLArray = ^TPointLLArray;

	EGlobeException = class(Exception);  { exception raised by the Globe object }


Longitude and Latitude are defined as minutes of a degree, this allows
reasonable accuracy i.e. a point on the globe can be specified to an accuracy
of one nautical mile and all points on the globe can fit within a 16 bit
integer value.

Longitude can range between -180 degrees to +180 degrees therefore the range
of values for Longitude is from -10800 to +10800.

Latitude can range between -90 degrees to +90 degrees therefore the range of
values for Latitude is from -5400 to +5400.



------------
TGLOBE Class
------------

	Publics
	-------

	function DecimalToLLPoint( DecimalLong, DecimalLat : Extended ) : TPoint;

		This method converts from the decimal Longitude, Latitude values to a
		Longitude, Latitude point that is used in the Globe datafile, e.g.

		The decimal Longitude and Latitude of London England is :

			Long  = 0.0    degrees
			Lat   = 51.51  degrees
			This will be converted to the point  ( 0, 3091 ).


	function DeviceXYToLL( iX, iY : integer; var ptLL : TPoint ) : Boolean;

		Converts the X, Y device coordinates to a Longitude, Latitude point on
		the surface of the Globe.  If the X, Y coordinates are are on the surface
		of the globe then True is returned otherwise ptLL is set to (10800, 10800)
		and False is returned.


	procedure LLPointAsDecimal( APoint : TPoint; var Long, Lat : Extended );

		This method converts the Longitude, Latitude point used in the globe
		datafile to it's Extended representation. ( See above )


	function LLPointAsString( APoint : TPoint ) : string;

		This method converts a Globe datafile Longitude, Latitude point to its
		string representation.  The string displays the point in degrees, minutes
		relative to the equator and the Greenwich meridian, e.g.

			London is located at : '00.00E 51.51N'


	function ObjectAtDeviceXY( X, Y : integer ) : TGLOBEObject;

		Converts the screen X, Y coordinates to Globe coordinates and returns the
		object found at that location, or nil if none found.  The X, Y coordinates
		of the Mouse events can be passed directly into this method to retrieve the
		object located under the mouse cursor.


	function AddAttribute( BColour : TColor; BStyle : TBrushStyle;
		PColour : TColor; PStyle : TPenSTyle ) : integer;

		BColour  =  Brush Colour
		BStyle   =  Brush Style
		PColour  =  Pen Colour
		PStyle   =  Pen Style
		Returns the ID of the Attribute set added.

		This adds an attribute object to the datafile.  If the attribute set has
		already  been defined then the existing attribute set ID is returned;
		The attributes are used in the definition of the Globe objects, these
		attributes define the colours used to display the globe objects.  The
		brush colour and style are used to fill the object and the pen colour
		and style are used to  outline the objects.


	function AddObject( const sTitle : string; cType : Byte;
		iLayer, iAttribute : integer; PointCount : LongInt;
		const PointArray : PTPointLLArray ) : TGLOBEObject;

		sTitle      =  Title that is associated with the object ( max 32 chars )
		cType       =  Type of object. 0 = Filled Polygon, 1 = Polyline object
		iLayer      =  0 - MAXLAYER. Layer 0 is painted first, Layer 255 last.
		iAttribute  = Attribute ID returned from AddAttribute.
		PointCount  = Count of the number of points in the object;
		PointArray  = pointer to an array holding the points.
		Returns the object added.

		Adds a new object to the Globe datafile.  The new object can have a type
		of either 0 to 1.  Type 0 objects are filled polygons e.g. countries and
		type 1 objects are polyline objects e.g. rivers.
		The pointarray is an array of TSmallPoint objects specifying the vertices of
		the object, the points should be arranged so that the points can be drawn
		consecutively either clockwise or anticlockwise.


	function AddText( Long, Lat : integer; const sTitle : string;
		iLayer : integer ) : TGLOBEObject;

		This will add a text string to the Globe datafile, The text will appear
		at the specified Longitude and latitude.


	function AddPointText( Long, Lat : integer; const sTitle : string;
		iLayer : integer ) : TGLOBEObject;

		This will add a text string with a small circle at the specified
		Longitude and latitude.


	procedure Clear;

		Clears the current globe datafile from memory.


	function LLToDeviceXY( iLong, iLat : integer; var ptXY : TPoint ) : Boolean;

		Converts the iLongitude / iLatitude coords to a device XY coordinate.  
		The boolean return if True indicates that the point is visible, if False
		then the point lies on the far side of the globe.
		

	procedure LoadGlobeFromFile( const sFileName : string );

		Loads the Globe datafile from an external file.


	procedure LocateObject( Obj : TGlobeObject );

		Rotates the globe so that the supplied object is positioned in or near
		the centre of the viewing window.


	procedure PanViewRect( iX, iY : integer );

		Scrolls the current view of the globe to the left, right, up or down by
		iX and iY nautical miles.


	procedure SaveGlobeToFile( const sFilename : string );

		Saves the current datafile to an external file. If the file already
		exists it will be overwritten.


	property AttributeCount : Integer;

		Holds the total number of Attribute in the Globe datafile. (read only)


	property Attributes[Index : LongInt] : TGLOBEAttribute;

		This allows access to all attribute sets in the Globe datafile.
		Index is in the  range 0 .. AttributeCount - 1.


	property LayerEnabled[Index : integer] : Boolean;

		Array of boolean flags that control the display of the datafile layers.
		If the flag is set to True then the Layer will be displayed.


	property ObjectCount : LongInt;

		Holds the total number of objects in the Globe datafile. (read only)


	property Objects[Index : LongInt] : TGLOBEObject;

		This allows access to all objects in the Globe datafile.
		Index is in the range 0 .. ObjectCount - 1.


	property ScaleFactor : Extended;

		This property is the value used to scale all objects on the globe.
		1/ScaleFactor is the number of logical lat/long points that fit inside a
		single device pixel.  An object that is say 100 logical points long can be
		scaled by multiplying by the ScaleFactor, the result gives the proportional
		length of the object relative to the globe. (read only)


	property SelectedObject : TGLOBEObject;

		Points to the currently selected object or nil if no object is selected.
		The Selected object is set by the User to any object on the Globe.  When
		the Globe is subsequently painted the selected object is highlighted in red.


	property ViewRect : TRect read FViewRect write SetViewRect;

		This defines the size of the view of the globe that is displayed.
		This rectangle is specified in nautical miles.  The rectangle is used
		to zoom into or out of the Globe.  To display the whole of the Globe set
		this rectangle to :

		Globe.ViewRect := Rect( -iEarthRadius, -iEarthRadius, EarthRadius, EarthRadius );

		The constant iEarthRadius is defined in the TGLOBE unit and is an integer version
		of the Extended EarthRadius value.



	Published Properties
	--------------------

	property DetailLevel : integer;

		The detail level partially controls the amount of detail that is displayed, this
		should be set to a value from 1 to 15, the lower the value the greater the amount
		detail of detail that will be displayed.
		Increasing this value will speed up the display of the Globe.
		As you zoom into the globe this value is automatically adjusted so that the detail
		will increase the closer you are to the surface of the globe.


	property DrawGrid : TDrawGrid;

		This can be set to either dgNone, dgBehind or dgInFront this will allow
		the grid to be switched off, or displayed behind or infront of the
		country objects.


	property GlobeColor : TColor;

		Sets the base colour of the Globe area for the control.  The Color property
		controls the components background colour.


	property GlobeFile : string;

		This is the path and filename of a TGLOBE datafile.  If this is set to a
		blank filename then the globe will be cleared.


	property LatitudeStep : integer;
	property LongitudeStep : integer;

		These properties control the spacing of the globe's grid lines, the
		values are in degrees and set relative to the equator and the Greenwich
		meridian.
		Setting the longitude step to 15 will display a grid line for every hour
		difference from GMT.
		If either property is set to zero then the grid will not be displayed.


	property MouseZoomButton : TMouseZoomButton;

		This can be set to mzbLeft, mzbRight, mzbMiddle or mzbNone.  By setting
		this to one of the mouse buttons an automatic zoom facility is enabled.
		If it is set to mzbRight then by pressing and holding the right mouse
		button a window can be drawn on the globe, when the mouse button is
		released the globe will expand to display the selected area of the globe.


	property OnViewChanged : TNotifyEvent;

		This event occurs when the globe is zoomed or panned.


	property OnZoomed : TNotifyEvent;

		This event occurs when the globe is zoomed.


	property Projection : TGlobeProjection;

		This can be set to gpSpherical or gpMercator.  If set to gpSpherical then a 3D
		Globe is displayed that can be zoomed or rotated.  If gpMercator is set then the
		World is displayed as a 2 dimensional map, the X and Y Rotation properties have
		no effect when gpMercator is set.


	property ScrollBars : TScrollStyle;

		This property controls the display of the horizontal or vertical scroll
		bars for the TGLOBE window.

	property XRotation : integer;
	property YRotation : integer;

		These set the amount that the globe is rotated about the X and Y axes.

		The axes are orientated in the standard way with the Y axes going from the
		bottom to the top and the X-axes going from then left to right of the screen.


-------------------
TGLOBEObject class
-------------------

	Properties
	----------
	Title : string[32];
		Associated title of the object.

	Origin : TPoint;
		Origin of the start of the object. (read only)

	AttributeIndex : SmallInt;
		Index of the associated attribute object.

	Layer : Byte;
		The layer that the object is displayed on.

	Count : integer;
		Number of points in the object. (read only)

	PointLLArray : PTPointLLArray;
		Array of points defining the object. (read only)

	Index : Longint;
		Index number of object on Object List. (read only)


	Methods
	-------

	procedure Delete;

		Method to delete the object from the datafile.


---------------------
TGLOBEAttribute class
---------------------

	Properties
	----------
		BrushColour : TColor;
		BrushStyle : TBrushStyle;
			Colour and style of filled Polygons object.

		PenColour : TColor;
		PenStyle : TPenSTyle;
			Colour and style used to outline object.

		Index : integer;
			Index number of attribute object in Attribute list. (read only)


Known Problems
--------------

	Interface with the component is simplistic and incomplete at present this will
	be opened up with later versions.

	The format of the datafile has not been published as this may be required to
	change.

	Sparse Documentation...

	Mercator projection has problems with zooming at times.


Future Plans
------------

	Fix other known bugs.
	Use Fixed point math for performance.
	Write Help file.
	Add Bitmap capture facility.


Licencing Information
---------------------

TGlobe is ShareWare.  It can be used for evaluation purposes only.

No profit through commercial redistribution of this package either in part 
or whole shall be gained. This package may be included as part of a component
group package providing that no charge is made for the package itself!

The registered version of TGlobe can be used, royalty free, in any way not 
in competition with TGlobe, as described above. But cannot be redistributed
in part or whole.


Registration Details
--------------------

TGlobe is a Shareware product.
No royalties or run-time fees are aplicable.

	
This is still really a beta version but people are requesting the source code 
so I have decided to make this available for a small charge.

If you register thi beta release I will send you update and the production 
release of the component for no charge when it is ready.

Sorry about the limited method of payment but I am looking into this.


Please send this order form to me with a cheque for the correct amount in
Sterling preferably drawn on a British bank.

On receipt I will send the component and source by email or snail mail if
requested.

******************      TGlobe 0.93 ORDER FORM          *******************
---------------------------------------------------------------------------

Name:

Company:                                Position (optional):

Address:				City:

State:					Country:	    Zip:

Tel:					Fax:

Email Address (very important):

----------------------------------------------------------------------------

Amount:		 50  Sterling.

Please add 2.50 Sterling if you want to receive a floppy by snail-mail 
(shipping and handling).


End of TGLOBE.TXT.

