This is the p3d spectral extraction routine. The algorithm works by integrating along the cross-dispersion direction. Optionally a shift of the image to the tracemask can be calculated and a flat field correction can be made.

his routine is actually a driver for the spectrum extraction outines p3d_extract_tophat and p3d_extract_optimal.

Input parameters:

	array		A raw spectrum image, of two dimensions.
	traces		A tracemask, that must have the same number of elements on the dispersion axis as ARRAY.

Keyword parameters:

	dout		The resulting error of the extracted image OUT. This is only calculated if DBIAS is set.
	bdout		The resulting error of the extracted image OUT_BSW. This is only calculated if DBIAS is set.
	parfile		The parameter list filename, this keyword must be present. This file is used to extract the number of spectra (SPNUM) and the spectrum extraction width (PROFWIDTH).
	flat		If flat fielding is requested, this variable should be set to the raw flatfield data, or the final flatmask.
	dflat		If present, this is the error in FLAT. The dimensions of DFLAT must be the same as those of FLAT. If BIAS and FLAT are present, DFLAT must also be present.
	bias		If bias subtraction is requested, this variable should give the bias image data.
	dbias		If present, this is the error in BIAS [ADU]. This value must be a decimal value (scalar or array). DOUT is only calculated if DBIAS is set. The number of elements of DBIAS must correspond to the number of rows of DETSEC.
	bpmask		This two-dimensional array, of byte type, is used, if set, by the routine p3d_extract_optimal.
	obpmask		A two-dimensional byte image of the same dimensions as OUT. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
	bobpmask		A two-dimensional byte image of the same dimensions as OUT_BSW. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
	satlimit		A scalar integer that specifies the saturation limit that is used to set each element in the saturation masks (SATMASK and BSATMASK) [ADU]. If any of the pixels that are considered across the center part of the profile is higher than this limit, the output element is masked.
	satmask		A two-dimensional output array of byte type, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set.
	bsatmask		A two-dimensional output array of byte type, which indicates spectrum elements of beam switched data that involved saturated raw-data pixels.
	gain		The data gain factor [e-/ADU]; a scalar floating-point type value. If DBIAS is present, GAIN must also be present.
	rdnoise		The readout noise [ADU]; a decimal value (scalar or array). If DBIAS is present, GAIN must also be present. The number of elements of RDNOISE must correspond to the number of rows of DETSEC.
	spnum		An optional scalar integer specifying the number of spectra; this keyword must only be set when finding spectra in simulated data (in this case, the value is found in the header keyword SIM_SPNM), in all other cases it is set here.
	userparfile		A scalar string specifying the name of an optional user-parameter file, that could contain some of the keywords below. If it does, these values are recognized used in the spectrum extraction: 'profwidth_ctex' optimal extraction 'profwidth_ex' optimal extraction 'profwidth_variable' tophat extraction 'deadfibersfile' dead fibers 'sls_maskwidth' scatt.-light subtraction 'sls_medfiltern' scatt.-light subtraction 'sls_polorder' scatt.-light subtraction 'sls_constantvalue' scatt.-light subtraction 'sls_gaussfiltersig' scatt.-light subtraction 'rebuildlib' C-routine
	detsec		A four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. DBIAS, GAIN, and RDNOISE must have as many elements as DETSEC has rows. Since all arrays of this routine and its subroutines are assumed to have a as the dispersion axis, the 0:1 and 2:3 columns of DETSEC are swapped if DAXIS = 2 (this swapping does not affect the input array).
	ifunum		Some instruments (/FVIRUS) use several IFU bundles with one setup file. For these setup this integer value specifies an IFU id, which associated entries are searched for in the dead-fibers file.
	cumulativedetsep		This keyword is passed on to p3d_misc_odetsec.
	bsw		A scalar integer, where a non-zero value specifies if the spectra are interleaved with another set of spectra using this integer pixel separation on the cross-dispersion axis; the value is unbinned. The default value is: 0
	bin		The CCD binning factor of the cross-dispersion axis; either the y-direction (DAXIS = 1) or the x-direction (DAXIS = 2). The default value is: 1
	xstr		An empty string, or a three character string that is appended to some of the tracing parameter names. The default value is: ''
	method		This scalar string specifies the used spectrum traction method: tophat' see p3d_extract_tophat optimal' see p3d_extract_optimal. In this case it is mandatory to also provide LPROFS. The default value is: 'tophat'
	lprofs		A three-dimensional array with the cross-dispersion line profiles of every spectrum and wavelength bin (in the third dimension). LPROFS is used iff METHOD == 'optimal'.
	proffun		A scalar string with the name of the function to use when (re-)calculating the profiles (using LPROFS).
	scattlightsubtract		If this keyword is set, a model of the ttered light is applied to the raw data. An ge with scattered-light image is first culated, and is thereafter subtracted from the s-subtracted image – before calculating the or or extracting any spectra. Upon exit of this tine the image is returned in this same iable. The model of the scattered light is ated in the following four steps: ll pixels within sls_maskwidth [1.5 * profwidth] ixels of a spectrum are masked to not be used. he remaining unmasked regions are edian-filtered one wavelength bin at a time, sing a median filter of size /sls_medfiltern// * //med_filtern// 20 / //bin// * 20 / //bin//] pixels. The filter s truncated at the boundaries of each region. polynomial of order sls_polorder [7] is fitted or each wavelength bin on the cross-dispersion xis. In order to keep the noise low the dataset hat is used for each wavelength bin is the edian of a region that is five pixels wide, entered on the current wavelength bin. he data is filtered with a Gaussian kernel with pre-defined width sigma sls_gaussfiltersig [30]). The data are onvolved first on the dispersion axis, and hereafter on the cross-dispersion axis. e! This approach to subtract scattared light nly works with instruments where there are some egions on the cross-dispersion axis that are ree of spectra. Ideally, there should be some ixels left on both boundaries, as well as etween the fibers.
	bbsw_pixelwise_subtraction		data may contain a full set of (beam-switched)
	bbsw_pixelwise_mfactor		never BBSW_PIXELWISE_SUBTRACTION is non-zero, s keyword, a scalar decimal value, sets the tiplication factor that is applied when tracting the offset spectra from the nominal ctra.
	exmonitor		If this keyword is set, a line profiles viewer is shown after all fitting is done when using optimal extraction.
	subtitle		If this keyword is set to a string, the string is added to the spectrum viewer title (in p3d_extract_optimal).
	nthreads		A scalar integer that specifies how many threads to use in the parallelized median calculation, as well as in the parallelized spectrum extraction. The default value is: 1
	daxis		Defines the dimension of the dispersion direction in the spectrum image; must be either 1 or 2. The default value is: 1
	cinv		Set this keyword to plot white lines on a black background instead of the default, which is to plot black lines on a white background.
	postscriptfile		see p3d_display_lineprofiles.
	compress		see p3d_display_lineprofiles.
	blockgui		The extracted-profiles checking GUI is blocked if this keyword is set.
	stawid		If set, various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
	topwid		If set, 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.
	font		Set this scalar string to the name of the font you want to use with all the widget components of this tool.
	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.
	cdebug		A keyword as DEBUG used with the called C routines.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

