STScI Logo

immodel xray.xspatial


NAME · USAGE · DESCRIPTION · PARAMETERS · MODEL_FUNCTIONS · SOURCE_OPTIONS
USER_FUNCTIONS_(COMING_SOON) · EXAMPLES · BUGS · SEE_ALSO

NAME

immodel -- make a synthetic image or apply synthetic data to an existing image

USAGE

immodel image outname function arg1 arg2 model_file normalize scale sources

DESCRIPTION

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.

PARAMETERS

image = "128" prompt = name of input image OR width and height

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.

outname = "foo" prompt = name of output image

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).

function = "gauss" prompt = type of source profile function

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.

arg= 2.0 prompt = function radius, sigma or width

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.

arg= 2.0 prompt = function power or height

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.

model_file = "" prompt = file containing profile data

The name of the file used by the file model type. See explanation of file under "MODEL FUNCTIONS", below.

normalize = yes prompt = normalize model as given

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.

scale = 1.prompt = initial scaling applied to model

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.

sources = "1 0" prompt = source <x y intensity>

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.

(clobber = no) [boolean]

Overwrite the existing image file if one exists with the same name as that given by output_image.

(display = 1) [int]

Display info to screen. Integer of range 0-5. The higher the number, the more verbose the display.

MODEL FUNCTIONS

Each supported model function is explained below:

boxcar arg1=width arg2=height

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.

expo arg1=radius

The exponential (expo) function has a circularly symmetric profile given by e**(-radius/expo_radius). The units are output image pixels.

file model_file=filename

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.

gauss arg1=sigma

The gaussian (gauss) function has a circularly symmetric profile given by e**(-(radius**2)/(2*(gauss_sigma**2))). The units are output image pixels.

lorentz arg1=gamma

The lorentzian (lorentz) function has a circularly symmetric profile given by (gamma/2)/((radius**2)+(gamma/2)**2). The units are output image pixels.

impulse

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.

king arg1=radius arg2=power

The king function has a circularly symmetric profile given by 1/((1+(radius/king_radius)**2)**king_power). The units are output image pixels.

mymod arg1=? arg2=?

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).

power arg1=radius arg2=power

The power function has a circularly symmetric profile given by 1/((1+(radius/power_radius))**power_power). The units are output image pixels.

tophat arg1=radius

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.

SOURCE OPTIONS

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_file

In 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.

USER FUNCTIONS (coming soon)

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 0

Buf 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.

EXAMPLES

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

BUGS

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.

SEE ALSO

Documentation on imsmooth (which uses much of the same library), and imcalc.

Documentation on coordinates (help coords ) for a description of PROS coordinate conventions.


Source Code · Search Form · STSDAS