TGLOBE

Module: TGLOBE Delphi Component

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

Author: Graham Knight

Web Page: http://www3.mistral.co.uk/helmstone/tglobe

Version: 1.00

Date: July 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 is a shareware component, the source is available on registration.

See the end of this document for registration details.

Any requests for clarification, comments or suggestions welcome.

Please check the Web site http:// www3.mistral.co.uk/helmstone/tglobe for the latest version of the component and demo program.

Contents

Version Control

Important Information

Installation Informtion

TGlobe Component

TGlobe Class

TGlobe Published properties

TGlobeOverlay Class

TGlobeObject Class

TGlobeAttribute Class

Known Problems

Future Plans

Licensing Information

Registration Information

Order Form

Version Control

1.00
Introduced Overlays
Improved performance
0.94
Added MaxTextHeight property to restrict the displayed text height
Added the ObjectByTitle method to find an object using its title.
Sorted out the Delphi 3 package, now the delphi 3 version is called Globe3.dcu.
I have removed the Globe.DPL package as it is not really necessary for D3.
Some optimisations in the painting routines.
0.93

Important Information

The TGLOBE component must be installed before compiling and running the Demo application. If you do not install the component you will receive errors when you try to compile and run the Demo application.

Component Installation.

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

globe32.dcu

globe32.dcr

and the Delphi 3 IDE :

globe3.dcu

globe3.dcr

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 Component from Delphi's menu.

Click the Browse button and locate the globe3.dcu file.

Select the full drive and directory name path to the globe.dcu and click

the open button.

TGLOBE Component

