MUSE Pipeline Reference Manual  2.1.1
Functions | Variables
Tracing

Functions

static cpl_vector * muse_trace_horizontal_cut (const muse_image *aImage, unsigned int aNRows)
 Create a vector containing a representative horizontal image cut. More...
 
cpl_vector * muse_trace_locate_slices (cpl_vector *aRowVec, const unsigned short aNSlices, double aFrac, const unsigned char aIFU)
 Find all slice midpoints across a CCD. More...
 
double muse_trace_edgefinder (const cpl_vector *aDataVec, double aFrac, double *aLeft, double *aRight, cpl_boolean *aHighSN, const unsigned char aIFU)
 Find the midpoint and edges of a cut through a slice. More...
 
static double muse_trace_refine_edge (cpl_vector *aDiffVec, double *aLeft, double *aRight, int aOffset, double aY, const unsigned short aSlice, const unsigned char aIFU)
 Find more exact midpoint and edge positions using a difference vector of the input data. More...
 
static cpl_polynomial ** muse_trace_iterate_fit (cpl_matrix *aX, cpl_vector *aY, cpl_vector *aWidths, const unsigned short aSlice, const unsigned char aIFU, const unsigned int aFitorder, const float aWSigma, const float aRSigma, cpl_vector *aMSE)
 iterate the tracing solution to remove outliers More...
 
cpl_table * muse_trace (const muse_image *aImage, int aNSum, double aEdgeFrac, int aFitorder, cpl_table **aSamples)
 carry out the tracing of the slices on CCD, save parameters in table More...
 
int muse_trace_table_get_order (const cpl_table *aTable)
 determine order of tracing polynomial from table More...
 
cpl_polynomial ** muse_trace_table_get_polys_for_slice (const cpl_table *aTable, const unsigned short aSlice)
 construct polynomial from the trace table entry for the given slice More...
 
void muse_trace_polys_delete (cpl_polynomial *aPolys[])
 Delete the multi-polynomial array created in relation to tracing. More...
 
cpl_error_code muse_trace_plot_samples (cpl_table *aSamples, cpl_table *aTrace, unsigned short aSlice1, unsigned short aSlice2, unsigned char aIFU, muse_image *aImage)
 Plotting of trace sample points and solution using gnuplot. More...
 
cpl_error_code muse_trace_plot_widths (cpl_table *aSamples, unsigned short aSlice1, unsigned short aSlice2, unsigned char aIFU)
 Plotting the width from trace sample points using gnuplot. More...
 

Variables

const muse_cpltable_def muse_tracesamples_def []
 MUSE tracing sample points table definition.
 

Detailed Description

Function Documentation

cpl_table* muse_trace ( const muse_image aImage,
int  aNSum,
double  aEdgeFrac,
int  aFitorder,
cpl_table **  aSamples 
)

carry out the tracing of the slices on CCD, save parameters in table

Parameters
aImagemuse_image that holds the image for tracing
aNSumnumber of image rows to combine when tracing; -1<=aNSum<=1: no combination < -1: use average, > 1: use median
aEdgeFracfraction of median used to identify an edge
aFitorderpolynomial order used for tracing
aSamplesthis table is filled with debug information on tracing sample points
Returns
the cpl_table* containing the trace parameters, or NULL on error

The algorithms used here do not work well to take into account bad pixels. The dq component of aImage is therefore used to interpolate all bad pixels as a first step. (Note however, that the original image is not changed.) Then create a horizontal cut through the slices. For this purpose, cut out a number of rows (on the order of 100 pix high) of the input image near its vertical center, use a median filter to remove cosmic rays, and average all rows to form a 1D cut. Using this cut, determine the center of each slice in the vertical center of the CCD, using muse_trace_locate_slices(), taking into account the aEdgeFrac parameter. Loop over all slices and within each slice over all tracepoints (determined by aNSum). For each tracepoint, create a cut by collapsing aNSum rows over a width larger than the expected slice width. For this cut, determine the exact center of the slice, using muse_trace_edgefinder(), taking into account the aEdgeFrac parameter. Fit the trace with a polynomial of order aFitorder and store the polynomial coefficients in the output table.

