USGS

ISIS 2 Documentation


Isis Programmer Documentation

----

There is extensive programmer documentation for ISIS. However, this documentation is incomplete and somewhat out of date. Thus, ISIS programming requires more effort than might otherwise be the case.

The following description assumes that the $ISIS environment variable is set to the root of the ISIS source tree. (The $ISISR environment variable is set to the root of the "running" ISIS tree, which contains the executable programs and associated files.)

The following are the main items of ISIS programmer documentation:

  1. ISIS User Documentation
  2. ISIS System Design Document (ISD)
  3. ISD Unix Supplement
  4. C DOUSER Interface Description
  5. Region of Interest Handling Description
  6. ISIS Source Code

1. ISIS USER DOCUMENTATION

The ISIS web site contains documentation on the user's view of the Unix Version of ISIS, which should be studied before attempting to read the other programmer documentation. In particular, you should study the Overview of ISIS Architecture and its associated appendices.

2. ISIS SYSTEM DESIGN DOCUMENTt (ISD)

One of the main programmer documents is the ISIS System Design document (ISD), which is a description of the design of the ISIS programming environment from the programmer's point of view. This includes an overview of the main I/O and utility routines and a description of how they are intended to be used. However, note that this document describes the ISIS design for the old VAX/VMS version of ISIS. (ISIS was originally developed in the VAX/VMS environment.)

The ISD is located in a set of files in $ISIS/doc/isd. The complete ISD is contained in the file isis_system_design.mem, whose size is approximately a mega-byte. This file was produced by running the VAX/VMS RUNOFF program. Note that there is an extensive index at the end of this document, which is intended to make it useful as a reference document. In addition, there is a set of files named chN.mem and apN.mem, which are considerably smaller and which contain the individual ISD chapters and appendices. Also, note that title_page.mem, isd.mec, and isd.mex contain the title page, table of contents, and index for the ISD.

3. ISD UNIX SUPPLEMENTAL

The changes to ISIS for the Unix version have been mostly additions to the VAX/VMS version. Thus, most of the information in the ISD is still a correct description of the Unix version. The file $ISIS/doc/vms_unix_diffs.txt describes some of the changes between the VAX/VMS version of ISIS and the Unix version. Note that this document is incomplete; there are additional changes.

4. C DOUSER INTERFACE DESCRIPTION

The file $ISIS/doc/c_douser.txt contains some information on writing C DOUSER routines for use in the ISIS DOCUBE programming environment, which automatically performs much of the tedious I/O handling needed by many of the ISIS programs.

5. REGION OF INTEREST HANDLING DESCRIPTION

The file $ISIS/doc/roi_design.txt describes the design of Region of Interest (ROI) handling in ISIS programs. This consists of storing ROI definitions in cube backplanes, e.g., such as that done by the "cv" program. This also includes accessing stored ROI definitions in backplanes, e.g., such as that done by "cv" and the "mask" program.

6. ISIS SOURCE CODE

The ISIS source code is included in the distributed system. Note that the source code is not needed for running the distributed ISIS programs. It is not necessary to compile the source code to produce a runnable system; the distributed system contains pre-compiled executable modules for a particular computer platform. Also, it is not necessary to compile the complete source code in order to be able to develop new application programs. The $ISISR "running" tree for an ISIS distribution contains all the object module libraries and include files needed for compiling/linking new programs.

However, the ISIS source code is needed for programming because existing programs illustrate working ISIS programs. Also, comments at the beginning of the source code for the various I/O and utility routines explain the caller's view of the routines, i.e., descriptions of the overall functioning of the routines and detailed descriptions of the required parameters.

The directories in $ISIS/apps/... contain the sources for the ISIS programs, e.g., $ISIS/apps/gen contains "general" programs. A good example program coded in C would be $ISIS/apps/gen/coreg.c. If you want to write a DOCUBE program, a good example program to look at would be $ISIS/apps/gen/bandstats.c. A good example FORTRAN program would be $ISIS/apps/gen/convert.F. A good example FORTRAN DOCUBE program would be $ISIS/apps/gen/dsk2dsk.F.

The directories in $ISIS/subs... contain sources for ISIS subroutine libraries, e.g., $ISIS/subs/libisis/q contains the "Q" routines for accessing ISIS qube (cube) files. $ISIS/subs/libisis/utilib contains ISIS utility routines.

Note that there are "binding" routines that allow C routines to be called from Fortran and vis-versa. For example, see $ISIS/subs/libisis/utilib/u_bind_F.c and u_bind_c.c. Due to differences in parameter passing between C and Fortran, the parameters when called from C can sometimes be different from the parameters when called from Fortran.

If you are coding programs in C, then you should look in the source code of C routines to see the parameters and description of the routine. E.g., look at $ISIS/subs/libisis/q/q_open.c for the Q_OPEN routine.

For calling a Fortran routine from a C program, you need to look at the Fortran source to see the description of the routine. But, you need to look at the prototypes in the include files to see the list of parameters for calling a Fortran routine from C. E.g., look at $ISIS/subs/libisis/utilib/u_check_unique.F for the description of the U_CHECK_UNIQUE routine. Then, look at the prototype for this in $ISISINC/u.h to see the list of paramters. (You might also want to look at the "binding" routines in $ISIS/subs/libisis/utilib/u_bind_F.c.) You will note that for this routine there is an extra parameter when calling it from C. This extra parameter specifies the length of the strings (which gets automatically supplied when called from Fortran).

