Functions of the Hipparchus Libraries

(Corresponds with Release 3.40).
Last updated 2004/05/04.

Two libraries are supplied with Hipparchus:

Return to Overview.

Hipparchus Library

The Hipparchus Library consists of a comprehensive set of C language object module functions designed to enable application developers to incorporate geographical information handling into their own applications. Although written in the C language, the functions are equally accessible to C++ language developers.

Hipparchus Library functions are 100% re-entrant. This means that Hipparchus functionality can be multi-threaded, which in turn means that Hipparchus-based server applications are scalable for multi-user access without any restrictions imposed by Hipparchus.

Hipparchus Library functions communicate with their host applications entirely through C or C++ language memory structures. These are defined by four Hipparchus Library C or C++ includable header files: hipparch.h, hippvrsn.h, hipproto.h and hippengn.h. These headers also define function prototypes, useful macros and manifest constants.

There are no I/O bindings of any kind: console, file or database. This leaves the application developer entirely free to combine Hipparchus functionality with data from any external source. Having said that, the Hipparchus spatial index used internally provides an excellent basis for a spatial index for external data.

Similarly, there are no bindings with any graphical user interface (GUI). This again leaves the application developer free to set Hipparchus functionality into the context of the GUI of his choice. However, Hipparchus Library functions provide the computational means to transform efficiently between several geographical coordinate systems and the plane of a display (map), in both directions. (Functions of the Hipparchus Auxiliary Library further transform these planar coordinates to or from pixel coordinates).

Hipparchus Library functions communicate with no operating system services other than a heap memory manager. Hipparchus function calls for heap memory management are made via two pass-through functions: h1_Malloc and h1_Free (see below). These functions in turn call the C or C++ run-time library functions malloc and free. As a consequence of this design, the developer is free to substitute more effective memory management functions, if required.

To reduce the possibly deleterious effects of repeated allocation and de-allocation of small blocks of memory, some of the Hipparchus Library functions allocate and de-allocate from a stack-like structure allocated initially from the system heap. This structure is shareable with other functions in the application.

Hipparchus Library functions are divided into seven sections numbered 1 to 7. The naming convention employs the letter h and one of the numerals 1 to 7 as the first two characters of each function name. For historical reasons each function has two names: a longer descriptive name and a shorter six-character name. Long names are translated to short names by the ANSI C pre-compiler, as prescribed in the supplied header files.

Many of the functions that appear in the listings that follow are primitives used by higher level functions in the same or different section. Although it is unlikely that the developer will need to call any of these primitives directly, they are provided for completeness of description and as an aid in problem analysis.

Data Conversion and Cell Lists

These functions provide general facilities for the conversion of latitudes, longitudes and other angles and dates to and from Hipparchus internal formats, for the management of logical bit and byte arrays, and for the management of lists of Voronoi cell identifiers.

Return to Library Section Directory.

Plane Geometry

These functions provide for the derivation of planar items such as circles and ellipses and for the calculation of planar productions such as the intersection of line segments. Included are functions that provide affine "rubber-sheet" transforms for planar data and functions that construct and reference surface TINs (Triangular Irregular Networks).

Return to Library Section Directory.

Spherical Geometry

These functions provide facilities for the vector algebraic calculation of spherical solid geometry productions. Examples include spherical arc, chord, line segments and point-line proximity. Functions for simple projective mapping and unmapping are included.

Return to Library Section Directory.

Ellipsoidal Geometry

These functions provide facilities for quadratic ellipsoidal geometry calculations including surface distances, azimuths and conversion between a specified ellipsoid and other domains. Functions are included that call on the satellite orbit modeler and relate orbital positions to points on the planetary surface.

Return to Library Section Directory.

Classical Cartographic Projections

These functions provide UTM (Gauss-Krueger) and Lambert to ellipsoid and other mapping/unmapping operations. (Note that either UTM or Lambert is the basis of the "state plane" systems used in the USA).

Return to Library Section Directory.

