PDS Rings Node Software Library
Version 1.3, September 2003

Mark R. Showalter


Click here for a text-only version of this file. Or click here to browse all the files directly.


The Profile Toolkit comprises a set of C and FORTRAN routines for manipulating ring profiles. The word profile is used here to describe any sequence of numbers tabulated as a function of time, radius or any other independent variable.

The toolkit includes routines for reading and manipulating PDS-formatted data files, including the filtering and resampling of data onto new sample grids. The routines keep track of the relationships between profiles, enabling the user to understand the statistical properties of derived data if the properties of the original data are known. The toolkit also includes routines for fitting curves to tabulated numbers, for the smooth interpolation of geometric or calibration quantities associated with a data file.

The toolkit is designed using the principles of object-oriented programming. The user freely creates objects by describing their properties and relationships, without worrying about the details of how they are implemented. This makes it possible to build extremely sophisticated tools very easily.

1.1 Change History





1.2 File Overview

This release of the Rings Node Profile Library is organized as follows:


Each routine in the Profile Toolkit is documented extensively in the source code. The source files should be consulted for a detailed description of how to use each routine. They are all found in the "source/" subdirectory.

The fundamental unit manipulated in the Profile Toolkit is an object. Each object has a class or type. The classes obey a hierarchy, in which each object class inherits the properties and behaviors of its superclass, while adding new properties of its own. The basic hierarchy of Profile object classes is as follows:

          |           |           |
        Series     Function     Label
          |           |
         Stat       Curve
For C programmers, all the Profile Toolkit routines have names beginning with "Pro_". Some more basic components of the Rings Node Library have names beginning with "RL_". For FORTRAN programmers, the routine names are the same except that they have an "F" prepended. In some circumstances, the numbers and types of the arguments differ slightly between FORTRAN and C versions.

2.1 Objects

At the highest level, all objects share the basic properties that they can be named, printed, and deleted. They also have X- and Y-coordinates.

Defined in file object.c:

2.2 Series

Series objects augment the generic object class with the property that they can be visualized as an indexed sequence of numbers. They all have the property that, if given an integer index, they return a numeric value. A series can also return a flag indicating that a specific sample is invalid or unknown.

In addition, all series objects have a sampling parameter. This is a floating-point number that varies linearly with the index, such as the time in seconds when a sample was acquired.

Defined in file series.c:

Two specific implementations of the series object are provided:

Defined in file array.c:

Defined in file column.c: For PDS COLUMN objects with multiple ITEMs, the derived series can include any single item from each column or, alternatively, all the ITEMs under the assumption that the file is organized as multiple samples per row.

2.3 Statistical series

A statistical series (often abbreviated "stat") extends the properties of a series with a new routine that gives the covariance between any pair of samples (or variance of any single sample).

Defined in file stat.c:

Several implementations of statistical series are supported, all of which involve the use of another series object.

Defined in file fixed.c:

Defined in file filtered.c: Defined in file resample.c: Defined in file weighted.c:

2.4 Functions

A function object returns a floating-point number y given another floating-point number x. The function works within a certain specified domain; attempts to evaluate the function for x-values outside this domain raise an error condition.

Defined in file function.c:

Several implementations of the function object are provided:

Defined in file lspline.c:

Defined in file software.c: Defined in file composit.c: Defined in file slope.c:

2.5 Curves

Curve objects extend the behavior of functions by adding the property that, at any location within the domain, the slope of the function can also be computed and returned.

Curve objects are generally smooth and continuous. Because of this property, curves are invertible, meaning that a routine is provided to return the best value of x given y. For curve inversions, the user must also specify the segment of the curve to be inverted. Segments are numbered from one, starting at the lower endpoint of the domain and separated by extrema and inflection points in the file, up to the upper endpoint of the domain.

Two specific curve implementations are provided:

Defined in file spline.c:

Defined in file inverse.c:

2.6 Point Spread Functions and Filters

The Profile Toolkit provides a few convenient routines to assist the user in describing the statistical properties of series samples and in determining filter coefficients.

