Two libraries are supplied with Hipparchus:
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.
Return to Library Section Directory.
Return to Library Section Directory.
Return to Library Section Directory.
Return to Library Section Directory.
Return to Library Section Directory.
Return to Library Section Directory.
Return to Library Section Directory.
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.
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.
All functions in this section are re-entrant. Return to Library Section Directory.
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.
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.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.
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).
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.
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.
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).
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.
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.
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.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:
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).
Geographics
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.
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.
Footnote
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.