Quality Assessment:
Statistics on the edge positions within each slice and comparing left and right edge of the slices should give a robust indication of tracing failures.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLinput image is missing
set CPL_ERROR_ILLEGAL_INPUT, return NULLaNSum is not positive
set CPL_ERROR_ILLEGAL_INPUT, return NULLaEdgeFrac is invalid (<=0 or >=1)
set CPL_ERROR_ILLEGAL_INPUT, return NULLaFitOrder is not positive
return NULL, propagating the error set by muse_trace_locate_slicescould not carry out first guess of slice positions
return NULL, propagate error of cpl_table_newcould not allocate space for tracing table
output warning, single failures can occur in spectral regions of low S/Nedge finding failed at one position

Definition at line 967 of file muse_tracing.c.

References muse_image::data, muse_image::dq, muse_image::header, muse_cpltable_new(), muse_image_delete(), muse_image_new(), muse_image_reject_from_dq(), muse_pfits_get_dateobs(), muse_trace_edgefinder(), muse_trace_horizontal_cut(), muse_trace_iterate_fit(), muse_trace_locate_slices(), muse_trace_polys_delete(), muse_trace_refine_edge(), and muse_utils_get_ifu().

double muse_trace_edgefinder ( const cpl_vector *  aDataVec,
double  aFrac,
double *  aLeft,
double *  aRight,
cpl_boolean *  aHighSN,
const unsigned char  aIFU 
)

Find the midpoint and edges of a cut through a slice.

Parameters
aDataVeccpl_vector with the data
aFracfraction of median used to identify an edge
aLeftreturn left edge found
aRightreturn right edge found
aHighSNreturn if the input vector has S/N high enough for significant edge detection
aIFUthe IFU number
Returns
the location of the derived midpoint as double, a negative value on error

Go along the input data vector to search for the two outer edges of the slice. An edge is detected by comparing the data value to the median value along the data vector; if the difference is larger than aFrac times the median of the data vector, an edge was found. The returned midpoint is the arithmetic mean of the two edge positions for each slice.

Quality Assessment:
Will be done in the calling function muse_trace().
Exceptions
return -1a right edge could not be found
return -2a left edge could not be found
set CPL_ERROR_ILLEGAL_INPUT, return -3the vector has too few elements
set CPL_ERROR_ILLEGAL_INPUT, return -4aFrac is invalid (<0 or >1)
set CPL_ERROR_NULL_INPUT, return -5the out parameters aLeft and aRight are NULL
output error message, return -11faulty interpolation at right-hand edge
output error message, return -12faulty interpolation at left-hand edge

Definition at line 372 of file muse_tracing.c.

References muse_cplvector_get_adev_const().

Referenced by muse_trace().

static cpl_vector* muse_trace_horizontal_cut ( const muse_image aImage,
unsigned int  aNRows 
)
static

Create a vector containing a representative horizontal image cut.

Parameters
aImagethe input image, most likely a master flat-field
aNRowsnumber of rows to collapse in each quadrant
Returns
the vertically collapsed data as cpl_vector or NULL on error

Use two data samples from a bit below and above the vertical image center, and create a vector containing the maximum of both samples. This minimizes the possible influence of dark columns onto the output vector.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaImage or its data component are NULL

Definition at line 78 of file muse_tracing.c.

References muse_image::data, muse_image::header, muse_quadrants_get_window(), and muse_utils_get_ifu().

Referenced by muse_trace().

static cpl_polynomial** muse_trace_iterate_fit ( cpl_matrix *  aX,
cpl_vector *  aY,
cpl_vector *  aWidths,
const unsigned short  aSlice,
const unsigned char  aIFU,
const unsigned int  aFitorder,
const float  aWSigma,
const float  aRSigma,
cpl_vector *  aMSE 
)
static

iterate the tracing solution to remove outliers

Parameters
aXmatrix with the tracing x coordinates
aYvector with the tracing y coordinates
aWidthsvector with the slice width at each point
aSlicethe number of the current slice (for debugging output)
aIFUthe IFU number
aFitorderthe polynomial order to use for the fit
aWSigmarejection sigma to use for widths
aRSigmarejection sigma to use for residuals
aMSEoutput mean squared error of fit (cpl_vector of MUSE_TRACE_NPOLY values)
Returns
The polynomial fits in a MUSE_TRACE_NPOLY-element array or NULL on error.

