Add contents of a row-stacked spectrum image to an output image.

This routine takes an image where spectra are stacked in the second dimension. Each spectrum is treated one-by-one in the following way:

• The default position on the cross-dispersion axis is calculated using the spectrum separation value 'dist_tr', which is adjusted for the used CCD binning factor, and the gaps file (both are specified in the instrument-parameter file). The entire block of spectra is centered on the image and the offset of the first spectrum is calculated as a first value [starting at the lower ('daxis' = 1) or left ('daxis' = 2) edge of the image]. Alternatively, the starting pixel is specified in the gaps file using the parameter 'startpx' in that file. Consecutive spectra are offset from the first spectrum considering the spectrum separation and the gaps.

• Cross-dispersion pixel positions are calculated for each spectrum and pixel on the dispersion axis using the polynomial coefficients specified using the keyword TRPOSPAR. The final position on the CCD is calculated by adding the default pixel position to the pixel positions resulting when using the polynomials. No additional pixel offsets are used when TRPOSPAR is undefined or if it is set to an array with zeros.

Convolution of spectrum

The spectrum can be convolved either with a two-dimensional kernel that handles both axes simultaneously (KERNEL) or separate one-dimensional kernels for the dispersion axis (DKERNEL) and the cross-dispersion axis (CKERNEL).

Using sets of two-dimensional kernels

A spectrum is convolved with the kernel image for each pixel separately on the dispersion axis. The kernel is shifted by the dispersion offset (trace offset) in the dispersion (spatial) dimension. One kernel can be used with all pixels on the dispersion axis or several kernels can be used at wavelengths defined with the keyword ARRAY (third dimension of KERNEL). In the latter case, the kernel at a specific pixel on the dispersion axis is interpolated from the two nearest kernels.

The subsampled image is rebinned to remove the subsampling on both axes.

Using sets of one-dimensional kernels

At first, each spectrum is convolved with a kernel on the dispersion axis (DKERNEL). One kernel can be used with all pixels on the dispersion axis or several kernels can be used at wavelengths defined with the keyword DARRAY (second dimension of DKERNEL). In the latter case, the kernel at a specific pixel on the dispersion axis is interpolated from the two nearest kernels.

In a second step, the convolved spectrum of the previous step is convolved with a cross-dispersion axis kernel used on the dispersion axis. The convolution is simple, considering that the input spectrum is one pixel wide. The convolved profile is simply the cross-dispersion kernel (CKERNEL) shifted by the trace offset. One kernel can be used with all pixels on the dispersion axis or several kernels can be used at wavelengths defined with the keyword CARRAY (second dimension of CKERNEL). In the latter case, the kernel at a specific pixel on the dispersion axis is interpolated from the two nearest kernels.

In a final step, the subsampled image is rebinned to remove the subsampling.

Input parameters:

image

The input data are provided as already subsampled (DSUBSAMPLE) stacked spectra in this one-dimensional array or two-dimensional image. The first dimension contains the spectra and the second dimension contains 'spnum' spectra (as specified in the instrument-parameter file). The same spectrum is used with all spatial elements if IMAGE is a one-dimensional array.

