A revised copy of this document is part of the 64-bit Galileo/Georama download package.
Information in this document is subject to change without notice.
Hipparchus® is a registered trademark of Geodyssey Limited.
©
Copyright 1992-2007 by Geodyssey Limited. All rights reserved, worldwide.
This publication describes how you can use the Galileo programs in your Windows computing environment.
The Hipparchus Galileo Guide is intended to be a companion to the Hipparchus Tutorial publication and is designed for use by computer application programmers and architects. It is intended to help such people to understand the scope and power of the Hipparchus geographic software development tools. It does not require specific programming skills. However, some dexterity with the operation of personal computers in the DOS and Windows operating environments is required.
If you are unfamiliar with the concepts and facilities of Hipparchus, we recommend that you now invest a few minutes to view the on-line Hipparchus Overview.
Galileo implements most of the functionality of the Hipparchus Libraries. Geographic objects may be entered or imported, manipulated using the comprehensive spatial calculus, then displayed, plotted or exported for use elsewhere. Application developers, GIS instructors and students will find the interactive functionality ideal for the exploration of GIS fundamentals.
Galileo can be used to advantage by programmers in developing prototypes of end-use applications. Customer-specific spatial data can be introduced and manipulated to produce results representative of those planned for a finished application. Occasionally, an end-use application can be implemented using components of Galileo alone.
The Hipparchus Galileo Guide and its sister publications, the Hipparchus Utilities Guide, the Hipparchus Georama for Windows Guide and the Hipparchus Tutorial are components of every Hipparchus Software Development Kit (SDK) distribution.
This Hipparchus Galileo Guide is the definitive reference describing the operation of the Galileo program.
If you have not alreay done so, you may want now to download the free Galileo for Windows executables and data offered at the Geodyssey website.
Please scan this Hipparchus Galileo Guide before attempting to use the Galileo programs.
To run the supplied Galileo programs in your computing environment, you will require:
Galileo is normally copied (unzipped) to a fixed disk in your computing environment.
If you have downloaded Galileo from the Geodyssey web site, then you will have received a file named "galileo_basic.exe", a self-extracting zipped archive. Installation instructions will have been presented in the web pages inviting the download.
Following installation, you should see two small text files (readme.txt and license.txt) and four sub-directories (runw32, scripts, data and temp). runw32 contains the executables, closely-coupled configuration files and a copy of this Guide. scripts contains the demonstration scripts. data contains vector data, supplementary voronoi index files and a few bitmaps. temp is merely a place-holder for transient objects. You may find it useful to set up desktop shortcuts to galileo.exe, galileo.html and the scripts and data folders.
Now is a good time to review the supplied readme and licence text.
You can start Galileo either directly or indirectly by using any of the Windows processes available. If you drag and drop a script file onto a Galileo icon, Galileo will start up and commence operation using that script. Alternatively, you may find it advantageous to establish Galileo.exe as the opening procedure for all files of type *.gal, so that when you double-click the icon for a script file, Galileo will start up using that script.
On start up, Galileo references the initialization file galileo.gin. This is a simple ASCII text file that you can easily edit to suit your local requirements. (It is described fully in the sub-section Custom Configurations).
By default, Galileo uses command scripts and data contained in the sub-directory data. Default path and file addressing is relative to a directory which is the parent of the directory from which Galileo.exe is executed. (This will usually be a root directory named galileo containing a sub-directory named runw32). However, default path addressing is controlled entirely by the galileo.gin file. Galileo contains no file references that assume a specific directory to be "current".
There are two categories of file types manipulated by Galileo:
These are "flat" files such as scripts and other text files. They are generally cross-platform portable, barring only slight differences in line endings.
Hipparchus objects have a formal definition as ASCII files. These are point set, line set and region objects, usually identified by use of the filename extensions .pts, .lns and .rgn, respectively. Their form and content are explained in a subsequent section, Object Management.
Binary Files
These are files such as Voronoi index files *.vix , Hipparchus binary objects *.hbo, and collections of points, lines and regions *.plr. Due to compiled structure alignment and "big-endian" vs "little-endian" differences between platforms, these binary files are generally NOT cross-platform portable. They should be accessed only on the same platform on which they were created. (There are however several exceptions to this rule that are noted in subsequent sections. For example, the binary bitmap files (*.bmp, *.jpg and *.png) are generally cross-platform portable).
Three important binary file types are:
Voronoi index files are an external form of the binary internal memory structures used by Hipparchus for spatial indexing. They are usually identified by the filename extension .vix. They are described in more detail in a subsequent section, Voronoi Index Management.
Collections of points, lines and regions are external binary files containing point, line or region object vector data which may be readily accessed for search and/or display purposes. They are usually identified by the filename extension .plr.
Collections are created from ASCII point, line or region data using the supplied utilities pts2plr, lns2plr or rgn2plr, respectively. Collections are created in the context of specific Voronoi index files. Their contents are recoverable ONLY in the presence of the Voronoi index used for their creation. Collection files are NOT PROCESSABLE in the context of any other Voronoi index.
Collection files have an internal structure that provides primary access to coordinate data via a binary search of a cell index for the collection. Each file has a header, a cell-ordered cell-contents index and a vector data coordinate pool. In the case of a collection of lines, individual lines are identified and their cell-appearance fragments linked back-and-forth in the coordinate pool. In the case of a collection of regions, individual regions and their boundary rings are identified and indexed. Any line or ring crossings of cell boundaries are included as "artifact" vertices, mainly for graphical rendering purposes. Internal linkages are implemented using C/C++ run-time stream I/O file pointer values and integer offsets.
The structures within a collection are defined by the hippdbse.h header file supplied with the Hipparchus Release 3.4 Source Materials.
As with regular Hipparchus objects, a datum may be associated with each point or line or ring vertex coordinate. This datum may be parsed from the ASCII source data file, the .pts, .lns or .rgn files, either as a long unsigned integer or a float value. It is then associated directly with the coordinate pair.
Alternatively, coordinate-associated attributes can be separated from the .plr collection and deposited in a related file, usually bearing the same root filename and the extension .dat. In this case, the datum directly associated with each coordinate pair is an offset value for the related coordinate attribute (relative to the commencement of the .dat associated file). Attribute text separated into a .dat file can be further processed by the utility program namendx to produce alphabetic index files (usually bearing the extension .ndx). A binary search of one of these files can provide direct entry into its associated collection file.
Both Galileo and Georama provide access to collections of points, lines and regions as a source for the search and display of data. Georama also provides access to collection data via name indexes ("gazetteers") and mouse proximity ("inspectors").
Memory-mappable files are used to great advantage in the Windows (and other) environments. Memory-mapped files can be addressed as though present in memory, but in reality are stored externally, on hard disk. In both Galileo and Georama, they are used to represent canonical Hipparchus memory objects. They are usually identified by the filename extension .hbo, (short for "Hipparchus Binary Object").
Hipparchus objects cast as memory-mapped hbo files are limited in size only by the declared limit to the virtual memory space in the operating system. Spatial operations such as DeriveRsetCommon ("polygon overlay") can therefore be carried out on very large objects without regard to real memory constraints.
Memory-mapped hbo files are bound to the specific Voronoi index present at the time of their creation. Memory-mapped hbo files are NOT PROCESSABLE in the presence of any other Voronoi index.
Memory-mapped hbo files may be created using appropriate Galileo Import... or Derive... commands or by execution of one of the supplied stand-alone utilities, pts2hbo, lns2hbo, rgn2hbo or bldptin.
Memory-mapped HBO files may be converted to ASCII format by use of the Galileo command ExportObject.
Memory-mapped HBO files are destroyed using the EraseObject command (or any ordinary Windows file deletion procedure).
This section of the Guide describes the structure and user interface of Galileo. It is assumed that you are somewhat familiar with the general concepts of Hipparchus, as explained in the Hipparchus Overview, the Hipparchus Tutorial, or similar texts.
The Galileo programs were created specifically to illustrate some of the uses of functions available in the Hipparchus Library and the Hipparchus Auxiliary Library. They were developed using the Hipparchus Release 3.4 Development Tools for Intel microprocessors, an SDK available from Geodyssey (see Licenses).
Galileo is a programmer's geographic workbench that permits developers to enter or import and export vector data defining both surface objects and satellite orbits. Using Galileo, you can derive new objects as spatial intersections, unions or proximities and prepare screen and hard copy graphic displays of these objects in the context of latitude/longitude grids, coastlines and Voronoi cell structures.
Galileo offers the developer an interactive command-line environment in which various Hipparchus operations can be performed and viewed interactively. Graphics are displayed "on the fly", so that you can see how they work. Scripts can be prepared that automate specific sequences of these commands, as would be required for live or loop demonstrations of the prototype of an application.
By contrast, Georama is an interactive end-user viewer application that gives life to a set of Atlases, providing scenes of geographic areas of interest as well as gazetteers relating place names to maps. In Georama, graphics are prepared "behind the scenes" and presented only when complete. Georama can be extended by the end user to provide new or modified scenes of existing Atlases. Atlas authors can add new Atlases without C or C++ programming.
Galileo and Georama are provided as counterpoint examples of methods that can be used to implement Hipparchus-based applications in a windowed computing environment. They provide quite different strategies for the display of geographics. Galileo draws features directly to the display while Georama draws to a bit map, delaying presentation until each scene is complete. Also, Georama demonstrates multi-threaded commputation, permitting the simultaneous thread-safe operation of Hipparchus components.
Galileo commands are entered at the cursor in the console window. Previously entered commands are scrolled upwards within the console window.
Note: If the console window should be obscured in part or in full by another window (such as the map window), then on subsequent restoration of the console window it will NOT be refreshed. The obscured portion of previously executed (and scrolled) commands may be lost from sight. This is in contrast to the map window, in which any portions obscured by other windows will be preserved and restored when the window again comes into focus.
Galileo commands are published as mixed-case codes. However, the command processor also accepts lower-case command codes. Also, any embedded underscores within a command code are removed before interpretation.
If you are uncertain of the precise code for the command you want, you may enter the first few letters of the command, press <Tab> and then the <Tab> or <Shift-Tab> keys to scroll through all of the commands beginning with the first letters entered. The cursor is positioned to the right of the command, ready for the possible entry of additional parameters. (If you repeatedly press the <Tab> key with no first letters entered, you will see the entire repertoire of commands).
If a command is misspelled or is not yet implemented, a red error message is displayed.
Most commands require a list of space- or comma-delimited positional parameters; the list is separated from the command by at least one space. A question mark ("?") given as the first parameter of a command will often produce a short reminder list of the parameters specifiable for that command.
Positional parameters can be space or comma delimited. If a comma is to be used as a delimiter, it must immediately follow the parameter it delimits, without intervening spaces. However, any number of spaces may precede a parameter. If any parameter is to contain delimiters, you must specify the parameter as a quoted string (using matched single or double quotes). A null parameter can be entered using a comma only for that parameter.
You may scroll backwards and forwards through a history of previously issued commands by use of the <UpArrow> and <DownArrow> keys.
You may edit any command by use of the <Backspace>, <Delete>, <LeftArrow>, <RightArrow>, <Home> and <End> keys. The default entry mode is Insert, but Overwrite mode is available. (The <Insert> key may be used to toggle between Insert and Overwrite modes). You may cancel the entry of a command at any time by pressing <Esc>.
File names or icons appearing elsewhere on your desktop may be dragged and dropped into a command at the cursor. This ensures accurate references to files (path, name and extension). This feature alone may make it worthwhile to open a window displaying the contents of the data directory (folder). (We like to display the contents of this folder on the right side of of our display, as a narrow list, sorted by extension type).
Rather than taking commands exclusively from the keyboard, Galileo can read commands from "script" files. These are simple ASCII text files containing Galileo commands, one per line. Reading from a script file can be initiated interactively simply by entering the script name as a command (without the .gal extension), or explicitly as a parameter of the Script command. You can also launch Galileo and initiate script reading by "dragging and dropping" the icon of a script file onto the Galileo icon (or shortcut).
Empty script lines or script lines beginning with a semi-colon (;) are ignored by Galileo. Such lines may be used as script commentary.
Script files may be created or modified using any elementary text editor. They are normally identified as script files by the use of the filename extension .gal. You are encouraged to modify the supplied scripts or create new ones to meet your own requirements.
Galileo is terminated by a Quit command. This can be embedded in a script file.
Some commands require pointer device (mouse) coordinate input. The mouse input interface follows these general principles:
Mouse input is acquired via the standard Windows interface. However, for most spatial data entry operations, Galileo requires that the mouse be moved some minimum number of pixels from its previously recorded position. This minimum is defined by the configuration parameter coincident.pixel.count in galileo.gin.
The mouse is assumed to be a two-button device. Typically, the (logical) left button will activate the recording of a mouse location while the (logical) right button reports the current geographical coordinates of the mouse.
For example, when entering a new object using one of the Enter... commands, you can point the mouse at specific geographic locations by "clicking" repeatedly on the right button while positioning the mouse to the desired position, guided by the latitude and longitude displayed in the console window. Once positioned as required, you enter the position by clicking the left button.
During many mouse data entry operations, two small buttons are displayed in the upper corners of the field of the map window. These are the [Esc] and [Done] buttons.
When mouse location entry is performed for multiple elements (for instance when recording the individual points of a point object), the entry sequence is terminated by left-clicking on [Done] or by pressing the <Enter> key.
When the entry is two-tiered (for instance, when recording the vertices of the lines of a line set or the rings of a region), you signal the end of an individual line or ring by left-clicking [Done] or by pressing the <Space> bar or the <+> key. When entering the ring(s) defining a region, you may alternatively signal the closure of a ring by clicking within the small circle defining the first vertex of the ring. In any case, you signal the end of the line/ring set by again clicking the [Done] or by pressing the <Enter> key.
Note: if you are right-handed, you might be interested in the fact that the "<Grey +>" and "<Grey Enter>" keys on the right-hand side of the keyboard are equivalent to the regular <+> and <Enter> keys.
Note: a simple method of "sampling" points or
line/ring vertices "on the fly" is to "drag" the mouse along the desired path
with its (logical) left button depressed. This is referred to as
"drag-drawing".
All of the data acquisition commands allow the user to escape from mouse data
entry sequences by clicking on the [Esc] button or by pressing the
<Esc> key.
Logical right mouse button
At any time, clicking the (logical) right button reports the current
geographical position expressed in latitude and longitude with precision
appropriate for the current map scale. In addition, this action reports the
Voronoi cell number containing this position and the leg and cumulative
distances between successive (logical) right clicks. Distances are reported
in units appropriate for the current map scale. The distance accumulator is
reset at the commencement of a session. It may be cleared at any time by
double-clicking the (logical) right button.
This term is used to describe the rich support provided for developers of
applications involving the geographical presentation of data. It must be
emphasized that this support is complementary to that provided by your GUI.
Hipparchus geographic functions mainly provide you with the means to relate
the "round world" to the "flat screen", and vice versa.
Geographic renderings can be made in any one of several display projections:
Galileo comes with built-in world coastlines at two levels of detail.
In response to the DrawCoast command, one or the other is drawn as
appropriate for the prevailing map scale and projection. This coastline data
is independent of any Voronoi index. DrawCoast is meant only to be
used for orientation purposes when displaying large surface objects or
satellite orbit traces. Other, more precise coastline data files may be
imported and are displayable using regular object management
commands. Several of these are supplied.
Galileo works with selectable Voronoi cell structures. This permits
you to associate objects with any Voronoi index and to observe their
relationship to those indexing cell structures. For example, Galileo
lets you find and display the specific Voronoi cells associated with any
object.
Galileo is capable of producing hard copy graphics on HP-GL/2
compatible devices (see the Galileo Plot... commands). You can
plot the drawings on-line or you can direct the plotter command stream to a
named file for off-line plotting. If you have access to a PCL5-class laser
printer such as the Hewlett-Packard LaserJet IIIP, you can use the printer as
a plotter.
The Galileo programs require specific parameters describing your
particular computing environment and preferences.
The stand-alone utility programs require parameters documented as "Usage"
notes, available on execution of the utility program with the /h or
/? switch set. For more details concerning the parameters and
operation of the stand-alone utility programs, you will need to consult the
Hipparchus Utilities
Guide and, if you have the SDK, inspect their source.
For initialization purposes, Galileo references an associated file,
galileo.gin. This file must be co-located with galileo.exe.
galileo.gin has the same general form and purpose as Windows
.ini files, consisting of ASCII text lines that provide initialization
strings to named parameters. Empty lines or lines beginning with a
semi-colon (";") are ignored.
The general format of a *.gin file is:
Any of these parameters may be changed at any time through use of a
Set command.
Several of the more common ellipsoids are:
This parameter may be changed at any time through use of a
Set command.
Note: ellipsoid.semiaxes and ellipsoid.number are
mutually exclusive parameters.
This parameter array may be changed at any time through use of a
Set command.
This parameter may be changed at any time through use of a
Set command.
This parameter may be changed at any time through use of a
Set command.
The first two of the four required integer parameters specify the
horizontal and vertical coordinates of the upper left corner of the
window, having zero-based values ranging 0-79 and 0-59, respectively.
The last two parameters specify the horizontal and vertical size
and have values ranging 1-80 and 1-60, respectively.
This parameter may be changed at any time through use of a
Set command.
This parameter may be changed at any time through use of a
Set command.
This parameter may be changed at any time through use of a
Set command.
Geographics
Custom Configurations
; Comments ...
parameter.name = value1 [value2 ... ]
parameter.name = value1 [value2 ... ]
...
...
where:
You can easily customize the supplied galileo.gin file using a text
editor. For example, two configuration parameters you may wish to change are
the default console and map window configurations set by the parameters
console.position and map.position.
galileo.gin
Here are the specific parameters required for Galileo:
[console]
Note that if this path name commences with the tilde symbol ("~"),
then the galileo.exe program supplies in its place the path name for the
"home directory", being the directory that contains the directory
containing the program executable file.
For example, if galileo is executed from
C:\anywhere\runw32\galileo.exe, then the .gin-file path name ~\data\
translates as C:\anywhere\data\.
[map]
[screen.rendering]
stereo, gnomonic, wwmerc, mercator, conical, ortho or wwview
[hpgl.mono.rendering]
[hpgl.color.rendering]
Error Messages
When running the Galileo programs, you may occasionally encounter error messages. For the most part, these error messages will be self-explanatory. Some, however, require further explanation.
Error messages of the form "Return Code = x" refer to internal conditions that may adversely affect the correct execution of the programs. These are generally Hipparchus Library function return codes set by the most recent Hipparchus Library function called by the command.
A few of the more common return codes are:
Note: All Galileo commands set a command error value, which may be interrogated with the IfErrorlevel or IfNotErrorlevel conditional script branch commands.
This command error value is distinct from the Hipparchus Library function error return codes referenced above.
Here are the error levels with a few examples:
(If you are a programmer with access to Galileo source code, be aware that the manifest constants that map specific errors to these general errorlevels are specified in galileo.h).
This section describes the detailed operation of each of Galileo's commands. Examples of most of these commands will be found in the demonstration scripts supplied. You might find it helpful at this point to make hard copies of the supplied scripts for ready reference.
In the following descriptions, P1/p1, P2/p2, ... Pn/pn denote the first, second, etc. positional parameters that the command accepts or requires. Upper case indicates required parameters while lower case indicates optional parameters. Bolded parameter values are keywords.
A number of command-line parameters are common to multiple commands; their descriptions follow:
This is a user-defined name, starting with a letter or underscore and containing only letters, numerals or the underscore ("_"). An object-name refers to a memory-mapped file having the extension .hbo (for Hipparchus Binary Object).
NOTE:If manipulating Hipparchus binary objects, be sure that the principal Voronoi index was the one present when the addressed object-name was entered, imported or derived. If merely displaying such objects, a search for the appropriate index will be initiated (see Object Display.
This is a character string, being the name of an external file, qualified by a path and extension as required. File-names may consist of letters, numerals or underscores commencing with a letter or underscore ("_") and containing NO spaces. Otherwise, file-names may be any that are valid for the operating system.
Special treatment is afforded filenames commencing with these path qualifiers: data\, scripts\, temp\ and georama\. For any of these qualifiers, Galileo substitutes the corresponding path defined by the .gin file (and possibly modified by a Set command).
In the absence of an explicit path specification, Galileo uses one of the initialization parameters: script.directory, data.directory or temporary.directory depending on the context of use of the file-name. These parameters may specify absolute or relative paths.
In the absence of an explicit file-name extension, Galileo supplies one of the following extensions, again depending on the context of usage:
This is a reference to a file type supported by certain functions of the Hipparchus Auxiliary Library. Files of this type are created and accessed using only the stream I/O facilities of the standard C/C++ run-time libraries. Such files are designated as "collections" of Hipparchus points, lines or regions. They share the same file extension, plr, but have an internal header that differentiates them.
This refers to the combined coordinate resolution and associated datum format indicator, as follows:
Resolution affects the maximum precision with which an object can be displayed or related to other objects. The resolution selected also affects the amount of memory required to model an object. Generally, the higher the resolution, the more memory required.
If you are having difficulty fitting your application into memory, you could try reducing the resolution of your larger objects. If speed is a significant factor, you should specify the float or float plus datum resolution.
associated data
When objects are exported to external storage, any data (or pointers) associated with its points or vertices are appended to the coordinate records as ASCII long unsigned integers.
When objects are imported from external storage and associated data has been specified for the memory object, then an attempt is made to parse each external point or vertex record for an optional third value (following its latitude and longitude coordinate values). An integer value found by this process is associated with the point or vertex as a long (32-bit) signed integer. When no integer value is found, the null datum (zero) is associated with the point or vertex. (Note that parsing for this integer will end with any character encountered that is other than a sign or digit).
When objects are imported from external storage and associated data has NOT been specified for the memory object, then any external data items associated with the points or vertices are simply ignored.
When objects are derived from other objects and associated data has been specified for the derived object, then each point or vertex of the derived object may have associated with it the datum from one or other of the parent objects, or the null datum, depending on the operation. For example, a point set object derived from a DerivePsetInside operation specifying associated data for its points will have copied into its derived points any data associated with the parent point set object. On the other hand, a point set object derived from the DerivePsetIntersectLines operation specifying associated data will have null data only associated with its points of intersection.
These are character strings representing angles expressed in the sexagesimal system. They may have no embedded spaces. Either ":" or "/" may be used as a sub-unit separator. Only the higher-order unit(s) need be specified. The lowest order unit can include up to 9 decimal fraction digits. Positive signed angles are normally prefixed by a space while negative signed angles are prefixed by a "-".
Latitudes may be prefixed by an optional "+", "n", "N" or space for North values or one of "-", "s" or "S" for South values. Longitudes may be prefixed by an optional "+", "e", "E" or space for East values or one of "-", "w" or "W" for West values. Examples of valid angles are:
Map scale is always specified as a scale denominator.
For example, to specify a map scale of 1:500,000, you specify the integer 500000 or an equivalent decimal or exponential value such as 0.5e6.
Scale controls the size of features and objects displayed on your monitor or plotter. It is calculated as a function of your monitor's (or plotter's) physical display area. It is NOT a function of the size of a map window displayed on that monitor. (The size of a map window controls the field of the map window, but not the scale).
Note: If you need a precise specification of scale, you will need to study this note. The choice of scale denominator depends on a knowledge of the physical dimensions of the display. You will need to divide one of the dimensions of the geographical area you wish to depict by the corresponding dimension of the display. For example, if the area you want to depict is 100 kilometers across (60 miles) and your display is 0.25 meters (10") wide, you would divide 100e3 by 0.25 for a scale denominator of 400e3. However, if the map display window is planned to be half the width of the display, you would specify a scale denominator of 2 x 400e3 = 800e6. If you subsequently change the size of the map window, you will alter its field but not its scale.
Wherever distance or proximity is required as a parameter, it is to be expressed in meters and presented in either integer, decimal or exponential format. Note that 1km = 1.0e3 meters, approximately 0.6 miles.
This is a character string specifying rendering attributes.
It is composed of a set of single-letter codes, each followed by a number (integer or real), which may be preceded by a hyphen. Letter-number pairs may optionally be separated by a colon (":") or a slash ("/"). For example, ..., c13/w2/v1, ...
Style letter codes not specified in a style string are assigned a value of zero. Most objects or features have a default rendering style specifiable in the initialization file.
Style letter codes are: crgb m wv n pq fjkl
These may be combined as appropriate for the object or feature being rendered:
000 Black 098 Dark Grey 117 Grey 196 Light Grey 102 Russet 150 Bright Red 186 Orange 167 Magenta 066 Green 204 Bright Green 039 Turquoise 210 Yellow 089 Blue 053 Bright Blue 137 Cyan 215 White
00 single pixel 04 small square 08 medium bullet 12 aeroplane 01 fat dot 05 medium square 09 medium pillow 13 ship 02 small circle 06 large square 10 X 14 star 03 large circle 07 triangle 11 house 15 reserved
Note that v1 is normally required to render lines in the wwmerc or ortho projections
0= 100% fill 03= 50% medm A 04= 50% medm B 05= 50% crse A 06= 50% crse B 07= 25% fine A 08= 25% fine B 09= 12% fine A 10= 12% fine B 11= 12% fine C 12= 12% fine DNote fill patterns A, B, C and D occupy separate display space and are therefore mutually transparent.
0= 100% fill 01= 50% rndm A 02= 50% rndm B 03= 25% rndm A 04= 25% rndm B 05= 12% rndm A 06= 12% rndm B 07= 6% rndm A 08= 6% rndm BNote fill patterns A and B occupy partially separate display space and are therefore partially mutually transparent.
Note that the letter codes p and q are mutually exclusive in any one style string.
When a graphic output command produces hard copy output, (i.e., when the command is given between Plot and PlotEnd commands), the style value is interpreted for a plotter.
These are the Galileo commands used to define the geometry of the map window and to render features and objects within its field.
Define displayed map center point, scale, projection (and orientation).
To recenter a map display to a specific location, you could specify only the latitude and longitude, e.g.,
geometry n51 w114
To rescale a map display to a specific scale, you could specify only the new scale, e.g.,
geometry ,,50e6
In the case of the world-wide projections (wwmerc and wwview), the latitude and scale specified in this command are ignored, as the projection will always be equatorial and a scale (and aspect ratio) calculated that can best be accommodated by the dimensions of the current map field.
The initial map window geometry is set by parameters in the [map] section of the galileo.gin initialization file.
Report current map field geometry in the console window. See also Geometry.
Clear the map window field to the style defined by p1 or to the overridable configuration parameter background.
The current map field geometry is undisturbed.
Note: If specified, this style will persist as the default Clear style for the remainder of the session.
Draw the latitude/longitude grid.
Draw the world coastlines.
Draw the global horizon.
Note: This command will have no effect in any of the map projections other than orthographic (ortho).
Insert annotation text within the map field. A supplied text string is drawn in the current map field in a specified text style, centered on a specific map field location.
P1 and P2 define the map field location for the annotation text.
If P1 and P2 are simple integers, they are interpreted as the absolute pixel coodinates of the location in the map field, P1 defining the horizontal pixel address, zero-based, counting left to right, and P2 defining the vertical pixel address, zero-based, counting from top to bottom.
If however P1 and P2 are supplied in any of the acceptable non-integer formats for latitude and longitude, then the text will be positioned appropriately within the current map field, providing only that the location specified lies within the field. If outside the field, or near a field border, the text does not display or may only partially display.
P3 style (for annotation).
P4 text string. If the string is to contain spaces or quotation marks, then it should itself be enclosed in matching single or double quotes. Note that the annotation text is limited to a single line of text; newline characters are not honored.
To learn the exact pixel dimensions of the current map field, see ReportMapField.
Using the mouse, change the center (tangency point) of the current map window.
(no parameters).
A new map center is taken from the position of the mouse when left clicked in the map window.
The current map field scale, projection and orientation are undisturbed.
Clearly, re-centering the map field by this means is limited to re-centering to geographic positions that are on-screen. If you wish to recenter to some point that is off-screen, you will need first to zoom out (e.g., ReScale 2.0) a number of times. Otherwise, you can explicitly restate the center for the map field using the geometry command.
Re-centering a wwmerc or wwview map field adjusts only the central meridian.
Using the mouse, change both the center and scale of the current map field.
(no parameters).
The new center is selected with the first left click of the mouse button. The second left click sizes the new map field, changing both the center and scale of the map field.
If the projection of the current map field is wwview, wwmerc or ortho, then the projection of the new map field becomes stereo. Otherwise, the projection remains unchanged.
Change the scale of the current map field.
P1 Scale factor (a positive real number), or one of the lower-case letters h, v or d.
If P1 is a scale factor, then the scale of the current map field is simply multiplied by the scale factor. Values less than 1.0 therefore result in a "zoom in" while values greater than 1.0 result in a "zoom out".
Alternatively, if P1 is one of the letters 'h', 'v' or 'd', then a new scale is defined for the current map field such that the tangential surface distance represented by the map field horizontally, vertically or diagonally through the map field center will be p2 meters.
The current map field center, projection and orientation parameters are undisturbed.
Center the map window field on an object. Optionally, the field may be re-scaled and its projection changed.
P1 object-name.
p2 scale (optional).
p3 projection (optional).
The center of an object is defined as the vector mean of all of the object's defining points or vertices. Note that this point is generally NOT the object's geographic centroid.
Set the size of the map window field such that its aspect ratio is p1 divided by p2 (approximately). The horizontal and vertical pixel dimensions of the resulting map field are adjusted to preserve the perimeter pixel count of the current map field. (See ReportMapField).
p1 aspect ratio numerator (an integer)
p2 aspect ratio denominator (an integer).
For map displays in the world-wide Miller-like projection wwview, best results will be seen with an aspect ratio of 1.242 (p1=1242/p2=1000).
For map displays in the world-wide Mercator projection wwmerc, best results will be seen with aspect ratios ranging from 1.10 (p1=1100/p2=1000) to 1.40 (p1=1400/p2=1000).
For map displays in all other projections, any reasonable aspect ratio will do.
If p1 and p2 are omitted, the map window is restored to its original size and location as specified by the galileo.gin file.
The resulting map window field is cleared to its current background style. The current map window field geometry is undisturbed.
Note that the dimensions of the map window will be somewhat larger to accommodate the window title bar and borders.
See also MapFieldSize.
Report current map window field size (in horizontal and vertical pixels) in the console window.
See also MapFieldSize and MapFieldAspect.
Set the size of the current map window field to a specific number of horizontal and vertical pixels.
p1 map window field horizontal pixel count
p2 map window field vertical pixel count.
Note that the dimensions of the map window will be somewhat larger to accommodate the window title bar and borders.
If p1 and p2 are omitted, the map window is restored to its original size and location as specified by the galileo.gin file.
The resulting map window field is cleared to its current background style. The current map field geometry is undisturbed.
Note: This command is intended for use in preparing bitmap displays or plots having specific pixel count dimensions.
See also MapFieldAspect.
Save map field bitmap to a bmp, jpg or png formatted graphics file.
P1 Bitmap file-name.
p2 Optional modifier(s) w|t|wt.
If a path is not specified in the file-name, then the configuration parameter data.directory in the galileo.gin file is supplied. If a file-name extension is not specified, then the extension .bmp is automatically supplied.
Note that the bitmap saved is the map field portion of the Windows "shadow" of the map window, NOT necessarily the image currently visible in the map field of the window. (The shadow is used by Windows to restore a window that has been (partially) obscured by some other window). Galileo commands such as Draw... and Display... automatically update the shadow. However, other Galileo commands such as Trace... that leave behind their visual effect do not automatically update the shadow. If their effect is to be recorded in a saved bitmap, then they should be followed by the UpdateBitmap command.
Map field bitmaps saved in the bmp format are processable by the Windows Paint program and most other graphics image editors. Be aware that the bmp file is created using the color depth currently in use by Windows. Therefore, if you are currently displaying a 16-bit or 24-bit color pixel, the saved file may be very large, and may require post-process reduction.
jpg images are processable by most browsers and graphics editors. For jpg images, be aware that the compression is "lossy" and therefore suitable ONLY for continuous images such as hypsographic surfaces. Images containing sharp edges, linework or lettering should never be saved in the jpg format.
png images are processable by most browsers and graphics editors. For png images, two additional modifiers are optional.
The w modifier specifies that the color pallette of the saved image be reduced to the closest colors in the 216 color "websafe" palette. Png images created using this option will be significantly smaller in size and thus faster to render.
The t modifier specifies that a png transparency is to be prepared. The color of the current Galileo background is marked for transparency.
When rendered by an application, pixels having this color are ignored. In this way the lines, lettering and area fills of a map may be overlaid on a stylized background (such as birch bark) or a road map can be overlaid on a hypsographic terrain representation.
See also ShowBitmap, ReportMapField, MapFieldSize and MapFieldAspect.
Show a bmp-format bitmap file in the current map field.
P1 file-name.
If a path is not specified in the file-name, then the configuration parameter data.directory in the galileo.gin file is supplied. If a file-name extension is not specified, then the extension .bmp is supplied.
The current map field dimensions will normally be the same as that of the map field from which the bitmap was previously saved (see SaveBitmap). Nevertheless, the named bitmap will be centered in the current map field, regardless of its dimensions. Providing the named bitmap is a .bmp meeting the "Device Independent Bitmap" standard, it can be expected to display correctly.
Note that Galileo does not currently show bitmaps of any format other than bmp.
See also UpdateBitmap, ReportMapField, MapFieldSize and MapFieldAspect.
Update the map window "shadow" bitmap to capture transient trace imagery such as satellite traces and swaths.
This command, when given immediately after a trace command, ensures that any subsequent restoration of a (partially) obscured map window and/or a subsequent SaveBitmap command will properly include the transient trace imagery.
See also ReportMapField, MapFieldSize and MapFieldAspect.
Initiate HP-GL/2 hard copy graphical output. All display commands occurring between the PlotStart and PlotEnd commands will produce an HP-GL/2 output stream, which may be directed to a hard copy device or to a file for subsequent processing.
If specified, a plot stream receiving filename must be either fully qualified or unqualified (the current directory is not defined). If unqualified, its path is supplied by the temporary.directory entry of the galileo.gin file. The default file extension is .hpg.
If a device name is specified, a temporary plot stream receiving file is opened (_temp.hpg in the temporary.directory). Valid device names are: PRN, LPT1, LPT2, LPT3, COM1, COM2, COM3 or COM4. (Device names may be specified in upper or lower case, with or without a colon suffix).
See also PlotEnd.
Causes a frame to be drawn around the perimeter of the plot map field.
Causes a character string to be included in the plot command stream.
See also PlotInclude.
Causes a file to be included in the plot command stream.
See also PlotString.
Terminates plot stream generation and closes the receiving plot file (whether named or temporary).
If the plot stream was directed to a printer/plotter device (e.g., PRN), then another program (GLPLOUT, co-located with Galileo) is initiated that copies the temporary file to the device (queue) and, when complete, deletes the temporary receiving file.
Subsequent Galileo display rendering commands are directed to the map window.
See also PlotStart.
Hipparchus Library functions recognize Hipparchus objects only in their canonical forms as (virtual) memory-resident structures.
Galileo however extends the definition of these objects to include several external forms.
Galileo commands in this section may be used to manage the conversion between the Hipparchus internal canonical forms and one or more of the external file forms known to Galileo.
Galileo implements Hipparchus canonical internal objects as Memory-Mapped Files. As such, these objects have an equivalent external binary file form, which is persistent. These external file objects are known as Hipparchus Binary Objects which are normally identified as files having the extension .hbo.
Any reference to one of these objects in a Galileo command via an object-name that does not explicitly specify the .hbo extension will have this extension added by Galileo.
Also, if the reference lacks a path specification, then Galileo supplies the configuration parameter data.directory defined in the galileo.gin initialization file.
External Hipparchus Binary Objects are generally NOT portable across platforms. Their use should be confined to those platforms on which they were created.
Both Galileo and Georama provide access to .hbo memory-mapped external data.
Galileo also implements a variety of ASCII text file formats for the portable external storage of Hipparchus objects in latitude-longitude point/vertex coordinate form. These file formats are identical with those used by previous releases of Galileo, and are therefore both forwards and backwards compatible with prior releases. In addition, these forms are generally cross-platform compatible, barring only minor differences in the treatment of line endings, which are easily overcome. These files are usually designated by their file-name extensions: .pts, .lns and .rgn, for point set, line set and region objects, respectively. (No specific external form for a surface object is implemented in this Release. However, such an object can be recreated from its source .pts file (cf. DerivePsetTin). Note that these coordinates are relative to some specific geodetic datum and ellipsoid. It is the application architect's responsibility to ensure that inter-system use of such coordinates is in the context of equivalent geodetic datums and ellipsoids.
Galileo also offers an alternative method of intersystem coordinate communication for objects in the form of "concise direction cosines". Like latitude-longitude coordinates, these represent an object's global point/vertex locations, but expressed as 3D vectors normal to the Hipparchus sphere. Since the sum of the squares of three (normalized) direction cosines equals unity, one can be dropped and recomputed as needed. The remaining two cosines are then expressed as signed 32-bit integers of which the two lowest order bits are used to encode which of the three cosines was dropped, and its sign. This scheme provides an isometric resolution of about 1cm on the Earth's surface. Objects exported/imported in this form are normally identified by the file extensions: .ptc, .lnc and .rgc, for point set, line set and region objects, respectively. Note that just as is the case with conventional latitude/longitudes, concise direction cosines are relative to some specific geodetic datum and ellipsoid. It is the application architect's responsibility to ensure that inter-system use of such coordinates is in the context of equivalent geodetic datums and ellipsoids.
The Hipparchus Utilities include stand-alone, cross-platform console programs for the batch conversion of external object files between many of their various forms.
Enter a point set object using the mouse.
P1 object-name for the new point set
p2 resolution.
If the resolution parameter specifies associated data, then the command associates a long integer serial number with each point entered, starting with 1.
The default coordinate resolution/datum format is f (float, no datum).
Enter a line set object using the mouse.
P1 object-name for the new line set
p2 resolution.
If the resolution parameter specifies associated data, then the command associates a long integer serial number with each vertex entered, starting with 1.
The default coordinate resolution/datum format is f (float, no datum).
Note that the line set may contain unintended self intersections. These can be detected by the subsequent application of the DerivePsetIntersectLineSelf command.
Enter a region (ring set) object using the mouse.
P1 object-name for the new region
p2 resolution.
If the resolution parameter specifies associated data, then the command associates a long integer serial number with each vertex entered, starting with 1.
The default coordinate resolution/datum format is f (float, no datum).
Note that the region is NOT VERIFIED on entry. This should be done by subsequent application of the VerifyRsetBoundary and VerifyRsetTopology comands, in that order.
Enter a quasi-circular container region using the mouse.
P1 object-name for the new region
p2 resolution
p3 region boundary vertex density factor [default is 2].
The first mouse button left-click defines the circle's center, the next defines a point on its circumference. Vertices for an approximating polygon are generated at intervals determined by the density factor.
If the resolution parameter specifies associated data, then null values are supplied.
The default coordinate resolution/datum format is f (float, no datum).
See also DeriveRsetNearPoints.
Enter a quasi-spiral sector container region using the mouse.
P1 object-name for the new region
p2 resolution
p3 region boundary vertex density factor [default is 2].
The first mouse button left-click defines the sector region's center and its first vertex. The next left-click defines the first vertex on the sector's circumference arc while a third left-click defines its last arc vertex. Vertices approximating a spiral arc are generated counter-clockwise at intervals determined by the density factor, as if the first arc vertex defined a circle.
If the resolution parameter specifies associated data, then null values are supplied.
The default coordinate resolution/datum format is f (float, no datum).
See also DeriveRsetNearPoints.
Enter a quasi-circular exclusion region using the mouse.
P1 object-name for the new region
p2 resolution
p3 region boundary vertex density factor [default is 2].
The first mouse button left-click defines the circle's center, the next defines a point on its circumference. Vertices for an approximating polygon are generated at intervals determined by the density factor.
If the resolution parameter specifies associated data, then null values are supplied.
The default coordinate resolution/datum format is f (float, no datum).
See also DeriveRsetAfarPoints.
Enter a quasi-spiral sector exclusion region using the mouse.
P1 object-name for the new region
p2 resolution
p3 region boundary vertex density factor [default is 2].
The first mouse button left-click defines an intermediate sector region's center and its first vertex. The next left-click defines the first vertex on this sector's circumference arc while a third left-click defines its last arc vertex. Vertices approximating a spiral arc are generated counter-clockwise at intervals determined by the density factor, as if the first arc vertex defined a circle. Since the requested region is an exclusion region, the order of vertices of the intermediate sector is then reversed.
If the resolution parameter specifies associated data, then null values are supplied.
The default coordinate resolution/datum format is f (float, no datum).
See also DeriveRsetAfarPoints.
Import a point set object from an ASCII .pts or .ptc file.
P1 new point set object-name
p2 ASCII file-name
p3 resolution.
p4 f if the optional datum is to be stored as a float value.
If the ASCII file-name (p2) is not specified, then an ASCII filename is manufactured having the same path and filename as object-name but with the extension .pts.
If the ASCII file-name is specified with the extension .ptc, then the expected external coordinates will be in the form of "concise direction cosines", represented as two ASCII integers.
The default coordinate resolution/datum format is f (float, no datum).
Note: A point set object may also be constructed from the vertices of an .lns or .rgn file. See also ExportObject.
Import a line set object from an ASCII .lns or .lnc file.
P1 new line set object-name
p2 ASCII file-name
p3 resolution.
p4 f if the optional datum is to be stored as a float value.
If the ASCII file-name (p2) is not specified, then an ASCII filename is manufactured having the same path and filename as object-name but with the extension .lns.
If the ASCII file-name is specified with the extension .lnc, then the expected external coordinates will be in the form of "concise direction cosines", represented as two ASCII integers.
The default coordinate resolution/datum format is f (float, no datum).
Note: A line set object may also be constructed from the boundary rings of a .rgn file, which may or may not be closed explicitly. See also ExportObject.
Import a region (ring set) object from an ASCII .rgn or .rgc file.
P1 new region object-name
p2 ASCII file-name
p3 resolution.
p4 f if the optional datum is to be stored as a float value.
If the ASCII file-name (p2) is not specified, then an ASCII filename is manufactured having the same path and filename as object-name but with the extension .rgn.
If the ASCII file-name is specified with the extension .rgc, then the expected external coordinates will be in the form of "concise direction cosines", represented as two ASCII integers.
The default coordinate resolution/datum format is f (float, no datum).
Verify region boundary rings(s).
P1 existing region object-name
Ring verification checks that each ring of the set does not touch or cross itself or have any embedded duplicate vertices.
If this verification test fails, you are notified by an error message and the command errorlevel is set to 2.
Verify region topology.
P1 existing region object-name
This region verification test assumes that the region has previously passed the VerifyRsetBoundary test. Topology verification checks that there is no point on the Earth's surface which is at the same time both inside and outside any two rings that can be reached from that point without crossing another ring. Stated otherwise, all pairs of nested rings must have opposite direction, clockwise vs counterclockwise. See also the formal definition of a region in the Hipparchus Tutorial.
If this verification test fails, you are notified by an error message and the command errorlevel is set to 2.
Verify that a region is null, i.e., has no extent, the complement of a world region.
P1 existing region object-name
If this verification test fails, you are notified by an error message and the command errorlevel is set to 2.
See also DeriveRsetComplement, VerifyRsetIsWorld
Verify that a region is world-wide, i.e., covers the planet, the complement of a null region.
P1 existing region object-name
If this verification test fails, you are notified by an error message and the command errorlevel is set to 2.
See also DeriveRsetComplement, VerifyRsetIsNull
Export an object to an ASCII file.
P1 existing object-name
p2 file-name
p3 format string for latitudes
p4 format string for longitudes.
This command understands the dimensionality of the object specified by object-name. If p2 is not specified, then the ASCII output will be written to a file of the same name as object-name except that the extension .pts, .lns or .rgn will be substituted, as appropriate.
ASCII output may consist of lines containing space-delimited latitude, longitude and associated datum (if present). Sets of coordinates are aligned with respect to the columnar placement of their components and decimals (if any).
If present in the object, the datum associated with each set of coordinates is output following the longitude as a space-delimited unsigned long integer.
If p2 is a null entry, or is specified explicitly, then the format of the ASCII sexagesimal latitude and longitudes output to the file-name p2 may optionally be specified by p3 and p4, according to the formatting rules defined for the Hipparchus Auxiliary Library function h0_AngleToString.
Examples follow:
n51.123456 w114.123456\n s5.123456 e87.654321\n n90.000000 w0.000000 0\n s90.000000 e180.000000 1\n n0.000000 w180.000000 4294967295\n
The format strings used to produce the example coordinates above are: "nsd6" and "ewd6". These are the default formats when the angle.sexagesimal parameter in the galileo.gin file is unspecified or set to zero. If angle.sexagesimal is set to one, the default formats for the export of latitude and longitude coordinates are "nss2" and "ews2", respectively, giving these angles in degrees, minutes, seconds and hundreths of seconds, separated by colons, i.e., ddd:mm:ss.ss.
If p2 is explicitly defined as a file having the extension .ptc, .lnc or .rgc, then the object's point/vertex coordinates will be output in the form of "concise direction cosines", as pairs of ASCII integers. If specified, p3 and p4 are ignored.
All output files are terminated with a line containing an asterisk marker in column 1. Non-empty line set and region files will also contain an asterisk marker line following the last vertex for each line or ring of the line set or region object.
On export, objects of reduced dimensionality may be derived from .hbo objects of higher dimensionality. This is signalled by explicit specification of an extension in p2. Thus a line set object (.lns) or a point set object (.pts) may be exported from a region object or a point set object (.pts) may be exported from a line set object. A line set object derived in this way from a region object contains (as lines) the boundary rings of the region, each closed explicitly by repetition of the first vertex of the ring. A point set object derived on export from a region has (as its points) only the vertices implicitly defining its rings. A point set object derived on export from a line set object has (as its points) every vertex defining the line set object. Note that such objects will be required for computational purposes only. For example, the line set object derived in this manner from a region may be imported and used to determine proximity of a point or point set to the boundaries of that region. Note also that such objects are generally NOT required to render the boundaries or vertices of regions or the vertices of line sets (see next section).
Hipparchus binary objects and collections are defined in the context of specific Voronoi indexes. When accessing these entities for display purposes, Galileo first attempts to match the entity to the principal Voronoi index, as defined in the control file galileo.gin (and possibly redefined by subsequent ReadVix, ReadDecryptVix or ReadTix commands). Should that match fail, the display commands initiate a search for previously loaded "secondary" Voronoi indexes. Should that search fail, then an external search is made of the data subdirectory. If found, that Voronoi index file is loaded as a "secondary" index. Should no matching index be found, or should there be an insufficient number of slots or memory to accommodate it, the user will be advised via an error message.
Display the points or vertices of a Hipparchus binary object or collection.
P1 existing object-name or collection-name
p3 Specified-points only indicator: s|e or p|v|b.
If p3 is specified and the object is a Hipparchus binary object line set, then only the ending vertices of the line(s) in the set are rendered as points. Code s specifies line start points while code e specifies line end points. These options are useful in graphically depicting the sense of the lines of a line set.
If p3 is specified and the object is a Hipparchus TIN, then subsets of triangle vertices may be selected: code p selects the vertices of triangles interior to cells, code b selects the vertices of triangles along cell boundaries while code v selects cell boundary vertices. These codes make possible the graphicical distinction between such triangles and their vertices.
Display the lines, rings or TIN edges of a Hipparchus binary object .hbo line set, region or Pset-TIN, respectively, or the lines or rings of a lines or regions collection .plr.
P1 existing object-name or collection-name
p3 TIN-edge selection indicator: a, i or b.
If the object is a Pset-TIN surface, then p3 specifies that cell- interior (i) or cell-boundary (b) TIN edges only are to be displayed. The default, a, displays all edges.
Display the filled areas of an .hbo region.
P1 existing region object-name
Note that the area fill for complex objects may require a larger-than- normal workspace. This may be remedied by application of the Set command (i.e., set work.space.size = nnnnnn (bytes)..
Display a Pset-TIN surface hypsographically, that is using a color gradient to represent "elevation", "depth" or other numeric attribute such as population or product sales.
P1 existing Pset-TIN object-name
The color gradient range is specified by means of the extended RGB specifiers of the style.
For wide-area displays, a generalized view is available via specification of the style item n1. In this view, cell segments are rendered hypsographically rather that individual TIN faces.
Display a Pset-TIN surface with "shading", that is using a color gradient to represent "elevation" or other numeric attribute, indirectly by differentiating between the orientation of TIN triangle faces with respect to a reference light-source (namely, the upper right-hand corner of the display field).
P1 existing Pset-TIN object-name
The color gradient range is specified by means of the extended RGB specifiers of the style.
For wide-area displays, a generalized view is available via specification of the style item n1. In this view, cell segments are shaded rather that individual TIN faces.
Display the distance from a location indicated by the mouse to the nearest point of a point set object.
P1 point set object-name
p2 color to temporarily highlight the nearest point.
Left-clicking the mouse reveals the geographic coordinates (and any associated datum) of the nearest point plus its distance (in kilometers) from the mouse position.
Right-clicking the mouse reveals its current coordinates and the leg and cumulative distances between successive right-clicks.
Display the distance from a location indicated by the mouse to the farthest point of a point set object.
P1 point set object-name
p2 color to temporarily highlight the farthest point.
Left-clicking the mouse reveals the geographic coordinates (and any associated datum) of the farthest point plus its distance (in kilometers) from the mouse position.
Right-clicking the mouse reveals its current coordinates and the leg and cumulative distances between successive right-clicks.
In a point set, find the nearest of up to n points within radius r of a designated mouse position, ordered by distance.
P1 point set object-name
P2 maximum number of points sought (n>1)
P3 maximum radius of search (meters)
p4 color to temporarily highlight the nearest point.
Left-clicking the mouse lists (in the console) the geographic coordinates (and any associated datum) of the nearest points (if any) and their distances (in kilometers) from the mouse position, in ascending order, which points are temporarily highlighted in the optional style.
Right-clicking the mouse reveals its current coordinates and the leg and cumulative distances between successive right-clicks.
Search a collection of points PLR file for a point near the mouse cursor, highlight that point in the map window and display in the console window any datum associated with that point.
p2 color to temporarily highlight the nearby point.
As the mouse is moved, nearby points in a point collection PLR file P1 are sought out and displayed (temporarily) as bullets (of optional color p2). The process is terminated by clicking on the Esc button or by pressing the Esc key.
Left-clicking the mouse reveals any data associated with a nearby point.
Right-clicking the mouse reveals its current coordinates and the leg and cumulative distances between successive right-clicks.
Note: this command will normally follow a DisplayPoints command so that the user can interactively view any data associated with points of interest.
Display the distance from a location indicated by the mouse to the nearest point of a line set object.
P1 line set object-name
p2 color to temporarily highlight the nearest point.
Left-clicking the mouse reveals the geographic coordinates of the nearest point lying on the object's nearest line segment, plus its distance (in kilometers) from the mouse position. Note that this point may NOT be a vertex. Any data associated with the vertex (or two bounding vertices) is displayed.
Right-clicking the mouse reveals its current coordinates and the leg and cumulative distances between successive right-clicks.
Display the distance from a location entered by the mouse to the farthest vertex of a line set object.
P1 line set object-name
p2 color to temporarily highlight the farthest point.
Left-clicking the mouse reveals the geographic coordinates (and any associated datum) of the farthest vertex plus its distance (in kilometers) from the mouse position.
Right-clicking the mouse reveals its current coordinates and the leg and cumulative distances between successive right-clicks.
Calculate and display in the console the following statistics for a line set object: the number of vertices for the line set object and the length of all of the lines of the set (km).
P1 line object-name.
Search a collection of lines PLR file for a line near the mouse cursor, highlight that line in the map window and display in the console window any datum associated with that line.
p2 color to temporarily highlight the nearby line.
As the mouse is moved, nearby lines in a line collection PLR file P1 are sought out and displayed (temporarily) as lines (of optional color p2). The process is terminated by clicking on the Esc button or by pressing the Esc key.
Left-clicking the mouse reveals any data associated with a nearby line.
Right-clicking the mouse reveals its current coordinates and the leg and cumulative distances between successive right-clicks.
Note: this command will normally follow a DisplayLines command so that the user can interactively view any data associated with lines of interest.
Calculate and display in the console the following statistics for a region object: the number of vertices, the area (km**2), and the perimeter length (km).
P1 region object-name.
p2 optional area calculator controls [s|p|r].
If p2 is s, then the calculator assumes that the region has a limited number of rings and is less than a hundred kilometers or so in extent and so performs the area calculation with considerably higher precision than in the general case, i.e., with p2 unspecified.
If p2 is p, then the calculator assumes that adjacent vertices having approximately the same latitude define a parallel of latitude, rather than a geodesic. p implies s. Therefore the calculator assumes that the object is of approximately the same complexity and extent as assumed above and the computation is performed with similar precision.
If p2 is r, then the calculator expects an object having a number of rings consisting of exactly four vertices each defining latitude-longitude "rectangles" on the ellipsoid. The area of this object is calculated with very high precision, which can be used to gauge the relative precision of the less stringent computations above. The boundaries of these rings may touch without invalidating the area computation, so that adjacent "rectangles" are tolerated. r implies p and s.
Note that perimeter lengths reported are cumulative geodesics and are unaffected by any of the above options.
Display the distance from a location indicated by the mouse to the nearest point of a region object.
P1 region object-name
p2 color to temporarily highlight the nearest point.
Left-clicking the mouse reveals the geographic coordinates of the nearest point lying on the object's nearest ring segment, plus its distance (in kilometers) from the mouse position. Note that this point may NOT be a vertex. Any data associated with the vertex (or two bounding vertices) is displayed.
Search a collection of regions PLR file for a region under the mouse cursor, fill that region in the map window and display in the console window any datum associated with that line.
p2 color to temporarily fill the selected region.
As the mouse is moved, regions in a collection of regions PLR file (P1) are sought out and highlighted (temporarily) as filled regions (of optional color p2). The process is terminated by clicking on the Esc button or by pressing the Esc key.
Left-clicking the mouse reports a region's area, perimeter and number of vertices.
Report in the console window interpolated Z values (such as elevation, depth, etc.) for a surface.
As the mouse is moved, the locally interpolated Z value for the surface is reported in the console window. If the left mouse button is clicked, then the lat/long of the position is reported, along with the Voronoi cell number. The process is terminated by clicking on the Esc button or by pressing the Esc key.
Erases a file or object.
P1 file-name or object-name.
Derived objects become new Hipparchus Binary Objects, with both internal and persistent external representation as object-name .hbo entities.
From an existing point set, derive a new point set in which any points sharing the same cell local coordinates are represented by a single point. The derived point set includes all other points in the existing point set.
P1 object-name of the new (derived) point set
P2 object-name of the existing point set
p3 resolution of the new point set (optional)
p4 datum, an optional keyword.
If the format of the existing object's coordinates includes associated data, then the specification of coordinate equivalence may be extended to include exact equivalence of the associated data, by use of the datum keyword.
If the format of the derived object is to include associated data, and associated data is available in the existing object, then that data is copied from the existing object. If the datum option is NOT specified, the datum supplied for points representing points sharing the same coordinates is taken from one of those points.
If the format of the derived object is to include associated data, and no data is associated with the existing object, then null datum values are supplied.
Note that if the existing set is empty, the derived point set object will also be empty.
From an existing point set, derive a new point set in which any points sharing the same cell local coordinates are represented by a single point. The derived point set excludes all other points in the existing point set.
P1 object-name of the new (derived) point set
P2 object-name of the existing point set
p3 resolution of the new point set (optional)
p4 datum, an optional keyword.
If the format of the existing object's coordinates includes associated data, then the specification of coordinate equivalence may be extended to include exact equivalence of the associated data, by use of the datum keyword.
If the format of the derived object is to include associated data, and associated data is available in the existing object, then that data is copied from the existing object. If the datum option is NOT specified, the datum supplied for points representing points sharing the same coordinates is taken from one of those points.
If the format of the derived object is to include associated data, and no data is associated with the existing object, then null datum values are supplied.
Note that the derived point set object may be empty.
From an existing point set, derive a new point set in which any points sharing the same cell local coordinates are excluded. The derived point set includes all other points in the existing point set.
P1 object-name of the new (derived) point set
P2 object-name of the existing point set
p3 resolution of the new point set (optional)
p4 datum, an optional keyword.
If the format of the existing object's coordinates includes associated data, then the specification of coordinate equivalence may be extended to include exact equivalence of the associated data, by use of the datum keyword.
If the format of the derived object is to include associated data, and associated data is available in the existing object, then that data is copied from the existing object.
If the format of the derived object is to include associated data, and no data is associated with the existing object, then null datum values are supplied.
Note that the derived point set object may be empty.
Derive a new point set object as the spatial OR of two existing point set objects.
In this spatial OR operation, any points in the first or second existing operand objects having no coordinate equivalent counterparts in the other object are output to the new derived object, (together with any associated datum, if indicated). Any points found in common between the two objects are represented in the derived object as a single point, with any opted datum copied preferentially from the first of the two operand objects.
P1 object-name of the new (derived) point set
P2 object-name of the first existing point set
P3 object-name of the second existing point set
p4 resolution of the new point set (optional)
p5 datum, an optional keyword.
The resolutions of the two existing objects must necessarily match with respect to their coordinate format, if not the presence of associated data.
If the format of both the existing object's coordinates includes associated data, then the specification of coordinate equivalence may be extended to include exact equivalence of the associated data, by use of the datum keyword.
If the format of the derived object is to include associated data, and associated data is available in either of the existing objects, then that data is copied preferentially from the first of the existing object operands.
If the format of the derived object is to include associated data, and no data is associated with either of the existing objects, then null datum values are supplied.
Operation of this command is defined for operand point sets having no points that share equivalent coordinates (after any extension of equivalency using the datum option). Such point sets may first be reduced to this state using DerivePsetReduced, DerivePsetUnique or DerivePsetDuplicates, as required.
Note that if both of the existing objects are empty, then the derived object will be empty.
Derive a new point set object as the spatial XOR of two existing point set objects.
In this spatial XOR operation, any points in the first or second existing operand objects having NO equivalent counterparts in the other object are output to the new derived object, (together with any associated datum, if indicated). Any points found in common between the two existing objects are NOT output to the derived object.
P1 object-name of the new (derived) point set
P2 object-name of the first existing point set
P3 object-name of the second existing point set
p4 resolution of the new point set (optional)
p5 datum, an optional keyword.
The resolutions of the two existing objects must necessarily match with respect to their coordinate format, if not the presence of associated data.
If the format of both the existing object's coordinates includes associated data, then the specification of coordinate equivalence may be extended to include exact equivalence of the associated data, by use of the datum keyword.
If the format of the derived object is to include associated data, and associated data is available in either of the existing objects, then that data is copied preferentially from the first of the existing object operands.
If the format of the derived object is to include associated data, and no data is associated with either of the existing objects, then null datum values are supplied.
Operation of this command is defined for operand point sets having no points that share equivalent coordinates (after any extension of equivalency using the datum option). Such point sets may first be reduced to this state using DerivePsetReduced, DerivePsetUnique or DerivePsetDuplicates, as required.
Note that the derived point set object may be empty.
Derive a new point set object as the spatial AND of two existing point set objects.
In this spatial AND operation, any points in the first or second existing operand objects having no coordinate equivalent counterparts in the other object are NOT output to the new derived object. Any points found in common between the two objects are represented in the derived object as a single point, with any indicated datum copied preferentially from the first of the two operand objects.
P1 object-name of the new (derived) point set
P2 object-name of the first existing point set
P3 object-name of the second existing point set
p4 resolution of the new point set (optional)
p5 datum, an optional keyword.
The resolutions of the two existing objects must necessarily match with respect to their coordinate format, if not the presence of associated data.
If the format of both the existing object's coordinates includes associated data, then the specification of coordinate equivalence may be extended to include exact equivalence of the associated data, by use of the datum keyword.
If the format of the derived object is to include associated data, and associated data is available in either of the existing objects, then that data is copied preferentially from the first of the existing object operands.
If the format of the derived object is to include associated data, and no data is associated with either of the existing objects, then null datum values are supplied.
Operation of this command is defined for operand point sets having no points that share equivalent coordinates (after any extension of equivalency using the datum option). Such point sets may first be reduced to this state using DerivePsetReduced, DerivePsetUnique or DerivePsetDuplicates , as required.
Note that the derived point set object may be empty.
Derive the subset of a point set that lies in proximity to a line set.
P1 new point set object-name
P2 existing point set object-name
P3 existing line set object-name
P4 proximity distance criterion (meters).
p5 resolution
Note that the derived point set object may be empty.
Derive the subset of a point set that lies NOT in proximity to a line set.
P1 new point set object-name
P2 existing point set object-name
P3 existing line set object-name
P4 proximity distance criterion (meters).
p5 resolution
Note that the derived point set object may be empty.
Find the subset of a point set that lies inside a region.
P1 new point set object-name
P2 existing point set object-name
P3 existing region object-name.
p4 resolution
Note that the derived point set object may be empty.
Find the subset of a point set that lies outside a region.
P1 new point set object-name
P2 existing point set object-name
P3 existing region object-name.
p4 resolution
Note that the derived point set object may be empty.
Find the point set that consists of the intersections of two line set objects.
P1 new point set object-name
P2 first existing line set object-name
P3 second existing line set object-name.
p4 resolution
If the resolution specifies associated data, then the null datum is supplied.
If no intersections are found, then the derived point set will be empty.
Find the point set that consists of the intersections of a line set object with itself.
P1 new point set object-name
P2 existing line set object-name
p3 resolution
If the resolution specifies associated data, then the null datum is supplied.
If no intersections are found, then the derived point set will be empty.
Note that self-intersections are duplicated in the derived point set. These may be reduced by subsequent application of the DerivePsetReduced command.
Derive a point set triangular irregular network (TIN) surface given a point set having associated data in 4-byte float format.
P1 new TIN point set object-name
P2 existing point set object-name
p3 optionally, the letter "n" to include the triangle neighbor list in the TIN, which is required if spot surface Z values are to be "inspected" or surface difference volumes calculated.
The data associated with each point may be elevation, depth or any other phenomina such as temperature, pressure or sales revenue, in wholly arbitrary units of measure. The input point set should contain a reasonably dense number of observations covering the area of interest (thirty or so per Voronoi cell would be minimal). Empty cells outside an area of interest will result an ill-defined edge for the surface.
See also OverheadSurface.
Find the subset of a line set that lies inside a region.
P1 new line set object-name
P2 existing line set object-name
P3 existing region object-name.
p4 resolution
Find the subset of a line set that lies outside a region.
P1 new line set object-name
P2 existing line set object-name
P3 existing region object-name.
p4 resolution
Find the spatial intersection (common region) of two regions. This is often referred to as the "polygon overlay" operation.
P1 new region object-name
P2 first existing region object-name
P3 second existing region object-name.
p4 resolution
Derive an Rset complementary to another Rset such that all that is outside one region is inside the complement.
P1 new region object-name
p2 existing region object-name If p2 is omitted, the derived object will cover the entire planet.
p3 resolution
Test for common points of a line set and a region.
P1 existing line set object-name
P2 existing region object-name p3 optional keyword b indicates that the ring boundaries of the region are to be included in the test.
The command returns its result in the console.
Test for common points of a region and another region.
P1 existing region object-name
P2 existing region object-name p3 optional keyword b indicates that the ring boundaries of the two regions are to be included in the test.
The command returns its result in the console.
Find the spatial union (combined region) of two regions.
P1 new region object-name
P2 first existing region object-name
P3 second existing region object-name.
p4 resolution
Create a "buffer" region around a point set in such a way that no point of the point set is nearer to the boundary of the buffer region than a prescribed distance. (The point set therefore is included within the buffer region).
P1 new region object-name
P2 existing point set object-name
P3 proximity distance (meters)
p4 resolution
p5 region boundary vertex density factor [default is 2].
The buffer region is constructed from the union of (possibly overlapping) polygons that are distant from each point of the point set. Each polygon is approximated by a multi-sided polygon having a surface area about equal to that of a region defined by a circular boundary.
The region boundary vertex density factor is an integer exponent between
1 and 6 specifying the number of defining boundary vertices as the function
12*pow(2.0, d), where d is the density factor.
Note that the construction and processing times for such regions
will increase exponentially with higher values of the density factor.
See also DeriveRsetAfarPoints.
DeriveRsetAfarPoints P1 P2 P3 [p4 [p5]]
Create a "buffer" region around a point set in such a way that all points of the point set are farther from the boundary of the buffer region than a prescribed distance. (The point set is therefore excluded from the buffer region, defining its void(s)).
P1 new region object-name
P2 existing point set object-name
P3 proximity distance (meters)
p4 resolution
p5 region boundary vertex density factor [default is 2].
This command is similar in operation to DeriveRsetNearPoints.
Find the convex hull region for a point set object.
P1 new region object-name
P2 existing point set object-name.
p3 resolution
Derive the region object that bounds the current map window.
P1 new region object-name
p2 resolution
Satellite files (*.sat) specify satellite orbit and sensor geometry.
The format of a .sat file is the same as the format of the georama.gin file. There are two parameter groupings:
The current implementation simplifies things somewhat by restricting a satellite file to one ORBIT_TYPE (classical) and one SENSOR_TYPE (allbands).
The parameters of the orbit.classical group are:
Other orbit types to be implemented are:
Keywords and data of the sensor.allbands group are:
Receiver files (*.rcv) specify sets of Earth telemetry stations.
The format of a .rcv file is the same as that of a .pts file except that multiple data are supplied for each receiver in the set:
Commands that require dates and times will accept these elements in the form parsed by the Hipparchus Auxiliary Library functions h0_StringToDaynumber and h0_String to Angle (timestrings being parsed as though angles). Examples of acceptable dates and times are:
1997-March-22 7:30 99/12/31 23:59:59.999999 2000-jan-1 0 2000/001 0
Note that Hipparchus times (and dates) are UT (GMT).
orbit number
Satellite orbits may be referenced by ordinals that number each orbit from
its defined epoch. When referenced in this manner, a satellite's positions in
that orbit will be calculated from the satellite's classical parameters given
by its .sat file.
time.scale
Real-time rendering of the various trace commands is subject to time
compression according to the configuration parameter time.scale
specified in the galileo.gin file. A real-time delay between
rendering successive orbit positions is calculated by dividing the simulated
time step in orbit by time.scale. For example, if the simulated time
step were 120 seconds and time.scale is 1200, then successive
positions would be planned to be rendered every 1/10th of a second. If the
time required for the computation for a particular step is less than the
planned delay, then rendering is delayed until the planned delay has expired.
Otherwise, the results of the step calculation are rendered immediately.
Note that the time.scale parameter can be changed at any time
by use of the Set command.
Trace a line of successive satellite orbit positions.
P2 trace start date
P3 trace start time
P4 trace end date
P5 trace end time
P6 trace step time (seconds in orbit, integer or real)
p7 orbit line style
In the orthographic projection, the trace is that of the satellite in space.
In all other projections it is that of the satellite's nadir.
The real-time presentation proceeds at a pace calculated from the
step time and time.scale parameter.
To interrupt the trace, press Esc or click in the console.
TraceOrbit P1 P2 P3 P4 P5 P6 [p7]
TraceSwath P1 P2 P3 P4 P5 P6 [p7]
Draws scanlines depicting the extent of a satellite's sensor's surface swath. At each step a line is drawn on the Earth's surface perpendicular to the path of the satellite's nadir.
P2 trace start date
P3 trace start time
P4 trace end date
P5 trace end time
P6 trace step time (seconds in orbit, integer or real)
p7 line style.
The real-time presentation proceeds at a pace calculated from the step time and time.scale parameter.
To interrupt the trace, press Esc or click in the console.
Combines the effects of TraceOrbit and TraceSwath.
P2 trace start date
P3 trace start time
P4 trace end date
P5 trace end time
P6 trace step time (seconds in orbit, integer or real)
p7 orbit line style
p8 sensor swath line style.
In the orthographic projection, the orbit trace is that of the satellite in space. In all other projections it is that of the satellite's nadir. The satellite's sensor's swath is depicted as scanlines drawn on the Earth's surface perpendicular to the path of the satellite's nadir.
The real-time presentation proceeds at a pace calculated from the step time and time.scale parameter.
To interrupt the trace, press Esc or click in the console.
Note that this command is not implemented for plot generation. Use instead the successive application of TraceOrbit and TraceSwath.
Trace a satellite's orbit while simultaneously indicating which ground station receivers (if any) are currently within telemetry range of the satellite. A receiver whose cone of reception intersects the satellite's orbital path is considered to be "active". Otherwise it is considered to be "inactive". A receiver's state is depicted by toggling its marker color.
P3 trace start date
P4 trace start time
P5 trace end date
P6 trace end time
P7 trace step time (seconds in orbit, integer or real)
p8 orbit trace line style
p9 active receiver marker color
p10 inactive receiver marker color.
In the orthographic projection, the trace is that of the satellite in space. In all other projections it is that of the satellite's nadir.
As the trace proceeds, a date-and-time-stamped log appears in the console window, recording the names of active receivers.
The real-time presentation proceeds at a pace calculated from the step time and time.scale parameter.
To interrupt the trace, press Esc or click in the console.
Note that this command is not implemented for plot generation.
Trace only those orbit points that are directly overhead a region.
P1 region object-name
P3 trace start date
P4 trace start time
P5 trace end date
P6 trace end time
P7 trace step time (seconds in orbit, integer or real)
p8 orbit line style
"Overhead" is defined as lying somewhere along the normal to a point on the ellipsoid, NOT, in the general case, along a vector passing through the center of the ellipsoid.
In the orthographic projection, the trace is that of the satellite in space. In all other projections it is that of the satellite's nadir.
The real-time presentation proceeds at a pace calculated from the step time and time.scale parameter.
To interrupt the trace, press Esc or click in the console.
Note that this command is not implemented for plot generation. Use instead the successive application of DeriveLsetNadir, DeriveLsetInside and DisplayLines.
Trace a satellite's nadir position and if the satellite is computed to be overhead any region in a named collection of regions, temporarily highlight that region.
P1 region collection file-name
P3 trace start date
P4 trace start time
P5 trace end date
P6 trace end time
P7 trace step time (seconds in orbit, integer or real)
p8 region temporary fill color
p9 orbit position trace color.
"Overhead" is defined as lying somewhere along the normal to a point on the ellipsoid, NOT, in the general case, along a vector passing through the center of the ellipsoid.
As the trace proceeds, a date-and-time-stamped log appears in the console window, recording the names of selected regions in the collection.
The real-time presentation proceeds at a pace calculated from the step time and time.scale parameter.
To interrupt the trace, press Esc or click in the console.
Note that this command is not implemented for plot generation.
Construct a line set object from the nadir trace of a satellite.
P1 new nadir line set object-name
P3 start datestring
P4 start timestring
p5 end datestring
P6 end timestring
P7 trace step time (seconds in orbit, integer or real)
p8 resolution.
If the resolution specifies associated data, then each successive vertex of the line set is assigned an integer vertex number, starting with 1.
Construct a region object from the sensor swath of a remote-sensing satellite.
P1 new swath region object-name
P3 start datestring
P4 start timestring
P5 end datestring
P6 end timestring
P7 trace step time (seconds in orbit, integer or real)
p8 resolution.
If the resolution specifies associated data, then each successive sensor-limit vertex pair is assigned an integer vertex number, starting with 1.
A swath region should be limited to less than one orbit. Otherwise, its ring boundary will likely intersect itself and the generated region will not be usable for other than line or point display. When in doubt as to its topological consistency, the generated swath region can be tested using VerifyRsetBoundary and VerifyRsetTopology, in that order.
See also DeriveRsetOrbit.
Construct a region object from the sensor swath of the specified orbit of a remote-sensing satellite.
P1 new swath region object-name
P3 orbit number
P4 trace step time (seconds in orbit, integer or real)
p5 resolution.
The swath region derived is expected to be topologically correct. To avoid the possible congruence of its start and end segments that define closure, the region is foreshortened by one second of time in orbit, at most.
Regions derived using this function may be freely combined with similar regions derived from any other orbits.
If the resolution specifies associated data, then each successive sensor-limit vertex pair is assigned an integer vertex number, starting with 1.
See also DeriveRsetSwath.
They are included here to establish specific Voronoi cell structures and to study their relationship to your application objects.
In earlier releases of Galileo, commands were provided to aid you in modifying existing Voronoi cell structures for use in your application. Since Release 3.1, these Voronoi cell structure modification and creation functions were moved to stand-alone non-graphical utility programs. This change was made in the interests of performance and cross-platform portability. These command-line utilities are supplied with Galileo, co-located with galileo.exe, and may be run independently of Galileo, or through Galileo via the Galileo Shell command.
Nevertheless, Galileo continues to support the basic Voronoi index operations required to establish specific Voronoi cell structures as spatial indexes and to visualize the relationship between those indexes and your data, in any of the available projections.
A "starter" Voronoi index file is supplied in ASCII center-points form. This is isotype.pts (located in the data directory). This Voronoi index should be regarded as a starter index when densifying or otherwise creating an application-specific Voronoi index. If you wish to use isotype directly as a binary file, you should generate the binary using cellwvs or cellins stand-alone utilities, like this:
cellwvs isotype.pts isotype.vix
The isotype index is relatively sparse, having just 272 cells. If your application requires a more-or-less regular but denser base, you can easily generate more dense "harmonic" subdivisions as follows:
cellwws isotype.pts isotype.vix cellpts isotype.vix isotype2.pts /c /g cellwvs isotype2.pts isotype2.vix ... cellpts isotypej.vix isotypek.pts /c /g cellwvs isotypek.pts isotypek.vix
Here the cellpts utility makes new cell center-points out of the corner-points of the current structure and adjusts the current cell center-points to a new "gravity" location, being the vector mean of the existing corner-points. The result of this operation is a new "rounded" structure having approximately three-fold as many cells. Since the time required to run cellwvs is very roughly the square of the number of cells, be prepared to wait awhile for the higher harmonics!
Before constructing your own Voronoi index, you may wish to view our offering of freely downloadable prebuilt Voronoi index structures at voronoi.html.
Replace the current principal Voronoi index with an external Voronoi index (stored in binary format).
p1 file-name (optional).
During initialization, Galileo reads and establishes as current a binary Voronoi index structure. This is also the default file read by the ReadVix command.
NOTE 1: Hipparchus Binary Objects and Point, Line or Region Collections are processable ONLY in the presence of the SAME Voronoi index used when they were created.
NOTE 2: Binary Voronoi index files are generally NOT cross-platform compatible. You may create a Voronoi index file in cross-platform ASCII text format by use of the supplied utility vix2tix.
See also ReadDecryptVix.
Replace the current principal Voronoi index with an external Voronoi index (stored in encrypted binary format).
P1 file-name.
P2 Passphrase or passkey. This command functions exactly the same as ReadVix except that the named .vix file is known to be encrypted and the passphrase or passkey is known.
This .vix file may have been previously encrypted using the vixcrpt utility.
The encryption/decryption is according to public domain functions based on Blowfish, only slightly modified to fit in with other components of the Hipparchus Auxiliary Library. For a complete description of this cryptography, see the Geodyssey web site at www.geodyssey.com.
Replace the current principal Voronoi index with an external Voronoi index (stored in cross-platform ASCII text format).
P1 file-name.
During initialization, Galileo reads and establishes as current the binary Voronoi index structure specified by the configuration parameter voronoi.index contained in the initialization file galileo.gin.
NOTE: Hipparchus Binary Objects and Point or Line Set Databases are processable ONLY in the presence of the SAME Voronoi index used when they were created.
NOTE: You may obtain a Voronoi index file in cross-platform ASCII text format by use of the supplied vix2tix utility.
Draw the boundaries of all Voronoi cells currently in the map window.
Draw the centerpoints of all Voronoi cells currently in the map window.
Draw the Delaunay duals of all Voronoi cells currently in the map window.
Draw the "spokes" between the cell centerpoint and cell corners for all Voronoi cells currently in the map window.
Display the cell numbers of all Voronoi cells currently in the map window.
Fill the Voronoi cells currently in the map window using a color gradient to depict their order.
p1 style (for color gradient).
Draw the boundaries of cells occupied by a point set object.
P1 existing point set object-name
p3 cell list file-name.
If a cell list file-name is specified, a list of occupied cells is output as an ASCII file of cell-identifier integers, one per line, in ascending order. If no file extension is specified, the extension .cll will be supplied.
Draw the boundaries of cells traversed by a line set object.
P1 existing line set object-name
p3 cell list file-name.
If a cell list file-name is specified, a list of traversed cells is output as an ASCII file of cell-identifier integers, one per line, in ascending order. If no file extension is specified, the extension .cll will be supplied.
Draw the boundaries of cells traversed by rings of a region object.
P1 existing region object-name
p3 cell list file-name.
If a cell list file-name is specified, a list of occupied cells is output as an ASCII file of cell-identifier integers, one per line, in ascending order. If no file extension is specified, the extension .cll will be supplied.
Draw the boundaries of cells entirely interior to a region object.
P1 existing point set object-name
p2 style
p3 cell list file-name (for lines).
If a cell list file-name is specified, a list of occupied cells is output as an ASCII file of cell-identifier integers, one per line, in ascending order. If no file extension is specified, the extension .cll will be supplied.
Select and draw cells proximate to (near) a specified location.
P1 command modifier: c, a or d
p2 cell boundary style (optional)
p3 cell center color or cell boundary style (optional).
You give the specific location and proximity criterion using a mouse. Left-click the mouse on the location, then left-click again at some distant point to define the radius of proximity (nearness).
Note that right-clicking the mouse reveals its gegraphic coordinates plus its leg and cumulative distances (in Km) from positions previously right-clicked.
Proximate cells are selected and drawn according to the command modifier and optional styles:
Traverse the path of a search for a new home cell.
p1 optional cell boundary line style.
This interactive command traces the search path followed internally when searching for the home cell of points designated using the mouse. The command will normally follow a DrawCells command. An initial home cell is designated by the first left-click of the mouse. When some other point in the display is designated by left-clicking the mouse, the path taken internally by the cell search facility to identify the new home cell is traced by drawing the boundaries of cells visited. The trace process may be continued for additional points. The process is ended by clicking the Esc button or by pressing the <Esc> key.
This interactive command permits the addition of one or more cells to the current Voronoi index, and illustrates the limited structural effects on the boundary definition of the new and neighboring cells.
p1 optional file-name into which the modified Voronoi index structure will be saved when done. If p1 is not specified, no permanent changes are recorded.
p2 optional line style with which to draw the boundaries of all cells affected by the addition of new cells.
This interactive command provides a mechanism to divide (possibly) over-populated cells, illustrates the limited effect of such division(s) and (optionally) saves for subsequent use the new Voronoi cell structure.
This command will normally follow a DrawCells command. New cell centers are designated by left-clicking the mouse. The process of cell reconfiguration may be continued indefinitely. The process is ended by clicking the Done button, at which time the new index structure p1 is saved. The process may be aborted without side-effects by left-clicking the Esc button or by pressing the <Esc> key. In any case, the current index structure remains unaffected.
Scripts are ASCII text files normally identified by the filename extension .gal.
Once launched, scripts are read and run automatically by Galileo command processor until end-of-file is encountered, at which time control returns to the console window. (Execution of the script may be monitored in the console window by setting to 1 the script.echo parameter in the [console] section of the galileo.gin file.)
Script execution may be suspended, resumed or terminated by operator action. You may suspend a running script by pressing any letter key. In this mode, you may complete and execute a command from the console. Script processing is resumed on completion of the interposed command. However, if a script command is interposed, then the running script is ended and a new script (if any) is started.
Script file lines that are empty or that commence with a semi-colon (';') are treated as commentary and are ignored by the command processor.
Labels: scripted commands are directly addressable via script file label entries. These are script file lines commencing with a colon (':') that introduces a label token. A label token consists of one to 32 characters commencing with a letter or underscore followed by letters, numerals or underscores. Conditional and unconditional branch commands can transfer control to the first command following a label entry. A script file can be started at the first command following a specific label entry in a script.
Delay: several commands provide timed delays for presentation purposes.
A timed delay can be for a specific amount of time. Specific time delays are scripted in terms of an integer number of seconds, but the script.pace parameter in the galileo.gin file can be set to alter this time scale, (but never reduce below one half second).
A scripted time delay of zero seconds is considered to be "forever", inviting a deliberate release using the mouse or keyboard.
Regardless of the delay specified, action can be restarted at any time by the operator clicking the left mouse button in the console window.
Reads and processes Galileo commands from a script file.
p1 script file-name
p2 label within a script.
A script command given within a script chains to rather than calls the named script file.
If both a script file and a label are specified, then execution of the script commences at the command following the specified label.
The operating environment of the named script is the current environment. Any changes made to that environment by the named script will persist after its completion.
If no parameters are specified, the command has no effect unless it was interposed from the console into a suspended script, in which case it has the effect of closing the suspended script (and any calling scripts), returning control to the console.
See also Call.
Reads and processes Galileo commands from another script file.
P1 script file-name
p2 label within a script.
A Call command embedded in a script transfers control to the named script. If a label is specified, then execution of the named script commences at the command following the specified label.
At end of file in the named script file, or upon encountering a Return command, control is returned to the issuing script immediately following the Call command.
The operating environment of the called script is that of the caller. Any changes made to that environment by the called script will persist on return to the calling script.
The Call command is effective only within a script. Nested Call commands are permitted to a reasonable limit, beyond which the command is ineffective.
Return control to the script that most recently issued a Call command.
If no Call command is outstanding, Return has no effect and control passes to the next scripted command.
Encountering end of file in a called script is equivalent to executing the Return command.
Keeps the map window in focus for some period of time.
P1 delay (an integer number of seconds).
Displays a text message panel in the map window and keeps the map window in focus for some period of time.
P1 delay.
P3 message text string.
The message text string consists of up to 64 lines of message text, with message lines separated by newline ("\n") characters.
Note that Galileo can read, compose and process command lines of up to 2K bytes in length.
Note also that this command line may be composed from lines that are "continued" by use of the "\" (backslash) as the last character of the line.
The text message panel is displayed in the map window and the map window is kept in focus for delay seconds. The panel is sized to accommodate the text of the message. The style parameter (interpreted for text panels) determines the text color, font size, line justification, panel background transparency or color and the panel placement.
P1 file-name. If not qualified by a path and/or extension, the file will be written to the data.directory with the extension .txt.
P2 one or more lines of text to be written to the named file. Multiple lines may be defined via the "continuation code", as defined for the ShowPanel command.
Note that this command may be used to create short text files, scripts and/or batch procedures for subsequent execution via the Shell command.
Echos its parameter(s) in the console window, regardless of the current setting of the script.trace configuration parameter.
P1 Parameter to be echoed.
See also Set.
Unconditionally transfers command execution control to the first command following a script label entry.
P1 label.
If the named object or file exists, then the command P2 is executed using any parameters following P2 as operands. Otherwise, execution continues with the next scripted statement following.
P1 object-name or file-name
P2 any command enabled for scripts.
Note that this command line may be composed from lines that are "continued" by use of the "\" (backslash) as the last character of the line.
If the named object or file does not exist, then the command P2 is executed using any parameters following P2 as operands. Otherwise, execution continues with the next scripted statement following.
P1 object-name or file-name
P2 any command enabled for scripts.
Note that this command line may be composed from lines that are "continued" by use of the "\" (backslash) as the last character of the line.
If the error value returned by the immediately previous command equals or exceeds the specified errorlevel, then the command P2 is executed using any parameters following P2 as operands. Otherwise, execution continues with the next scripted statement following.
P1 errorlevel
P2 any command enabled for scripts.
Note that this command line may be composed from lines that are "continued" by use of the "\" (backslash) as the last character of the line.
If the error value returned by the immediately previous command does NOT equal or exceed the specified errorlevel, then the command P2 is executed using any parameters following P2 as operands. Otherwise, execution continues with the next scripted statement following.
P1 errorlevel
P2 any command enabled for scripts.
Note that this command line may be composed from lines that are "continued" by use of the "\" (backslash) as the last character of the line.
Exit Galileo.
Note that this command is unconditional, whether issued from the console or from within a script.
Call an operating system function, Hipparchus utility program or batch command procedure (i.e., Unix shell script).
P1 String containing a command and its parameters.
Unless specifically qualified, the command is sought first via the system path, then within the same directory containing galileo.exe. For this reason, it is convenient to co-locate the Hipparchus Utilities with galileo.exe.
In the Windows operating system, the command is executed as a separate window that disappears on completion of the command. Therefore, if you wish to inspect the stdout or stderr of the command, you will need to pipe it to more or construct a batch procedure containing a pause. Such procedures can be built on the fly by use of the WriteTextFile command.
Note that the P1 string will normally contain space or comma delimiters, and should therefore be enclosed in matching single or double quotation marks.
Note also that the command specified by P1 will be executed within an operating system sub-shell in which the current environment is inherited but cannot be modified (see SetEnv).
Display in the console window the time it took to execute the immediately preceding command.
(no parameters).
Change the value of a selected configuration parameter.
P1 Configuration parameter name
P2 Value to which parameter is to be set.
p3 Additional values for a parameter array, where applicable.
Only these configuration parameters may be named:
work.space.size, angle.sexagesimal, ellipsoid.number, ellipsoid.semiaxes, gravity.parameters, script.echo, script.pace, time.scale, data.directory, script.directory, temporary.directory and georama.directory.The form and purpose of these parameters is explained in the description of the galileo.gin file and in the commands that access them.
Set (or reset) an operating system variable in the current environment.
P1 String containing an operating system "setenv" (or equivalent) command.
Note that the string will normally contain space or comma delimiters, and should therefore be enclosed in single or double quotation marks.
See also Shell.
Suggests several methods of obtaining help.
(no parameters).
Reports the Galileo build date plus Hipparchus Library and OS version information.
(no parameters).
Report current virtual memory configuration.
Report current directory paths for data\, temp\, script\ and georama\ keywords.
Dump a Hipparchus binary object into an annotated ASCII text file.
P1 object-name
p2 file-name.
If p2 is not specified, a file-name is manufactured having the same path and filename as object-name except that the filename extension .dmp will be substituted for that of the .hbo object.
(No parameters are required).
This command illustrates graphically the domain of Concise Direction Cosine (CDC) geographic coordinates. It is best issued in the context of orthographic (ortho) or world-wide views (wwview) of the planet. Using a color continuum, the command illustrates the continuous nature and discontinuities associated with the numeric behavior of the CDC coordinate domain.
See also PaintDCos3 and PaintLatLong.
(No parameters are required).
This command illustrates graphically the domain of Direction Cosine geographic coordinates (DCos3). It is best issued in the context of orthographic (ortho) or world-wide views (wwview) of the planet. Using a color continuum, the command illustrates the continuous nature and absence of discontinuities associated with the numeric behavior of the DCos3 coordinate domain.
See also PaintCDC and PaintLatLong.
(No parameters are required).
This command illustrates graphically the domain of Latitude Longitude geographical coordinates (LatLong). It is best issued in the context of orthographic (ortho) or world-wide views (wwview) of the planet. Using a color continuum, the command illustrates the continuous nature, discontinuities and singularities associated with the numeric behavior of the Latitude Longitude coordinate domain.
See also PaintCDC and PaintDCos3.
This is a stub "place-holder" command for use by developers in implementing new or modified versions of Galileo command subprograms.
(parameters as required).
These stand-alone utilities share a simple command-line user interface. Their command line usage is self-documenting. For on-line help as to usage, you simply enter an /h or /? switch after the program name. For detailed instructions as to their use, you will need to refer to the Hipparchus Utilities Guide and/or the source code.
The following is a list of some of the Hipparchus Utilities including a brief explanation of their purposes:
Many of these utilities are mentioned elsewhere in this publication, in the context of related topics.
By this time, you likely will have reviewed the operation of the various supplied scripts. If not, take the time now to browse the contents of the ~\scripts directory, looking for .gal files. You can view these files with any text editor.
Following the examples given, you should have very little trouble in developing your own scripts.
Geodyssey is interested in receiving, and possibly publishing, your most interesting or unusual Galileo scripts.
Here are the submission rules:
Your scripts must be self documented with commentary such that they can be included "as is" in future releases of the Galileo distribution.
You will have the first ten lines of commentary entirely to yourself as your credit and copyright notice. The first line must identify your script and its author's name and date. Additional comment lines should identify your organization, address, telephone, fax or e-mail contact numbers. If you wish, you might also provide your professional qualifications, specialties and website address.
In addition, you may commence your script with a single opening ShowPanel message of maximum duration two seconds, which may identify you and/or your script. In this way, you can have run-time credit.
You may submit your script by mailing a 3.5" disk to Geodyssey Limited at the address given elsewhere in this Guide. If your script requires specific data files not supplied by Geodyssey, you should include these on your disk submission. To be eligible for publication, your script and data files must be limited to 100K bytes of ASCII material, when decompressed.
Submissions will not normally be returned by Geodyssey. From submissions received, Geodyssey may select your submission for publication in future releases of this product. Your submission is made by you and received by Geodyssey with the clear understanding that Geodyssey Limited will have no liability to you or your organization for future royalties or other considerations.
If your submission is selected for publication, you will first be contacted for reconfirmation of your permission to publish. In order to avoid conflict between submissions and to ensure that your work will properly function in future releases, Geodyssey Limited reserves the right to make editorial changes to your work.
We look forward to receiving your submissions.
Galileo is intended to be a companion to the Hipparchus Tutorial so that you can better understand the concepts and facilities of the Hipparchus Library. As such, the Hipparchus Galileo Guide is not updated automatically.
Ongoing support is generally available from the Geodyssey Limited website at http://www.geodyssey.com.
Galileo, Georama and Hipparchus are exclusively owned and distributed by Geodyssey Limited of Calgary, Alberta, Canada. Geodyssey is a privately owned company of software professionals dedicated to the promotion and support of these remarkable products. Geodyssey makes this technology available under simple development and end-use licensing agreements, usually free of on-going royalties.
Geodyssey's general licensing policy provides the developer with affordable access to this remarkable technology while deferring payment of any additional licensing fees until the resulting end-use application has demonstrated the benefits of the technology.
Geodyssey also offers extensive training, consulting and application development services.
For additional information, please visit our extensive web site at http://www.geodyssey.com or call, fax or write to Geodyssey.
The Hipparchus Galileo Guide provides the information needed to install and use Galileo components in a Wndows environment. The installation procedures are simple and straightforward. Demonstration scripts serve to verify the installation and provide insight into the power of Hipparchus. Reference materials permit you to prototype many of the geographic aspects of your applications. You can build new scripts to give life to your own application area. Interesting or unusual scripts should be submitted to Geodyssey for possible inclusion in future releases of Galileo.
AddCellCenters | Area | Call | CenterOn | Clear | DeriveLsetInside | DeriveLsetNadir | DeriveLsetOutside | DerivePsetAfarLines | DerivePsetCombinedAll | DerivePsetCombinedUnique | DerivePsetCommon | DerivePsetDuplicates | DerivePsetInside | DerivePsetIntersectLines | DerivePsetIntersectLineSelf | DerivePsetNearLines | DerivePsetOutside | DerivePsetReduced | DerivePsetTin | DerivePsetUnique | DeriveRsetAfarPoints | DeriveRsetCombined | DeriveRsetComplement | DeriveRsetCommon | DeriveRsetHullOfPoints | DeriveRsetNearPoints | DeriveRsetOrbit | DeriveRsetSwath | DeriveRsetWindow | DisplayArea | DisplayCellsBoundary | DisplayCellsInterior | DisplayCellsOccupied | DisplayCellsTraversed | DisplayLines | DisplayPoints | DisplaySurfaceHypso | DisplaySurfaceShade | DrawCellCenters | DrawCellDuals | DrawCellNumbers | DrawCellOrder | DrawCells | DrawCellSpokes | DrawCoast | DrawGrid | DrawHorizon | DrawText | DumpObject | Duration | Echo | EnterLset | EnterPset | EnterRset | EnterRsetInsideCircle | EnterRsetInsideSector | EnterRsetOutsideCircle | EnterRsetOutsideSector | EraseObject | ExportObject | FarthestInLset | FarthestInPset | Geometry | GoTo | Help | IfErrorlevel | IfExist | IfNotErrorlevel | IfNotExist | ImportLset | ImportPset | ImportRset | Length | MapFieldAspect | MapFieldSize | NearestCells | NearestInLset | NearestInPset | NearestInRset | NearestOrderedInPset | NearLineInCollection | NearPointInCollection | OverheadRsetInCollection | OverheadSurface | PaintCDC | PaintDCos3 | PaintLatLong | PlotEnd | PlotFrame | PlotInclude | PlotStart | PlotString | PtestLsetRset | PtestRsetRset | Quit | ReadDecryptVix | ReadTix | ReadVix | ReCenter | ReFrame | ReportMapField | ReportMapGeometry | ReportMemory | ReportRunEnvironment | ReScale | Return | SaveBitmap | Script | Set | SetEnv | Shell | ShowBitmap | ShowMap | ShowPanel | TraceOrbit | TraceOrbitOverheadCollection | TraceOrbitOverheadRset | TraceOrbitReceivers | TraceOrbitSwath | TraceSwath | TraverseCells | UpdateBitmap | VerifyRsetBoundary | VerifyRsetIsNull | VerifyRsetIsWorld | VerifyRsetTopology | Version | WriteTextFile | Zzz