This function expects at least 3 trace points in the input structures and will return CPL_ERROR_ILLEGAL_INPUT if this is not the case.

aX, aY, and aWidth will be changed by this function, if outliers are present they are removed.

The sigmas are given in terms of median absolute deviations.

The aMSE values will have a value of FLT_MAX in case the polynomial fit returned an error.

The returned array of polynomials has to be freed using muse_trace_polys_delete() after use.

Definition at line 715 of file muse_tracing.c.

References muse_cplvector_erase_element(), muse_cplvector_get_adev_const(), and muse_utils_iterate_fit_polynomial().

Referenced by muse_trace().

cpl_vector* muse_trace_locate_slices ( cpl_vector *  aRowVec,
const unsigned short  aNSlices,
double  aFrac,
const unsigned char  aIFU 
)

Find all slice midpoints across a CCD.

Parameters
aRowVeccpl_vector containing the row data from the (middle) of the CCD
aNSlicesnumber of slices in the MUSE CCD
aFracstart fraction of median used to identify edges
aIFUthe IFU number
Returns
the slit centers as cpl_vector * or NULL in case of failure
Remarks
The first slice is assumed to be fully located within the first aFirstSlice pixels, a slice is assumed to be no wider than aMaxWidth pixels.

Go along the input data vector to search for the two outer edges of the first slice. An edge is detected by comparing the data value to the median value along the data vector. If the difference is larger than aFrac times the median of the data vector, an edge was found. This procedure is repeated for all aNSlices. If not all slices are located at least a certain distance apart, the routine is rerun with a decreased aFrac. The returned midpoints are the arithmetic mean of the two edge positions for each slice.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaRowVec is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaFrac is invalid (<0 or >1)
set MUSE_ERROR_SLICE_LEFT_MISSING, return NULLsearch for first slice (left-edge) failed
set MUSE_ERROR_SLICE_RIGHT_MISSING, return NULLsearch for first slice (right-edge) failed
set MUSE_ERROR_SLICE_EDGE_MISSING, return NULLsearch for an edge of any of the other slices failed (less than 96 edges are found)
set CPL_ERROR_ACCESS_OUT_OF_RANGE, return NULLinitial slice was found to be too narrow or too wide

Definition at line 162 of file muse_tracing.c.

References muse_cplvector_get_adev_const().

Referenced by muse_trace().

cpl_error_code muse_trace_plot_samples ( cpl_table *  aSamples,
cpl_table *  aTrace,
unsigned short  aSlice1,
unsigned short  aSlice2,
unsigned char  aIFU,
muse_image aImage 
)

Plotting of trace sample points and solution using gnuplot.

Parameters
aSamplesthe table with all trace sample points
aTracethe table with the tracing solution
aSlice1first slice to plot (1 or lower starts with the first one)
aSlice2last slice to plot (kMuseSlicesPerCCD or higher ends with the last one)
aIFUthe IFU number (only used if > 0)
aImagethe image to use as background for the plot
Returns
CPL_ERROR_NONE on success a CPL error code on failure
Exceptions
return CPL_ERROR_NULL_INPUTinput aSamples table is NULL
return CPL_ERROR_ILLEGAL_INPUTinput table is not a MUSE trace samples table
return CPL_ERROR_ASSIGNING_STREAMgnuplot stream (pipe) could not be opened
return CPL_ERROR_UNSUPPORTED_MODEplatform does not have popen() or pclose()
set CPL error message to contain failing filename, return CPL_ERROR_FILE_NOT_CREATEDcould not open temporary file for plotting of data

Definition at line 1546 of file muse_tracing.c.

References muse_image::data, muse_cpltable_check(), and muse_trace_table_get_order().

cpl_error_code muse_trace_plot_widths ( cpl_table *  aSamples,
unsigned short  aSlice1,
unsigned short  aSlice2,
unsigned char  aIFU 
)

Plotting the width from trace sample points using gnuplot.

