MUSE Pipeline Reference Manual  2.1.1
Data Structures | Enumerations | Functions | Variables
Geometrical calibration

Data Structures

struct  muse_geo_table
 Structure definition of MUSE geometry table. More...
 

Enumerations

Functions

cpl_table * muse_geo_table_extract_ifu (const cpl_table *aTable, const unsigned char aIFU)
 Extract the part of a geometry table dealing with a given IFU. More...
 
double muse_geo_table_ifu_area (const cpl_table *aTable, const unsigned char aIFU, double aScale)
 Compute the area of an IFU in the VLT focal plane. More...
 
cpl_vector * muse_geo_lines_get (const cpl_table *aLines)
 Select lines suitable for geometrical calibration from a line list. More...
 
cpl_table * muse_geo_measure_spots (muse_image *aImage, muse_imagelist *aList, const cpl_table *aTrace, const cpl_table *aWave, const cpl_vector *aLines, double aSigma, muse_geo_centroid_type aCentroid)
 Detect spots on a combined image and measure them on the corresponding series of images. More...
 
static cpl_table * muse_geo_get_spot_peaks (cpl_table *aSpots, unsigned char aIFU, unsigned short aNSlice, unsigned char aNSpot, double aLambda, double aVPosRef, cpl_boolean aVerifyDY, cpl_array *aDY)
 Use spot measurements of one IFU to compute vertical pinhole distance. More...
 
cpl_error_code muse_geo_compute_pinhole_local_distance (cpl_array *aDY, cpl_table *aSpots)
 Use spot measurements of one IFU to compute vertical pinhole distance. More...
 
double muse_geo_compute_pinhole_global_distance (cpl_array *aDY, double aWidth, double aMin, double aMax)
 Use vertical pinhole distance measurements of all IFUs to compute the effective global value. More...
 
muse_geo_tablemuse_geo_table_new (cpl_size aNRows, double aScale)
 Create a new MUSE geometry table. More...
 
muse_geo_tablemuse_geo_table_duplicate (const muse_geo_table *aGeo)
 Make a copy of a MUSE geometry table. More...
 
void muse_geo_table_delete (muse_geo_table *aGeo)
 Deallocate memory associated to a geometry table object. More...
 
muse_geo_tablemuse_geo_determine_initial (cpl_table *aSpots, const cpl_table *aTrace)
 Use spot measurements to compute initial geometrical properties. More...
 
static cpl_size muse_geo_determine_horizontal_wmean (const cpl_table *aSlice, const char *aCol, const char *aColErr, double *aValue, double *aError, double *aMedian, double aSigma)
 Interatively reject outliers and compute (weighted) statistics of intermediate geometry table columns. More...
 
static void muse_geo_determine_horizontal_vpos (const cpl_table *aSlice, double *aP, double *aPE, double *aPM, double aDY, double aF)
 Compute properly weighted vertical slice position mean from intermediate geometry table columns. More...
 
muse_geo_tablemuse_geo_determine_horizontal (const muse_geo_table *aGeo)
 Use per-spot and per-wavelength partial geometry to determine the horizontal geometrical properties for each slice. More...
 
cpl_error_code muse_geo_refine_horizontal (muse_geo_table *aGeo, cpl_table *aSpots)
 Refine relative horizontal positions of adjacent IFUs. More...
 
muse_geo_tablemuse_geo_determine_vertical (const muse_geo_table *aGeo)
 Use all properties of the central spot and the horizontal properties in each slice to compute the vertical position. More...
 
cpl_error_code muse_geo_finalize (muse_geo_table *aGeo)
 Create a final version of a geometry table. More...
 
cpl_error_code muse_geo_correct_slices (muse_geo_table *aGeo, cpl_propertylist *aHeader, double aSigma)
 Correct deviant slices in an existing MUSE geometry table. More...
 
cpl_error_code muse_geo_qc_global (const muse_geo_table *aGeoTable, cpl_propertylist *aHeader)
 Add the global QC parameters to the geometry table. More...
 

Variables

const muse_cpltable_def muse_geo_measurements_def []
 Spots measurement table definition for geometrical calibration. More...
 
const muse_cpltable_def muse_geo_table_def []
 Geometry table definition. More...
 
const muse_cpltable_def muse_geo_measurements_def []
 Spots measurement table definition for geometrical calibration. More...
 
const muse_cpltable_def muse_geo_table_def []
 Geometry table definition. More...
 

Detailed Description

The following functions deal with the geometrical calibration, i.e. calibrating the relative location of all MUSE slices within the VLT focal plane.

Enumeration Type Documentation

Type of centroiding algorithm to use.

Enumerator
MUSE_GEO_CENTROID_BARYCENTER 

barycenter centroiding

MUSE_GEO_CENTROID_GAUSSIAN 

Gaussian profile fit

Definition at line 91 of file muse_geo.h.

Function Documentation

double muse_geo_compute_pinhole_global_distance ( cpl_array *  aDY,
double  aWidth,
double  aMin,
double  aMax 
)

Use vertical pinhole distance measurements of all IFUs to compute the effective global value.

Parameters
aDYarray containing all vertical pinhole position measurements
aWidthbin width to use for the initial histogram
aMinlower edge of the initial histogram
aMaxupper edge of the initial histogram
Returns
The effective vertical pinhole distance in mm.