For calling a C routine from a Fortran program, you need to look at the C source to see the description of the routine. You then need to look at the binding routine to see the exact list of parameters to be used when calling the routine from Fortran.

Note that you should explicitly declare the size of variables in your ISIS programs. This helps prevent problems when building the programs on various different computer platforms. For example, in Fortran use INTEGER*4 or REAL*4 rather than INTEGER or REAL. In C, use the ISIS data types INT4, FLOAT4, etc., rather than int, float, etc. See $ISISINC/isistypes.h for the defined ISIS data types.

To compile and link an application program, use a command such as:

    %make -f dsk2dsk.mak dsk2dsk

The directory $ISIS/idl/externals contains the source files for routines that can be called from an IDL program using CALL_EXTERNAL. These routines provide much greater flexibility than the simpler READISIS, WRITEISIS and READBACKPLANE routines.

If you want to be adventurous and just can't resist the temptation to re-build the entire ISIS system, the build scripts are located in $ISIS/build.

6.1 UPDATED FEATURES (as of ISIS Release 06-24-05, Version 2.3.0)

The reference systems for Linux, Solaris and Mac OS X are unchanged from our last release. ISIS binaries are built using Suse 9.0 for Linux, SunOS 5.9 for Solaris, and Panther (10.3) for Mac OS X. We are not actively developing ISIS with Tiger (10.4) on the Mac platform as of yet. We do understand that ISIS does run on Tiger, but you will have issues with compiling and linking against the ISIS binaries. As mentioned in a previous notice (Ref#1), we outlined the reference systems for each OS we support and compatability issues with each one.

The latest release of ISIS is available only through rsync. ISIS can be acquired from isisdist.wr.usgs.gov using rsync. Instructions for download and installation can be acquired from our ISIS Support site (Ref#2).

To get started, issue the following command:

        rsync isisdist.wr.usgs.gov::isis/install/quick_start.txt .

6.2 WHAT'S NEW

The majority of changes that occured in this release of ISIS are structural within the ISIS development infrastructure. The organization of the source directories has been modified and the make/build procedure has completely redesigned. Specific tests for particular hardware environments have been eliminated to better accomodate other architectures (e.g., Linux on AMD). GNU make is now required for all platforms. This is not an issue for Linux or Mac OS X as GNU make is standard for these platforms, however, this is not the case for Solaris. Developers must acquire and install GNU make if they wish to write ISIS software. The current version of ISIS is now reported in every ISIS application. This release is officially version "2.3.1-REL_1_0". The TAE software that ISIS uses as its user interface has also had a major overhaul of its make/build procedures. It now also requires GNU make in order for it to be built from source. This was required as the old procedure could no longer be maintained for the three platforms ISIS supports. ISIS is now using NAIF Version 58. There were no major differences in this version from the last. Only the addition of several new routines that we intend to utilize in future development efforts.

6.3 PROGRAMMING IN ISIS 2.3.X

One of the major goals of the reorganization of the ISIS development infrastructure was to minimize the impact on ISIS application development. That goal was achieved. Most of the impact in integrating ISIS source code from the Linux and Solaris version with Mac OS X affected the maintainence of ISIS shared libraries. The creation and use of shared libraries on the Mac OS X platform is significantly different than Linux and Solaris. This was the fundamental reason for redesigning the infrastructure. If you maintain your own ISIS library, see a Makefile in one of the directories in ISIS/subs as to see how they are currently maintained. For main applications, the typical make file should not require any modifications with the exception of C++ main applications. Below are a few of the major issues you may encounter with existing ISIS code that require modification in this release:

  1. Do not include malloc.h directly in C source code. It does not exist on the Mac OS X system. You should use stdlib.h or use isismalloc.h provided with this release to address this issue.
  2. C++ development in ISIS has been completely integrated in the development infrastructure. Use the same make file format as with a C main application. See the application in /apps/gen/deltack for an example.
  3. Oh by the way, you may now find some applications in directories of the same name. This is to better accomodate C++ application development as these applications typically result in numerous source files.
  4. The old use of make rules has change to usage of configuration files. This is mainly a conceptual difference that acheives the same thing. The files pertinent to building ISIS software can be found in $ISISMAKE for each platform. All files for each platform are included there.

6.4 NOTES FOR MAC OS X USERS

If you intend to do your own development, you will need to "ranlib" all the archive module libraries. These are the files that end with the '.a' file extention. We have not provided a script that does it but the following command is helpful:

        find  -name '*.a' -exec ranlib -s {} ;

This command will find all archive files and "ranlib" them. You will encounter link problems if you have not ranlib'ed all archive libraries after installation.

Please visit our new ISIS Support Center (Ref#2) for assistance and information with all things ISIS.

6.5 REFERENCES

Ref#1: http://isis.astrogeology.usgs.gov/IsisSupport/viewtopic.php?t=124 Initial announcement of this release containing important system and support information.

Ref#2: http://isis.astrogeology.usgs.gov/IsisSupport Our ISIS Support web page.

Ref#3: http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=90902 Bugzilla entry detailing the RedHat problem related to applications that hang unexplicably.

----
Documentation | Tutorials | Technical Documents | Isis Support Center (URL: http://isis.astrogeology.usgs.gov/IsisSupport/) | Home

Last updated: Mar 6 2012