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.
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.
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.
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.
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
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
int muse_trace_table_get_order (const cpl_table *aTable)
 determine order of tracing polynomial from table
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
void muse_trace_polys_delete (cpl_polynomial *aPolys[])
 Delete the multi-polynomial array created in relation to tracing.
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.
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.

Variables

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

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:
aImage muse_image that holds the image for tracing
aNSum number of image rows to combine when tracing; -1<=aNSum<=1: no combination < -1: use average, > 1: use median
aEdgeFrac fraction of median used to identify an edge
aFitorder polynomial order used for tracing
aSamples this 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 NULL input image is missing
set CPL_ERROR_ILLEGAL_INPUT, return NULL aNSum is not positive
set CPL_ERROR_ILLEGAL_INPUT, return NULL aEdgeFrac is invalid (<=0 or >=1)
set CPL_ERROR_ILLEGAL_INPUT, return NULL aFitOrder is not positive
return NULL, propagating the error set by muse_trace_locate_slices could not carry out first guess of slice positions
return NULL, propagate error of cpl_table_new could not allocate space for tracing table
output warning, single failures can occur in spectral regions of low S/N edge finding failed at one position

Definition at line 936 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:
aDataVec cpl_vector with the data
aFrac fraction of median used to identify an edge
aLeft return left edge found
aRight return right edge found
aHighSN return if the input vector has S/N high enough for significant edge detection
aIFU the 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 -1 a right edge could not be found
return -2 a left edge could not be found
set CPL_ERROR_ILLEGAL_INPUT, return -3 the vector has too few elements
set CPL_ERROR_ILLEGAL_INPUT, return -4 aFrac is invalid (<0 or >1)
set CPL_ERROR_NULL_INPUT, return -5 the out parameters aLeft and aRight are NULL
output error message, return -11 faulty interpolation at right-hand edge
output error message, return -12 faulty 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:
aImage the input image, most likely a master flat-field
aNRows number 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 NULL aImage 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:
aX matrix with the tracing x coordinates
aY vector with the tracing y coordinates
aWidths vector with the slice width at each point
aSlice the number of the current slice (for debugging output)
aIFU the IFU number
aFitorder the polynomial order to use for the fit
aWSigma rejection sigma to use for widths
aRSigma rejection sigma to use for residuals
aMSE output 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 684 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:
aRowVec cpl_vector containing the row data from the (middle) of the CCD
aNSlices number of slices in the MUSE CCD
aFrac start fraction of median used to identify edges
aIFU the 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 NULL aRowVec is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULL aFrac is invalid (<0 or >1)
set MUSE_ERROR_SLICE_LEFT_MISSING, return NULL search for first slice (left-edge) failed
set MUSE_ERROR_SLICE_RIGHT_MISSING, return NULL search for first slice (right-edge) failed
set MUSE_ERROR_SLICE_EDGE_MISSING, return NULL search for an edge of any of the other slices failed (less than 96 edges are found)
set CPL_ERROR_ACCESS_OUT_OF_RANGE, return NULL initial 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:
aSamples the table with all trace sample points
aTrace the table with the tracing solution
aSlice1 first slice to plot (1 or lower starts with the first one)
aSlice2 last slice to plot (kMuseSlicesPerCCD or higher ends with the last one)
aIFU the IFU number (only used if > 0)
aImage the 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_INPUT input aSamples table is NULL
return CPL_ERROR_ILLEGAL_INPUT input table is not a MUSE trace samples table
return CPL_ERROR_ASSIGNING_STREAM gnuplot stream (pipe) could not be opened
return CPL_ERROR_UNSUPPORTED_MODE platform does not have popen() or pclose()
set CPL error message to contain failing filename, return CPL_ERROR_FILE_NOT_CREATED could not open temporary file for plotting of data

Definition at line 1515 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:
aSamples the table with all trace sample points
aSlice1 first slice to plot (1 or lower starts with the first one)
aSlice2 last slice to plot (kMuseSlicesPerCCD or higher ends with the last one)
aIFU the 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_INPUT input aSamples table is NULL
return CPL_ERROR_ILLEGAL_INPUT input table is not a MUSE trace samples table
return CPL_ERROR_ASSIGNING_STREAM gnuplot stream (pipe) could not be opened
return CPL_ERROR_UNSUPPORTED_MODE platform does not have popen() or pclose()
set CPL error message to contain failing filename, return CPL_ERROR_FILE_NOT_CREATED could not open temporary file for plotting of data

Definition at line 1735 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:
aPolys the array of polynomials

Definition at line 1421 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:
aDiffVec cpl_vector with the data
aLeft initial value and return parameter for left edge
aRight initial value and return parameter for right edge
aOffset offset of coordinates to master flat image
aY approximate center in the vertical direction (just for debugging output)
aSlice the slice number
aIFU the 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 -1 output midpoint is shifted too much with regard to initial values
set CPL_ERROR_ILLEGAL_INPUT, return -3 the vector has too few elements
set CPL_ERROR_NULL_INPUT, return -5 the out parameters aLeft and aRight are NULL
set CPL_ERROR_NULL_INPUT, return -6 aLeft and aRight contain bad initial values

Definition at line 510 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:
aTable trace 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 1332 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:
aTable trace table holding the trace solution
aSlice the 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 NULL aTable is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULL aSlice is outside the valid range of slices for MUSE
set CPL_ERROR_DATA_NOT_FOUND, return NULL the requested slice cannot be found in the table
set CPL_ERROR_ILLEGAL_OUTPUT, return NULL a coefficient in aTable cannot be read

Definition at line 1362 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().


Generated on 26 Jan 2017 for MUSE Pipeline Reference Manual by  doxygen 1.6.1