This function does a simple statistical analysis of the single pinhole distance measurements in the input aDY array. First, to reject outliers, a histogram is built from aDY, using the input parameters aWidth, aMin, aMax. Any entry in aDY that is beyond a 1 bin-wide gap is rejected. Average value and standard deviation of the remaining entries determine the width of a second histogram (mean +/- 2 x sigma) which contains 20 bins. Again, entries beyond single-bin gaps are rejected before computing the final statistics.

The average value computed like this is then displayed, and set in the environment variable MUSE_GEOMETRY_PINHOLE_DY, unless this environment variable already exists.

Exceptions
set CPL_ERROR_NULL_INPUT, return 0.aDY is NULL
set CPL_ERROR_INCOMPATIBLE_INPUT, return 0.aDY is not of type CPL_TYPE_DOUBLE
set CPL_ERROR_ILLEGAL_INPUT, return 0.all entries in aDY are invalid

Definition at line 1112 of file muse_geo.c.

References muse_cplarray_erase_outliers(), and muse_cplarray_histogram().

cpl_error_code muse_geo_compute_pinhole_local_distance ( cpl_array *  aDY,
cpl_table *  aSpots 
)

Use spot measurements of one IFU to compute vertical pinhole distance.

Parameters
aDYthe array to which to add the distance measurements
aSpotstable containing measurements of all spots
Returns
CPL_ERROR_NONE on success, another CPL error on failure

Loop over over all slices on the CCD, over all lines, and over all (kMuseCUmpmSpotsPerSlice) spots: if the spot-data of a slice contains two or more peaks, then the distance of their centroids is measured using the VPOS of the spot measurements and added to the aDY array.

The modification of the input array is contained in a single critical section, so that this function can be used in parallel on the same aDY array.

Exceptions
return CPL_ERROR_NULL_INPUTaDY or aSpots are NULL
return CPL_ERROR_INCOMPATIBLE_INPUTaDY is not of type CPL_TYPE_DOUBLE
return CPL_ERROR_ILLEGAL_INPUTaSpots contains less than 10 rows
return CPL_ERROR_INCOMPATIBLE_INPUTaSpots does not have all the columns as defined by muse_geo_measurements_def
return CPL_ERROR_ILLEGAL_INPUTmultiple or invalid sub-field number(s) found in input table
return CPL_ERROR_ILLEGAL_INPUTaSpots contains a range of values of ScaleFOV
output debug message, skip the current slice, continue with the next wavelengthcombination of slice/wavelength/spot not found in aSpots
output warning message, skip the current slice, continue with the next wavelengthdetection of peaks fails for the current combination of slice/wavelength/spot
output warning message, skip the current slice, continue with the next wavelengthall peaks found are too close to one end of the exposure series

Definition at line 1016 of file muse_geo.c.

References muse_cplarray_erase_invalid(), muse_cpltable_check(), muse_cplvector_get_unique(), and muse_geo_get_spot_peaks().

cpl_error_code muse_geo_correct_slices ( muse_geo_table aGeo,
cpl_propertylist *  aHeader,
double  aSigma 
)

Correct deviant slices in an existing MUSE geometry table.

Parameters
aGeotable containing full solution
aHeaderheader for the input table (optional, can be NULL)
aSigmarejection sigma level
Returns
CPL_ERROR_NONE on success, another CPL error code on failure

The input table aGeo is thought to be produced by muse_geo_finalize().

This function first checks that all mandatory table columns are present (MUSE_GEOTABLE_FIELD, MUSE_GEOTABLE_CCD, MUSE_GEOTABLE_SKY, MUSE_GEOTABLE_X, MUSE_GEOTABLE_Y, MUSE_GEOTABLE_ANGLE, and MUSE_GEOTABLE_WIDTH, and the corresponding error columns).

It then loops through the table, marking slices that belong to a given slicer stack of one IFU at a time. This is extracted into a separate table, for which all four properties (x and y position, angle and width) are then fitted to a linear relation (one relation per property).

Values which have a large error estimate attached to them (the hardcoded values used are printed in debug output when this function is called, compared to the median error of each column) are the replaced using the value interpolated from the linear relation. The same happens to points in the stack which have a value that deviate more than aSigma sigma (in terms of RMS) from the linear relation.

If aHeader was given, the numbers of changed slices for all of the four parameters are recorded as QC keywords.

Exceptions
set and return CPL_ERROR_NULL_INPUTaGeo or aGeo->table are NULL
set and return CPL_ERROR_ILLEGAL_INPUTaGeo is missing one of the mandatory columns
set and return CPL_ERROR_DATA_NOT_FOUNDaGeo is missing one of the mandatory columns
set and return CPL_ERROR_INCOMPATIBLE_INPUTone of the position/error columns is not of type CPL_TYPE_DOUBLE

Definition at line 3364 of file muse_geo.c.

References muse_geo_table::table.

muse_geo_table* muse_geo_determine_horizontal ( const muse_geo_table aGeo)

Use per-spot and per-wavelength partial geometry to determine the horizontal geometrical properties for each slice.

