USGS

ISIS 2 Documentation


Isis Exchanging Data with Other Software Systems

----

The following sections contain some suggestions on techniques for exchanging data between ISIS and other software systems. This includes the following subjects:

  1. GENERAL DATA EXPORT CONSIDERATIONS
  2. IMPORTING PDS IMAGE DATA
  3. IMPORTING MISSION-SPECIFIC IMAGE DATA
  4. IMPORTING "FOREIGN" IMAGE DATA
  5. EXPORTING "RAW" IMAGE DATA
  6. IMPORTING BAND_BIN INFORMATION TO ISIS CUBE FILES
  7. IMPORTING ASCII TABLE DATA
  8. EXPORTING TABLE DATA TO ASCII
  9. EXPORTING SPECTRA TO ASCII
  10. IMPORTING ASCII SPECTRAL LIBRARY DATA
  11. EXPORTING IMAGE DATA TO POSTSCRIPT
  12. EXPORTING IMAGE DATA TO JPEG AND TIFF
  13. WRITING IDL PROGRAMS
  14. EXCHANGING IMAGE DATA WITH VICAR
  15. EXCHANGING IMAGE DATA WITH PICS
  16. EXPORTING IMAGE DATA TO ENVI
  17. EXPORTING IMAGE DATA TO PHOTOSHOP
  18. EXPORTING IMAGE DATA TO ARC/INFO

1. GENERAL DATA EXPORT CONSIDERATIONS

For 8-bit and 16-bit pixel data types, the label keywords CORE_BASE and CORE_MULTIPLIER are applied to the 8-bit or 16-bit values stored in the core of an ISIS cube file in order to determine the real floating point pixel values that are being represented. The 8-bit or 16-bit core values considered alone do not give the correct pixel values. Other software systems do not understand the ISIS CORE_BASE and CORE_MULTIPLIER keyword values. Thus, it is usually desirable to run "dsk2dsk" to convert the cube files to 32-bit format before export to other software systems.

ISIS data files frequently contain ISIS special pixel values. Most other software systems do not understand these special pixel values. For example, in 32-bit floating point pixel format, the special pixel values are very large negative numbers that are near the lower end of the range of values that can be represented. Most other software systems have difficulty dealing with these numbers. Thus, when exporting ISIS data to other software systems, it is usually desirable to first translate the ISIS special pixels to more "reasonable" valid values, e.g. 0.0 or -1.0. This can be accomplished by running the "convert" program. It is not necessary to convert to a different platform format when doing this.

Some ISIS cube files can include suffix data, i.e., backplanes, sideplanes, and/or bottomplanes. Most other software systems are not able to directly handle these suffix data planes. For example, a software system might be able to access ISIS cube file image data by skipping over the ISIS cube label and history areas in the file. However, in a Band Sequential storage order cube, sideplane data pixels are stored at the end of each line of image data. Thus, it might be necessary to eliminate the backplane/sideplane/bottomplane data before exporting ISIS cube files to other software systems. The subcube specifier (TAE SFROM parameter) can be used to eliminate suffix data. For example, when running the "dsk2dsk" or "convert" programs described above, use SFROM="S(~(1-*)):S(~(1-*)):S(~(1-*))".

2. IMPORTING PDS IMAGE DATA

The "pds2isis" program converts PDS image data to ISIS cube file format.

3. IMPORTING MISSION-SPECIFIC IMAGE DATA

The "uax2isis" program converts UAX (University of Arizona) IMP (Imager for Mars Pathfinder) files to ISIS cube file format.

The "msi2isis" program converts NEAR Discovery MSI raw images, which are in a FITS format, to ISIS cube file format.

The "plancd" program converts JPL archive CD files to ISIS cube file format. This program handles files that are in the VICAR format for the Voyager, Viking, Mariner 9 and Mariner 10 missions.

4. IMPORTING "FOREIGN" IMAGE DATA

The "raw2isis" program converts "raw" image data to ISIS cube file format. This allows skipping over header or label information at the beginning of the file before reading the image data.

5. EXPORTING "RAW" IMAGE DATA

The "isis2raw" program converts the core data of an ISIS cube file to a "raw" image file that contains no label or history information. Some other software system are able to handle this "raw" image format.

6. IMPORTING BAND_BIN INFORMATION TO ISIS CUBE FILES

The "labels" program allows reading a list of values from an ASCII file and inserting it as the value of a keyword in the BAND_BIN group of a cube label. For example, this can include the list of wavelengths (BAND_BIN_CENTER) or the list of bandwidths (BAND_BIN_WIDTH). This can also include the solar spectrum (BAND_BIN_SOLAR_FLUX), which would then allow running the "solardiv" program to produce an I/F cube.

