Filed on -- cosmos:/folio/arcade/help/internal.doc Internal Format of Image Data Data transfer of image data between modules will be done using the internal format specifications given in the header file "internal.h". This format consists of a header block followed by the raster scanline data. It is intended that this format is only for the temporary transfer of information between modules. Any temporary files written containing this type of data will be deleted after the job is completed. This format is not intended as a new file format. The proper file format for scanned data is RES. Initially, we will will be using AIS until the RES standard is fully implemented. Two modules for reading (and writing) files and translating them into (and from) the internal format will be provided. Initially, these modules are readais and writeais, but they will be replaced by readres and writeres. Since all other modules read and write internal format images, they will not have to be changed as we convert over to the RES file format. Header The internal format consists of a short header followed by the raster data. The header is used to describe the total size and the organization of the raster data that will be read by that module. If in its processing of the data, the module will change the quantity of data in the image, then it has to change the header to reflect those changes. Raster Data An internal image consists of two parts, an image raster and a mask raster. Either can be present or absent, but both cannot be absent simultaneously. If both are present, then the internal image is the combination of the two rasters. If the mask raster is absent, then a mask raster of all ones, the size of the image raster, is assumed. If the image raster is absent then the internal image is considered to be a mask only and not an image. Wherever the mask raster is zero the values of the raster image are undefined. The image raster only has meaning in places where the mask raster is non-zero. The mask raster must be the same size (in pixels and scanlines) as the image raster, but it may have a different number of bits/pixel. Both the image and mask rasters are divided into scanlines and each scanline is, in turn, divided into pixels. If a mask raster exists, then the scanlines of the image and mask rasters are alternated, starting with the image raster. Each scanline contains an integral number of bytes (8 bits). The scanlines of the image and mask rasters may differ in length. Each scanline contains the same number of pixels and each pixel (for a given raster) has the same number of bits. The photometry of the image raster is linear with reflectance and increasing values correspond to whiter pixels. The values corresponding to white and black are specified in the header. A TRC can be specified, which follows the fixed length portion of the header. A TRC, if it exists, is represented by knots consisting of input and output pairs. These knots, when connected by straight lines, represent the look up table through which the image raster pixels should be referenced to produce tha actual image pixels. A mask raster, if it exists, is not affected by this TRC. Structure Definitions The fields of the "header" structure in "internal.h" have the following meanings: "length" The total length of the header information in bytes. This length can be variable and depends on the value of the "trcLength" field. "password" The password is changed as changes are made to the "header" structure. Checking the password is a good way of insuring that a module is up-to-date. "pixels" The number of pixels in each scanline. If a mask exists with the image, then it has the same number of pixels in each of its scanlines. "scanlines" The number of scanlines in the image and mask rasters. "bytesperSL" The number of bytes in each scanline of the image raster. The pixels are left justified in the scanline and if the number of bits necessary to represent the scanline is not a multiple of 8, then there may be some padding bits at the end of the scanline. "bitsperPixel" The number of bits in each pixel of the image raster "signed" A flag, which if equal to unity, indicates that the pixels should be used as SIGNED integers. If it is equal to zero, it indicates that the pixels should be used as UNSIGNED integers. "histoValid" This flag indicates if the histogram of the original image has been invalidated by some previous processing step. If a process performs an operation which would invalidate the original image's histogram, then it should zero the flag. "imageExists" The flag which indicates if an image raster is present in the data. "maskExists" The flag which indicates if a mask raster is present in the data. "maskbytesperSL" The number of bytes in each scanline of the mask raster. This number may be different than the number of bytes in each scanline of the image raster. "maskbitsperPixel" The number of bits in each pixel of the mask raster. Note that the number of bits representing each pixel does not have to be the same for the image and the mask rasters. If a pixel of the mask raster is zero, then the corresponding pixel of the image raster is undefined, even though it is present in the data. If the pixel of the mask raster is non-zero, then the image raster pixel value is multiplied by the mask raster pixel value and divided by the maximum value of the mask raster. "maskmaxValue" The maximum sample value of the mask raster. "whiteValue" The value of image data corresponding to white. This value may be positive or negative and does not have to be in the range of numbers defined by "bitsperPixel" and the "signed" flag. The white value must be greater than the black value. "blackValue" The value of image data corresponding to black. This value may be positive or negative and does not have to be in the range of numbers defined by "bitsperPixel" and the "signed" flag. The black value must be less than the white value. "trcLength" The number of trc knots following the "header" structure. The number of bytes in the trc is equal to the TRC length multiplied by the size in bytes of the TRC knot structure. Structure "knot" An x-y pair of input-output values, which when connected by straight lines form a curve through which every pixel value of the image raster is referenced to determine the proper pixel value.