ISIS 2 Documentation
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:
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-*))".
The "pds2isis" program converts PDS image data to ISIS cube file format.
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.
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.
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.
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.
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.
The "tbl2asc" program converts an ISIS binary table file to an ASCII table file.
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.
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.
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).
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).
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.
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.)
The "pics2isis" and "isis2pics" programs allow exchanging image data with the USGS VAX/VMS Planetary Image Cartography (PICS) software system.
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).
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.
sfrom="::s(~(1-*))" ; removes backplanes
- or -
sfrom="s(~(1-*)):s(~(1-*)):s(~(1-*))" ; removes side, bottom, back
otype=3 ; 32-bit or floating point
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.
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.
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.
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 FILENote: 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.
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 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 | | | | 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:
---------------------------------------- | | | | | | 180 <----(90)----- 0 | | and | | 360 <----(270)----- 180 | | | | | | | | | ----------------------------------------