Parameters
aGeopartially filled geometry table containing pre-processed results of all spots
Returns
a cpl_table * containing a partial output geometry or NULL on error

The input table aGeo is thought to be produced by muse_geo_determine_initial(). From aGeo extract those entries with "spot" = 2 into the result table.

Loop over over all slices on the CCD and extract all entries belonging to this SliceCCD number into a temporary table. Loop over this table to compute weighted averages for the angle, width, and relative horizontal shift, plus unweighted average and standard deviation of the peak positions, in effect averaging over all measurements at all wavelengths. Save these properties and their errors into the columns MUSE_GEOTABLE_ANGLE, MUSE_GEOTABLE_WIDTH, "xrel", and "vpos" (with the errors in the corresponding columns with "err" appended). These entries replace the original entries in the result table.

Next, loop over all rows of slices. Use the relative horizontal shift and the slice width to compute the gap between slices in this slicer row, starting with the central gap. Together with the width this gives the horizontal center of each slice in the field of view, which is saved in the MUSE_GEOTABLE_X of the result table. Errors are propagated from the individual measurements and saved in the MUSE_GEOTABLE_X"err" column. If a gap has an unlikely width (either negative or above 0.5 pix), the gap is reset to a standard width and the square root of the previously computed gap is added onto its error; a warning message is printed.

If the environment variable MUSE_GEOMETRY_STD_GAP is set to a positive integer, it will use an older way to compute the gaps.

Further process the output table with muse_geo_determine_vertical() to derive the full geometry.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaGeo or aGeo->table is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaGeo contains less than 50 rows
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLaGeo does not have all the columns as defined by muse_geo_table_def
set CPL_ERROR_ILLEGAL_INPUT, return NULLmultiple or invalid sub-field number(s) found in input table
continue with next slicespot 2 of a given slice not present in aGeo
continue with next row of slicesone of the central slices are not present in the input table aGeo for a slicer row
skip position computation for this sliceone of the outer slices are not present in the input table aGeo for a slicer row

Definition at line 1929 of file muse_geo.c.

References muse_cpltable_check(), muse_geo_determine_horizontal_vpos(), muse_geo_determine_horizontal_wmean(), muse_geo_table_duplicate(), muse_geo_table::scale, and muse_geo_table::table.

static void muse_geo_determine_horizontal_vpos ( const cpl_table *  aSlice,
double *  aP,
double *  aPE,
double *  aPM,
double  aDY,
double  aF 
)
static

Compute properly weighted vertical slice position mean from intermediate geometry table columns.

Parameters
aSlicetable which contains the data to use
aPmean value to return
aPEstandard deviation to return
aPMmedian value to return
aDYvertical pinhole distance to use
aFinversion factor to use

This computes the statistics of the "vpos" data in the table, and tries to fix it, in case the standard deviation is found to be too large (> 0.01). The fix is either to offset part of the data by one vertical pinhole distance (aDY), or if that doesn't work, to iteratively reject outliers using muse_geo_determine_horizontal_wmean().

To be used from muse_geo_determine_horizontal().

Exceptions
returnaSlice, aP, aPE, or aPM are NULL

Definition at line 1784 of file muse_geo.c.

References muse_geo_determine_horizontal_wmean().

Referenced by muse_geo_determine_horizontal().

static cpl_size muse_geo_determine_horizontal_wmean ( const cpl_table *  aSlice,
const char *  aCol,
const char *  aColErr,
double *  aValue,
double *  aError,
double *  aMedian,
double  aSigma 
)
static

Interatively reject outliers and compute (weighted) statistics of intermediate geometry table columns.

Parameters
aSlicetable which contains the data to use
aColrelevant data column in the table
aColErrerror column related to the data column in the same table, can be NULL to not weight the data
aValuevalue to return
aErrorsigma error value to return, can be NULL
aMedianmedian value to be returned, can be NULL to skip median computation
aSigmasigma level to use for iterative rejection
Returns
number of rejected elements in input table or -1 on error

To be used from muse_geo_determine_horizontal().

Exceptions
return -1aSlice, aCol, or aValue are NULL
return -1cannot get data for column aCol from aSlice

Definition at line 1630 of file muse_geo.c.

References muse_cplvector_get_adev_const().

Referenced by muse_geo_determine_horizontal(), and muse_geo_determine_horizontal_vpos().

muse_geo_table* muse_geo_determine_initial ( cpl_table *  aSpots,
const cpl_table *  aTrace 
)

Use spot measurements to compute initial geometrical properties.

Parameters
aSpotstable containing measurements of all spots
aTracetracing table
Returns
a cpl_table * containing a partial per-wavelength geometry or NULL on error
Remarks
The returned object has to be deallocated using cpl_table_delete().

Loop over over all slices on the CCD, over all lines, and over all (kMuseCUmpmSpotsPerSlice) spots: first extract all entries for this slice/wavelength/spot from aSpots into a new table. Use the "flux" column to detect one or multiple peaks in the flux distribution of this spot over the exposure series (down to the 0.5 sigma level in terms of median deviation above the median but at most 500.). If multiple peaks are found, select the most central one in the series, or the one closest to the previous spot in the same slice at the same wavelength. Integrate the total flux of the selected peak and use it to create a weighted mean of the center of the spot (in x and y) and the centroid of the peak in the series, i.e. the centroid of the illumination depending on mask position. Propagate the interesting properties from aSpots to the output table.