7. IMPORTING ASCII TABLE DATA

The "asc2tbl" program converts ASCII table data to an ISIS binary table file. If the table contains a spectrum, then the "ratiocs" program can then be used to normalize a cube by dividing by the spectrum. If the spectrum is a dark current measurement, then the "addspec" program can be used to subtract (with MUL=-1.0) the dark current from a spectral cube.

8. EXPORTING TABLE DATA TO ASCII

The "tbl2asc" program converts an ISIS binary table file to an ASCII table file.

9. EXPORTING SPECTRA TO ASCII

The "cubespec" program computes an average spectrum for a rectangular spatial area of a cube file and writes the result to an ISIS binary table file. "tbl2asc" can then be used to convert this to an ASCII table file. Note that the selected spatial area can include just a single spatial pixel.

When a multi-band cube is being displayed by "cv", the "Average Spectrum" functions (in the Statistics category in the Functions menu) compute and plot the average spectrum of a rectangular spatial region. The "AveSpec Output - Table File" function in the File menu in the plot window writes these data to an ISIS binary table file, which is in the same format as the file written by "cubespec". "tbl2asc" can then be used to convert this to an ASCII table file. As with "cubespec", the selected spatial area can include just a single spatial pixel. In addition, the "AveSpec List" function displays a list of the numerical values. Function buttons on this window allow writing the listing to an ASCII file.

The "Region of Interest" function in the "cv" program allows computing and plotting the average spectrum for an arbitrary spatial region. As with the rectangular region function, the data can be written to an ISIS binary table file, listed, and written to an ASCII table file. In addition, there is a function to write the average data to multiple ASCII files in one operation.

10. IMPORTING ASCII SPECTRAL LIBRARY DATA

The "asc2tbl" program converts a spectum in an ASCII table file to an ISIS binary table file. The "hdrkeys" program can then be used to set the values of the spectral header entries. Then, the "tbl2isl" program will insert the spectrum into an ISIS Instrument Spectral Library file.

11. EXPORTING IMAGE DATA TO POSTSCRIPT

In the "cv" program, the "PostScript Output" function in the Functions menu on the main display window writes the contents of one of the image display windows to a PostScript file. Note that this consists of the image as currently displayed in the window, including display stretch, color table selection, and spatial sub-sampling (for the subsampled display window).

12. EXPORTING IMAGE DATA TO JPEG AND TIFF

The "isis2std" program displays either a single band of an ISIS cube file as a gray-scale image or three selected bands as a Red/Green/Blue color composite image. It then writes the displayed image to either a JPEG format file or a TIFF format file. This includes the full spatial resolution of the cube file (without any subsampling that might be used in the display).

13. WRITING IDL PROGRAMS

The "readisis" routine, which is callable from an IDL program, reads the core of an ISIS cube file into an IDL array. The "writeisis" routine writes an IDL array to the core of a new ISIS cube file. This allows writing IDL programs that perform specialized processing of ISIS cubes. The "readbackplane" routine can also be used to read an ISIS backplane into and IDL array. Note that the "writeisis" routine writes only a minimal set of label keywords to the output file. Thus, a "readisis"/"writisis" sequence will lose much of the label information that was contained in the input file. It thus might be usefull to use the "cpylab" program to copy the label information from the input file to the output file.

Both "readisis" and "writeisis" are documented in the ISIS program lists even though they are not TAE programs.

14. EXCHANGING IMAGE DATA WITH VICAR

The "vicar2isis" and "isis2vicar" programs allow exchanging image data with the JPL VICAR software system. Note that these programs are only available on the some ISIS platforms (e.g., Solaris) because they use VICAR routines that exist only on these ISIS platforms. (Since they are not available on all platforms, these programs are not listed in the web-based ISIS documentation.)

15. EXCHANGING IMAGE DATA WITH PICS

The "pics2isis" and "isis2pics" programs allow exchanging image data with the USGS VAX/VMS Planetary Image Cartography (PICS) software system.

16. EXPORTING IMAGE DATA TO ENVI

