Hipparchus® Tutorial
and Programmer's Guide

Internet Edition
(Corresponding to Hipparchus Release 3.4)
Last updated 2004/02/27.

by Ron V. Gilmore, Vice President and John Russell, President

Geodyssey Limited
Calgary, Alberta, Canada

© Copyright Geodyssey Limited, 1993-2004. All rights reserved, worldwide.

Table of Contents

Table of Contents | Next Chapter


About Hipparchus

Hipparchus (pronounced hip-ARK-us) was perhaps the greatest of the ancient Greek astronomer mathematicians. The inventor of latitudes and longitudes, he used these measurements to calculate distances on the surface of the Earth. As you learn more about this software product, you will soon see why we named it as we did.

About This Publication

The Tutorial, (short for Hipparchus Tutorial and Programmer's Guide), is currently presented in HTML format only, on the web at www.geodyssey.com, and as a part of all subsequent Hipparchus SDK distributions. If you are viewing this document on the web, please understand that any hyperlinks to components of the Hipparchus Library Reference Manual are resolvable only in the context of a properly licensed Hipparchus Software Development Kit (SDK).

The purpose of the Tutorial is to acquaint you with Hipparchus concepts and its programmer's facilities. We will focus on helping you with the design of application systems using the Hipparchus Libraries of functions. We will try to explain the who, what, why, how, when and where of Hipparchus. The material presented will cover the following topics:

Although this publication is not intended for everyone, we have made some effort to make the material readable by most. But its content is designed for a particular audience.

Intended Audience

This publication is intended to be used by computer application development professionals who will be working with the Hipparchus Geographic Software Tools, (or are otherwise considering it).

We occasionally make reference to graphical user interface and database management software. Readers are assumed to have some knowledge of these subjects, or have access to others that have it.

In addition, you are assumed to have a reasonable familiarity with traditional positional coordinate systems (latitude and longitude), measurement systems (imperial and metric) and certain simple mathematical terms. We will make frequent reference to these items. A glossary of terms and a list of reference reading are provided to help you bridge any gaps. An effort is made to provide popular analogies and real life examples to help

Although we may at times gloss over some of the rigor associated with the underlying mathematics of the subject matter (called computational geodesy), be assured that the software provides precise treatment. For most, this should suffice. If you have a need to understand the underlying premises and theory, we recommend that you review the cited references.

How To Use The Tutorial

The Tutorial is organized to lead you along a gradual learning curve (we hope).

The following is a reading guide to the Tutorial:

Chapter 1 introduces Hipparchus. This is a must for all readers.

Chapter 2 describes the computing platform requirements. If you plan to put Hipparchus to work immediately, study this chapter carefully. Otherwise, you might just skim it for its general content.

Chapter 3 describes the Hipparchus Library material. This chapter is for the programmer. If at this stage you are only interested in concepts, you might review only the first section or two of this chapter.

Chapter 4 gets you started using Hipparchus. This chapter is for the C or C++ language programmer. However, if you have any programming experience at all, you might benefit by a cursory glance at this chapter. Alternatively, you could flip to Appendix B and work with some of the pre-programmed sample programs provided.

Chapters 5, 6 and 7 introduce important design concepts. These chapters are a must for all application architects, regardless of their programming skills or background.

Chapter 8 describes the Hipparchus Utilities and several pre-programmed file options that are available for use by developers, (and others).

Chapter 9 addresses the role played by Hipparchus in supporting the graphical presentation of geographic data. This chapter should be read by anyone planning a graphical user interface to their application.

Chapter 10 addresses satellite orbit modeling. This chapter is for anyone planning to work with satellite data. No programming skills are required.

Chapter 11 reviews debugging techniques. This chapter is strictly for the programmer.

Chapter 12 contains information on advanced topics. This chapter is mainly for the working Hipparchus application developer.

Appendix A is a glossary of terms. If you run across an unfamiliar word or acronynm, try finding it here.

Appendix B references several of the sample applications provided.

Appendix C provides some bibliography.

Appendix D provides some facts about planet Earth.

Appendix X provides an index to this publication.

About Our Company

Geodyssey Limited is a privately-owned corporation based in Calgary. The firm is dedicated to the promulgation of Hipparchus Technology. The sole aim of the organization is the marketing, distribution and support of Hipparchus. As owner of the exclusive worldwide rights to Hipparchus, we are committed to provide our customers with quality new products and top-flight support.

To help you apply the full power of Hipparchus, Geodyssey Limited periodically offers hands-on customer training courses in major cities of the world. In addition, should you or your company require related application development assistance, we can supply experienced Hipparchus analysts and programmers to assist you directly. Hipparchus has been carefully crafted to meet most geographic application needs. Nevertheless, should your application require special treatment or enhancements, Geodyssey will be pleased to provide product extensions.


We realize that some of the concepts we have already introduced via this Tutorial may be quite new and different. This is a challenge we have attempted to overcome. We recognize that some readers will struggle with the specifics. It should be no surprise then if you discover that the Tutorial is not the kind of book that can be read lightly, such as something that you might read on a commuter plane. Absorbing the material presented will require some of your valuable time, and more particularly, will test your powers of concentration.

We encourage you to run the Windows 95/98/NT demonstration programs: (Columbus, Galileo and Georama. This will accelerate your ride up the learning curve. Do you remember when you were first introduced to the concept of "programming"? This new idea was strange at first, but at some magic moment the light went on and you have "owned" the concept ever since. Watch for similar magic moments as you make your own voyage of discovery through Hipparchus.

Enjoy this voyage. See our world on your computer screen and move about as if you were on a magic carpet floating high above the oceans and continents. Drop down to the surface and pinpoint the relative locations of all manner of things and events. Skim across the terrain with a new multi-dimensional measuring tape of amazing flexibility and accuracy. Revel in the thrill of solving problems that foiled the ancient scholars, and even some of our best contemporary minds at that.

Envision yourself building startling new computer applications with ease, speed and precision. A stunning array of powerful new tools for business, engineering, government and the mass consumer market now awaits creative developers. And there's newly garnished data to power such applications.

An ancient Chinese philosopher once said "The journey of a thousand miles begins with a single step". Take that first step now on your journey of discovery through Hipparchus. Immerse your mind in the words that follow.

Top of Preface | Next Chapter