PDS_VERSION_ID = PDS3 RECORD_TYPE = STREAM DATA_SET_ID = "VG1/VG2-S-ISS-2/3/4/6-PROCESSED-V1.0" OBJECT = TEXT PUBLICATION_DATE = 2006-08-15 NOTE = "Tutorial on how to use the files in this data set." END_OBJECT = TEXT END Tutorial for the Processed Voyager Image Data Set ================================================= This document provides a tutorial on how to make optimal use of this data set. It is organized as follows: 1. Data Set Overview 2. Volume Organization 2.1 Volume Names 2.2 Directory Structure 2.3 File Names 3. File and Data Formats 3.1 ASCII Text Files 3.2 Binary Data Files 3.3 Binary Integers 3.4 Binary Floating-Point (REAL) Numbers 4. PDS Labels 4.1 Types of Labels 4.2 Image Labels 4.3 Table Labels 5. VICAR Files 5.1 VICAR Overview 5.2 Voyager Image File Structure 5.3 VICAR Headers 5.4 VICAR Tables 6. Voyager Imaging Overview 6.1 Reseau Markings and Geometry 6.2 Dark Current 6.3 Calibration 1. Data Set Overview ==================== This data set contains calibrated and geometrically corrected versions of all the Voyager images from Saturn. It has been derived from the original PDS data set VG1/VG2-S-ISS-2-EDR-V1.0, which is archived on volumes VG_0004, VG_0005, and VG_0026 through VG_0038. The original data set contains raw experiment data record (EDR) files in compressed format. This much larger data set contains the same images but uncompressed and at several levels of processing. It should be substantially easier to use. Also included are ancillary files for any user who might wish to revisit one or more of the steps in the image processing. The files have been generated using the VICAR software, as provided by JPL's Multi-mission Image Processing Laboratory. See their home page at http://www-mipl.jpl.nasa.gov/ for more information. The complete processing history of the images is discussed in the file DOCUMENT/PROCESSING.TXT 2. Volume Organization ====================== 2.1 Volume Names ---------------- The PDS originally released raw, compressed "EDR" versions of all the Voyager images on a set of CD-ROMs identified as VG_0001 through VG_0038. The organization is as follows: VG_0001-0003: The complete Uranus images. VG_0004-0005: Selected Saturn images. VG_0006-0008: Selected Jupiter images. VG_0009-0012: The complete Neptune images. VG_0013-0025: The complete Jupiter images. VG_0026-0038: The complete Saturn images. This derived set of volumes is identified VGISS_0001 through VGISS_0038. For simplicity, we have maintained a one-to-one correspondence between the old and new volumes. This data set comprises all the Saturn images, i.e. volumes 4, 5 and 26-38. The boundaries between volumes are chronological, as defined by Voyager's Flight Data System ("FDS") clock. Within the Saturn data set, boundaries between volumes are as follows: VG_0004: Selected images 33575.27 - 43901.56 VG_0005: Selected images 43901.59 - 44304.45 VG_0026: All images 32499.21 - 33562.53 VG_0027: All images 33562.55 - 34476.28 VG_0028: All images 34476.32 - 34781.49 VG_0029: All images 34781.52 - 35028.01 VG_0030: All images 35028.06 - 35363.02 VG_0031: All images 35363.06 - 35629.19 VG_0032: All images 35629.23 - 35893.16 VG_0033: All images 35893.19 - 42278.08 VG_0034: All images 42278.14 - 43290.40 VG_0035: All images 43290.46 - 43579.44 VG_0036: All images 43579.47 - 43863.41 VG_0037: All images 43863.44 - 44157.24 VG_0038: All images 44157.28 - 44304.52 As a general rule, Saturn images beginning with 3 are from Voyager 1 and those beginning with 4 are from Voyager 2. 2.2 Directory Structure ----------------------- The directory structure matches that of the original Voyager image volumes. Each new volume VGISS_00xx contains the same images and follows the same structure as that of the original EDR volume VG_00xx. At the top levels of each volume, images are organized by nominal target. Directories are named as follows. CALIB Calibration (typically dark current) images (Volumes VG_0004 and VG_0005). CALIB/DARK Alternative dark current directory (Volumes VG_0026 to VG_0038). CALYPSO DIONE ENCELADU Short for Enceladus EPIMETHE Short for Epimetheus HELENE HYPERION IAPETUS MIMAS OTHER/SKY Sky images OTHER/STAR Star images PANDORA PHOEBE PROMETHE Short for Prometheus RHEA SATURN S_RINGS TETHYS TELESTO TITAN UNK_SAT For satellites that were unnamed at the time of imaging. Many of these are now identified as the smaller moons Helene, Telesto, Calypso, Prometheus and Pandora. Note that these are nominal targets; many images contain more than one target and some images missed their intended target, so the directory structure provides nothing more than general guidance about what images may be of interest. Image search tools at the PDS Rings Node, http://pds-rings.seti.org/catalog/ may provide further guidance. When the aforementioned directory would contain a large number of images, it is further subdivided by FDS count. Subdirectories are named CnnnnXXX, where 'nnnn' is replaced by the first four digits of the FDS count, and all the images beginning with those four digits are found within. 2.3 File Names -------------- All files are named by the associated seven-digit FDS clock count (without a decimal point) at the time the image was read out of the camera. For example, a file named C3456712*.* is associated with the image read out at FDS time 34567.12. For most images, this corresponds to the time when an exposure ended; however, in some circumstances (modes "BOTSIM" and "BSIMAN") both the wide-angle and narrow-angle cameras were triggered simultaneously; under these circumstances, the narrow-angle camera was read out first and the wide-angle image has an FDS number a few digits higher (as defined by the scan rate; see below). In the original raw, compressed volumes, files were named Cnnnnnnn.IMQ where 'nnnnnnn' is the FDS count and "IMQ" indicates that the file is a compressed image. In this data set, the associated files have the following names: Cnnnnnnn_RAW.IMG: uncompressed, raw image. Cnnnnnnn_RAW.LBL: detached PDS label for the above. Cnnnnnnn_CLEANED.IMG: cleaned version of the image, with spikes and reseau markings erased. Cnnnnnnn_CLEANED.LBL: detached PDS label for the above. Cnnnnnnn_RESLOC.DAT: binary table of reseau marking locations. Cnnnnnnn_RESLOC.TAB: ASCII table of reseau marking locations. Cnnnnnnn_RESLOC.LBL: combined-detached PDS label for both of the above. Cnnnnnnn_CALIB.IMG: calibrated image. Cnnnnnnn_CALIB.LBL: detached PDS label for the above. Included in the label is the rough conversion factor from pixel values to absolute reflectivity. Cnnnnnnn_GEOMA.DAT: binary table of tie points for modeling the geometric distortion. Cnnnnnnn_GEOMA.TAB: ASCII table containing the same information as the above. Cnnnnnnn_GEOMA.LBL: combined-detached PDS label for both of the above. Cnnnnnnn_GEOMED.IMG: geometrically corrected version of the calibrated image. Cnnnnnnn_GEOMED.LBL: detached PDS label for the above. Thus, almost every Voyager image from Saturn has 14 associated files in this data set. On a few occasions, files on the original EDR volumes were found to be corrupted. In those cases, a smaller number of files might be found. An uncompressed raw version of every image is present, however. 3. File and Data Formats ======================== Data files on this volume are named according to PDS standards, where the characters after the period indicate the file type. The file types used for data on this volume are: ASCII text files: PDS labels *.LBL ASCII tables and indices *.TAB Binary files Binary images *.IMG Binary data files *.DAT 3.1 ASCII Text Files -------------------- Different popular operating systems use different standards for how ASCII text files are formatted. On Unix systems, lines are terminated by a (linefeed character, control-J, ASCII 10). On Macintosh computers, lines in many text files are terminated by a (carriage return character, control-M, ASCII 13). On PCs, lines are terminated by a pair. PDS standards require all text files to use line termination. If the PDS label indicates INTERCHANGE_FORMAT = ASCII or RECORD_TYPE = STREAM, then this line termination is in use. On occasion, users on Unix and Macintosh computers may need to change the line termination on some text files before they can use them. This can be handled via text editors or a variety of utilities. For example, the Unix tr (translate) command can be used to change carriage returns to blanks: tr "\015" " " newfile.txt ASCII tables indicate RECORD_TYPE = FIXED_LENGTH and include an additional parameter RECORD_BYTES, which indicates the length in bytes of each record in the file. It should be noted that all ASCII files still include the line terminators, and these two bytes are included in the byte count. For this reason, it is unwise to convert the line terminator to a single character ( on Unix or sometimes on Macintosh) because this can change the number of bytes per record and make it incompatible with the label. In these situations, it is recommended that the line terminator be replaced by a space plus or a space plus instead. 3.2 Binary Data Files --------------------- The binary files on this volume are provided in VICAR format. This is a relatively simple fixed-length binary file format consisting of an ASCII header followed by consecutive rows of the image as binary integers. See http://www-mipl.jpl.nasa.gov/vicar/vic_file_fmt.html for a complete description of the VICAR file format. This information can also be found in DOCUMENT/VICAR.HTML and DOCUMENT/VICAR.ASC. 3.3 Binary Integers ------------------- Some image files contain two-byte integers. All binary integers are in least-significant byte (LSB) format, meaning that the least significant byte comes first. This is the native format for Intel-based computers. Users of these computers should be able to read the two-byte data files directly. Sun and Macintosh PowerPC-based computers order their bytes differently, with the most-significant byte (MSB) first. Users of these computers will need to perform a pair-wise swap of the bytes prior to using the numbers in these data files. Here is a sample FORTRAN function to convert an LSB two-byte integer to its MSB value. It could be easily ported to another language. c*********************************************************************** c Function to return swapped value of a two-byte integer c*********************************************************************** integer*2 function MSB_int2(value) integer*2 value c Equivalence declarations so that bytes can be accessed individually integer*2 oldval, newval byte oldbytes(2), newbytes(2) equivalence (oldval, oldbytes(1)) equivalence (newval, newbytes(1)) c Swap bytes oldval = value newbytes(1) = oldbytes(2) newbytes(2) = oldbytes(1) c Return swapped value MSB_int = newval return end c*********************************************************************** 3.4 Binary Floating-Point (REAL) Numbers ---------------------------------------- Floating-point (REAL) binary numbers are in the native Vax D-floating format. This format is no longer widely used so most of these files have also been converted to ASCII text format for convenience. For the rare user who might wish to interpret Vax binary values, the following FORTRAN subroutine converts from Vax D floats to IEEE (MSB) floats. It could be readily converted to any other language: c*********************************************************************** c Function to return the IEEE equivalent of a Vax D-float c*********************************************************************** real*4 function IEEE_float4(value) real*4 value c Equivalence declarations so that bytes can be accessed individually real*4 oldval, newval byte oldbytes(4), newbytes(4) equivalence (oldval, oldbytes(1)) equivalence (newval, newbytes(1)) c Swap bytes to convert from Vax ordering: 1-2-3-4 to 2-1-4-3 oldval = value newbytes(1) = oldbytes(2) newbytes(2) = oldbytes(1) newbutes(3) = oldbytes(4) newbytes(4) = oldbytes(3) c Update exponent IEEE_float4 = newval * 4. return end c*********************************************************************** For binary floating-point numbers on LSB platforms such as Intel, the byte ordering is reversed: c*********************************************************************** c Function to return the LSB real equivalent of a Vax D-float c*********************************************************************** real*4 function LSB_float4(value) real*4 value c Equivalence declarations so that bytes can be accessed individually real*4 oldval, newval byte oldbytes(4), newbytes(4) equivalence (oldval, oldbytes(1)) equivalence (newval, newbytes(1)) c Swap bytes to convert from Vax ordering: 1-2-3-4 to 3-4-1-2 oldval = value newbytes(1) = oldbytes(3) newbytes(2) = oldbytes(4) newbutes(3) = oldbytes(1) newbytes(4) = oldbytes(2) c Update exponent LSB_float4 = newval * 4. return end c*********************************************************************** 4. PDS Labels ============= 4.1 Types of Labels ------------------- On this volume, every data file has a detached PDS label. Whatever the name of the data file (*.IMG, *.DAT, or *.TAB), there is a corresponding file *.LBL that describes it. The labels are of two types. Images have a simple detached label, which means that 'image.LBL' describes the single file 'image.IMG'. Tables have combined- detached labels, which means that the pair of files 'table.DAT' and 'table.TAB', which have the same name but different extensions, are both described by the single label file 'table.LBL'. PDS labels contain nothing but ASCII text and can be viewed using any editor or word processor software. However labels have a very specific format that can be read by humans and also (relatively) easily parsed by computers. A label consists of a sequence of expressions of the form "keyword = value". These keywords are sometimes nested inside data objects, indicated by "OBJECT = xxx" and terminated by "END_OBJECT = xxx". These data objects describe specific components of the corresponding data files. PDS objects can be nested; for example a PDS TABLE object generally contains multiple COLUMN objects. Keywords inside the TABLE object describe the overall properties of the table, and afterward the keywords inside each COLUMN object describe one particular column. PDS maintains definitions of the keywords that appear in labels. They can be found in the PDS Data Dictionary. A lookup tool can be found at http://pds.jpl.nasa.gov/tools/data_dictionary_lookup.cfm This page also provides a link to the dictionary file itself. For convenience, all the keywords used in this data set have been extracted from the global data dictionary and are found in DOCUMENT/PDSDD.TXT. 4.2 Image Labels ---------------- Here is an annotated example of an image label. It refers to file DIONE/C3488236_CALIB.IMG on volume VG_0004. The label begins with information about the structure of the data file: PDS_VERSION_ID = PDS3 RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 1600 FILE_RECORDS = 802 ^VICAR_HEADER = ("C3488236_CALIB.IMG", 1) ^IMAGE = ("C3488236_CALIB.IMG", 2) ^VICAR_EXTENSION_HEADER = ("C3488236_CALIB.IMG", 802) This indicates that file contains 802 fixed-length records, each of which is 1600 bytes long. The file is organized in three parts: a VICAR header, an image, and finally a VICAR extension header. The header appears in the first 1600-byte record of the file. The image appears beginning in the second record and continues for the next 800 records total. Finally, the extension header occupies the final (802nd) record of the file. Next come some cataloging parameters related to the file: DATA_SET_ID = "VG1/VG2-S-ISS-2/3/4/6-PROCESSED-V1.0" PRODUCT_ID = "C3488236_CALIB.IMG.V1" PRODUCT_CREATION_TIME = 2006-07-01T16:00:00 SOURCE_PRODUCT_ID = ("C3488236_CLEANED.IMG.V1", "DC1_NA_31_C3486307_07.IMG", "FICOR77_VG1_NA_UV.DAT", "VGRSCF.DAT") PRODUCT_TYPE = CALIBRATED_IMAGE This includes information about the data set and the product. The product ID is unique for each label file in the data set; it generally corresponds to the name of the data file. However, in a few cases the same image appears twice in this data set, in which case the first occurrence has a ".V1" suffix (which stands for "Version 1"). Most commonly, images are duplicated because they appeared first on the "sampler" volumes VG_0004 and VG_0005. Occasionally, images are duplicated because a later version appeared in the FOUND directory of the final volume, VG_0038. Regardless of the reason, it is recommended that the user at least check the later version of the same image to determine if the files are the same. If differences appear, the later version (without the ".V1" suffix in the product ID) is probably to be preferred. Also listed are the ID or IDs of the files that were used in the processing of this particular file; because this is a calibrated image, it has been generated from the corresponding cleaned image "C3488236_CLEANED.IMG.V1", a dark current file "DC1_NA_31_C3486307_07.IMG", a calibration model "FICOR77_VG1_NA_UV.DAT", and a calibration update "VGRSCF.DAT". When a parameter has multiple values such as this one, the sequence is surrounded by parentheses and separated by commas. Note that parameter values can extend across multiple lines as needed. Next come some descriptive parameters relating to the particular image: /* Image Description */ SPACECRAFT_NAME = "VOYAGER 1" SPACECRAFT_ID = VG1 INSTRUMENT_NAME = "IMAGING SCIENCE SUBSYSTEM - NARROW ANGLE CAMERA" INSTRUMENT_ID = "ISSN" MISSION_PHASE_NAME = "SATURN ENCOUNTER" TARGET_NAME = "DIONE" IMAGE_ID = "1720S1-003" IMAGE_NUMBER = 34882.36 IMAGE_TIME = 1980-11-10T22:38:10.00 EARTH_RECEIVED_TIME = 1980-11-11T00:02:59 SCAN_MODE_ID = "3:1" SHUTTER_MODE_ID = "NAONLY" GAIN_MODE_ID = "LOW" EDIT_MODE_ID = "1:1" FILTER_NAME = "UV" FILTER_NUMBER = 7 EXPOSURE_DURATION = 2.880 START_TIME = 1980-11-10T22:38:07.12 STOP_TIME = 1980-11-10T22:38:10.00 SPACECRAFT_CLOCK_START_COUNT = "34882:35:752" SPACECRAFT_CLOCK_STOP_COUNT = "34882:36:001" NOTE = "Optical navigation + multispectral longitude coverage; 1 of 5 frames." Note that comments appear between /* and */. Also, when needed, a value is accompanied by units surrounded by "<>" as in the EXPOSURE_DURATION above. Following is a relatively informative description of the file: DESCRIPTION = "This image is the result of calibrating the corresponding CLEANED image (C3488236_CLEANED.IMG). It was created ...." Last come the descriptions of the three objects in the file, as pointed to near the top of the file. The VICAR header is described very briefly here: OBJECT = VICAR_HEADER HEADER_TYPE = VICAR BYTES = 1600 RECORDS = 1 INTERCHANGE_FORMAT = ASCII DESCRIPTION = "VICAR format label for the image." END_OBJECT = VICAR_HEADER Note that the size and number of records are indicated. The INTERCHANGE_FORMAT parameter indicates that VICAR headers are simple ASCII text. Next the image is described: OBJECT = IMAGE LINES = 800 LINE_SAMPLES = 800 SAMPLE_TYPE = LSB_INTEGER SAMPLE_BITS = 16 SAMPLE_DISPLAY_DIRECTION = RIGHT LINE_DISPLAY_DIRECTION = DOWN HORIZONTAL_PIXEL_FOV = 5.2250E-04 /* approximate */ VERTICAL_PIXEL_FOV = 5.2250E-04 /* approximate */ HORIZONTAL_FOV = 0.4180 /* approximate */ VERTICAL_FOV = 0.4180 /* approximate */ REFLECTANCE_SCALING_FACTOR = 3.3450E-04 END_OBJECT = IMAGE The basic information is that the image has 800 lines, 800 samples per line, and that each pixel is given as a 16-bit (i.e., two-byte) integer with least- significant byte (LSB) first. Additional parameters provide information about how to display the image and some (in this case very approximate) information about the field of view. Third comes the description of the VICAR extension header: OBJECT = VICAR_EXTENSION_HEADER HEADER_TYPE = VICAR BYTES = 1600 RECORDS = 1 INTERCHANGE_FORMAT = ASCII DESCRIPTION = "Continuation of the VICAR header." END_OBJECT = VICAR_EXTENSION_HEADER Finally, every PDS label ends with an END statement. END 4.3 Table Labels ---------------- All tables on this data set appear in two forms, binary (xxx.DAT) and ASCII (xxx.TAB). The ASCII forms are intended for typical users; the binary versions are included simply for completeness. The files have the same names but different extensions. These pairs of files are described by a single combined- detached PDS label (xxx.LBL). The structure of a combined-detached label differs a bit from the simple detached labels described above. Here is an annotated example, from DIONE/C3488236_RESLOC.LBL on volume VG_0004. The file begins with the same version information as before: PDS_VERSION_ID = PDS3 However, details of the file format do not appear at the top of the label. The next information is the cataloging information: DATA_SET_ID = "VG1/VG2-S-ISS-2/3/4/6-PROCESSED-V1.0" PRODUCT_CREATION_TIME = 2006-07-01T16:00:00 PRODUCT_ID = "C3488236_RESLOC.DAT.V1" SOURCE_PRODUCT_ID = "C3488236_RAW.IMG.V1" PRODUCT_TYPE = RESEAU_TABLE The next section provides the parameters of the corresponding image, and is identical to the analogous section in the image labels: /* Image Description */ SPACECRAFT_NAME = "VOYAGER 1" SPACECRAFT_ID = VG1 ... NOTE = "Optical navigation + multispectral longitude coverage; 1 of 5 frames." Next the two individual files are described via PDS FILE objects. The binary, VICAR-format file is described first. As you can see, this contains the same structural information as is found at the top of a simple detached label. /* Label for VICAR-format file */ OBJECT = VICAR_FILE FILE_NAME = "C3488236_RESLOC.DAT" RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 512 FILE_RECORDS = 13 ^VICAR_HEADER = ("C3488236_RESLOC.DAT", 1) ^BINARY_TABLE = ("C3488236_RESLOC.DAT", 1557 ) ^VICAR_EXTENSION_HEADER = ("C3488236_RESLOC.DAT", 8) DESCRIPTION = "This file contains a table of ...." ... END_OBJECT = VICAR_FILE Because the VICAR file will not be widely used, we skip ahead here to the ASCII table file for further details. As with the binary case, the label for the ASCII file begins with structural information: /* Label for derived ASCII-format file */ OBJECT = ASCII_TABLE_FILE FILE_NAME = "C3488236_RESLOC.TAB" RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 27 FILE_RECORDS = 202 ^TABLE = ("C3488236_RESLOC.TAB", 1) DESCRIPTION = "This is a table of ...." ASCII tables, like binary tables, consist of fixed-length records. Note that the record length identified by the RECORD_BYTES keyword includes the final carriage return and line feed that marks the end of each record in an ASCII file. Next we describe the table. A table is organized by rows and columns: OBJECT = TABLE INTERCHANGE_FORMAT = ASCII ROWS = 202 COLUMNS = 4 ROW_BYTES = 27 Nested within the PDS TABLE object is a sequence of COLUMN object, one describing each column of the table, in order: OBJECT = COLUMN NAME = ROW_NUMBER START_BYTE = 1 BYTES = 3 DATA_TYPE = ASCII_INTEGER FORMAT = "I3" DESCRIPTION = "The row number in the file, 1-202." END_OBJECT = COLUMN OBJECT = COLUMN NAME = LINE START_BYTE = 5 ... END_OBJECT = COLUMN OBJECT = COLUMN NAME = SAMPLE ... END_OBJECT = COLUMN OBJECT = COLUMN NAME = RESEAU_NUMBER ... END_OBJECT = COLUMN Note that a name and brief description are included for each column. The START_BYTE keyword indicates where each value begins within the row, with numbering starting at 1. Finally the nested objects in the file are terminated, followed by the END statement. END_OBJECT = TABLE END_OBJECT = ASCII_TABLE_FILE END The table file itself consists of formatted fields separated by commas. For example, here are the first few lines of the table described above. 1, 3.2653, 11.0521, 1 2, -1.1518, 50.3261, 3 3, 1.2436,126.0593, 4 4, 0.3144,205.2472, 5 --- -------- -------- --- | LINE SAMPLE RESEAU_NUMBER | ROW_NUMBER 5. VICAR Files ============== 5.1 VICAR Overview ------------------ As noted above, the binary data files on this volume (*.IMG and *.DAT) are in VICAR format. VICAR files have fixed-length records, with one or more leading records containing the VICAR header. Following the header is the data file, generally in binary format. You can read the VICAR header relatively easily by importing it into your favorite text editor. You can also type it to a terminal or perhaps use the Unix 'strings' command. Note that under some circumstances, the act of processing a file creates a revised VICAR header that no longer fits in the allotted number of records at the top of the file. When this happens, the remainder of the VICAR information is appended to the end of the file in a "VICAR extension header." The PDS labels on the data files usually indicate whether an extension header is present; it can be easily overlooked if you merely scan the beginning of a data file. 5.2 Voyager Image File Structure -------------------------------- The image files on this volume have a particularly simple format, where one line of the image corresponds to one record of the file. Here are the details of how most of the image files are structured. ------------------------------------------------------------------------ File Record Header Extension Bytes per Samples Lines per Type Bytes Records Records Sample per Line Image ------------------------------------------------------------------------ RAW 1024[1] 1 1 1[2] 800 800 CLEANED 800 2 0 1[2] 800 800 CALIB 1600 1 1 2[3] 800 800 GEOMED 2000 1 0 2[3] 1000 1000 ------------------------------------------------------------------------ Notes: [1] In the RAW images, the first 224 bytes of each record contain "housekeeping" data and should be ignored. The final 800 bytes contain the image data. [2] Single-byte images contain unsigned values ranging from 0 to 255. [3] Two-byte images contain signed values ranging from -32768 to 32767. The least-significant byte comes first. The above table contains everything you need to know if your goal is to write a simple program to read the image data from a file. Declare an array with the specified number of samples and lines, using the specified data type. Open the file as fixed-length records of the given length. Read or skip over the given number of header records. Then read the next sequence of records into the array. Specifically for raw images, you should read the first 224 bytes of each record into a dummy array, followed by the remaining 800 going into a row of your image array. When reading an image, you can ignore any extension records. 5.3 VICAR Headers ----------------- Each VICAR header contains a variety of useful information about the image. However, the typical user need not worry about the details of the headers; the table above should provide sufficient information to read any file, and the PDS label contains most of the key information about each image. Nevertheless, some information about the processing history of each image can be found only in the header. Here we provide a few samples. Note that the actual headers contain no line breaks; breaks have been added here to enhance readability. Note also that the complete details of the VICAR file format are given elsewhere, in DOCUMENT/VICAR.HTML and VICAR.ASC. Here is a VICAR header for a raw image, S_RINGS/C3499442_RAW.IMG. LBLSIZE=1024 FORMAT='BYTE' TYPE='IMAGE' BUFSIZ=20480 DIM=3 EOL=1 RECSIZE=1024 ORG='BSQ' NL=800 NS=800 NB=1 N1=800 N2=800 N3=1 N4=0 NBB=224 NLB=2 HOST='AXP-VMS' INTFMT='LOW' REALFMT='VAX' BHOST='VAX-VMS' BINTFMT='LOW' BREALFMT='VAX' BLTYPE='' TASK='TASK' USER='SHOWALTER' DAT_TIM='Thu Aug 4 15:56:10 2005' LAB01=' 800 800 800 800 L 1 SC' LAB02='VGR-1 FDS 34994.42 PICNO 1246S1+001 SCET 80.319 16:18:59 C' LAB03='WA CAMERA EXP 15360.0 MSEC FILT 2(CLEAR ) LO GAIN SCAN RATE 3:1 C' LAB04='ERT 80.319 17:43:40 1/ 1 FULL RES VIDICON TEMP -80.00 DEG C C' LAB05='IN/113880/19 OUT/xxxxxx/xx S_RINGS DSS #14 BIT SNR 7.641 C' LAB06=' xxxxx A/xxxxxxxx B/xxxx C/xxxx D/xxxxxxxx ETLM/xxxxxxxxxxxxxxxxxxxxS AC' LAB07='NA OPCAL xx(015360.0*MSEC)PIXAVG 000/0 OPERATIONAL MODE 3(WAONLY) AC' Note in particular that the strings in the header identified by "LAB01" through "LAB07" provide a number of operating details of the camera for this particular image. At each step in the processing, further information is appended to the header. Here is the header for the cleaned image, S_RINGS/C3499442_CLEANED.IMG. LBLSIZE=1600 FORMAT='BYTE' TYPE='IMAGE' BUFSIZ=20480 DIM=3 EOL=0 RECSIZE=800 ORG='BSQ' NL=800 NS=800 NB=1 N1=800 N2=800 N3=1 N4=0 NBB=0 NLB=0 HOST='AXP-VMS' INTFMT='LOW' REALFMT='VAX' BHOST='VAX-VMS' BINTFMT='LOW' BREALFMT='VAX' BLTYPE='' TASK='TASK' USER='SHOWALTER' DAT_TIM='Thu Aug 4 15:56:10 2005' LAB01=' 800 800 800 800 L 1 SC' LAB02='VGR-1 FDS 34994.42 PICNO 1246S1+001 SCET 80.319 16:18:59 C' LAB03='WA CAMERA EXP 15360.0 MSEC FILT 2(CLEAR ) LO GAIN SCAN RATE 3:1 C' LAB04='ERT 80.319 17:43:40 1/ 1 FULL RES VIDICON TEMP -80.00 DEG C C' LAB05='IN/113880/19 OUT/xxxxxx/xx S_RINGS DSS #14 BIT SNR 7.641 C' LAB06=' xxxxx A/xxxxxxxx B/xxxx C/xxxx D/xxxxxxxx ETLM/xxxxxxxxxxxxxxxxxxxxS AC' LAB07='NA OPCAL xx(015360.0*MSEC)PIXAVG 000/0 OPERATIONAL MODE 3(WAONLY) AC' LAB08='CAM ECAL CYCLE BEAM RESET OPEN CLOSE FLOOD AEXPM FIL G1 SHUT MODE AC' LAB09='NA NO PREP NO YES NO NO NO NO 0 P * NORMAL AC' LAB10='WA NO READ YES NO NO NO NO NO 2 P 7 NORMAL AC' LAB11='LSB_TRUNC=OFF TLM_MODE=GS-4B COMPRESSION=OFF L' NLABS=11 TASK='VGRFILLI' USER='SHOWALTER' DAT_TIM='Wed Aug 24 21:00:15 2005' LIN_CNT=1 TASK='RESSAR77' USER='SHOWALTER' DAT_TIM='Wed Aug 24 21:00:17 2005' PIX_CNT=17647 TASK='ADESPIKE' USER='SHOWALTER' DAT_TIM='Wed Aug 24 21:00:18 2005' ADJ_LINE=1160 SAM_LINE=351 Here some of the structural information about the file (e.g., LBLSIZE) has been updated and a few additional LABnn lines have been added. Afterward, each task that has modified the file is described by a new entry beginning with TASK='...'. For example, this label indicates that VICAR routine RESSAR77 was run on August 24, 2005 and resulted in the modification of 17647 image pixels. (The particular routines listed here, VGRFILLIN, RESSAR77 and ADESPIKE, are described in DOCUMENT/PROCESSING.TXT.) The header for the calibrated image S_RINGS/C3499442_CALIB.IMG contains the same information as above, but continues: TASK='FICOR77' USER='SHOWALTER' At this point the header ends, but the file has an extension header at the end, where the rest of the information can be found: LBLSIZE=1600 DAT_TIM='Thu Aug 25 12:44:36 2005' LABEL1='FICOR77 MINSAT= 852 NUMSAT= 59825' LABEL2='FOR NANOWATTS/CM**2/STER/NM MULTIPLY DN VALUE BY 0.00219' LABEL3='FOR (I/F)*10000., MULTIPLY DN VALUE BY 0.01000' LABEL4='FICOR77 DARK CURRENT FDS = 35012.12' COMMENT=' PICTURE MULTIPLIED BY 0.88 FICOR 2/02/86 VERSION' SCALE='JUPITER' The parameters LABEL1 through LABEL4 record the resulting calibration of the image, including the multiplicative factor to convert from image pixel values to physical units. However, the last keyword, SCALE='JUPITER', warns that this scaling applies to a Jupiter image, and needs to be updated based on solar distance to be applicable to an image from the Saturn encounter. Finally, the header for the geometrically corrected image S_RINGS/C3499442_GEOMED.IMG appends the indicator that VICAR task GEOMA has been run. TASK='GEOMA' USER='SHOWALTER' DAT_TIM='Thu Aug 25 12:44:40 2005' 5.4 VICAR Tables ---------------- The binary table formats in this data set (files *.DAT) are in a VICAR "IBIS" format. The details are beyond the scope of this document but can be found in the VICAR file documentation DOCUMENT/VICAR.HTML and .ASC. The binary IBIS files are provided primarily for documentation and reference and are not recommended to most users. Instead, every table file has an ASCII format equivalent (file *.TAB). These files contain the same numbers but are much easier to read and use. Values are aligned in columns of uniform length, one row per file record. The associated PDS label describes meaning of the numbers in each column, as discussed above in Section 4.3. 6. Voyager Imaging Overview =========================== The processing history of the Voyager images is described fully in DOCUMENT/PROCESSING.TXT. Here we provide a brief overview of how the cameras operated, with particular emphasis on the quirks of the images that a typical user might encounter. Details of the instrument can be found in the very useful article, Danielson, G. E., Kupferman, P. N., Johnson, T. V. and Soderblom, L. A. 1981. Radiometric performance of the Voyager cameras. Journal of Geophysical Research 86, 8683-8689. Far greater detail can be found in a document that, unfortunately, is not widely available: Benesh, M., Jepsen, P. 1978. Voyager Imaging Science Subsystem Calibration Report, Voyager Document Number 618-802, Jet Propulsion Laboratory, California Institute of Technology, Pasadena, California. 6.1 Reseau Markings and Geometry -------------------------------- Unlike modern CCDs, the vidicons in the Voyager cameras produce an intrinsic geometric distortion that varies both with time and with the distribution of light within an image. For this reason, the camera faceplate contained a grid of "reseau markings" that can be readily seen as dark spots in the raw images. Using these markings, it is possible to model and remove the geometric distortion. The archived files *_RESLOC.TAB contain centroid locations of the reseaux, as derived by VICAR routine RESLOC. In the cleaned images *_CLEANED.IMG, each marking has been replaced by an average of all the adjacent pixels, as accomplished by VICAR routine RESSAR77. This step improves the image cosmetically, but can also introduce artifacts, such as when a marking lands atop a sharp brightness transition. If a small circular region in a cleaned image appears particularly different from its surroundings and/or particularly free of noise, it is probably an artifact of the reseaux removal. If in doubt, check the same location in the raw file. The distortion is removed by VICAR routine GEOMA. This uses a tabulation *_GEOMA.DAT, which describes the relationship between a reseau's observed and geometrically correct locations. (See the corresponding .TAB file for the numbers.) VICAR routine GEOMA resamples the image so that each reseau lands at its geometrically correct position in the new image. This is how the final image in the processing, *_GEOMED.IMG, is generated, using a calibrated images as input. Note that the distortion involves resampling the image onto a slightly finer pixel grid, so that the resulting image is 1000x1000 pixels, not 800x800. Every GEOMED image is surrounded by an irregular blank frame where no image data was available to resample. In general, the internal geometry of a GEOMED image should be reliable at the level of ~ 1 pixel. In situations where still finer geometric precision and/or resolution is required, the cleaned or calibrated images might be a better choice. A pixel position in one of these images can be compared to the nearest reseaux, as tabulated in *_GEOMA.TAB, and 2-D interpolation will probably yield a more precise result. Finally, note that in applications such as photometry where precise geometric precision is not needed, the calibrated image can be used instead of the geometrically corrected one. The PDS labels of all the images contain parameters HORIZONTAL_PIXEL_FOV and VERTICAL_PIXEL_FOV, which provide the conversion from pixel location to direction in space. However, note that these values are only approximate for the RAW, CLEANED and CALIB images. They should be quite precise for the GEOMED images. 6.2 Dark Current ---------------- Another quirk of vidicons is that they build up a signal even when the shutter is closed. This is referred to as "dark current." The Voyager imaging team would model the dark current by taking occasional images in which the camera shutter was never opened. These images could then be used to subtract from a science image to (mostly) remove the dark current. The dark current varies with time and instrument temperature during each planetary flyby, so it is always best to choose the dark current taken closest in time to the image you wish to calibrate. The Voyager cameras had a set of operating "scan rates," which describe the amount of time it took to read out the image after the shutter closed. An image obtained with scan rate "n:1" was read out in n x 48 seconds. Because the dark current continues to build up during readout, one must always match the dark current to the scan rate of the image being calibrated. The dark current is automatically subtracted from an image during the calibration step, via VICAR routine FICOR77. That means that the CLEANED images still contain a nonzero dark current, but the CALIB images should not, at least in principle. In practical terms, you increase the noise in an image when you subtract a dark current. To reduce this problem, we have generated a set of averaged dark currents for the processing of all the Saturn images. Further information can be found in PROCESSING.TXT and the images are included on volume VGISS_0038 in the SUMDARKS directory. Using these dark current models, the calibrated images in this data set show only a modest increase in noise relative to the raw and cleaned images. Nevertheless, no dark current model is perfect. As a result, regions of dark sky within a calibrated image do not necessarily have numeric values near zero. If a region of dark sky happens to appear near a location where the user wishes to obtain precise photometry, then it is always wise to measure the sky and subtract this from the target measurement. For images without any visible dark sky, one can study the variations among the dark current frames taken closest in time to estimate the overall uncertainty in the dark current. In general, images of bright targets (with raw pixel values of order 100 or more) should be relatively unaffected by uncertainties in the dark current. 6.3 Calibration --------------- The Voyager vidicons were subjected to extensive testing both on the ground and in flight. Attempts were made to measure the responsivity to light of every image pixel. This information is captured in the large calibration model files found in the MIPL directory on volume VGISS_0038. These files served as key inputs to VICAR routine FICOR77, which generates the calibrated images. Nevertheless, in-flight observations tended to show deviations between Earth- and Voyager-based measurements, which were attributed to calibration errors. Around the time of the Uranus and Neptune encounters in 1986 and 1989, a new set of scale factors were determined to convert from the default calibration to one that was believed to be more precise. Some of the memos describing the re-calibration of the cameras can be found on line at the PDS Rings Node. See http://pds-rings.seti.org/voyager/hardware/iss/index.html#CALIB for these documents. All of these images have been calibrated using what were considered the final set of calibration factors. Derived corrections were as large 10-20%. These corrections are encapsulated in the file VGRSCF.DAT, found in the MIPL directory of volume VGISS_0038. Nevertheless, several caveats must be considered when interpreting a Voyager image photometrically. (1) Absolute calibration is still probably no more accurate than 5-10%. (2) All the recalibration work focused on Voyager 2, which flew by all four gas giants. At that point the Voyager 1 mission was complete so no attempts were made to derive correction factors for its cameras. Nevertheless, in this calibration project we have proceeded on the assumption that the Voyager 1 and 2 calibration corrections are the same. (3) Two of the Voyager 1 wide-angle filters, CH4_U and NAD, were never well calibrated for Voyager 1. We have used the calibration models for Voyager 2. However, because the gains of the cameras were different, the (relatively few) images obtained by Voyager 1 through these filters are certain to be incorrect in absolute terms. (4) The FICOR77 software was never updated to handle the different solar distances for Voyager 1 at Jupiter and at Saturn. FICOR77 automatically calibrates all Voyager 1 Saturn images as if they were Jupiter images. We have attempted to rectify these problems (except #3) in the PDS labels. They all contain a parameter REFLECTANCE_SCALING_FACTOR that converts from image pixel value to I/F. These values are very approximate for the uncalibrated RAW and CLEANED images. However, they should be accurate to the advertised 5-10% level for the CALIB and GEOMED images.