First, create an ISIS cube that contains no special pixel values, contains floating point pixels, and does not contain any suffix planes (sideplanes, bottomplanes, or backplanes).

  1. Use the ISIS "convert" program to change all the special pixel values to some valid value (such as 0.0).

    Make note of the data type (type 1 is 8-bit, type 2 is 16-bit, type 3 is 32-bit or floating point), and whether suffix planes exist in the input file.

  2. Use the ISIS "dsk2dsk" program to convert the pixel data type to floating point (if necessary), and to remove any suffix planes.
        sfrom="::s(~(1-*))"		; removes backplanes
    	  - or -
        sfrom="s(~(1-*)):s(~(1-*)):s(~(1-*))"  ; removes side, bottom, back
    
        otype=3			; 32-bit or floating point
    
  3. Make note of the numbers of samples, lines, and bands in your input file. You will also need to know the size of the ISIS header to be offset. To do this, either record them while the ISIS programs are running, or just "more" the file (also see note below).

Next, start up ENVI. (The following instructions apply to ENVI 3.0. See Notes on Use of the IDL Display Programs for information on running ENVI with ISIS.) From the "File" menu, select "Open Image File" and select your cube file. ENVI will then give you a panel that allows you to specify parameters for the ENVI header to be created.

  1. Set the number of Samples, Lines, and Bands.
  2. Set Data Type to floating point.
  3. Set Byte Order to Network (IEEE).
  4. Set File Type to Unknown (under the "external" sub-menu).
  5. Set the Offset value (this specifies the number of bytes to skip over to get to the actual image data in the core of the cube file). Look in the label of your cube (use the "labels" program or just "more" it) and find the value of the ^QUBE keyword. This is the one-based record number of the start of the core data. Thus, the Offset for ENVI is the value of ^QUBE minus 1 times 512 (the record size in bytes).

17. EXPORTING IMAGE DATA TO PHOTOSHOP

If you are mostly interested in getting a single-band Photoshop image that looks nice, you might try the following. (If you need to have meaningful numbers for the pixel values and/or you have a mult-band image, then things are a bit more complex.)

First, run "dsk2dsk" to determine the range of values that occurs in your 32-bit image. (Use TO=" " to examine the core of the file without creating a new file.) Then, run "dsk2dsk" to convert your 32-bit file to 8-bit format. Specify an ORANGE that corresponds to the range of values determined by the first run of "dsk2dsk". (Or, specify any other desired range of values for ORANGE.) Then, run "isis2raw" (with default OTYPE and ORANGE) to create the output 8-bit raw file for input to Photoshop.

By the way, when reading a 16-bit raw file into Photoshop, there is a way to select the byte order for the input raw file. If you specify this wrong, you will of course not get the right image displayed in Photoshop.

18. EXPORTING IMAGE DATA TO ARC/INFO

There are two major problems one must understand when exporting ISIS image data to ARC/INFO if it is desired to preserve the georefrencing information supplied by SPICE.

First, ISIS cubes work in Lat, Lon coords no matter what projection they are in. In contrast, if an ARC/INFO image is in a projection other than "geographic" or Simple Cylindrical, it works in an X, Y coordinate system that is in meters or feet. Thus, if the image is in a Mercator or Lambert projection the only way for that image to be georeferenced is if you know in meters or feet where it should be located in its projection's coordinate system. (The coordinate system is defined by the projection's central lon, center lat, scale, standard parallels, east/north shifts, spheroid ...)

Second, GIS packages like Arc/Arcview only work in positive east longitude systems. Most planetary bodies are positive west, e.g., Mars. To get Mars images to work in ARC/INFO you must fool ARC/INFO. This is also explained below.

18.1 Creation of the ASCII header file

The image or .cub file must be renamed to have an extension defined by the layout parameter

    .bil  (mars.cub would be renamed mars.bil)
    .bsq
    .bip
