| import | dataio | import |
import -- create an IRAF image from an arbitrary binary file
import binfiles images
INPUT PARAMETERS
where
type = b # byte (no conversions)
u # unsigned integer
i # signed integer
r # ieee floating point
n # native floating point
x # ignore (skip)
nbytes = 1, 2, 4, or 8
tag is something like 'r','g','b' (color triplets), 'r',
'i' (complex data), etc. If no tags are given one will
automatically be assigned of the form 'b1', 'b2', etc.
OUTPUT PARAMETERS
The import task is used to convert arbitrary raster binary files to IRAF format images. The input format may be specified either through the task parameters (format set to none), or as an entry in a database of known formats (format set to the name of the entry). If the format of the image is not known a priori, the database can be searched and each record will be evaluated for an expression which identifies the format (format set to "sense"). The task will output either an IRAF image, a list of pixel values in a manner similar to the LISTPIX task, or information about the file format if it is supported in the database.
The input raster is assumed to be at most three dimensional, with pixels of various sizes that can be interleaved in a variety of ways. No compression schemes are yet supported, except in the case of builtin formats where special code has been written to handle to format. Byte-swapping and floating point conversion of pixels (from IEEE to native) is also supported.
The pixtype and interleave parameters define the pixel storage in the binary file. Pixtype is a comma delimited string, the elements of which define the type and size of each pixel. An optional tag name may be given to each pixel for use in the outbands expressions. If no tag is given one will automatically be assigned. For composite pixtypes (i.e. when more than one element is listed), the data are assumed to be pixel interleaved (e.g. stored as { {RGB}, {RGB} ...} triplets). For atomic (i.e. single) pixtypes, a positive value of interleave indicates that the data are stored in a line-interleaved manner (e.g. a line of R, a line of G, ...). If interleave is zero and pixtype is atomic, then no interleaving is done and the image bands are thought to be stored sequentially. Minimal error checking is done to make sure the combination of these parameters is correct.
The file may contain arbitrary padding around the pixels as defined by the tskip , bskip , lskip , and lpad parameters, header information may be skipped by setting the hskip parameter. Additionally, pixels may be ignored on input while still specifying the full format.
Once a format has been found, the task may output an iraf image by setting output to "image", a list of the pixels in the file can be written to STDOUT by setting output to "list", or information about the input file can be printed by setting output to "info". If output is set to "none" then no output will be generated, this can be used to check for read errors on the input file to verify task parameters. The datatype of the output image can be set by specifying the outtype parameter.
The outbands parameter is a list of expressions which are evaluated to compute the pixels in each band of the output image. Operands in these expressions consist of numeric constants and the pixtype tags (either user-supplied tags or the automatic tags), general arithmetic expressions are supported, which can include any of the special functions listed below. The simplest expression is the name of a tag itself. Regardless of the storage of pixels in the input file, each image band is separated on output unless an expression is given which combines them. See below for more details on outbands .
Header information may be added to an output image by naming either a keyword file or an existing image header listing in the imheader parameter. A header keyword data file consists of lines of FITS format cards. Leading whitespace is ignored. Lines not recognized as FITS cards are ignored. A valid FITS card is defined as beginning with a keyword of up to 8 uppercase, digit, hyphen, or underscore characters. If less than 8 characters the remaining characters are blanks. The ninth character may be an equal sign but must be immediately followed by a blank. Such value cards should be in FITS format though no attempt is made to enforce this. Any other ninth character is also acceptable and the line will be treated as a comment. Note that this way of recognizing FITS parameters excludes the case of comments in which the first 8 characters are blank. The reason for allowing leading whitespace and eliminating the blank keyword case is so that the long output of imheader may be used directly as input.
The outbands parameter is a comma delimited list of expressions, the simplest of which is the name of a tag itself (or the default names of the tags if none are provided in the pixtype param). The input pixels, regardless of how they are stored in the binary file, are always stored as separate bands in the output IRAF image. The outbands expressions will be evaluated to compute the pixels in each band of the output image. This means that e.g. RGB triplets in an input file will be separated into differents bands in the output image, unless a signle expression is given that combines them. The components named in pixtype may be eliminated or re-ordered in outbands to exclude certain input bands, or to change the channel order. For example the commands:
cl> import file img pixtype="u1:a,u1:r,u1:g,u1:b" outbands="g,r,a" cl> import file img pixtype="u1,u1,u1,u1" outbands="b3,b2,b1"
both convert an input 32-bit image with ARGB components. In the first case the output image is an IRAF image where the B component has been eliminated and the channel order reversed. The second case is the same as the first but uses the automatic tag names. A combination of user-supplied tags and defaults could also be used.
General interpreted arithmetic expressions are supported and can contain any of the standard expression evaluator functions (see the imexpr help page for more details). Special functions in expressions also include:
flipx (arg) - flip image in X
flipy (arg) - flip image in Y
gr[ea]y (r,g,b) - RGB to grayscale using the NTSC Y formula
red (arg) - get the red component of a colormap image
green (arg) - get the green component of a colormap image
blue (arg) - get the blue component of a colormap image
gamma (arg, gamma) - apply a gamma correction to the image
The two flip functions can change the image orientation by reversing the order
of pixels within a line (a flipx() call), or it can flip an image from top-
to-bottom (a flipy() call). The flipping will apply to all bands of the out-
put image even if it was only used in one expression. To reverse the channel
order simply change the order of the tags in the outbands parameter. RGB
images may be converted to a single grayscale image using the NTSC formula:
gray = (0.289 * r) + (0.587 * G) + (0.114 * B)Note that a similar grayscale conversion can be done by explicitly defining a similar equation in outbands and supplying different coefficients.
The red() , green() , or blue() functions can be used to get a single color component from a colormap image rather than the grayscale equivalent of the colormap. For example, to separate an 8-bit GIF color image into it's RGB components one could specify an outbands parameter such as
cl> import foo.gif bar format=gif outbands="red(b1),green(b1),blue(b1)"
Functions may also be nested in complex expressions such as:
flipy (gray(r,g,b)) - convert to grayscale, flip in Y flipx (flipy (gray (r,g,b))) - convert to grayscale, flip in X & Y gray (r,g,255) - use constant 255 as the B band gray (r,g+100,-b) - add constant to G, negate B
The format database is a text file named as a task parameter. Each record of a database entry is of the form:
<format_name>:
<alias>:
keyword = <expr>
keyword = <expr>
...and so on
A database record begins with the format name at the beginning of a line. Whitespace at the beginning of a line is considered the continuation of a previous line. Comments may be inserted in the database using the normal # character, the remainder of the line is considered a comment. Blank lines and comments are ignored, a record ends at the next line with a format name at the beginning of the line. The task database parameter defines the text files to be scanned as the database. If the parameter is a list of files then each file in the list will be concatenated to a single database file used by the task.
The format_name field is a string identifying each entry in the database, any number of aliases may also be given to identify the same format possibly known by another name. Supported keywords include:
image_id - A boolean expression identifying the image type
id_string - Verbose name of file format
bswap - is file byte-swapped? (See Below)
dims - a whitespace/comma delimited string of dimensions
pixtype - pixel type, size [and tag], may be a composite
interleave - describes how pixels are stored
hskip - # of bytes of header info to skip
tskip - # of bytes of trailing info to skip at end of file
bskip - # of bytes of info to skip between image bands
lskip - # of bytes of info to skip at front of each line
lpad - # of bytes of info to skip at end of each line
error - A condition that would cause a file read error,
returns a string with the error message, otherwise
returns the string "okay"
The image_id string is an expression to be evaluated which, if true, uniquely identifies the file format (such as a comparison to a "magic number"). The id_string is a verbose name of the format. The error keywords use the "? :" conditional syntax to define a boolean expression which, when true, returns an error message and is used to indicate a condition in a format which isn't supported. The remaining keywords have the same meaning as the task parameters. Keywords not present in the database record will take the default parameter value.
Expressions consist of any valid string that may be evaluated with the standard system expression evaluator evvexpr(). (See the documentation for this procedure or the IMEXPR task help page for details of builtin functions and operators.) Operators within expressions may be boolean, arithmetic, or the string operators ?= (substring equality) and // (concatenation). Operands may be the special functions named below, previously defined keywords, constants (numeric or strings), and the special operands
In addition to the intrinsic functions already provided there are a number of input and utility functions for the database. These are:
\fIINPUT FUNCTIONS\fR
ctocc ([offset]) - convert byte to printable char constant
ctod ([offset]) - convert string to double precision real
ctoi ([offset]) - convert string to integer
ctol ([offset]) - convert string to long
ctor ([offset]) - convert string to single precision real
ctowrd ([offset]) - get 1st white-space delimited word from str
getstr ([offset,] len) - get a string at offset
getb ([offset]) - get a byte at offset
getu ([offset]) - get an unsigned short int at offset
geti[24] ([offset]) - get a signed int at offset
getr[48] ([offset]) - get an IEEE fp number at offset
getn[48] ([offset]) - get a native fp number at offset
locate ([offset,] pat) - find an offset to a pattern
line (n) - offset of line N
\fIUTILITY FUNCTIONS\fR
skip (nbytes) - move offset by N-bytes
bswap (arg) - byte swap the argument
substr (str, c1, c2) - extract a substring from argument
stridx (test, str) - get 1st occurance of 'test' w/in 'str'
parameter (param) - return the current task parameter
default (param) - return the default task parameter
lsb_host () - returns true if host is little-endian
msb_host () - returns true if host is big-endian
The bswap database entry is similar to the task parameter, it may be used to set byte swapping for the whole file, or for only certain data types. The value is a string parameter that may be "yes" to byteswap the whole file, "no" to not swap anything, or a comma delimited string of types described below to enable swapping for only those values.
bswap = { no | yes | i2 i4 }
no # no swapping (default)
yes # byte swap whole file
i2 # byte swap short ints only
i4 # byte swap long ints only
The bswap task parameter applies only to the pixel data, but the bswap keyword in a database record sets byte-swapping for the header information: arguments to the input and conversion functions will be byteswapped prior to being evaluated by the function. The bswap() special function can be used to negate byteswapping for a particular argument if it is or is not set by the keyword (the default is no byte swapping).
Get a list of known input formats:
cl> import "" "" output=info
Get a list of known input formats, including those defined by the user:
cl> import "" "" output=info database="dev$images.dat,mydb.dat"
Get a list of the file formats of each image in the directory:
cl> import file* "" format="sense" output=info verbose-
file1.ras Sun rasterfile
file1.eps unknown format
file1.pgm 8-bit PGM file
: :
Get a list of the file formats of each image in the directory and
print out some information about each file:
cl> import file* "" format="sense" output=info verbose+
file1.ras: Sun Rasterfile
Resolution: 320 x 200
Pixel type: 8-bit unsigned integer
Pixel storage: non-interleaved
Header length: 137 bytes
Byte swapped: no
... :
Read a raw 8-bit file of pixels into an unsigned short IRAF image:
cl> import file img format="none" dims="512,512" pixtype="b1" \
>>> outtype="u" outbands="b1"
Read a JPL VICAR image or 8-bit Sun rasterfile:
cl> import file img format="vicar"
cl> import file img format="sunras"
Concatenate three separate red, blue, and green images and convert
to a single grayscale image:
cl> concat pic.[rgb] > rgb
cl> import rgb img format=none dims="640,480,3" \
>>> pixtype="u1" interleave=0 outbands="gray(b1,b2,b3)"
Read an 8-bit colormap GIF image and separate the RGB colors into
separate bands in the output image:
cl> import file.gif img outbands="red(b1),green(b1),blue(b1)"
Read three 8-bit rasterfiles with 200 byte-headers as if they were
a single image, and combine the images to a single output band:
cl> concat pix.* > rfiles
cl> import rfiles img dims="512,512,3" pixtype="b1" \
>>> hskip=200 bskip=200 interleave=0 outbands="gray(b1,b2,b3)"
Read a FITS image with one header record in which the data bytes
are incorrectly swapped, but the header info is in the right order:
cl> rfits nite1.fits "" nite1
File: nite1 1866-A Size = 640x480
cl> imheader nite1 l+ > imheader.dat # Save the header info
cl> imdel nite1.imh
cl> import nite1.fits nite1 format="none" dims="640,480" \
>>> bswap+ hskip=2880 pixtype="i2" outtype="s" imheader="imheader.dat"
Bitmap images are not yet supported. Their most logical use would be as pixel masks but there hasn't been much call for these formats so they may be implemented at a later time.
export. imexpr, hedit, default image database imcnv$lib/images.dat