out

The resulting image of the extraction.

This routine is a wrapper for the two routines that perform the actual task of optimal extraction, viz. p3d_extract_optimal_mox and p3d_extract_optimal_mpd.

After the spectra have been extracted the line profile viewer of p3d is launched to allow an examination of the result.

Input parameters:

	im		A two-dimensional array, that holds the spectra that will be extracted here.
	traces		A two-dimensional array, that for every spectrum bin provides the y-position of every spectrum line on the raw data CCD image.
	dim		A two-dimensional array of the same dimensions as IM, with the errors of IM. DIMAGE must be present. The variance of IM is DIMAGE².
	lprofs		A three-dimensional array, that for every spectrum bin, of every spectrum, holds the fitting parameters of a cross-dispersion profile. The default value is: sp=size(lprofs)

Keyword parameters:

	ecalc		Errors are calculated and returned (DOUT) if this keyword is set. The default value is: 1
	bpmask		A two-dimensional array of byte type, and of the same dimensions as IM. The weight of all pixels that are non-zero in BPMASK are set to 0. This way bad pixels and pixels that are hit by cosmic rays are given no weight when the spectra are extracted. Note: If this mask is specified, the eliminate_crays option of the modified optimal extraction is always unset.
	obpmask		A two-dimensional output byte array, which indicates how many bad pixels each spectrum element involves. This array is only calculated if BPMASK is set.
	satmask		A two-dimensional output byte array, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set (passed on via _EXTRA here).
	proffun		A scalar string with the name of the function to use when (re-)calculating the line profile.
	profwidth		2 * PROFWIDTH + 1 is the total pixel-width of the interval where the flux is integrated. This parameter is only used if OPTEXMETHOD == 'modhorne', but is always used when plotting the profiles if MONITOR is set.
	userparfile		A scalar string specifying the name of an optional user-parameter file, that could contain any of the keywords that are described in the routine description.
	monitor		If this keyword is set, a line profiles viewer is shown after the extraction is done. The default value is: 1
	subtitle		If this keyword is set to a string, the string is added to the spectrum viewer title.
	cinv		Set this keyword to plot white lines on a black background instead of the default, which is to plot black lines on a white background.
	nthreads		A scalar integer that specifies how many threads to use in the parallelized spectrum extraction.
	postscriptfile		see p3d_display_lineprofiles.
	bbsw_pixelwise_subtraction		A keyword that is only used here to determine if the direct pixelwise subtraction is used; because, in this case this keyword is non-zero.
	noC		The C routines are not used if this keyword is set.
	stawid		If set, various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
	topwid		If set, 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		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.
	cdebug		A keyword as DEBUG used with the called C routines.
	help		Set this keyword to show this routine documentation, and then exit.
	_extra		Contains keywords that are passed on to other routines.