Use a text editor to create an ASCII header file x.hdr (for the file x.cub) that looks like the following example:
/* START OF FILE
nrows 3050         /* nrows = nl
ncols 4570         /* ncols = ns
nbands 1           /* number of bands
nbits 8            /* pixel data type of image (8,16,...)
byteorder I        /* M,I for hardware arch.
layout bil         /* storage order of data (BIL,BSQ,BIP)
skipbytes 22016    /* skipbytes = RECORD_BYTES * (^QUBE - 1)
nodata 9999.0      /* NULL data value - optional - doesn't always see
/* END OF FILE
Note: the /* allows you have comments in the header. It is a good idea to keep them in there so you don't forget what they mean.

Note: RECORD_BYTES and ^QUBE are both in the ISIS cube file label. To see the label contents, run the "labels" program or simply "more" the cube file.

You can also have the georeferencing info in this header file. This is accomplished by adding the following keywords: (We usually use a world file instead - explained below).

xulcorner     345.535   /* for georeferencing middle of upper left pixel
yulcorner     7456.565  /* for georeferencing middle of upper left pixel
  - OR -
xllcorner     345.535   /* for georeferencing middle of lower left pixel
yllcorner     -6456.565 /* for georeferencing middle of lower left pixel
cellsize      100       /* for georeferencing (size of pixel on ground)
Note: you only need one pair of xulcorner,yulcorner or xllcorner,yllcorner for georeferencing.

18.2 Creation of the georefencing "world" file

For the world file we need the following (This file georeferences the image):

    x,y cell size
    rotation (should always be zero)
    top left pixel lat,lon in meters/feet (coords for the
        center of the pixel)

******example file format*******
file name: x.blw (erase from -> on)
28.50000000000000  -> X cellsize (ex. 28.5 meters)
0.00000000000000  -> should be zero if not rectifying
0.00000000000000  -> should be zero if not rectifying
-28.50000000000000  -> Y cellsize (usually same as X and negative -
                         MAKE SURE NEGATIVE)
13356427.02278839100000  -> x in projected meters or feet
813809.65608045168000  -> y in project meters or feet
If image is a Sunraster then world file is image.rsw
if image is a BSQ then image.bqw
if image is a TIFF then image.tfw
...

To get the lat,lon into y,x you can do the commands in ARC. Create a new file with the lon lat (x,y) on one line.

Example File: mars_tic.txt
120.245345 45.4534533

ARC> project file mars_tic.txt mars_merc
     input
     projection geographic
     units dd
     parameter
     output
     projection mercator
     units meters
     parameter 3393400 3375700 (semi-major, semi minor axis for MARS)
                               (define spheroid here)
     ...
     ...  In this area fill out parameters that are needed like
     ...  central merdian, parallels ...  Always skip "SHIFT" for planets
     ...
     END
Now look at the file mars_merc.tic and it will have the lon, lat in meters in projection.

If you only have the top left of the top left pixel then subtract 1/2 of the x cell size to the coord and subtract 1/2 of the y cell size. (Note since the y cell size is negative you will really be adding.) Here is an illustration:

Top left pixel

     *----------
     |         |
     |         |  the world file needs the @ location but usually only
     |    @    |  the * location is known, this is when you need to shift
     |         |  the coords by 1/2 of the x and y cell size to
     |         |  get to the @ coords.
     -----------

We will diverge into a small section on vector files. Since Arc/Arcview cannot project images on the fly (only vector coverages) the image must be georefenced first. If the vector data is in lat, lon you must project it to the same projection as the image. This would be another way to get a lat lon point into meters for the image's world file.

To get Arcview to project vector information on Mars, we have a small Arcview script that allows you to accomplish this. You can also update the default.prj file and add Mars but this script is easier. This will allow you to bring over a lat/lon graticule to lay over the georeferenced image.

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' MarsSinu.ave
' By Trent Hare - USGS Flagstaff, AZ
'
' This will only work for Sinusoidal.  For other projections
' look in the Arcview help on the particular projection.
' This script will project Lat, Lon vector data into a
' Sinusoidal projection defined by a Mars spheroid in meters
'
theView = av.GetActiveDoc

p = Sinusoid.Make(theView.ReturnExtent)
p.SetSpheroid(#SPHEROID_SPHERE)
p.SetCentralMeridian(0.0)
s = p.GetSpheroid
s.SetMajorAndMinorAxes(3393400.0,3375700.0)
theView.SetUnits(#UNITS_LINEAR_METERS)
theView.SetProjection(p)

theView.Invalidate
Return
' end MarsSinu.ave
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
INFO about Coordinates:
Mars coords looks like (see below), since it is positive west (defined by direction of the spheres' rotation).
  ----------------------------------------
  |               MARS                   |
  |                 |                    |
 180 <----90------  0                    |
  |                and                   |
  |                 0 -----(-90)----->  -180
  |                 |                    |
  |                 |                    |
  |                 |                    |
  ----------------------------------------
Arcview likes -180->180 (Earth) which is called positive east (rotates opposite of Mars) So again you must convert the coordinates (basically negate all longitudes for Mars to fit in an Earth based system)
  ----------------------------------------
  |                 |                    |
  |                 |                    |
 -180 <---(-90)---- 0                    |
  |                and                   |
  |                 0  ------90------>  180
  |                 |                    |
  |                 |                    |
  |                 |                    |
  ----------------------------------------
Mars can also look like:
(this also needs to be changed to Earth coord above)
  ----------------------------------------
  |                 |                    |
  |                 |                    |
 180 <----(90)----- 0                    |
  |                and                   |
  |                360  <----(270)----- 180
  |                 |                    |
  |                 |                    |
  |                 |                    |
  ----------------------------------------

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

Last updated: Oct 24 2003