UVES Pipeline Reference Manual  5.4.0
Functions
Recipe: Order Position

Functions

static cpl_table * trace_order (const cpl_table *ordertable, int order, const cpl_image *inputimage, const cpl_image *noise, const cpl_binary *image_bad, int TRACESTEP, double MAXGAP)
 Trace a single order line.
static int count_orders (const cpl_table *tracetable)
 Count orders in trace table.
static double fit_order_linear (cpl_table *singletrace, int order, double KAPPA, double *slope)
 Make a linear fit of an order trace.
static int get_xcenter (int nx, int ny, cpl_table *ordertable, int row)
 Calculate the x-center of an order.
static int get_ycenter (int nx, int ny, cpl_table *ordertable, int row)
 Calculate the y-center of an order.
static int get_orderlength (int nx, int ny, cpl_table *ordertable, int row)
 Calculate the length of an order line.
static double estimate_threshold (const cpl_image *inputimage, const cpl_image *noise, cpl_table *ordertable, int row, double relative_threshold)
 Calculate threshold for order tracing algorithm.
static bool find_centroid (const cpl_image *inputimage, const cpl_image *noise, const cpl_binary *image_bad, double threshold, int spacing, int x, double *yguess, double *dY)
 Find order line centroid.
cpl_table * uves_locate_orders (const cpl_image *inputimage, const cpl_image *noise, cpl_table *ordertable, int TRACESTEP, double MINTHRESH, double MAXGAP, double MAXRMS, int *DEFPOL1, int *DEFPOL2, double KAPPA, polynomial **bivariate_fit, int *orders_traced)
 Trace all orders.
static cpl_table * detect_lines (cpl_image *htrans, int minintersept, const cpl_image *inputimage, int NORDERS, bool norders_is_guess, int SAMPLEWIDTH, double PTHRES, double MINSLOPE, double MAXSLOPE, int SLOPERES, bool consecutive)
 Detect order lines from the Hough image.
static cpl_error_code delete_peak (cpl_image *htrans, int minintersept, int hxmax, int hymax, int SPACING, int imagewidth, int SAMPLEWIDTH, double MINSLOPE, double MAXSLOPE, int SLOPERES)
 Delete peak in Hough image.
static int firsttrace (int nx, int SAMPLEWIDTH)
 Get the first trace column.
static int calculate_spacing (const cpl_image *image, int x)
 Estimate spacing of order lines.
static double autocorr (const cpl_image *image, const int x, const int shift)
 Calculate auto-correlation function of image column.
static cpl_error_code update_max (const cpl_image *htrans, int *xmax, int *ymax, int SPACING, int imagewidth, int SAMPLEWIDTH, double MINSLOPE, double MAXSLOPE, int SLOPERES)
 Improve position of a peak in the Hough image.
cpl_table * uves_hough (const cpl_image *image, int ymin, int ymax, int NORDERS, bool norders_is_guess, int SAMPLEWIDTH, double PTHRES, double MINSLOPE, double MAXSLOPE, int SLOPERES, bool consecutive, cpl_image **htrans, cpl_image **htrans_original)
 Compute Hough transform and detect lines.
cpl_error_code uves_draw_orders (const cpl_table *ordertable, cpl_image *image)
 Draw detected order lines.

Detailed Description

This recipe determines the echelle order locations. See man-page for details.


Function Documentation

static cpl_table * trace_order ( const cpl_table *  ordertable,
int  order,
const cpl_image *  inputimage,
const cpl_image *  noise,
const cpl_binary *  image_bad,
int  TRACESTEP,
double  MAXGAP 
)
static

Trace a single order line.

Parameters:
ordertableBasic order table
order(Relative) number of order to trace
inputimageThe input image
image_badimage bad pixel map
noiseNoise of input image
TRACESTEPThe step size (i.e. x-increment) used when tracing
MAXGAPThe maximum gap length to jump (in units of image width)
Returns:
A table defining the order trace, or NULL on error

The order is traced in both directions starting from the center of the order (which is inferred from the slopes and intersepts read from the provided ordertable).