Parameters
aSamplesthe table with all trace sample points
aSlice1first slice to plot (1 or lower starts with the first one)
aSlice2last slice to plot (kMuseSlicesPerCCD or higher ends with the last one)
aIFUthe IFU number (only used if > 0)
Returns
CPL_ERROR_NONE on success a CPL error code on failure

Uses color-coded lines/points for each relevant slice, ranging from red on the leftmost slice to green on the rightmost one.

Exceptions
return CPL_ERROR_NULL_INPUTinput aSamples table is NULL
return CPL_ERROR_ILLEGAL_INPUTinput table is not a MUSE trace samples table
return CPL_ERROR_ASSIGNING_STREAMgnuplot stream (pipe) could not be opened
return CPL_ERROR_UNSUPPORTED_MODEplatform does not have popen() or pclose()
set CPL error message to contain failing filename, return CPL_ERROR_FILE_NOT_CREATEDcould not open temporary file for plotting of data

Definition at line 1766 of file muse_tracing.c.

References muse_cpltable_check().

void muse_trace_polys_delete ( cpl_polynomial *  aPolys[])

Delete the multi-polynomial array created in relation to tracing.

Parameters
aPolysthe array of polynomials

Definition at line 1452 of file muse_tracing.c.

Referenced by muse_geo_determine_initial(), muse_geo_measure_spots(), muse_pixtable_create(), muse_quality_flat_badpix(), muse_trace(), muse_wave_calib(), muse_wave_calib_lampwise(), and muse_wave_map().

static double muse_trace_refine_edge ( cpl_vector *  aDiffVec,
double *  aLeft,
double *  aRight,
int  aOffset,
double  aY,
const unsigned short  aSlice,
const unsigned char  aIFU 
)
static

Find more exact midpoint and edge positions using a difference vector of the input data.

Parameters
aDiffVeccpl_vector with the data
aLeftinitial value and return parameter for left edge
aRightinitial value and return parameter for right edge
aOffsetoffset of coordinates to master flat image
aYapproximate center in the vertical direction (just for debugging output)
aSlicethe slice number
aIFUthe IFU number
Returns
the location of the derived midpoint as double, a negative value on error

Fit Gaussians to positive peak near initial position *aLeft and to negative dip near initial position *aRight to get more exact slice edges. The returned midpoint is the arithmetic mean of the two edge positions for each slice.

Exceptions
return -1output midpoint is shifted too much with regard to initial values
set CPL_ERROR_ILLEGAL_INPUT, return -3the vector has too few elements
set CPL_ERROR_NULL_INPUT, return -5the out parameters aLeft and aRight are NULL
set CPL_ERROR_NULL_INPUT, return -6aLeft and aRight contain bad initial values

Definition at line 541 of file muse_tracing.c.

Referenced by muse_trace().

int muse_trace_table_get_order ( const cpl_table *  aTable)

determine order of tracing polynomial from table

Parameters
aTabletrace table holding the trace solution
Returns
the polynomial order or a negative value on error

Assumption: the table only contains the coefficients, the slice number, the MSE, and the slice width.

Definition at line 1363 of file muse_tracing.c.

Referenced by muse_pixtable_create(), muse_trace_plot_samples(), muse_trace_table_get_polys_for_slice(), and muse_wave_map().

cpl_polynomial** muse_trace_table_get_polys_for_slice ( const cpl_table *  aTable,
const unsigned short  aSlice 
)

construct polynomial from the trace table entry for the given slice

Parameters
aTabletrace table holding the trace solution
aSlicethe slice number, between 1 and kMuseSlicesPerCCD
Returns
the polynomials defining the trace of the given slice as a three-element array or NULL on error

The returned polynomials have to be deallocated using muse_trace_polys_delete() after use.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaTable is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaSlice is outside the valid range of slices for MUSE
set CPL_ERROR_DATA_NOT_FOUND, return NULLthe requested slice cannot be found in the table
set CPL_ERROR_ILLEGAL_OUTPUT, return NULLa coefficient in aTable cannot be read

Definition at line 1393 of file muse_tracing.c.

References muse_trace_table_get_order().

Referenced by muse_geo_determine_initial(), muse_geo_measure_spots(), muse_pixtable_create(), muse_quality_flat_badpix(), muse_wave_calib(), muse_wave_calib_lampwise(), and muse_wave_map().