Keyword parameters:

	kernel		A four-dimensional array that provides two-dimensional kernels across both axes for one or several wavelengths (third dimension) and one or all spectra (fourth dimension). The kernels are assumed to be subsampled according to the values of DSUBSAMPLE and CSUBSAMPLE.
	dak		A scalar integer that specifies the dispersion axis in KERNEL; either 1 or 2.
	dkernel		A two- or three-dimensional array that provides one-dimensional kernels across the dispersion axis of the CCD for several wavelengths and one or all spectra. A two-dimensional variable implies that the same kernel is used with all spectra. The kernels are assumed to be subsampled and the number of elements in a kernel must be odd. The same kernel is used at all wavelengths if the number of elements in the second dimension is 1.
	dsubsample		A scalar integer that specifies the subsampling factor used on the dispersion axis; DSUBSAMPLE >= 1. The default value is: 1
	darray		A one-dimensional decimal-value array with a unique list of monotonically increasing wavelengths for each kernel in the first dimension of DKERNEL. The kernels are assumed to be specified at the same wavelength for all spectra.
	dispmask		A scalar string with the name of an existing fits file that contains a dispersion mask. The data must be available in the PARAMS or zeroth extension as a two-dimensional decimal-value array that contains polynomial coefficients for each spectrum; for each spectrum, the polynomial converts pixel values (x) to wavelengths (y). The dispersion mask must be setup to use the same pixel subsampling as is used with DSUBSAMPLE or DKERNEL. The first pixel (index 0) must be the wavelength of the lower range minus half the kernel width (DKERNEL). The last pixel must extend to – at least – the last pixel of the selected wavelength range, plus half the kernel width (DKERNEL). As an example, assuming the CCD is 2000 px wide on the dispersion axis and the dispersion kernel is 31px wide, the dispersion mask must be setup using (31 – 1) / 2 + 2000 + (31 – 1) / 2 = 2030 px. Hence, the first pixel in the dispersion mask is used with the lowest pixel in the kernel when the kernel is centered on the first pixel in the CCD image. Note: It is important that the dispersion axis in the dispersion mask is the same as in the simulated data!
	dispoffset		An array with decimal values that specifies a pixel offset for the first pixel on the dispersion axis for each spectrum; this keyword is easier to use than DISPMASK for cases where there is a pixel offset and all spectrum pixels have the same wavelength extent. This keyword is ignored when DISPMASK is set. The values of the array are the coefficients of a polynomial as used by the IDL routine POLY. For example, to create a n offset array for //n// spectra with a parabolic shape where the minimum offset is at //n*2/3// and the offset is //sa0// pixels, use the following array: x = long(n * 2d0 / 3d0) DISPOFFSET = – [1d0, -2d0/x0, 1d0/x0^2] * sa0
	cdelt		A scalar decimal value that specifies the pitch of the output image on the dispersion axis; cdelt > 0. The keyword WLRANGE is required instead if CDELT is undefined.
	wlrange		Optional parameter that is only used if CDELT is undefined or if DISPMASK is undefined, and in this case it is mandatory. A two-dimensional decimal-value array that specifies the wavelength range in the output image; the second value must be higher than the first value. This keyword is used to calculate a value on CDELT as: cdelt = (wlrange[1] – wlrange[0]) / ((dcw – 1) * dsubsample)
	trpospar		Optional one- or two-dimensional decimal-value array that provides polynomial coefficients for the relative spectrum center position of each spectrum on the cross-dispersion axis as function of the pixels on the dispersion axis. The same polynomial is used with all spectra if TRPOSPAR is a one-dimensional array. The center positions are relative to the respective center cross-dispersion position calculated using the spectrum gaps file and the spectrum-separation parameter 'dist_tr'. The polynomial order corresponds to the number of columns in TRPOSPAR – 1.
	ckernel		A two- or three-dimensional array that provides one-dimensional kernels for the cross-dispersion axis across the dispersion axis of the CCD for several wavelengths and one or all spectra. A two-dimensional variable implies that the same kernel is used with all spectra. The kernels are assumed to be subsampled (considering CSUBSAMPLE) and the number of elements in a kernel must be odd. The same kernel is used at all wavelengths if the number of elements in the second dimension is 1.
	csubsample		A scalar integer that specifies the subsampling factor used on the cross-dispersion axis; CSUBSAMPLE >= 1. The default value is: 1
	carray		A one-dimensional decimal-value array with a unique list of monotonically increasing wavelengths for each kernel in the first dimension of CKERNEL. The kernels are assumed to be specified at the same wavelength for all spectra.
	randompos_array		A decimal-value array that is used to store random- valued spectrum separation offsets between calls to this routine.
	parfile		A scalar string that specifies the name of a file with instrument-specific setup parameters. These files follow a strict format.
	userparfile		A scalar string with the name of a file with user-defined parameters. The following parameters are read here from this file: 'dist_tr' The value of the constant separation between spectra. 'keywordsfile' The name of the file with instrument-specific header keywords. 'gapfile' The name of the file that specifies the spectrum gaps.
	detector		A scalar integer that selects the setup in the instrument-parameter file; DETECTOR is a zero-based value. The default value is: 0
	ndetectors		A scalar integer that provides the number of detectors (configurations) used in the instrument parameter file.
	kwrdlist		A scalar string with the name of a file that contains instrument-specific keyword names for use with p3d.
	preset_kwrdlist		A scalar string with the name of a file that contains instrument-specific keyword names with preset values for use with p3d.
	gapfile		A scalar string with the name of a file that contains instrument and configuration-specific spectrum gaps. This keyword is ignored when GAPSNUM is set.
	gapsnum		Optional three-element decimal array that contains the constant number of spectra per group, the constant number of "empty spectra" between the groups, and the starting pixel. The keyword GAPFILE is ignored when this keyword is set.
	npixs		A two-element integer array defining the number of physical pixels on the dispersion and cross-dispersion axes of the CCD, respectively.
	spnum		Optional scalar integer that specifies the total number of spectra. The DETECTOR-specific instrument parameter 'spnum' is ignored when this keyword is set.
	dist		Optional scalar decimal value that specifies the constant separation between spectra. The DETECTOR- specific instrument parameter 'dist_tr' is ignored when this keyword is set. Note! The value is divided with the binning factor on the cross-dispersion axis.
	aberration_fwhm		A scalar decimal value that specifies the FWHM of a Gaussian profile that is used to convolve the simulated image after it is created; the intention is to simulate effects of spherical aberration.
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		An error handler is not setup if this keyword is set. Otherwise, the error handler is setup using the routine CATCH, which makes each subroutine exit quietly when a bug is encountered. Use this keyword when debugging p3d.
	cdebug		A keyword as DEBUG used with the called C routines; valid values are 0-6 where a higher number results in more output to STDERR.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