Output parameters:

	out		A two-dimensional array of the extracted spectra with the same dimensions as TRACES.
	dout		A two-dimensional array of the extracted spectra with the same dimensions as OUT. This is the error of OUT.

This routine extracts spectra from a two-dimensional spectrum image using the modified optimal extraction of Sandin et al. 2010, A&A, 515, A35. Optimal extraction weights are calculated according to the approach of Horne, K. 1986, PASP, 98, 609-617 (all equations in the comments refer to this paper).

The spectra are extracted using (pre-calculated) input profiles (over the cross-dispersion axis) to sum up the flux at every wavelength bin. The input image is turned into an extracted spectrum image, where every spectrum is placed in an individual row.

In order to correct for cross-talk the extraction is iterated; thereby recalculating the fraction every profile occupies of the total profile at every pixel. The total profile is the sum of all profiles in the cross-dispersion direction.

This method also allows for removal of cosmic rays, although note that it may be difficult to remove them efficiently. Also note that the flux is just removed if this method is used, no flux replacement or interpolation is used.

The following parameters are read from the user-parameter file:

Input parameters:

	im		A two-dimensional array, that holds the spectra that will be extracted here. The dispersion axis must be the x-axis.
	dim		A two-dimensional array of the same dimensions as IM, with the errors of IM. DIM must be present. The variance of IM is DIM².
	lprofs		A three-dimensional array, that for every spectrum bin, of every spectrum, holds the fitting parameters of a cross-dispersion profile. The default value is: sp=size(lprofs)