For TGLOBE the following are defined:


	EarthRadius = 3437.7; { in minutes of a degree or nautical miles }
	MAXPOINTS = 10000; { Maximum number of points in an object }
	MAXOVERLAYS = 10; { maximum number of overlays on the globe }
	MAXLAYERS = 255; { maximum number of layers on the 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.

The component can contain a number of overlays. Each Overlay holds a single Globe datafile. Globe datafiles can be divided into layers.

TGLOBE Class

property Bitmap;

Captures a Bitmap of the current screen display. This will not include any graphics drawn during the OnPaint event.

property Canvas;

Canvas that can be used to place data on the globe during the OnPaint event

procedure Clear;

Clears the Globe database of all data and objects. All Overlays are cleared.

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 LineLLtoLL( ptFromLL, ptToLL : TPoint );

Connects the 2 points with a line drawn on the surface of the globe. The points are specified in minutes.

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;

Converts a Longitude, Latitude point in minutes to a string representation.

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 LocateObject( Obj : TGlobeObject );

Adjusts the Xrotation and Yrotation of the globe to bring the supplied object into the viewing area.

function ObjectAtDeviceXY( iX, iY : 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 ObjectAtLL( Long, Lat : integer ) : TGlobeObject;

Returns the object located at the coordinates supplied, if no object found then nil is returned. This will search all enabled Overlays for an object at the location.

function ObjectByTitle( const sTitle : string; ObjStart : TGlobeObject ) : TGlobeObject;

Finds an object in the object list which has a matching Title. the ObjStart parameter specifies where in the list the search will start from. If the ObjStart parameter is nil then the search will start from the beginning of the list, if an object is supplied then the search will start from the next object in the list. If no object is found then nil is returned. The returned object can be passed to LocateObject to rotate the globe. This will search all enabled Overlays for an object with the supplied title.

property Overlays[Index : LongInt];

You can load from 0 to MAXOVERLAYS Globe datafiles, these will be displayed one over the other with overlay 0 being displayed first. Each overlay is independent of any other overlay.

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.

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;

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( 0,0,0,0 );
TGLOBE Published

property DetailLevel : integer;

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;

This is the path and filename of a TGLOBE database file. The file will be loaded into Overlay 0.

property LatitudeStep;

property LongitudeStep;

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 MinTextHeight;

This controls the minimum size of text. If the scaled text is small than this value then it is not displayed. If the value is set to 0 then the text will always be displayed.

property MouseZoomButton;

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 OnPaint : TNotifyEvent;

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.

TGLOBEOverlay Class

XRotation, YRotation : integer; { Associated default X and Y rotations }

procedure Clear;

Clears all of the Objects and Attributes from the Overlay.

function AddAttribute( oAttr : TGlobeAttribute ) : TGlobeAttribute;

Adds the Attribute object created by calling TGLobeAttribute.CreateAttribute, to the list of attributes associated with the Overlay. If the attribute object has already been defined then the existing attribute object is returned.

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 Overlay database. 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, iSize : integer ) : TGlobeObject;

Long, Lat = Location for text

STitle = Text to display

ILayer = Layer within this overlay to display text on

ISize = Maximum size the text will scale to.

This will add a text string to the Globe datafile, The text will appear at the specified Longitude and latitude. As the Globe is zoomed the text is automatically scaled

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

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

function ObjectAtLL( Long, Lat : integer ) : TGlobeObject;

Returns the object located at the coordinates supplied, if no object found then nil is returned.

function ObjectByTitle( const sTitle : string; ObjStart : TGlobeObject ) : TGlobeObject;

procedure SaveToFile( const sFileName : string );

Stores the Overlay database of attributes and objects to the file specified. If the file exists it will be overwritten.

procedure LoadFromFile( const sFileName : string );

Loads the Overlay with the data from the supplied file.

property Objects[Index : LongInt];

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

property Attributes[Index : LongInt];

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

property LayerEnabled[Index : integer];

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 Index : integer;

This is the Index number of the Overlay in the range 0 to MAXOVERLAYS.

property Enabled : Boolean;

If set to False then any object on this overlay will only be displayed they will not be located by the ObjectAtLL method.

property ObjectCount : LongInt;

Holds the total number of Objects in the Overlay database. (read only)

property AttributeCount : LongInt;

Holds the total number of Attributes in the Overlay database. (read only)

property Filename : string;

TGLOBEObject class

Properties

Title : string[32];

Associated title of the object.

Origin : TPoint;

Origin of the start of the object. If this is modified to then the object will move across the face of the globe.

Attributes : TGlobeAttribute;

The associated attribute object.

Kind : Byte read FObjType;

This holds the type of the object, 0 = Polygon, 1 = Polyline, 2 = text, 3 = Point text.

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)

property OverlayIndex : integer;

Index of the Overlay that this object belongs to.

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)

Constructor CreateAttribute( BColour : TColor; BStyle : TBrushStyle; PColour : TColor; PStyle : TPenSTyle );

BColour = Brush Colour

BStyle = Brush Style

PColour = Pen Colour

PStyle = Pen Style

This creates an attribute object which can be added to the Globe database using the AddAttribute method of the Overlays property.

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.

Known Problems

Sparse Documentation...

Mercator projection has problems with zooming and scrolling at times.

Future Plans

List of current plans, not in any specific order.

Fix known bugs.

More globe objects, e.g. points, squares, circles.

User defined globe objects.

Dynamic objects - will allow interactive moving objects on the globe.

Earth day / night line or shadow.

Texture mapped data.

Write Help file.

Licensing Information

TGlobe is Shareware.

The Shareware version of TGlobe can be used for evaluation and non-commercial 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.

TGlobe is free for non-commercial or educational use.

No royalties or run-time fees are applicable.

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

If it is not possible to raise a cheque in Sterling then please add the equivalent of £5 Sterling to the registration fee before sending the cheque in your currency. This is because my bank will charge me a flat fee of £5 to convert the foreign check to Sterling on top of the exchange rate.

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

Globe 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).

All mail should be addressed to:

Graham Knight

54 Matlock Road

Brighton

Sussex BN1 5BF

England

End of TGLOBE.HTM