The order line is sampled at x-positions seperated by the parameter TRACESTEP. At each x-position, the y-centroid of the order is calculated. The trace stops if the intensity of the order line is below a certain threshold value in a range determined by the parameter MAXGAP.

The order is traced as far as possible using the lowest threshold value.

The returned table contains three columns, 'X', 'Y' (describing the trace of the order) and 'dY' (uncertainty of 'Y').

Definition at line 1127 of file uves_orderpos_follow.c.

References check, find_centroid(), uves_msg_debug, and xcenter().

Referenced by uves_locate_orders().

static int count_orders ( const cpl_table *  tracetable)
static

Count orders in trace table.

Parameters:
tracetableThe order trace table
Returns:
Number of different values present in the column 'Order'

/*/ /*—————————————————————————-

Definition at line 948 of file uves_orderpos_follow.c.

References passure.

Referenced by uves_locate_orders().

static double fit_order_linear ( cpl_table *  singletrace,
int  order,
double  KAPPA,
double *  slope 
)
static

Make a linear fit of an order trace.

Parameters:
singletraceOrder table containing a single order
order(Relative) number of the order to fit (used only for messaging)
KAPPAValue used for kappa-sigma clipping
slope(output) from linear fit
Returns:
The RMS error of the fit, or undefined on error.

The function fits a straight line to the specified order and returns the RMS error of the fit. The columns 'Polynomial fit', 'Residual_Square' and 'OrderRMS' (containing the RMS at every row) are added to the table.

Definition at line 992 of file uves_orderpos_follow.c.

References check, passure, uves_msg_debug, uves_polynomial_delete(), uves_polynomial_evaluate_1d(), uves_polynomial_get_coeff_1d(), and uves_polynomial_regression_1d().

Referenced by uves_locate_orders().

static int get_xcenter ( int  nx,
int  ny,
cpl_table *  ordertable,
int  row 
)
static

Calculate the x-center of an order.

Parameters:
nxWidth of input image
nyHeight of input image
ordertableBasic order table
rowRow of order table to use
Returns:
X-coordinate of the order line center

Note that the line center is different from nx / 2, if the order line crosses the upper or low boundary of the image.

Definition at line 1374 of file uves_orderpos_follow.c.

References check.

Referenced by get_ycenter(), and uves_locate_orders().

static int get_ycenter ( int  nx,
int  ny,
cpl_table *  ordertable,
int  row 
)
static

Calculate the y-center of an order.

Parameters:
nxWidth of input image
nyHeight of input image
ordertableBasic order table
rowRow of order table to use
Returns:
Y-coordinate of the order line center

See get_xcenter() .

Definition at line 1426 of file uves_orderpos_follow.c.

References check, and get_xcenter().

Referenced by uves_locate_orders().

static int get_orderlength ( int  nx,
int  ny,
cpl_table *  ordertable,
int  row 
)
static

Calculate the length of an order line.

Parameters:
nxWidth of input image
nyHeight of input image
ordertableBasic order table
rowRow of order table to use
Returns:
Order line length

The function returns (x1 - x0) where x1 and x0 are the x-coordinates of the line's endpoints.

Definition at line 1325 of file uves_orderpos_follow.c.

References check.

Referenced by uves_locate_orders().

static double estimate_threshold ( const cpl_image *  inputimage,
const cpl_image *  noise,
cpl_table *  ordertable,
int  row,
double  relative_threshold 
)
static

Calculate threshold for order tracing algorithm.

Parameters:
inputimageThe input image
noiseNoise of input image
ordertableBasic order table
rowRow of order table to use
relative_thresholdParameter defining the threshold to calculate (see text)
Returns:
The calculated threshold

This function calculates the threshold levels used by the order tracing algorithm. The threshold computed is min + relative_threshold * (max - min), where min and max are the minimum and maximum pixel values at the center column of the order. The threshold is always above the noise level.

Definition at line 1459 of file uves_orderpos_follow.c.

References check, passure, and uves_msg_debug.

Referenced by uves_locate_orders().

static bool find_centroid ( const cpl_image *  inputimage,
const cpl_image *  noise,
const cpl_binary *  image_bad,
double  threshold,
int  spacing,
int  x,
double *  yguess,
double *  dY 
)
static

Find order line centroid.

Parameters:
inputimageThe input image
noiseNoise of input image
image_badImage bad pixel map
thresholdDetection threshold
spacingApproximate distance between orders (near this order)
xFind centroid in this column
yguessGuess location of centroid, will be updated with centroid location
dYThe uncertainty (which is 'returned') associated with yguess. If this (positive number) cannot be calculated, the variable is set to -1.
Returns:
true if the order line could be traced at this x, false otherwise

The function calculates the centroid of the vertical strip containing yguess.

All pixels above half peak maximum contribute to the centroid calculation, and the centroid position is refined by making a gaussian fit. Additionally, the function returns true, if the peak intensity is more than 10 sigma, where sigma is the RMS error of the gaussian fit.

Definition at line 1600 of file uves_orderpos_follow.c.

References passure, uves_error_reset, uves_gauss(), uves_gauss_derivative(), and uves_msg_debug.

Referenced by trace_order().

cpl_table* uves_locate_orders ( const cpl_image *  inputimage,
const cpl_image *  noise,
cpl_table *  ordertable,
int  TRACESTEP,
double  MINTHRESH,
double  MAXGAP,
double  MAXRMS,
int *  DEFPOL1,
int *  DEFPOL2,
double  KAPPA,
polynomial **  bivariate_fit,
int *  orders_traced 
)

Trace all orders.

Parameters:
inputimageThe input echelle image
noiseNoise of input image
ordertableThe basic order table (one row pr. order)
TRACESTEPSee trace_order()
MINTHRESHSee trace_order()
MAXGAPSee trace_order()
MAXRMSIndividual orders are rejected if RMS of a linear fit of the order is larger than MAXRMS * mRMS, where mRMS is the median of all order's RMSs.
DEFPOL1Degree of global fit (as function of x) If negative, will be set to actual degree used
DEFPOL2Degree of global fit (as function of order number) If negative, will be set to actual degree used
KAPPAKappa used for kappa-sigma clipping of linear fits and final global fit
bivariate_fit(output) The global fit of order positions
orders_traced(output) Number of orders detected
Returns:
The order trace table, or NULL on error

This function creates the order trace table starting from the basic ordertable which contains the (guess) order line slopes and intersepts.

  • First, all orders are traced in both directions starting from the center which is inferred from the 'Slope' and 'Intersept' columns of the ordertable . The detection threshold used for a certain order is min + MINTHRESH * (max - min), where min and max are the minimum and maximum pixel values at the center column of that order. See also trace_order() and estimate_threshold() .
  • Then each order is fitted with a straight line, and the entire order is rejected if the RMS is too large.
  • A global polynomial of degree (DEFPOL1, DEFPOL2) is fitted to all orders, and individual points are rejected using kappa-sigma clipping.

Definition at line 250 of file uves_orderpos_follow.c.

References assure_nomsg, check, check_nomsg, count_orders(), estimate_threshold(), fit_order_linear(), get_orderlength(), get_xcenter(), get_ycenter(), passure, trace_order(), uves_error_reset, uves_msg, uves_msg_debug, uves_msg_low, uves_msg_warning, uves_polynomial_delete(), and uves_polynomial_regression_2d().

static cpl_table * detect_lines ( cpl_image *  htrans,
int  minintersept,
const cpl_image *  inputimage,
int  NORDERS,
bool  norders_is_guess,
int  SAMPLEWIDTH,
double  PTHRES,
double  MINSLOPE,
double  MAXSLOPE,
int  SLOPERES,
bool  consecutive 
)
static

Detect order lines from the Hough image.

Parameters:
htransThe Hough transform image (detected features will be deleted)
mininterseptMinimum intersept represented in Hough image
inputimageThe raw image
NORDERSThe number of orders to detect
norders_is_guessFlag indicating if we are allowed detect fewer orders than specified by NORDERS.
SAMPLEWIDTHThe seperation of sample traces in the raw image
PTHRESIf NORDERS is zero, or if norders_is_guess is true, this is the threshold used for peak detection (detection stops when intensity drops to below PTHRES * (previous intensity))
MINSLOPEMinimum line slope to search for
MAXSLOPEMaximum line slope to search for
SLOPERESWidth of Hough image
consecutiveIf true, orders are not assumed to be consecutive
Returns:
CPL_ERROR_NONE A table describing the detected lines

This function locates the peaks in the input Hough image. After detecting a peak, the peak itself and the area around it are deleted to avoid several detections of the same feature (see delete_peak() ).

The peak locations are initially defined as the local maximum points but are refined by calculating the centroid of the local area around the maximum (see update_max() ).

The number of order lines to detect is specified by the parameter NORDERS. If this parameter is set to zero, the function will detect lines until the intensity of the next candidate drops to below PTHRES times the dimmest line (PTHRES must be between 0 and 1; if norders_is_guess is false, the parameter PTHRES is ignored).

An important parameter for the peak removal to work is the (approximate) interorder spacing. This parameter is estimated as the raw image height divided by the predicted number of orders (NORDERS). In automatic mode it is estimated as the first minimum of the auto-correlation function along the column in the Hough image containing the global maximum. Note that these methods assume that the inter order spacing does not vary too much as function of order number.

The results of the detection are written to the returned table in the columns 'Slope' (slope of order), 'Intersept' (y-intersept of order) and 'Spacing' (appropriate interorder distance at this order). The table is sorted according to 'Intersept'. The column 'Order' is a label of the order number starting from 1.

Definition at line 398 of file uves_orderpos_hough.c.

References calculate_spacing(), check, check_nomsg, delete_peak(), passure, update_max(), uves_msg, uves_msg_debug, and uves_msg_warning.

Referenced by uves_hough().

static cpl_error_code delete_peak ( cpl_image *  htrans,
int  minintersept,
int  hxmax,
int  hymax,
int  SPACING,
int  imagewidth,
int  SAMPLEWIDTH,
double  MINSLOPE,
double  MAXSLOPE,
int  SLOPERES 
)
static

Delete peak in Hough image.

Parameters:
htransThe Hough transform
mininterseptThe minimum intersept represented in Hough space
hxmaxX-position of peak in Hough space
hymaxY-position of peak in Hough space
SPACINGSpacing of order lines
imagewidthWidth of raw image
SAMPLEWIDTHWidth between traces on raw image
MINSLOPEMinimum line slope to search for
MAXSLOPEMaximum line slope to search for
SLOPERESWidth of Hough image
Returns:
CPL_ERROR_NONE iff okay

This function deletes a (previously detected) peak in Hough space, and the butterfly shaped area around the peak.

The peak location (in Hough space) is mapped to a line in the input image (using the inverse Hough transformation). The Hough transform of this (one-dimensional) line is a (two-dimensional) butterfly-shaped area, which is then removed. See code for details.

Definition at line 966 of file uves_orderpos_hough.c.

References check, and firsttrace().

Referenced by detect_lines().

static int firsttrace ( int  nx,
int  SAMPLEWIDTH 
)
static

Get the first trace column.

Parameters:
nxWidth of raw image
SAMPLEWIDTHSeparation between traces in raw image
Returns:
The x-position of the first trace column

The function returns the location of the first trace column of the raw image. The location is defined smallest value greater than 0 of (nx / 2 - N * SAMPLEWIDTH), where N is an integer. This ensures that there is always a sample column at nx/2.

Definition at line 930 of file uves_orderpos_hough.c.

Referenced by delete_peak(), and uves_hough().

static int calculate_spacing ( const cpl_image *  image,
int  x 
)
static

Estimate spacing of order lines.

Parameters:
imageThe Hough transform
xThe column to look at
Returns:
The estimated order spacing

The function estimates the interorder spacing as two times the first minimum point of the auto-correlation function along the column at x in the Hough image.

Definition at line 837 of file uves_orderpos_hough.c.

References autocorr(), check, and uves_msg_debug.

Referenced by detect_lines().

static double autocorr ( const cpl_image *  image,
const int  x,
const int  shift 
)
static

Calculate auto-correlation function of image column.

Parameters:
imageThe image
xThe column to look at
shiftWhere to evaluate the auto-correlation function
Returns:
The auto-correlation function

The function returns image(x, y) * image(x, y + shift)) The average is over y-values ranging from 1 to ny - shift (both inclusive).

Definition at line 875 of file uves_orderpos_hough.c.

Referenced by calculate_spacing().

static cpl_error_code update_max ( const cpl_image *  htrans,
int *  xmax,
int *  ymax,
int  SPACING,
int  imagewidth,
int  SAMPLEWIDTH,
double  MINSLOPE,
double  MAXSLOPE,
int  SLOPERES 
)
static

Improve position of a peak in the Hough image.

Parameters:
htransThe Hough transform
xmaxPeak x-position which will be updated
ymaxPeak Y-position which will be updated
SPACINGSpacing of order lines
imagewidthWidth of raw image
SAMPLEWIDTHSeparation between traces in raw image
MINSLOPEMinimum line slope to search for
MAXSLOPEMaximum line slope to search for
SLOPERESWidth of Hough image
Returns:
CPL_ERROR_NONE iff okay

This function improves a peak position (from the max. pixel value) to the center of mass of a line passing through the middle of the 'butterfly wings' in hough space. The slope of this line in Hough space is ( -(width of input image) / 2 ).

Only pixels with values above ( (1 - 0.5 / NOT) * peak_value ) contribute to the calculation of the centroid. (Here NOT is the number of sample traces in the input image, and peak_value is the pixel value of the detected maximum.)

Definition at line 756 of file uves_orderpos_hough.c.

References uves_msg_debug.

Referenced by detect_lines().

cpl_table* uves_hough ( const cpl_image *  image,
int  ymin,
int  ymax,
int  NORDERS,
bool  norders_is_guess,
int  SAMPLEWIDTH,
double  PTHRES,
double  MINSLOPE,
double  MAXSLOPE,
int  SLOPERES,
bool  consecutive,
cpl_image **  htrans,
cpl_image **  htrans_original 
)

Compute Hough transform and detect lines.

Parameters:
imageInput image
yminFirst image row to consider (inclusive, FITS convention)
ymaxLast image row to consider (inclusive, FITS convention)
NORDERSThe number of orders to detect, or zero
norders_is_guessFlag indicating if we are allowed detect fewer orders than specified by NORDERS.
SAMPLEWIDTHThe seperation of sample traces in input image
PTHRESIn automatic mode, the ratio between the dimmest and next-dimmest line
MINSLOPEMinimum line slope
MAXSLOPEMaximum line slope
SLOPERESWidth of Hough image (number of slopes represented)
consecutiveIf true, orders are assumed to be consecutive
htrans(output) computed Hough transform with peaks deleted
htrans_original(output) computed Hough transform (returned)
Returns:
Table describing the detected lines (see detect_lines() for details )

This function computes the Hough transform of the image image. The input image is traced along vertical lines seperated by SAMPLEWIDTH.

See also detect_lines().

Possible order line slopes range from MINSLOPE to MAXSLOPE . The function assumes that all slopes are positive and small. To detect lines with slopes larger than 0.3 - 0.5 or so, the algorithm should be changed to use polar (i.e. rotation invariant) coordinates in Hough space.

Definition at line 194 of file uves_orderpos_hough.c.

References assure_nomsg, check, check_nomsg, detect_lines(), firsttrace(), passure, uves_msg, uves_msg_debug, and uves_msg_warning.

cpl_error_code uves_draw_orders ( const cpl_table *  ordertable,
cpl_image *  image 
)

Draw detected order lines.

Parameters:
ordertableThe order table
imageThe image to draw on
Returns:
CPL_ERROR_NONE iff okay

This function draws on the input image the lines listed in the provided order table. The intersept and slope of the lines are read from the order table.

Definition at line 1018 of file uves_orderpos_hough.c.

References check, and passure.