Keyword parameters:

	profwidth		2 * PROFWIDTH + 1 is the total pixel-width of the interval where the flux is integrated.
	detsec		A four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. RDNOISE must have as many elements as DETSEC has rows.
	gain		The data gain factor [e-/ADU]; a scalar decimal value.
	rdnoise		A decimal scalar or decimal array that specifies the readout noise [ADU]. RDNOISE must have as many elements as DETSEC has rows.
	proffun		A scalar string with the name of the function to use when (re-)calculating the line profile.
	nextensions		A scalar integer indicating the number of data extensions in the input raw data file. The default value is: 0
	rawdataarecombined		When this keyword is set, raw data of e blocks are read from separate files, which n combined into one image. Otherwise, they d from separate extensions. The default value is: 1
	ecalc		If this keyword is set, output errors are calculated. The default value is: 0
	bpmask		A two-dimensional array of byte type, and of the same dimensions as IM. The weight of all pixels that are non-zero in BPMASK are set to 0. This way, for example, bad pixels and pixels that are hit by cosmic rays are given no weight. Note: If this mask is specified, the eliminate_crays option of the modified optimal extraction is always unset.
	obpmask		A two-dimensional byte image of the same dimensions as OUT. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
	satlimit		A scalar integer that specifies the saturation limit that is used to define the value of the pixels in the saturation mask (SATMASK) [ADU]. If any of the pixel values that are included across the center part of the profile is higher than this limit, the output element is masked.
	satmask		A two-dimensional output byte array, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set.
	pmultfac		A scalar integer that specifies a profile multiplication factor; the profile is evaluated at this many times more points than the number of pixels in a profile.
	userparfile		A scalar string specifying the name of an optional user-parameter file, that could contain any of the keywords that are described in the routine description.
	skipw		This keyword can be set to a one-dimensional array with as many elements as there are wavelength bins. If it is set, no spectrum is calculated for bins j where skipw[j] == 1. This is a useful option with multi-extension data where there are empty bins between the detectors.
	rimage		A two-dimensional array of the same dimensions as IM, with the unprocessed version of IM. This array is used to calculate the saturated-pixels image that is available in SATMASK. This array is only considered if SATLIMIT is set.
	win_bsw		A three-dimensional integer array that specifies windows where the profile is set to zero.
	noC		The C routines are not used if this keyword is set.
	stawid		If set, various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
	topwid		If set, 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		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.
	cdebug		A keyword as DEBUG used with the called C routines.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

	out		A two-dimensional array of the extracted spectra with the same dimensions as the first two dimensions of LPROFS.
	dout		A two-dimensional array of the extracted spectra with the same dimensions as OUT. This is the error of OUT. DOUT is onlyt present if ECALC is set.

This routine extracts spectra from a two-dimensional spectrum image using the multi-profile deconvolution approach of Sharp & Birchall 2010, PASA, 27, 91.

The spectra are extracted using (pre-calculated) input profiles (over the cross-dispersion axis) to sum up the flux at every wavelength bin. The input image is turned into an extracted spectrum image, where every spectrum is placed in an individual row.

Depending on the number of neighbor profiles that are fitted a diffe- rent method is used to minimize the residual to find the intensities. If only one neighbor profile is used on either side of the reference profile then a tri-diagonal system of equations can be solved. If the number (MPDNPROF) is larger than 1 then it is possible to use either:

• A band-diagonal sparse matrix solver (MPDMETHOD='band-diagonal')

• Or solving by singular value decomposition (SVD, MPDMETHOD='svd'; see Numerical Recipes, 2nd ed., Sect. 2.6).

Note: This method has not yet been optimized for sparse arrays and is therefore extremely slow.

If either one of these latter two methods is used then the maximum number of iterations is MPDITMAX. If the SVD-method is used, all singular values which are smaller than MPDSVDLIM are set to 0 before calculating the intensities.

The following parameters are read from the user-parameter file:

Input parameters:

	im		A two-dimensional array, that holds the spectra that will be extracted here. The dispersion axis must be the x-axis.
	dim		A two-dimensional array of the same dimensions as IM, with the errors of IM. DIM must be present. The variance of IM is DIM².
	lprofs		A three-dimensional array, that for every spectrum bin, of every spectrum, holds the fitting parameters of a cross-dispersion profile. The default value is: sp=size(lprofs)

