| immodel | xray.xspatial | immodel |
immodel -- make a synthetic image or apply synthetic data to an existing image
immodel image outname function arg1 arg2 model_file normalize scale sources
Immodel creates synthetic images by adding values according to the given profile function for each given source. The values are scaled by the sources given intensity, a global scaling factor, and an optional function normalization factor. Model data can be applied to a blank image (input_image = none) or added to (or subtracted from) an existing image. Immodel can only handle one function at a time, but that function can be applied to any number of sources. To apply data with more than one function, call the immodel task once for each different function, reading the model image in as the input_image and writing it out to the same file, each time. Model data can be applied as impulse, to be smoothed later by the response function, but an impulse position is always the center of the nearest pixel.
An image file containing data to which the model is to be applied. Data can be read from any valid IRAF image file with or without subsection specification. Typically, the input image contains background data for the model or a partially completed model.
If no input image was given, the width and height of the output image must be explicitly given in integers. If an input image is given, its dimensions (or that of the specified subsection if one is given) will be used.
The name of the output file. The output file is a standard IRAF image file with real*4 data. Its dimensions will be that of the input (after any subsection and/or blocking reductions).
The name of the model function. The meaningful choices are: boxcar, expo, gauss, lorentz, impulse, king, power, tophat, file, and mymod. Impulse applies all of its counts at the pixel nearest to the source coordinates. File reads model pixel values from an IRAF image file (see file_name below). Note that impulse and file both have the effect of moving the center of each source to the center of the pixel. Mymod calls a user's subroutine which must have been linked to the model task (see below). The model profile will be applied at each center (see below). The function name can be given by any unique abbreviation (e.g. gau). The appropriate parameters will then be requested (see below). The impulse function has no parameters.
The first of two parameters to define a model function. arg1 is used for the x axis width of boxcars, the radius of exponential, king, power, and tophat profiles, the sigma of a gaussian profile, and the gamma of the lorentzian profile. Arg1 is not used by file, and impulse models. See model function explanations below for more specifics.
The second of the two parameters used to shape model functions. It is used for the y axis height of boxcars, and the power parameter for king and power profiles. arg2 is not used by expo, file, gauss, lorentz, tophat, and impulse models. See model function explanations below for specific details.
The name of the file used by the file model type. See explanation of file under "MODEL FUNCTIONS", below.
When normalize is yes, the normalization value for the function will be determined empirically by applying the function to the center of a dummy image of the same size as the output file and summing the pixel values. This normalization value will then be applied along with any other scaling. Without normalization, most of the functions peak at 1.0. Normalization works with any function, including file and mymod.
When applied at a source's coordinates, the model profile function is scaled by the source intensity, the initial (overall) scale, and (optionally) the function normalization factor. If no overall scale is to be applied to the image, use 1.0. Note: subtraction of model data can be performed by giving a negative value for the global scale.
A list of sources consisting of the x coordinate, the y coordinate, and a measure of intensity. This can be entered directly or you may give the name of an ASCII list file or an SDAS tables file from which the sources will be read. See below for an explanation of the entry formats.
Overwrite the existing image file if one exists with the same name as that given by output_image.
Display info to screen. Integer of range 0-5. The higher the number, the more verbose the display.
Each supported model function is explained below:
A boxcar function is an orthogonal rectangle in x-y space. Pixels are either included or not included. Values are not interpolated at the edge. The width and height should be odd. Even dimensions cannot be precisely centered with discrete pixels, resulting in a small phase error (shift of the output image). The units are output image pixels.
The exponential (expo) function has a circularly symmetric profile given by e**(-radius/expo_radius). The units are output image pixels.
The function pixel values are read in from an IRAF image file. The function data must be centered on the pixel at ((file_width+1)/2), ((file_height+1)/2)). In a 320x512 file, the center is (160,256). Note that this differs slightly from the same function in imsmooth. The data will be applied, pixel for pixel, centered at the pixel which includes the source center coordinates (see sources below). Note that this moves the source center to the center of the nearest pixel (it does not interpolate values). Scaling and normalization apply as for any other function.
The gaussian (gauss) function has a circularly symmetric profile given by e**(-(radius**2)/(2*(gauss_sigma**2))). The units are output image pixels.
The lorentzian (lorentz) function has a circularly symmetric profile given by (gamma/2)/((radius**2)+(gamma/2)**2). The units are output image pixels.
The impulse function has no paramters. It places the scaled intensity of the given source in the pixel nearest the source center. Note that this moves the center of the source in real coordinate terms to the center of that pixel.
The king function has a circularly symmetric profile given by 1/((1+(radius/king_radius)**2)**king_power). The units are output image pixels.
When using your own subroutine, the two arg values will be passed to it along with the other parameters. You may use them as runtime parameters for your own needs, however arg1 must be given a value greater than 1.0 (there is a valid radius check in immodel ). Scaling and normalize options work the same with your own subroutine as with any other. (See discussion of USER FUNCTIONS below).
The power function has a circularly symmetric profile given by 1/((1+(radius/power_radius))**power_power). The units are output image pixels.
The tophat function is a constant within a radius of tophat_radius. Pixels are either included or not included. Values are not interpolated at the edge. The units are output image pixels.
The source parameter contains a description of the sources to be input into the model. This description consists of one or more source expressions , separated by semi-colons. Each source expression describes one or more sources and is in one of the following formats:
1) x y intensity
or
x, y, intensity etc.
In this format, the x, y, and intensity are input explicitly.
2) list_file
In this format, the expression is an IRAF ASCII list file containing a
list of x, y, and intensities. There must be 3 columns, with only
whitespace in between. Lines beginning with # are ignored.
3) table_fileIn this format, the expression is a STScI table file. The columns from which x, y, and intensity are taken are defaulted to columns named "x", "y", and "net". (These are the columns in the source file created by eos2tab ).
4) table_file intensitycol
or
table_file(intensitycol)
In this format, the expression is a STScI table file. The column
names from which x and y are taken are defaulted to columns named "x",
"y". The column from which the intensity is taken is supplied by the
user.
5) table_file xcolumn ycolumn intensitycol
or
table_file xcolumn,ycolumn,intensitycol
or
table_file(xcolumn, ycolumn, intensitycol) etc.
In this format, the expression is a STScI table file. The column names from which x, y, and intensity are taken are supplied by the user.
For example, if a user wishes to model sources from the list file called foo.lst containing the following data:
# x y intensity 100 200 300.1 200 300 400.2 300 400.4 500 400.1 500 600.3 as well a source at 512, 512 with intensity 1000, he can input: "foo.lst; 512 512 1000"as input to the source parameter, and immodel will create a model containing the 5 specified sources.
You can write your own model profile function and link it to your own copy of immodel. This requires several steps. First, several files must be copied to your subdirectory. After writing your own subroutine as outlined below, the copied mkpkg must be executed (mkpkg fortran if your subroutine is in fortran). Finally, within IRAF's cl, type task immodel="<your subdirectory pathname>/model.e". Bring up the package by typing mymodel. Bring up your copy of the model task by typing immodel. Don't forget to give mymod as the model function type.
The subroutine can be written in SPP or fortran with the name and calling arguments as shown below (copied from mymod.x or mymod.f).
procedure my_model (buf, width, height, xcen, ycen, radius, power, scale, complex) real buf[ARB] # i: image buffer int width, height # i: image dimensions real xcen, ycen # i: center of function real radius # i: runtime parameter for user subroutine real power # i: runtime parameter for user subroutine real val # i: value by which to multiply function int complex # i: 1 if buffer is complex data type, else 0Buf is the data buffer, treated as a one-dimensional real array. Width and height are the dimensions of the buf array. Xcen and ycen are the centers of the source (the subroutine is called once for each given source). The radius and power variables are set by the user exclusively for this subroutine when calling immodel at runtime. They can be used to tailor the profile. Val is the composite scaling computed as the product of the source intensity, the global scaling factor and optionally the normalization factor computed for this function. Complex will normally be 0. If my_model is linked to imsmooth instead of immodel , the data buffer will have complex data (alternating real and imaginary parts) and will be so indicated by complex having the value 1.
cl> immodel name of input image (128 128): 512 512 output image (foo): model10 delete old copy of output image (no): type of source profile function (gauss): power function radius, sigma or width (2.0): 1.7 function power or height (2.0): 4.2 normalize model as given (yes): yes initial scaling applied to model (1.0): 10.0 source <x y intensity> (1 1 0): source.list computing model normalization adding model data ...... writing image to model10 cl> immodel name of input image (512 512): model10 output image (model10): model10 delete old copy of output image (no): yes type of source profile function (power): pow function radius, sigma or width (1.7): 1.4 function power or height (4.2): 3.7 normalize model as given (yes): yes initial scaling applied to model (10.0): 7.0 source <x y intensity> (source.list): computing model normalization reading data file adding model data ...... writing image to model10 cl> immodel name of input image (128 128): mybkgd output image (foo): model12 delete old copy of output image (yes): no type of source profile function (power): mymod function radius, sigma or width (1.0): 5.2 function power or height (2.0): 3.8 normalize model as given (yes): initial scaling applied to model (7.0): 10.0 source <x y intensity> (source.list): 132.2 241.74 12.3 computing model normalization reading data file adding model data . writing image to model10
Functions are applied to every image pixel for each source, even far from the source center where the model value is effectively zero. This is time consuming on large images.
Documentation on imsmooth (which uses much of the same library), and imcalc.
Documentation on coordinates (help coords ) for a description of PROS coordinate conventions.