Hipparchus Utilities Guide

By John Russell, President
Geodyssey Limited, Calgary

Version 3.40, May, 2004.
As may be seen within www.geodyssey.com.

Tested with Internet Explorer 5, Opera 4 and Mozilla 1.4.
Last updated 2004/05/05.

Information in this document is subject to change without notice.
Hipparchus® is a registered trademark of Geodyssey Limited.
© Copyright 1992-2004 by Geodyssey Limited.
All rights reserved, worldwide.

Table of Contents

As an aid to the preparation of data for a Hipparchus-based application, a suite of Hipparchus-based cross-platform command-line utility programs is provided.

Here are some general comments.

The Utilities divide into six categories:

  1. generate and modify Voronoi cell index structures

  2. transcribe lat/long or concise direction cosine coordinates between ASCII text and packed binary formats

  3. modify and/or check data structures

  4. construct Hipparchus Binary Object (HBO) files

  5. construct static point. line or region data collections (PLR) files

  6. transcribe or generate GPS NMEA sentences.

Here's an alphabetic index of the Utilities.


The Hipparchus Utilities are batch programs written in ANSI C and distributed in source. For maximum portability, they employ a simple console interface implemented using only the stdin, stdout and stderr facilities of the C language run-time library. Run-time file I/O is restricted to the stream I/O facilities of C/C++.

Because many of the Utilities write or read binary data elements or structures, it is essential that the Utilities be compiled and run in the target computing environment of the application they support. Otherwise, differences in machine architecture and compiled structures may render the results unuseable.

Most of the Utilities call functions of the Hipparchus Auxiliary Library and the Hipparchus Library proper. Before attempting to compile the Utilities, the developer should first compile and build a local Hipparchus Auxiliary Library for the target application platform and verify the availability of the Hipparchus Library binaries for that platform.

Executable copies of the utilities will normally be invoked from a system console, but note that they may also be invoked from Galileo via the Shell command.

Command-line Interface

The Utilities share a common command-line interface. Their command line takes this form:

  utility-name [options] in-file-name [out-file-name] [options]


At run time, Utilities report their usage in response to a command line specifying no parameters or one specifying the help option ("/h" or "/?").

Voronoi Cell Index Generation and Modification

These Utilities all have to do with the generation and modification of Voronoi cell structures for use as spatial indexes within the Hipparchus-based application. Although the application can construct such an index on the fly, most will employ an index built off-line, using one or more of these utilies:

Coordinate Transcription

This Utility provide for the transcription of point or vertex latitude-longitude coordinates between ASCII and packed binary formats. Although most coordinate data will originate in the ASCII format, high volume vector coordinates often can be more efficiently archived or reprocessed in packed binary format. Many of the other Hipparchus Utilities accept coordinates in either format.

Modify and/or Check Data Structures

These Utilities provide for the elimination of duplicate or otherwise unneccessary coordinates within data structures.

Convert Coordinate Data To Hipparchus Binary Objects

Objects constructed in the context of a particular Voronoi cell structure have a precise canonical form in memory, which form is defined by the constructor functions of the Hipparchus Library, namely h7_GlobalToPset, h7_GlobalToLset and h7_GlobalToRset. All elements of an object's canonical form are binary values of type integer, float or double. Owing to differing machine architectures, such internal objects clearly are not directly cross-platform portable.

Some operating systems (such as Windows 95/98/2000/XP/NT and many Unix systems) support memory-mapped file access via their virtual memory manager. Within such systems an external file that represents a Hipparchus internal object is known as a Hipparchus Binary Object (HBO). Such objects may be opened and closed using functions of section h8 of the Hipparchus Auxiliary Library. Once open, an HBO may be accessed by a program just as if it were memory resident. Any operation permissible in Hipparchus for a memory object may be carried out on an HBO, via buffers managed by the operating systems's virtual memory manager. It is not required that such objects first be fetched into real memory. Therefore, operations on Hipparchus Binary Objects are not restricted by real memory constraints, and otherwise complex operations such as region intersections may be carried out very efficiently.

An application can generate HBO's on the fly (see Galileo). Another alternative is to generate them off-line using Hipparchus Utilities. Three programs are provided for this purpose:

Convert Coordinate Data To Hipparchus PLR Collection Files

While an HBO is an external file representation of a single Hipparchus internal object, there exists a demonstrated need for an external collection of such objects. Such collections may be managed by an application using the facilities of a formal database manager (DBMS).

Recognizing that the preponderance of such data is unchanging (static), and to demonstrate the value of the Voronoi tessellation as an efficient spatial index, a simple yet effective file system is provided via functions of the Hipparchus Auxiliary Library and certain Hipparchus Utilities.

Known as Hipparchus Point-Line-Region collection files (PLR's), simple stream I/O files constructed according to the Hipparchus PLR schema may be accessed efficiently by the Hipparchus-based application to retrieve application coordinate data in a form immediately useable by the application. PLR collections are indexed primarily by the identifiers of the Voronoi cells that contain (own) the collection's member points or vertices. For line or region collections, secondary indexing is provided by line or region identifier. Construction of a PLR collection is always carried out in the context of an application-specific Voronoi index.

A PLR collection is created using one of these Hipparchus Utilities:

GPS Support

Several Utilities support the capture or real-time simulation of GPS receiver interface message traffic. GPS ASCII interface messages (known as Natianal Marine Electronics Association (NMEA) sentences) may be captured and converted to ASCII lat/long line sets or may be generated for subsequent transmission between computers, simulating real-time GPS reception.

Two utilities are provided. They are:


Hipparchus provides a portable set of batch programs for off-line application support. These are supplied in ANSI C language source and are largely self-documented. They employ a simple console user interface and stream I/O only. They easily may be modified to pre-process application data existing in proprietary formats.


bldptin | cellbld | cellcat | celldns | cellins | cellord | cellpts | cellwvs | cluster | convert | dumphbo | dumpplr | duplpts | gnrlize | gtr2lns | hbo2cdc | lns2hbo | lns2plr | namendx | nmeagen | plrdat2 | pts2hbo | pts2plr | rptarea | rgn2hbo | rgn2plr | ringchk | vix2tix | vixcrpt.