Keyword parameters:

	detsec		A four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. RDNOISE must have as many elements as DETSEC has rows.
	rdnoise		A decimal scalar or decimal array that specifies the readout noise [ADU]. RDNOISE must have as many elements as DETSEC has rows.
	proffun		A scalar string with the name of the function to use when (re-)calculating the line profile.
	nextensions		A scalar integer indicating the number of data extensions in the input raw data file. The default value is: 0
	rawdataarecombined		When this keyword is set, raw data of e blocks are read from separate files, which n combined into one image. Otherwise, they d from separate extensions. The default value is: 1
	ecalc		If this keyword is set, output errors are calculated.
	bpmask		An two-dimensional array of byte type, and of the same dimensions as IM. The weight of all pixels that are non-zero in BPMASK are set to 0. This way, for example, bad pixels and pixels that are hit by cosmic rays are given no weight.
	obpmask		A two-dimensional byte image of the same dimensions as OUT. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
	satlimit		A scalar integer that specifies the saturation limit that is used to define the value of the pixels in the saturation mask (SATMASK) [ADU]. If any of the pixel values that are included across the center part of the profile is higher than this limit, the output element is masked.
	satmask		A two-dimensional output byte array, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set.
	pmultfac		A scalar integer that specifies a profile multiplication factor; the profile is evaluated at this many times more points than the number of pixels in a profile.
	nthreads		A scalar integer that specifies how many threads to use in the parallelized spectrum extraction.
	userparfile		A scalar string specifying the name of an optional user-parameter file, that could contain any of the keywords that are described in the routine description.
	skipw		This keyword can be set to a one-dimensional array with as many elements as there are wavelength bins. If it is set, no spectrum is calculated for bins j where skipw[j]==1. This is a useful option with multi-extension data where there are empty bins between the detectors.
	rimage		A two-dimensional array of the same dimensions as IM, with the unprocessed version of IM. This array is used to calculate the saturated-pixels image that is available in SATMASK. This array is only considered if SATLIMIT is set.
	bsw		A scalar integer that defines if the data contain beam-switched spectra (BSW <> 0) or not (BSW = 0).
	win_bsw		A three-dimensional integer array that specifies windows where the profile is set to zero.
	noC		The C routines are not used if this keyword is set.
	stawid		If set, various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
	topwid		If set, 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		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.
	cdebug		A keyword as DEBUG used with the called C routines.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

	out		A two-dimensional array of the extracted spectra with the same dimensions as the first two dimensions of LPROFS.
	dout		A two-dimensional array of the extracted spectra with the same dimensions as OUT. This is the error of OUT. DOUT is onlyt present if ECALC is set.

This routine loads a science-object image, a bad-pixel mask image, a trace-mask image, and a master-bias image. The data are checked for consistency in terms of array sizes and used binning parameters. In a second step, all data are trimmed of prescan and overscan regions using the DETSEC keyword.

The data are returned as is (i.e. no transposing).

Input parameters:

	extractfile		The input raw data image that is to be treated.
	tracefile		A corresponding input file for tracing.

Keyword parameters:

	kwrdlist		A two-dimensional string array holding the instrument-specific keywords for a defined set of keywords which are used to determine the ROI on the CCD. KWRDLIST must have two columns.
	crmaskfile		The filename of an, optional, cosmic-ray hit mask file. If this keyword is used the argument must be different from an empty string to use the keyword. If this keyword is at all present and the filename that is contained in CRMASKFILE does not exist, an attempt is made to read the mask from the (EXTNAME=)'MASK' extension in EXTRACTFILE.
	bpmaskfile		The filename of an, optional, bad-pixel mask file.
	bpmaskdata		Returns a bad-pixel mask image that is the ORed version of the input images of CRMASKFILE and BPMASKFILE, where prescan and overscan regions, if any, have been removed (only present if BPMASKFILE is set).
	userparfile		A scalar string specifying the name of an optional user-parameter file, that could contain the keyword 'detsec'. If it does, the value of that keyword is used to trim the data. If there are several 'detsec'-lines in the file, only the first is used.
	xbin		The CCD binning number; x-direction.
	ybin		The CCD binning number; y-direction.
	masterbias		The data of MASTERBIAS will be used as bias data.
	poscanonly		The trace-mask image is not considered if this keyword is set. This is useful if the only required output are the prescan and the overscan arrays.
	parfile		A string specifying the filename of an existing file containing instrument-specific parameters.
	xsize		Upon return, this value is set to the x-size of the extracted data.
	ysize		Upon return, this value is set to the y-size of the extracted data.
	x0		Upon return, this value is set to the x-offset of the extracted data.
	y0		Upon return, this value is set to the y-offset of the extracted data.
	blocksarecombined		If this keyword is set, the prescan and overscan gions are assumed to have been removed from the put data already.
	rawdataarecombined		When this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
	prescanx		This keyword is used with multi-block instruments that do not use the 'blocksarecombined' instrument parameter, as well as all single block instruments. For each block this keyword contains the x axis prescan array (as tags 'd1'–'dn', where n is short for the number of blocks). Each array has as many elements as the data have rows (on the y axis). The tag contains the scalar integer -1 when there is no x-axis prescan.
	prescany		This keyword is used with multi-block instruments that do not use the 'blocksarecombined' instrument parameter, as well as all single block instruments. For each block this keyword contains the y axis prescan array (as tags 'd1'–'dn', where n is short for the number of blocks). Each array has as many elements as the data have columns (on the x axis). The tag contains the scalar integer -1 when there is no y-axis prescan.
	overscanx		This keyword is used with single-block instruments. It contains the x axis overscan array (as tag 'd1'). The array has as many elements as the data have rows (on the y axis). The tag contains the scalar integer -1 when there is no x-axis overscan.
	overscany		This keyword is used with single-block instruments. It contains the y axis overscan array (as tag 'd1'). The array has as many elements as the data have columns (on the x axis). The tag contains the scalar integer -1 when there is no y-axis overscan.
	exptime_sec		A scalar decimal value that is set to the exposure time when using beam-switched data; the returned value is half the exposure time read from the raw input file.
	exptime_str		A one or two-element string array with the name of the exposure time keyword used to write the exposure time in EXPTIME_SEC.
	daxis		Specifies the dispersion dimension in the input images (EXTRACTFILE, TRACEFILE, MASTERBIAS). The default value is: 1
	detector		A scalar integer that specifies the currently selected detector; DETECTOR is a zero-based value. This value is passed on to p3d_misc_detsec.
	topwid		If set, 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		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.