A point spread function (abbreviated PSF) describes the sensitivity of an individual series sample to a theoretical, infinitesimal feature in the data, as a function of the distance between the sample's center point and the feature. Three PSFs are currently supported: boxcar, triangle and sinc.

A "boxcar" PSF has a constant value within a certain distance of the origin, but is zero outside that domain. If it has unit width, this means that a sample is uniformly sensitive to any point feature that falls less than half-way to either adjacent sample, but completely insensitive to features further away than that.

Defined in file boxcar.c:

A "triangle" PSF has a peak value at the origin and decreases linearly to zero in either direction. If it has a full width of two, this means that a sample is most sensitive to a point feature falling at its center, completely insensitive to features falling at the center of its neighbors, and has linearly variable sensitivity between these limits.

Defined in file triangle.c:

A "sinc" PSF has sensitivity that varies as sin(pi*x)/(pi*x). This is what one expects when a series contains infinitesimally local samples of a function that contains no signal of spatial wavelength shorter than twice the spacing between samples.

Defined in file sinc.c:

In addition to the PSF routines, the Profile Toolkit includes a handy routine for determining a set of filter coefficients. Filtering a profile can be understood as converting the data from one PSF to another.

Defined in file psffilt.c:

2.7 Labels

A label object is simply the Profile Toolkit's name for its internal representation for the PDS label of a data file. A label object has the property that the user is able to look up information about the data file and use this information to read and manipulate the numbers found. The Profile Toolkit only recognizes data objects identified as a TABLE or a SERIES in a PDS label.

Note that a label object does not make use of the coordinate name and domain properties of other Profile Toolkit objects such as series and functions.

Defined in file label.c:

2.8 RingLib Error Handling Routines

In addition, the Profile Toolkit provides a general mechanism for dealing with error conditions. Each routine raises one of a specific set of error conditions when something goes wrong. Users have complete control over what to do in response to any of these conditions. By default, the program will print an error message and abort. However, users can decide on a condition-by-condition whether to print, hide or redirect the message, and whether to abort or continue the program afterward. The error conditions raised are identified by character strings. The complete set of error conditions raised by the Profile Toolkit is as follows: Two other error conditions are raised by lower-level routines.

2.9 Other Source Files

The following files contain additional source code in the form of routines that are generally not to be called directly by the user. Files that are specific to the Profile Toolkit are as follows: In addition, these files contain generic RingLib routines.


Two sample programs are provided with the toolkit, along with their needed data files. They are found in the "examples/" subdirectory.

3.1 Program "ppsfilt.for"

This FORTRAN program illustrates the use of the data filtering capabilities of the toolkit. It generates a smoothed, ASCII-formatted data file containing a segment of the Voyager PPS data set, calibrated and listed with its radial scale.

File "filtout.tab" contains the output from a sample run of the program, using data files "ppsdata.lbl/.dat", "ppsgeom.lbl/.tab" and "ppscalib.lbl/.tab", also included. These are versions of the PDS-formatted files containing the data, geometry and calibration information from the Voyager PPS ring occultation experiment at Saturn, volume VG_2801. Consult the source code for an explanation of how to regenerate this file.

3.2 Program "ppsresam.for"

This FORTRAN program illustrates the use of the data resampling capabilities of the toolkit. It generates a smoothed, ASCII-formatted data file containing a segment of the Voyager PPS data set, calibrated and listed with its radial scale. Unlike program "ppsfilt.for", this program resamples the data onto a uniform radius grid. It is also significantly slower.

File "resamout.tab" contains the output from a sample run of the program, using data files "ppsdata.lbl/.dat", "ppsgeom.lbl/.tab" and "ppscalib.lbl/.tab", discussed above. Consult the source code for an explanation of how to regenerate this file.


The file "profile.h" should be included in all C programs using the Profile Toolkit. This file declares prototypes for every routine in the toolkit, and also defines a few useful types, symbols and constants. All Profile objects should be declared of type PRO_OBJECT*. The toolkit is built atop PDS's Object Access Library (OAL), which is also needed when linking programs.

Within the Profile Toolkit and the remainder of the Rings Node Software Library, special data types are defined to "hide" some variations among implementations of C from one platform to the next. These special data types are as follows:

These types are defined in the include file "ringlib.h", which is included automatically by "profile.h".

For FORTRAN programmers, the file "fprofile.inc" is provided. It declares the type of every function within the toolkit and also defines some useful parameters. All object pointers should be declared integer*4.


5.1 General Information

A single set of source files generates both the Standard Mode and Quick Mode object files. The difference is that Quick Mode object code is generated when the C macro "QUICK" is defined at the time of compilation. The build scripts described below generate both versions of the object libraries.

The difference is that when the library is compiled using "Quick" Mode, the code performs less self-checking so it runs faster; see Section 1.1 above. In general, user programs will not need to be modified to execute in Quick Mode; all the user will have to do is re-load the program with the "Quick" version of the Profile Library.

5.2 Object Access Library

Several components of the Profile Library make use of the Object Access Library (OAL), distributed by the PDS Central Node. It can be obtained from in compressed Unix tar file oalV13.tar.Z. In spite of the directory name, the library builds successfully on many different platforms under multiple operating systems. Follow the instructions provided with that library.

However, when building OAL, it is recommended that you replace the files "source/rprt_err.c" and "source/struct_l.c" with the versions found in the "oalsrc/" subdirectory accompanying this library. These revised versions suppress a large number of warnings and informational messages that interfere with the performance of the Profile Library.

NOTE: As a simpler alternative, the version of the OAL toolkit found on Rings Node archive volumes already contains these changes in the "software/oal/source" subdirectory. Also, an included file "software/oal/aareadme.txt" contains a very streamlined description of how to build the toolkit.

5.3 UNIX Build Instructions

To build the tools, you must have already built the PDS Object Access Library. This directory must contain a copy of the library "oal.a", or else a symbolic link to the library. The directory must also contain a subdirectory "oal" containing the C include files "*.h" for the OAL, or else a symbolic link to the directory. By default, these files reside in the "source/" subdirectory of the OAL library tree.

For example, if the OAL is in a parallel directory called "oal/", then these commands will create the necessary links:

    ln -s ../oal/source/oal.a oal.a
    ln -s ../oal/source oal
This library has been tested on UNIX systems by DEC, Sun, and Silicon Graphics and Macintosh OS X. To build the library and test binaries on a Sun, type
    chmod +x makesun.com
To build the library and binaries on a system by DEC or Silicon Graphics, type
    chmod +x makedec.com
To build the library and binaries on a Macintosh under OS X, type
    chmod +x makemac.com
The script file "make*.com" will compile each file and build two archive files called "profile.a" and "qprofile.a". (Note that any pre-existent files called "profile.a" and "qprofile.a" should be removed first). The sample program binaries are called "ppsfilt" and "ppsresam" and are found in the "examples/" subdirectory.

Note that the commands "cc" and "f77" are used by these scripts. Be sure that your command search path includes these before executing the script.

To use the library, include either "profile.a" (for Standard Mode) or "qprofile.a" (for Quick Mode) among the files that appear on a cc or f77 command line. Also include "oal.a". Note that for C programs, you must also include the "-lm" option to load in the C math libraries.

5.4 VMS Build Instructions

To build the tools, you must have already built the PDS Object Access Library. You must then define a logical symbol "OAL", which points to the directory/directories containing the PDS Object Access Library "OAL.OLB" and the C include files "*.h" for that library.

For example, if the OAL is in a parallel directory called OAL.DIR, then this command will define the necessary symbol:


To build the library and executables on a Vax or Alpha using the VMS operating system, type

This will compile each file and build two object libraries called PROFILE.OLB and QPROFILE.OLB. The sample program binaries are called PPSFILT.EXE and PPSRESAM.EXE.

To use the library, specify PROFILE/LIBRARY (for Standard Mode) or QPROFILE/LIBRARY (for Quick Mode) among the files in a LINK command. You must also include OAL:OAL/LIBRARY. For programs written in FORTRAN, you must also include SYS$LIBRARY:VAXCRTL/LIBRARY because the C libraries are not linked in by default.

Toolkits | Rings Node Home