Cell Structures and Local Coordinates

These functions provide facilities to construct, verify, maintain and navigate Voronoi cell structures. Other functions provide for conversion between global and local differentially-encoded coordinates and for the management of stack-like Hipparchus workspaces.

Return to Library Section Directory.

Spatial Objects and Operators

These functions provide facilities to construct, verify, manipulate and relate terrestrial objects (point sets, line sets, regions and surfaces). The higher-level functions permit new objects to be derived from others as a function of their spatial relationships. Other functions set the stage for the efficient export and import of objects from external storage.

Return to Library Section Directory.

Hipparchus Auxiliary Library

Hipparchus Auxiliary Library functions are also 100% re-entrant. This means that the Hipparchus Libraries functionality can be multi-threaded. This in turn means that Hipparchus-based server applications are scalable without any restrictions imposed by their use.

These functions have only descriptive (long) names, prefixed h8, h9 and h0.

Since these functions are supplied in source, they may be freely modified as required to perform satisfactorly in specific graphics or file I/O environments other than those demonstrated in Columbus, Galileo, Georama and the Hipparchus Utilities.

Function prototypes, structures and manifest constants relevant to the Hipparchus Auxiliary Library are defined by the header files hippttys.h, hippdbse.h, hippmmpf.h, hippdraw.h, hippguis.h and h0cryp.h.

File Options

These functions provide very basic, yet quite possibly adequate, external storage access facilities for Hipparchus-related data structures. They may apply if one or other of the following conditions exist:
  1. there is a very high volume of static geographic objects and/or vector coordinate data, and:

    • run-time C/C++ stream I/O and binary search facilities are available and
    • a formal DBMS has not been mandated.

    Several functions provide direct access to stream I/O files constructed according to the Hipparchus PLR schema, being collections of points, lines, regions or global surfaces (which are normally constructed using an appropriate Hipparchus utility).

  2. very large individual objects are to be created and accessed and

    • run-time memory-mapped file access facilities are available and
    • an object is to be searched rigorously for proximate elements, or
    • a large and complex object is to be intersected with a smaller region, (such as an "area of interest" polygon).

Several functions facilitate the run-time setup and closure of memory-mapped file access to Hipparchus Binary Objects (HBO's) and other files. This permits Hipparchus functions in general to access and manipulate Hipparchus binary objects via the facilities of the operating system's virtual memory manager, eliminating the overhead of first copying those objects into real (or virtual) memory. Hipparchus binary objects may be created on-line by the application or off-line via the appropriate Hipparchus utility.

All functions in this section are re-entrant. As such they may be used freely in the construction of scalable multi-threaded server applications.

Return to Library Section Directory.


These functions provide support for the rendering of terrestrial objects, surfaces and satellite orbits as well as latitude-longitude reference grids, horizons and Voronoi cell structures. Renderings can be displayed or plotted in any of the gnonomic, stereographic, orthographic, local or world-wide Mercator, Lambert-like or Miller-like projections. These functions are designed for cross-platform GUI integration and assume only the availability of the minimal primitives: move-to, set-pixel, line-to and fill-convex-polygon.

All functions in this section are re-entrant.

Return to Library Section Directory.

Utility User Interfaces

These functions provide user-oriented data conversion and interface facilities. They are supplied in source and may be freely modified as required. Note that in addition to platform-specific screen and hardcopy graphics, support is provided for hardcopy output on HP-GL/2 capable plotters and laser printers. This can be used as a model for other dedicated graphical output sub-systems.

If you are developing for DOS-level systems, please note that another sub-set of h0 functions is provided, in source, "as is", in the GRAB_BAG. These are DOS-level console and graphics routines that we have used beneficially in the past for applications having limited hardware resources.

Return to Library Section Directory.


If you have found the foregoing somewhat daunting, you might consider browsing the Hipparchus Galileo Guide in which the higher-level macros of Galileo suggest the power and versatility of the Hipparchus Libraries.

Return to Table of Contents.