oimage

Upon a successful execution, this variable contains the spectrum image when the routine exits.

Splits an image into blocks and saves the blocks as extensions in a FITS file. The properties of the individual images are defined in the instrument keywords and instrument keywords setup files, which are specified using the keywords KWRDLIST and PRESET_KWRDLIST. The same files are used to write the keywords that p3d then uses to reduce the written data files.

The individual image blocks are scaled using the values of the gain and the readout noise that are provided in the instrument setup file.

Input parameters:

	filename		A scalar string that specifies the name of the file to write.
	iimage		A two-dimensional array with the image to write.

Keyword parameters:

	bias_level		- A scalar decimal value that specifies a bias level (unit electrons). The default value is: 600.0
	copies		A scalar integer that specifies how many copies to write; default is one copy. Noise is added to each copy and the number is reflected in the resulting output filename. The default value is: 1
	spnum		An optional scalar integer that specifies the number of spectra in the image; this keyword is used when the used number is not part of the default setup.
	dist		An optional scalar decimal value that specifies the constant separation between spectra; this keyword is used when the used value is not part of the default setup.
	gapsnum		An optional two- (or three-)element decimal-value array that specifies the number of spectra per group of spectra and the number of empty spaces between spectra; this keyword is used when the gaps setup is not part of the default setup.
	grating_id		A scalar string that must be set to the name of the used [grating] setup in the instrument gratings file.
	kwrdlist		A scalar string with the name of a file that contains instrument-specific keyword names for use with p3d.
	preset_kwrdlist		A scalar string with the name of a file that contains instrument-specific keyword names with preset values for use with p3d.
	p3dftype		A scalar string with the value that is written to the header keyword listed as the value of RAWREQDTYPE in KWRDLIST.
	compress		Set this keyword to compress the output file using gzip; the file suffix '.gz' is then appended to FILENAME. The default value is: 0
	nthreads		A scalar integer that specifies how many threads are used when compressing the written data file.
	detsec		This keyword is set if the keyword GET_DETSEC is set, and the routine returns to the caller when DETSEC has been calculated.
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	help		Set this keyword to show this routine documentation, and then exit.