If the present spot is the last spot (the kMuseCUmpmSpotsPerSlice'th one) of this slice at this wavelength, compute the width, the horizontal shift relative to the pinhole mask, and the angle: The width of the slice can be computed from the known full width as determined by tracing at the vertical location of the spots. The distance between the spots in this slice gives a scale in mm / pix which can be used to compute the width of the slice in pix, using nominal scales for MUSE (for the sampling) and the VLT focal plane. The relative horizontal shift is simply the position of the spots relative to the slice center as determined by the trace table. The angle is finally determined geometrically using the difference in peak positions and the known horizontal distance (kMuseCUmpmDX) between pinholes in the mask.

Errors computed for these three properties are simple standard deviations of the values computed for the different spots in this slice at the same wavelength.

The output table is in the format given by muse_geo_table_def, and is thought to be further processed by muse_geo_determine_horizontal().

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaSpots or aTrace are NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaSpots contains less than 10 rows
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLaSpots does not have all the columns as defined by muse_geo_measurements_def
set CPL_ERROR_ILLEGAL_INPUT, return NULLmultiple or invalid sub-field number(s) found in input table
set CPL_ERROR_ILLEGAL_INPUT, return NULLaSpots contains a range of values of ScaleFOV
continue with next slice, propagate errortracing polynomials could not be constructed for a given slice
output debug message, skip the current slice, continue with the next wavelengthcombination of slice/wavelength/spot not found in aSpots
output warning message, skip the current slice, continue with the next wavelengthdetection of peaks fails for the current combination of slice/wavelength/spot
output warning message, skip the current slice, continue with the next wavelengthall peaks found are too close to one end of the exposure series
output warning message, skip the current slice, continue with the next wavelengthintegrated flux is not positive
output warning message, do not record value in output tablecomputed property is outside reasonable range (between kMuseSliceLoLikelyWidth and kMuseSliceHiLikelyWidth for the width; below kMuseGeoSliceMaxAngle for the angle)

Definition at line 1313 of file muse_geo.c.

References muse_cpltable_check(), muse_cplvector_get_unique(), muse_geo_get_spot_peaks(), muse_geo_table_new(), muse_trace_polys_delete(), muse_trace_table_get_polys_for_slice(), and muse_geo_table::table.

muse_geo_table* muse_geo_determine_vertical ( const muse_geo_table aGeo)

Use all properties of the central spot and the horizontal properties in each slice to compute the vertical position.

Parameters
aGeopartially filled geometry table containing pre-processed results of the central spot of each slice
Returns
a cpl_table * containing the output geometry or NULL on error

The input table aGeo is thought to be produced by appending multiple output tables from muse_geo_determine_horizontal() – or rather muse_geo_refine_horizontal() – with different IFUs to each other.

Duplicate the input table into the result table. In a temporary column, convert the "vpos" values to offsets relative to a reference slice. Then loop through all slicer stacks and over all slices within each stack to find the y-position relative to the reference slice. If the expected vertical distance between two slices is off by more than a factor of 2 in one direction or a factor of 5 in the other, then the slice was illuminated by a different pinhole. Subtracting the pinhole distance (kMuseCUmpmDY) from the relative offset then gives the proper vertical position. If one of more IFUs are missing, a gap of kMuseGeoIFUVGap is added for each missing IFU, and a warning is printed. The error estimated in MUSE_GEOTABLE_Y"err" is copied from "vposerr".

The above gives good results for all slices, except for those on the edge towards the next IFU. These might partly lie in the shadow of that adjacent IFU. To correct for this, this function computes the standard vertical distance between all non-edge slices and uses that to correct the offset of the top and bottom slices. Such an offset is only computed and applied, if the distance between the edge slices and the standard distance is significant.

Finally, MUSE_GEOTABLE_Y and MUSE_GEOTABLE_Y"err" are converted to pix units.

The output table only contains the mandatory columns of muse_geo_table_def and their error estimates, but is not sorted and only contains entries for slices with a valid result. Use muse_geo_finalize() to convert it to a fully usable GEOMETRY_TABLE.

Quality Assessment:
An INM-generated field will be used to check that the geometry computed by this routine is accurate.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaGeo or aGeo->table are NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaGeo->table contains less than 10 rows
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLaGeo->table does not have all the columns as defined by muse_geo_table_def
set CPL_ERROR_ILLEGAL_INPUT, return NULLmore than one spot is still present in the input table

Definition at line 2737 of file muse_geo.c.

References muse_cpltable_check(), muse_geo_table_duplicate(), muse_geo_table::scale, and muse_geo_table::table.

cpl_error_code muse_geo_finalize ( muse_geo_table aGeo)

Create a final version of a geometry table.

Parameters
aGeotable containing all propoerties that could be measured
Returns
CPL_ERROR_NONE on success, another CPL error code on failure

The input table aGeo is thought to be produced by muse_geo_determine_vertical(), but does not require the columns with error estimates.

This function first checks that all mandatory table columns are present (MUSE_GEOTABLE_FIELD, MUSE_GEOTABLE_CCD, MUSE_GEOTABLE_SKY, MUSE_GEOTABLE_X, MUSE_GEOTABLE_Y, MUSE_GEOTABLE_ANGLE, and MUSE_GEOTABLE_WIDTH).

If it detects MUSE_GEOMETRY_PINHOLE_DY set in the environment, it then modifies the input geometry table by adapting the vertical scaling to the real vertical mask pinhole distance (kMuseCUmpmDY), changing the entries in the columns MUSE_GEOTABLE_Y and MUSE_GEOTABLE_ANGLE accordingly.

It then adds missing slices of IFUs that are present: entries for such slices are filled with NANs for x and y position, a zero width, and a zero angle. IFUs for which no slices are present are not filled in.

The table is finally flipped (unless the environment variable MUSE_GEOMETRY_NO_INVERSION is set to a positive integer) and sorted by increasing IFU number and increasing sky slice number.

This finally puts the table into the format format of the GEOMETRY_TABLE as defined in the DRLDesign document, Sect. 5.1.

Exceptions
return CPL_ERROR_NULL_INPUTaGeo or aGeo->table are NULL
return CPL_ERROR_ILLEGAL_INPUTaGeo is missing one of the mandatory columns

Definition at line 3142 of file muse_geo.c.

References muse_utils_iterate_fit_polynomial(), and muse_geo_table::table.

static cpl_table* muse_geo_get_spot_peaks ( cpl_table *  aSpots,
unsigned char  aIFU,
unsigned short  aNSlice,
unsigned char  aNSpot,
double  aLambda,
double  aVPosRef,
cpl_boolean  aVerifyDY,
cpl_array *  aDY 
)
static

Use spot measurements of one IFU to compute vertical pinhole distance.

Parameters
aSpotstable containing measurements of all spots
aIFUIFU number, only for (debug) output
aNSliceslice number on the CCD, for spot selection
aNSpotspot number in this slice, for spot selection
aLambdawavelength of the spot to use, for spot selection
aVPosRefvertical reference position, for peak selection (should be negative if there is no reference yet)
aVerifyDYif to run vertical pinhole distance with full debug output into many files
aDYarray to record the vertical pinhole distance measurement
Returns
a cpl_table * with all entries belonging to the best peak or NULL on error

Extract all table entries belonging to the given aNSlice, aNSpot, aLambda combination into a new table. Convert the "flux" column of this table into an image, and use this for peak detection. If aVPosRef is positive, try to select the peak closest to this given vertical position. (The vertical mask position of a given peak is accesible using the "VPOS" column.) Extract the table values around the chosen peak into the returned table.

If the spot-data of the selected combination contains two or more peaks, then the distance of their centroids is measured (in mm) and added to the aDY array.

Exceptions
quietly return NULLaSpots is NULL
skip pinhole distance computationaDY is NULL
output debug message, return NULLcombination of slice/wavelength/spot not found in aSpots
output warning message, return NULLdetection of peaks fails for the current combination of slice/wavelength/spot
output warning message, return NULLall peaks found are too close to one end of the exposure series

Definition at line 798 of file muse_geo.c.

Referenced by muse_geo_compute_pinhole_local_distance(), and muse_geo_determine_initial().

cpl_vector* muse_geo_lines_get ( const cpl_table *  aLines)

Select lines suitable for geometrical calibration from a line list.

Parameters
aLinesmaster line list to select from
Returns
a cpl_vector * containing the wavelengths of the selected lines or NULL on error
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaLines is NULL
set CPL_ERROR_DATA_NOT_FOUND, return NULLless than 5 suitable lines were found

Definition at line 354 of file muse_geo.c.

cpl_table* muse_geo_measure_spots ( muse_image aImage,
muse_imagelist aList,
const cpl_table *  aTrace,
const cpl_table *  aWave,
const cpl_vector *  aLines,
double  aSigma,
muse_geo_centroid_type  aCentroid 
)

Detect spots on a combined image and measure them on the corresponding series of images.

Parameters
aImagethe combined image of all pinhole mask exposures
aListthe series of all related pinhole mask exposures
aTracethe table containing the trace solution
aWavethe table containing the wavelength calibration solution
aLinesvector with wavelengths of arc lines to use
aSigmaspot detection sigma level (in terms of median deviation above the median)
aCentroidtype of centroiding to use for the spot measurements
Returns
a cpl_table * or NULL on error
Remarks
The returned object has to be deallocated using cpl_table_delete().

Loop over all arc lines in aLines and over all slices on the CCD: first determine the approximate position of the wavelength in the slice and use this image location to construct a box within which the spots (arc lines of the pinholes) are detected, on aImage. If the number of detections is not kMuseCUmpmSpotsPerSlice, skip the rest of the processing for this slice.

Using the now known locations of these spots, loop through aList and measure each spot at the detected position in each image. The local background is computed in a box of halfsize BACKGROUND_HALFSIZE (XXX 7 pix), the flux of the spot is intergrated within a halfsize of MEASUREMENT_HALFSIZE (XXX 5 pix). If aCentroid is MUSE_GEO_CENTROID_GAUSSIAN, the resulting measurement is refined using a Gaussian fit, to give final CCD position and FWHM. Since the input data should contain only emission features (arc lines) negative integrated fluxes are set to zero. Together with the x-/y-centroid and the x-/y-FWHM the measurements and the mask position are saved to the output table.

The columns of the table are given by muse_geo_measurements_def. Note that the x- and y-FWHM may be negative, in case they could not be determined.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLone of aImage aList, aTrace, aWave, or aLines is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaSigma is not positive
set CPL_ERROR_ILLEGAL_INPUT, return NULLaList contains less than five images
set CPL_ERROR_ILLEGAL_INPUT, return NULLaLines contains less than three wavelengths
set CPL_ERROR_ILLEGAL_INPUT, return NULLaCentroid does not contain a supported value
continue with next slice, propagate errortracing and/or wavelength calibration polynomials could not be constructed for a given slice

Definition at line 458 of file muse_geo.c.

References muse_image::data, muse_image::header, muse_astro_posangle(), muse_cpltable_new(), MUSE_GEO_CENTROID_GAUSSIAN, muse_imagelist_get(), muse_imagelist_get_size(), muse_matrix_new_gaussian_2d(), muse_pfits_get_focu_scale(), muse_pfits_get_posenc(), muse_pfits_get_pospos(), muse_trace_polys_delete(), muse_trace_table_get_polys_for_slice(), muse_utils_get_ifu(), and muse_wave_table_get_poly_for_slice().

cpl_error_code muse_geo_qc_global ( const muse_geo_table aGeoTable,
cpl_propertylist *  aHeader 
)

Add the global QC parameters to the geometry table.

Parameters
aGeoTablethe output geometry table
aHeaderthe header to modify
Returns
CPL_ERROR_NONE on success, another CPL error code on failure.

The parameters are the mean value of all slice angles and the horizontal mean position of the central interstack gap as well as statistics for the latter.

Since the propertylist items are all updated, it is possible to run this function more than once.

Exceptions
set and return CPL_ERROR_NULL_INPUTaGeoTable or aHeader are NULL
output warning, continue with next slicer row tozero or unequal slice counts for central slicer stacks in one IFU

Definition at line 3508 of file muse_geo.c.

References muse_geo_table::table.

cpl_error_code muse_geo_refine_horizontal ( muse_geo_table aGeo,
cpl_table *  aSpots 
)

Refine relative horizontal positions of adjacent IFUs.

Parameters
aGeopartially filled geometry table containing pre-processed results of the central spot of each slice
aSpotsspots table, merged dataset of measurements from all IFUs
Returns
a cpl_table * containing the output geometry or NULL on error

The input table aGeo is thought to be produced by appending multiple output tables from muse_geo_determine_horizontal() with different IFUs to each other.

Note
This function modifies aSpots by appending extra columns ("SliceCCD" and "stack") and changing the selection.

Select the topmost and bottommost slices of each IFU of the central two slicer stacks in the aSpots table. Loop through all IFUs except the last and find the central spots at all wavelengths that appear in the adjacent slices at the same mask positions. Use their position relative to the center of the slice to compute the real offset in the focal plane between those adjacent slices. Collect the offsets in two arrays (one for each slice stack), reject outliers using histograms, and compute weighted mean offsets. These offsets are applied to all subsequent IFUs in the aGeo table, by subtracting this from the MUSE_GEOTABLE_XPOS column of the target IFU (and add it to the "xrel" column in mm); the corresponding error estimate is applied to the MUSE_GEOTABLE_XPOS"err" column. Finally, search the reference point (the middle between the middle of the row of the reference slices in the reference IFU), and shift the whole geometry table so that this point is at MUSE_GEOTABLE_XPOS = 0.

If the environment variable MUSE_GEOMETRY_HORI_OFFSETS is set to a comma-delimited string of floats, then these floats are taken as extra pixel offsets used to shift subsequent IFUs, in addition to the automatic computation done here.

Use muse_geo_determine_vertical() as the next step after this function to convert it to a fully usable GEOMETRY_TABLE.

Exceptions
return CPL_ERROR_NULL_INPUTaGeo, or aGeo->table, and/or aSpots are NULL
return CPL_ERROR_ILLEGAL_INPUTaGeo contains less than 50 rows
return CPL_ERROR_INCOMPATIBLE_INPUTaGeo does not have all the columns as defined by muse_geo_table_def
return CPL_ERROR_INCOMPATIBLE_INPUTaSpots does not have all the columns as defined by muse_geo_measurements_def
return CPL_ERROR_DATA_NOT_FOUNDno or only one IFU listed in the input aGeo table
return CPL_ERROR_ILLEGAL_INPUTaSpots contains a range of values of ScaleFOV
continue with the next position/wavelengthnot enough spots found at given position/wavelength that can be used for the comparison

Definition at line 2360 of file muse_geo.c.

References muse_cplarray_erase_invalid(), muse_cplarray_erase_outliers(), muse_cplarray_histogram(), muse_cplarray_new_from_delimited_string(), muse_cpltable_check(), muse_cplvector_get_unique(), muse_geo_table::scale, and muse_geo_table::table.

void muse_geo_table_delete ( muse_geo_table aGeo)

Deallocate memory associated to a geometry table object.

Parameters
aGeoinput MUSE geometry table

Calls cpl_table_delete() for the table component of of a muse_geo_table, and frees memory for the aPixtable pointer. As a safeguard, it checks if a valid pointer was passed, so that crashes cannot occur.

Definition at line 1237 of file muse_geo.c.

References muse_geo_table::table.

muse_geo_table* muse_geo_table_duplicate ( const muse_geo_table aGeo)

Make a copy of a MUSE geometry table.

Parameters
aGeoinput MUSE geometry table
Returns
pointer to the new table, or NULL in case of NULL input

Creates a new geometry table structure, calls cpl_table_duplicate() to duplicate the table component and assigns the scale to the new object.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaGeo is NULL

Definition at line 1217 of file muse_geo.c.

References muse_geo_table::scale, and muse_geo_table::table.

Referenced by muse_geo_determine_horizontal(), and muse_geo_determine_vertical().

cpl_table* muse_geo_table_extract_ifu ( const cpl_table *  aTable,
const unsigned char  aIFU 
)

Extract the part of a geometry table dealing with a given IFU.

Parameters
aTablethe input table
aIFUthe IFU/subfield to extract
Returns
a cpl_table * or NULL on error
Remarks
The returned object has to be deallocated using cpl_table_delete().

This function sorts a duplicate of the input table to make sure that all information for one subfield is in consecutive order, with the on-CCD slice numbers increasing, and then extracts the relevant part of the table.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLinput table is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLinvalid IFU number given
set CPL_ERROR_ILLEGAL_OUTPUT, return NULLthe data for the given IFU is incomplete (not kMuseSlicesPerCCD slices)

Definition at line 235 of file muse_geo.c.

Referenced by muse_geo_table_ifu_area(), and muse_pixtable_create().

double muse_geo_table_ifu_area ( const cpl_table *  aTable,
const unsigned char  aIFU,
double  aScale 
)

Compute the area of an IFU in the VLT focal plane.

Parameters
aTablethe input table
aIFUthe IFU/subfield to handle
aScalescale factor to use [length / arcmin]
Returns
The area or 0. on error.

This function sums up the widths of the relevant slices in the input geometry table (column MUSE_GEOTABLE_WIDTH) for each slicer stack, and multiplies this result with the height of a slice in this stack, by multiplying with 1/11 of the vertical distance between top and bottom slices (using column MUSE_GEOTABLE_Y).

Since a geometry table is in units of pixels, the result is first computed in pix**2. The factor aScale determines the output unit of the area. Normally this should be in cm/arcmin (i.e. ~3.5 cm/arcmin), so that the computed area is in cm**2 in the VLT focal plane. The function muse_pfits_get_focu_scale() can be used to get relevant information from the FITS headers.

Exceptions
set CPL_ERROR_NULL_INPUT, return 0.input table is NULL
set CPL_ERROR_ILLEGAL_INPUT, return 0.invalid IFU number given or incomplete table was input

Definition at line 297 of file muse_geo.c.

References muse_geo_table_extract_ifu().

muse_geo_table* muse_geo_table_new ( cpl_size  aNRows,
double  aScale 
)

Create a new MUSE geometry table.

Parameters
aNRowsnumber of rows for the new table
aScalescale to set in the new table
Returns
pointer to the new table

Creates a new geometry table structure, calls muse_cpltable_new() to create the table component with all initial columns, and assigns the scale to the new object.

Definition at line 1196 of file muse_geo.c.

References muse_cpltable_new(), muse_geo_table::scale, and muse_geo_table::table.

Referenced by muse_geo_determine_initial().

Variable Documentation

const muse_cpltable_def muse_geo_measurements_def[]

Spots measurement table definition for geometrical calibration.

Such a spots table has the following columns:

  • 'filename': (raw) filename from which this measurement originates
  • 'image': number of the image in the series
  • 'POSENC2': x position of the mask in encoder steps
  • 'POSPOS2': x position of the mask
  • 'POSENC3': y position of the mask in encoder steps
  • 'POSPOS3': y position of the mask
  • 'POSENC4': z position of the mask in encoder steps
  • 'POSPOS4': z position of the mask
  • 'VPOS': real vertical position of the mask
  • 'ScaleFOV': focus scale in VLT focal plane (from the FITS header
  • 'SubField': sub-field number
  • 'SliceCCD': slice number as counted on the CCD
  • 'lambda': wavelength
  • 'SpotNo': number of this spot within the slice
  • 'xc': x center of this spot on the CCD
  • 'yc': y center of this spot on the CCD
  • 'xfwhm': FWHM in x-direction on the CCD
  • 'yfwhm': FWHM in y-direction on the CCD
  • 'flux': flux of the spot as integrated on the CCD image
  • 'bg': background level around the spot
  • 'dxcen': distance to center of slice at vertical position yc (positive: right of center)
  • 'twidth': trace width of the slice at the vertical CCD position of the spot

Definition at line 90 of file muse_geo.c.

const muse_cpltable_def muse_geo_measurements_def[]

Spots measurement table definition for geometrical calibration.

Such a spots table has the following columns:

  • 'filename': (raw) filename from which this measurement originates
  • 'image': number of the image in the series
  • 'POSENC2': x position of the mask in encoder steps
  • 'POSPOS2': x position of the mask
  • 'POSENC3': y position of the mask in encoder steps
  • 'POSPOS3': y position of the mask
  • 'POSENC4': z position of the mask in encoder steps
  • 'POSPOS4': z position of the mask
  • 'VPOS': real vertical position of the mask
  • 'ScaleFOV': focus scale in VLT focal plane (from the FITS header
  • 'SubField': sub-field number
  • 'SliceCCD': slice number as counted on the CCD
  • 'lambda': wavelength
  • 'SpotNo': number of this spot within the slice
  • 'xc': x center of this spot on the CCD
  • 'yc': y center of this spot on the CCD
  • 'xfwhm': FWHM in x-direction on the CCD
  • 'yfwhm': FWHM in y-direction on the CCD
  • 'flux': flux of the spot as integrated on the CCD image
  • 'bg': background level around the spot
  • 'dxcen': distance to center of slice at vertical position yc (positive: right of center)
  • 'twidth': trace width of the slice at the vertical CCD position of the spot

Definition at line 90 of file muse_geo.c.

const muse_cpltable_def muse_geo_table_def[]

Geometry table definition.

This type of table is used to define the location of all slices of MUSE within the field of view. It is used to create pixel tables.

The geometry table has the following columns

Mandatory columns:

  • MUSE_GEOTABLE_FIELD: sub-field (IFU / channel) number
  • MUSE_GEOTABLE_CCD: the slice number on the CCD, counted from left to right
  • MUSE_GEOTABLE_SKY: the slice number on the sky
  • MUSE_GEOTABLE_X: x position within field of view
  • MUSE_GEOTABLE_Y: y position within field of view
  • MUSE_GEOTABLE_ANGLE: rotation angle of slice
  • MUSE_GEOTABLE_WIDTH: width of slice within field of view

Extra columns to carry error estimates of the main columns:

  • MUSE_GEOTABLE_X"err": error estimated of x position within field of view
  • MUSE_GEOTABLE_Y"err": error estimate of y position within field of view
  • MUSE_GEOTABLE_ANGLE"err": error estimate of rotation angle
  • MUSE_GEOTABLE_WIDTH"err": error estimate of slice width

Extra columns initially created to support deriving the mandatory coordinates (these disappear during processing and are usually only saved to disk for debugging purposes):

  • 'stack': slicer stack that this slice belongs to (optical numbering)
  • 'spot': spot number in this slice
  • 'xrel': x offset of this spot relative to the slice center
  • 'xrelerr': error of the relative x offset of this spot
  • 'xc': x center of this spot on the CCD
  • 'yc': y center of this spot on the CCD
  • 'dxl': distance to left edge of slice on the CCD
  • 'dxr': distance to right edge of slice on the CCD
  • 'dx': pinhole distance in x on the CCD
  • 'dxerr': error estimate of the pinhole distance in x on the CCD
  • 'vpos': (averaged) vertical position of the mask
  • 'vposerr': error estimated of the (averaged) vertical position of the mask
  • 'flux': flux of the spot as integrated on the CCD image
  • 'lambda': wavelength

Definition at line 169 of file muse_geo.c.

const muse_cpltable_def muse_geo_table_def[]

Geometry table definition.

This type of table is used to define the location of all slices of MUSE within the field of view. It is used to create pixel tables.

The geometry table has the following columns

Mandatory columns:

  • MUSE_GEOTABLE_FIELD: sub-field (IFU / channel) number
  • MUSE_GEOTABLE_CCD: the slice number on the CCD, counted from left to right
  • MUSE_GEOTABLE_SKY: the slice number on the sky
  • MUSE_GEOTABLE_X: x position within field of view
  • MUSE_GEOTABLE_Y: y position within field of view
  • MUSE_GEOTABLE_ANGLE: rotation angle of slice
  • MUSE_GEOTABLE_WIDTH: width of slice within field of view

Extra columns to carry error estimates of the main columns:

  • MUSE_GEOTABLE_X"err": error estimated of x position within field of view
  • MUSE_GEOTABLE_Y"err": error estimate of y position within field of view
  • MUSE_GEOTABLE_ANGLE"err": error estimate of rotation angle
  • MUSE_GEOTABLE_WIDTH"err": error estimate of slice width

Extra columns initially created to support deriving the mandatory coordinates (these disappear during processing and are usually only saved to disk for debugging purposes):

  • 'stack': slicer stack that this slice belongs to (optical numbering)
  • 'spot': spot number in this slice
  • 'xrel': x offset of this spot relative to the slice center
  • 'xrelerr': error of the relative x offset of this spot
  • 'xc': x center of this spot on the CCD
  • 'yc': y center of this spot on the CCD
  • 'dxl': distance to left edge of slice on the CCD
  • 'dxr': distance to right edge of slice on the CCD
  • 'dx': pinhole distance in x on the CCD
  • 'dxerr': error estimate of the pinhole distance in x on the CCD
  • 'vpos': (averaged) vertical position of the mask
  • 'vposerr': error estimated of the (averaged) vertical position of the mask
  • 'flux': flux of the spot as integrated on the CCD image
  • 'lambda': wavelength

Definition at line 169 of file muse_geo.c.