Output parameters:

	trace		Returns the trace mask data array where prescan and overscan regions, if any, have been removed.
	object		Returns the science-object image where prescan and overscan regions, if any, have been removed.
	mbias		If MASTERBIAS is set, this variable returns the master-bias image where prescan and overscan regions, if any, have been removed.
	bsw		A scalar integer where a non-zero value indicates that the spectra are beam switched; i.e. the spectra are interleaved with another set of spectra, which could be of the sky or another instrument setup. A non-zero number corresponds to the unbinned pixel separation on the cross-dispersion axis.

This routine provides a simple spectrum extraction algorithm. Using the input image an extracted spectrum image is calculated, where each spectrum is placed in an individual row.

The spectra are extracted from the input image by summing up the flux in each wavelength bin over an interval of the width 2 * PROFWIDTH + 1 in the cross-dispersion direction. The input trace mask is used to find the spectra.

Input parameters:

	image		A two-dimensional array.
	traces		A two-dimensional array, which for every spectrum bin provides the y-position of every spectrum line on the raw data CCD image.

Keyword parameters:

	dimage		A two-dimensional array of the same dimensions as IMAGE, with the errors of IMAGE. If this keyword is present, an output error image, DOUT, is calculated.
	bpmask		A two-dimensional array of byte type, and of the same dimensions as IMAGE. This array is used to calculate an output bad-pixels mask that is returned in OBPMASK.
	obpmask		A two-dimensional byte image of the same dimensions as OUT. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
	satlimit		A scalar integer that specifies the saturation limit that is used to set each element in the saturation mask (SATMASK) [ADU].
	satmask		A two-dimensional output byte array, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set.
	profwidth		2 * PROFWIDTH + 1 is the total width of the interval where the flux is integrated; only used when VARIABLE_PROFWIDTH == 0.
	variable_profwidth		When this keyword is set, the spectrum width, for every spectrum bin in the cross-dispersion direction, is estimated to be half the separation between any two separated spectra. The default value is: 0
	skipw		This keyword can be set to a one-dimensional array with as many elements as there are wavelength bins. If it is set, no spectrum is calculated for bins //j// where skipw[j] == 1. This is a useful option with multi-extension data where there are empty bins between the detectors.
	rimage		A two-dimensional array of the same dimensions as IMAGE, with the unprocessed version of IMAGE. This array is used to calculate the saturated-pixels image that is available in SATMASK. This array is only considered if SATLIMIT is set.
	crebuild		The C-library is recompiled when this keyword is set.
	noC		The C routine is not used if this keyword is set.
	nthreads		A scalar integer that specifies how many threads to use in the parallelized spectrum extraction.
	stawid		If set, various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
	topwid		If set, 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		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.
	cdebug		A keyword as DEBUG used with the called C routine.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

out

A two-dimensional array of the extracted spectra with the same dimensions as TRACES.