List of Routines
ADN | ANB | CBD |
CNV | DEC | FSM |
MCD | OBJ | PEX |
PRE | RTI |
Routine Descriptions
ADN
[Next Routine] [List of Routines]NAME: ADN ROUTINE'S PURPOSE: ADN manages the simulation for the ADd Noise (ADN) module, that is to call the module's initialization routine (adn_init) at the first iteration of the simulation project. MODULE'S PURPOSE: ADN permits to add photon noise, background noise, read-out noise and dark-current noise to an image or a cube of images. ADN allows also to simulate the saturation of the CCD as well as the perturbations due to flat-field and bad-pixels. CATEGORY: main module's routine CALLING SEQUENCE: error = adn(inp_img_t, out_img_t, par, INIT=init) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_img_t: structure of type img_t. par : parameters structure. INCLUDED OUTPUTS: out_img_t: structure of type "img_t" containing the characteristics of the noisy map, the following fields are contained in this structure: out_img_t = $ { $ data_type : out_type[0] , $ data_status: !caos_data.valid , $ image : noisy_map , $ ; IMAGE with same resolution as PSF. npixel : inp_img_t.npixel , $ ; Number of pixels (per subaperture) resolution : inp_img_t.resolution , $ ; Pixel size [arcsec/pix] lambda : inp_img_t.lambda , $ ; Mean detection wavelength [m] width : inp_img_t.width , $ ; Wavelength band width [m] time_integ : inp_img_t.time_integ , $ ; Integration time for each image [s] time_delay : 0. , $ ; [NOT USED WITHIN AIRY] psf : 0B , $ ; this is an image, not a PSF background : background , $ ; the value of the background snr : fltarr(360) , $ ; [NOT YET EVALUATED] header : PTR_NEW('') $ ; Header (modified by this procedure) } *out_img_t.header = header ;update the pointer KEYWORD PARAMETERS: INIT: initialization data structure. COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : total number of iteration during the simulation run. this_iter : current iteration number. SIDE EFFECTS: none. RESTRICTIONS: none. CALLED NON-IDL FUNCTIONS: adn_add_noise.pro : add the noise (Poisson and Gaussian) in the map adn_ccd_sat.pro : CCD saturation control MODULE MODIFICATION HISTORY: module written : version beta, Serge Correia (OAA) [correia@arcetri.astro.it], Marcel Carbillet (OAA) [marcel@arcetri.astro.it]. ROUTINE MODIFICATION HISTORY: routine written: june 2000, Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : july 2000, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed. -call to adn_prog eliminated (useless). : january 2003, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -use of variable "calibration" eliminited for version 4.0 of the whole system CAOS. MODULE MODIFICATION HISTORY: module written : Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : for version 1.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed. -call to adn_prog eliminated (useless). : for version 2.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -no more use of the common variable "calibration" and the tag "calib" (structure "info") for version 4.0 of the whole Software System CAOS. : march 2004, Barbara Anconelli (DISI) [anconelli@disi.unige.it]: -now having control over initial seed when generating read-out noise. : april 2004, Barbara Anconelli (DISI) [anconelli@disi.unige.it]: -added possibility of choice between three type of noise: poisson, read-out and dark-current -having control over initial seed when generating also poisson noise and dark-current noise. : october 2005, Gabriele Desidera' (DISI) [desidera@disi.unige.it]: -use of variable "time_integ" now is active. -fixed bug in calculation of dark_current noise : april 2006, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -CCD saturation and full-well capacity parameters added in order to simulate the saturation of the CCD. -function 'add_ccd_sat.pro' added. : for version 5.0, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -added possibility to simulate multi-frame images. Multi-frame images cannot be saved (by WFT), but can be only automatically reduced by using PRE. -DITHERING added: each frame can be shifted in two different ways: a) random shifts: the positions will be created within a circle of given radius; b) user defined shifts: the values are stored into a file and will be loaded in the ADN_ADD_NOISE procedure. In this case each line of the file must contain X and Y shifts, separated by a comma. Dithering can be applied to either each frame or every N frames (N is given by the user). -Added the MASKing of the images. -FLAT-FIELD and BAD-PIXELS perturbations added. : march 2011, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -added another TAB in the GUI containing the possibility of clipping negative values after RON and converting the output to an arbitrary IDL data type. -The function "addnoise.pro" has been integrated within the routine "adn_add_noise.pro". : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : May 2012, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]: -small changes in the GUI + changes in "addnoise.pro" routine. : May 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -The header of the input/output image is kept up-to-date with noise information -background is now an array (from previous modules or a new array). Small changes to the GUI
(See adn/adn.pro)
ANB
[Previous Routine] [Next Routine] [List of Routines]NAME: anb ROUTINE'S PURPOSE: ANB executes the simulation for the ANalysis Binary (ANB) module. MODULE'S PURPOSE: ANB module performs the astrometric and photometric analysis on a restored binary type object. CATEGORY: main module's routine CALLING SEQUENCE: error = anb(inp_img_t, $ par, $ INIT=init ) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_img_t: structure of type img_t (image type). par : parameters structure from anb_gui. KEYWORD PARAMETERS: INIT: initialisation data structure COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : total number of iteration during the simulation run. this_iter : current iteration number. SIDE EFFECTS: none. RESTRICTIONS: 1-In some cases, namely when the object is a double star of faint magnitude the MMM algorithm can return an incorrect value (0) for the background evaluation. For this kind of cases it is recommended to use an alternative method for background evaluation. 2- The background estimation done by PRE module can be contaminated by the object if the extension of the object is a large fraction of the image frame. The estimated mean value of the sky background and especially its rms value are then biased. A simple solution is to compute directly the mean background using the routine n_phot (found in .../caos/lib/, help at the IDL/CAOS prompt with the command <>). For example, with a 0.01 arcsec pixel size, a telescope collecting surface of 10 m^2, an integration time of 100 s and an overall efficiency of 0.3, the K band mean background (per pixel) is: 0.3*(n_phot(0.,BAND="K",DELTA_T=100.,SURF=10.))[1]*0.01^2 Then it is necessary to enter by hand the value found within the PRE module GUI (using the option "consider a user-defined background"). CALLED NON-IDL FUNCTIONS: ap_phot_cent.pro ap_phot_cent_comp.pro detect_binary_star.pro legend_windt_m.pro make_graph_bin.pro model_binary.pro ROUTINE MODIFICATION HISTORY: routine written: october 2000, Serge Correia (OAA) [marcel@arcetri.astro.it]. modifications : february 2003, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -use of variable "calibration" eliminited for version 4.0 of the whole system CAOS. : may 2011, Marcel Carbillet (Fizeau) [marcel.carbillet@unice.fr]: -help completed. MODULE MODIFICATION HISTORY: module written : Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : for version 2.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -no more use of the common variable "calibration" and the tag "calib" (structure "info") for version 4.0 of the whole Software System CAOS. : for version 5.0, Marcel Carbillet (Fizeau) [marcel.carbillet@unice.fr]: -GUI resized. : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : April 2013, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]: -Some small changes in the GUI (Text and position of the inputs). : march 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]: Added verbosity choice [default = no]
(See anb/anb.pro)
CBD
[Previous Routine] [Next Routine] [List of Routines]NAME: CBD ROUTINE'S PURPOSE: CBD manages the simulation for the Constrained Blind (or myopic) Deconvolution (CBD) module, that is: 1-call the module's initialization routine cbd_init at the first iteration of the simulation project, 2-call the module's program routine cbd_prog. MODULE'S PURPOSE: CBD performs the deconvolution of a cube of images (i.e. p images corresponding to different orientations of the baseline) when the user don't have a PSF. The module gives back an image and an estimate of the PSF(s) and has in input a PSF(s) and an image(s). If the user has already an initial estimate of the PSF(s) he can give it directly in input; otherwise the module generates an estimate by an operation based on the autocorrelation operator on the image supplied in input. It is possible to obtain these two reconstructions by perform alternatively two partial reconstructions, the first one to the image(s) and the second one to the PSF(s). There are two different methods for image deconvolution and just one for PSFs reconstruction. In the first case the user can choose between the OS-EM method (see for details: "Application of the OS-EM method to the restoration of LBT images", M. Bertero and P. Boccacci, A&AS 144, May 2000, 181-186) and the LR-EM method. CBD fits the PSFs dimensions to the images dimensions, if they do not match, through zero-padding. The background evaluation performed by PRE module is used to restore the object with a correct sky-value, while the reconstructed PSFs are managed without background (this is subtracted before the deconvolution process). In this version no stopping rule is given. The rates of convergence may be different for different types of objects. This algorithm is sensible to the number of the iterations that the user set in the reconstruction box of images and PSFs. In the case of a point-like stellar object, it is easy to have a good estimate of the initial PSFs. In the case of diffuse objects (i.e. galaxies) is more difficult to obtain a good estimate about the PSFs shape making the autocorrelation of the input image and it is recommended to supply a different one. CATEGORY: main module's routine CALLING SEQUENCE: error = cbd(inp_img_t2, out_psf_t, out_img_t, par, INIT=init) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_img_t2: structure of type img_t, corresponding to images par : parameters structure. INCLUDED OUTPUTS: out_psf_t: structure of type "img_t" (with one more feature, the filter to use to maintain in band the same PSFS) containing the characteristics of the deconvolved PSF(s). The following fields are contained in this structure: out_psf_t = $ { $ data_type : out_type[0] , $ data_status: !caos_data.valid , $ image : cube2 , $ psf : 1B , $ ; This is a PSF npixel : N , $ ; Number of pixels (per subaperture) resolution : inp_img_t2.resolution , $ ; Pixel size [arcsec/pix] lambda : inp_img_t2.lambda , $ ; Mean detection wavelength [m] width : inp_img_t2.width , $ ; Wavelength band width [m] time_integ : inp_img_t2.time_integ , $ ; Integration time for each image [s] time_delay : inp_img_t2.time_delay , $ ; [NOT USED WITHIN AIRY] background : make_array(N,N,P) , $ ; the PSF's background is zero snr : inp_img_t2.snr , $ ; snr header : PTR_NEW('') $ ;header of the output PSF } *out_psf_t.header = *inp_img_t2.header out_img_t: structure of type "img_t" containing the characteristics of the deconvolved object. The following fields are contained in this structure: out_img_t = $ { $ data_type : out_type[0] , $ data_status: !caos_data.valid , $ image : cube , $ psf : 0B , $ ; This flag indicates that this is a IMAGE npixel : N , $ ; Number of pixels (per subaperture) resolution : inp_img_t2.resolution , $ ; Pixel size [arcsec/pix] lambda : inp_img_t2.lambda , $ ; Mean detection wavelength [m] width : inp_img_t2.width , $ ; Wavelength band width [m] time_integ : inp_img_t2.time_integ , $ ; Integration time for each image [s] time_delay : inp_img_t2.time_delay , $ ; [NOT USED WITHIN AIRY] background : inp_img_t2.background , $ ; background snr : inp_img_t2.snr , $ ; snr header : PTR_NEW('') $ ; header of the output object } *out_img_t.header=*inp_img_t2.header KEYWORD PARAMETERS: INIT: initialization data structure. COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : int scalar. Total number of iteration during the simulation run. this_iter : int scalar. Number of the current iteration. It is defined only while status eq !caos_status.run. (this_iter >= 1). SIDE EFFECTS: none. RESTRICTIONS: none. CALLED NON-IDL FUNCTIONS: -other routine from the folder .../cbd/cbd_gui_lib. ROUTINE MODIFICATION HISTORY: routine written: May 2005, Gabriele Desidera' (DISI) [desidera@disi.unige.it]. MODULE MODIFICATION HISTORY: module written : december 2008, Gabriele Desidera' (DISI) [desidera@disi.unige.it]. modifications : for version 5.0, Gabriele Desidera' (DISI) [desidera@disi.unige.it]: -the module (previously called BLI) has been renamed in CBD after the work done for the paper (+revisions): G. Desiderà, M. Carbillet, "Strehl-constrained iterative blind deconvolution for post-adaptive-optics data", 2009, A&A 507, pp. 1759-1762. : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -output's order exchanged: (WAS) top=PSF, bottom=OBJ; (NOW IS) top=OBJ, bottom=PSF, as it is in the whole Soft.Pack.AIRY -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : February 2014, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -GUI rewritten with TAB, several optional outputs added. : March 2015, -Add another method of Blind Deconvolution, based on the paper cited in the file "AIRYSoftPack6.1_From6.0to6.1.txt" -Some changes on the GUI (internal tabs added and several input fields moved here and there). : May 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -RON and GAIN have been moved to PRE (and the values are read into the header) -addded save_obj_fun and save_obj_fun_file -the header is saved in the output structure and eventually modified with the deconvolution parameters. -added optional output save: objective function : February 2017, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], - cbd_init.pro debugged
(See cbd/cbd.pro)
CNV
[Previous Routine] [Next Routine] [List of Routines]NAME: cnv ROUTINE'S PURPOSE: cnv manages the simulation for the CoNVolution (CNV) module, that is to call the module's initialization routine cnv_init at the first iteration of the simulation project. MODULE'S PURPOSE: CNV permits to make a convolution between a 2D (3D) PSFs and an object 2D (3D) map. The parameters related to the observing conditions (efficiency, integration time, telescope surface collecting surface) can be chosen. The pixel size of the resulting cube of images is driven by the PSFs pixel size, whatever is the object map one. Both the object map and the PSFs arrays are by the way put in 2^N (N integer) pixels arrays, if they are not originally 2^N arrays. The maximum size for this last operation is set to 2048 pixels (that corresponds to N=11). CATEGORY: main module's routine CALLING SEQUENCE: error = cnv(inp_img_t, inp_src_t, out_img_t, par, INIT=init) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_img_t: structure of type img_t. inp_src_t: structure of type src_t. par : parameters structure. INCLUDED OUTPUTS: out_img_t: structure of type "img_t" containing the characteristics of the convolved map, the following fields are contained in this structure: out_img_t = $ { $ data_type : out_type[0] , $ data_status: !caos_data.valid , $ image : image , $ ; IMAGE with same resolution as PSF. npixel : nb_pix_opt , $ ; Number of pixels (per subaperture) resolution : inp_img_t.resolution, $ ; Pixel size [arcsec/pix] lambda : lambda[0] , $ ; Mean detection wavelength [m] width : width[0] , $ ; Wavelength band width [m] time_integ : par.int_time , $ ; Integration time for each image [s] time_delay : 0. , $ ; [NOT USED WITHIN AIRY] psf : 0B , $ ; IMAGE=1, PSF=0 background : back_frame , $ ; sky background array [ph/pixel] snr : 0. , $ ; [NOT YET EVALUATED] header : PTR_NEW('') $ ; header of the two structures merged } *out_img_t.header = header ; update the pointer KEYWORD PARAMETERS: INIT: initialisation data structure. COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : total number of iteration during the simulation run. this_iter : current iteration number. SIDE EFFECTS: none. RESTRICTIONS: The object map and the PSFs arrays are put to 2^N (N integer) pixels arrays if they are not originally 2^N arrays. Doing it the maximum size is set to 2048 pixels (that corresponds to N=11). CALLED NON-IDL FUNCTIONS: ROUTINE MODIFICATION HISTORY: routine written: june 2000, Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : july 2000, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed. -call to cnv_prog eliminated (useless). -parameters needed for image complete definition now considered (total efficiency, telescope collecting surface, integration time). : february 2003, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -use of variable "calibration" eliminited for version 4.0 of the whole system CAOS. : december 2003, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed. : october 2005, Gabriele Desidera' (DISI) [desidera@disi.unige.it], -use of variable "time_integ" activated for the output structure. MODULE MODIFICATION HISTORY: module written : version beta, Serge Correia (OAA) [correia@arcetri.astro.it], Marcel Carbillet (OAA) [marcel@arcetri.astro.it]. modifications : for version 2.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -no more use of the common variable "calibration" and the tag "calib" (structure "info") for version 4.0 of the whole Software System CAOS. : for version 5.0; Andrea La Camera (DISI) [lacamera@disi.unige.it]: -added the possibility to convolve objects and PSF "many to many" (it was "one to many"). -added possibility to simulate multi-frame images. Multi-frame images cannot be saved (by WFT), but only auto-reduced by PRE module. : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : May 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -The header of the input/output image is kept up-to-date with convolution information -background is now an array, which dimensions are the same of the input image.
(See cnv/cnv.pro)
DEC
[Previous Routine] [Next Routine] [List of Routines]NAME: dec ROUTINE'S PURPOSE: DEC manages the simulation for the image deconvolution (DEC) module, that is: 1-call the module's initialization routine dec_init at the first iteration of the simulation project, 2-call the module's program routine dec_prog. MODULE'S PURPOSE: DEC performs the deconvolution of a cube of images (i.e. P images corresponding to different orientations of the baseline). There are five different methods for image deconvolution, according to the noise model. For Poisson noise, the Richardson-Lucy (RL) and the Ordered-Subset Expectation Maximization (OSEM) methods are available. Recently (from v.6.1) we added the Scaled Gradient Projection (SGP) method [7]. It is an optimized method for solving the minimization of the KL divergence. As concerns Gaussian noise both the Image Space Reconstruction Algorithm (ISRA) and the OS-ISRA are implemented. (see [1] for details). DEC also allows to reduce the boundary effects in the reconstructed image (see [2,8] for details). When the object is complex, as a high dynamic range image, a regularized version of the algorithm can give better results. In this cases, eight different regularizations are available in DEC: Tikhonov (0th order), Tikhonov (2nd order, aka Laplacian), Cross-Entropy, Edge Preserving MRF, High Dynamic Range (HDR), Mistral, Hypersurface, and Tikhonov 1st order (see [8] for details). Depending on the regularization chosen, one or a couple of parameters control the efficacy of the regularization. For RL and OSEM methods, two accelerated versions of the algorithms are also available, following the Biggs and Andrews method (see [3,4] for details). The background (now an array) evaluation performed by PRE module is used to restore the object with a correct sky-value. In this new version of DEC up to five different stopping rules are given. Concerning SGP, RL, and OSEM algorithms, five stopping rules are implemented: 1) Set a total number of iterations and stop the algorithm when this number is reached. This is valid for all available methods; 2) Stop the iterations when the relative L2-norm of the difference between the current iteration and the previous one is less than a given tolerance. i.e. || f(k) - f(k-1) ||^2 / || f(k) ||^2 < tol where f(k) is the current iteration, f(k-1) the previous one, and ||.||^2 the L2-norm (squared) 3) Stop the iterations when the total functional is approximately constant, according to a user-defined tolerance. i.e. | J(k) - J(k-1) | / | J(k) | < tol where J(k) is the objective function defined as J_0 + beta * J_R, J_0 the kullback-leibler divergence, J_R the regularization functional, and beta the regularization parameter (see [8] for more information). In the case of no-regularization (beta=0), then J becomes simply J_0. 4) Stop the iteration when the discrepancy function crosses a given tolerance (that should be around 1). This criterion is called discrepancy principle for Poisson data (see [5]). 5) Stop the iterations when the relative r.m.s error reaches a minimum value. This stopping rule can be used only in the case of numerical simulations, when the true object is known. The first and the last stopping rules are also available for ISRA and OS-ISRA. In DEC we also implemented an algorithm for super-resolving compact objects such as a binary system with an angular separation smaller than the angular resolution of the telescope. (see [1,6] for details). The method is based on a simple modification of the RL/OSEM (and SGP) method and in general consist of 3 steps: the first one requires a large number of RL/OSEM (or SGP) iterations (typically 10^4, smaller numbers in the case of SGP), which are used to estimate the domain of the unresolved object; the second one is a RL/OSEM restoration (typically 5000 iterations) initialized with the mask of the domain, as estimated in step 1. These two steps are used to estimate the positions of the two stars while their magnitudes can be obtained in a possible 3rd step by solving a simple least-squares problem. The first two steps are included in DEC. In the second step it is possible to choose, in the GUI, the image and the mask used to initialized the method. The mask is an image with values 0/1. There are 3 kind of masks: the 1st is a mask based on percentage of the image maximum, the 2nd one is a circular mask, and the 3rd is a user-defined mask. Finally the discrepancy, the objective function, and - in the simulation case - the restoration error can be also saved as ASCII files. References: [1] La Camera et al., 2012, "AIRY: a complete tool for the simulation and the reconstruction of astronomical images", Proc. SPIE 8445, 84453D [2] Anconelli et al., 2006, "Reduction of boundary effects in multiple image deconvolution with an application to LBT LINC-NIRVANA", A&A 448, 1217–1224. [3] Biggs and Andrews, 1997, "Acceleration of iterative image restoration algorithms", Applied Optics 36, 1766. [4] Biggs and Andrews, 1998, "Asymmetric iterative blind deconvolution of multiframe images", Proc. SPIE 3461, 328–338. [5] Bertero et al., 2010, "A discrepancy principle for Poisson data", Inverse Problems 26, 5004. [6] Anconelli et al., 2005, "Restoration of interferometric images. IV. An algorithm for super-resolution of stellar systems", Astronomy and Astrophysics 431, 747–755. [7] Bonettini et al, 2009, "A scaled gradient projection method for constrained image deblurring", Inverse Problems 25, 015002. [8] Prato et al, 2016, "Reconstruction of high-dynamic range Poisson data with an application to Io imaging", Inverse Problems, submitted. [9] La Camera et al, 2016, "The Software Package AIRY 7.0: new efficient deconvolution methods for post-adaptive optics data", Proc. SPIE, in Adaptive Optics Systems V (AS106) Please pay attention to the fact that the TOP BOX-INPUT of the module dec is supposed to receive images, while the BOTTOM BOX-INPUT of the module dec is supposed to receive PSFs. CATEGORY: main module's routine CALLING SEQUENCE: error = dec(inp_img_t1, inp_img_t2, out_img_t, par, INIT=init) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_img_t1: structure of type img_t, corresponding to PSF's inp_img_t2: structure of type img_t, corresponding to images par : parameters structure. INCLUDED OUTPUTS: out_img_t: structure of type "img_t" containing the characteristics of the deconvolved object, the following fields are contained in this structure: out_img_t = $ { $ data_type : out_type[0] , $ data_status: !caos_data.valid , $ image : img , $ psf : 0B , $ ; This flag indicates that this is a IMAGE npixel : init.NN , $ ; Number of pixels (per subaperture) resolution : inp_img_t2.resolution , $ ; Pixel size [arcsec/pix] lambda : inp_img_t2.lambda , $ ; Mean detection wavelength [m] width : inp_img_t2.width , $ ; Wavelength band width [m] time_integ : inp_img_t2.time_integ , $ ; Integration time for each image [s] time_delay : inp_img_t2.time_delay , $ ; [NOT USED WITHIN AIRY] background : inp_img_t2.background , $ ; background snr : inp_img_t2.snr , $ ; snr header : PTR_NEW('') $ ; header of the output file } *out_img_t.header = *inp_img_t2.header ; update the pointer KEYWORD PARAMETERS: INIT: initialization data structure. COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : int scalar. Total number of iteration during the simulation run. this_iter : int scalar. Number of the current iteration. It is defined only while status eq !caos_status.run. (this_iter >= 1). SIDE EFFECTS: none. RESTRICTIONS: none. CALLED NON-IDL FUNCTIONS: -other routine from the folders .../dec/dec_gui_lib and .../dec/dec_lib ROUTINE MODIFICATION HISTORY: routine written: november 1999, Massimo Barbati (USG) [massimo@dirac.disi.unige.it]. modifications : march 2000, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -adapted to dec version of the CAOS structure (v 2.0). : may 2000, Massimo Barbati (USG) [massimo@dirac.disi.unige.it]: -Help form, Restore form. -Variables Names, Comments. : july 2000, Massimo Barbati (USG) [massimo@dirac.disi.unige.it]: -beta version for package AIRY. : july 2000, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed + a few minor changes. : Barbara Anconelli (DISI) [anconelli@disi.unige.it]: -help completed. MODULE MODIFICATION HISTORY: module written : Massimo Barbati (USG) [massimo@dirac.disi.unige.it]. modifications : for version 2.0, Barbara Anconelli (DISI) [anconelli@disi.unige.it]: -second output of type "src_t" added. -super-resolution stuff added. : for version 2.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -no more use of the common variable "calibration" and the tag "calib" (structure "info") for version 4.0 of the whole Software System CAOS. : for version 2.0, Serge Correia (AIP) [scorreia@aip.de]: -added the possibility to choose between the OS-EM method and the LR/EM method (par.method added). : for version 2.0, Barbara Anconelli (DISI) [anconelli@disi.unige.it], Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -"real acquisition" button commented and 2nd output of type "src_t" momentaneously eliminated. -normalization constant "c" from PAR to INIT structure. -background substracted from PSF too now. : for version 3.0, Barbara Anconelli (DISI) [anconelli@disi.unige.it], -added a dec accelerate version of OS-EM method (par.acc addded) -ISRA method inserted -added regularization for OS-EM method. -visualization of a mask added. -restructuration of interface -choice of differents regularizations type added : for version 4.0, Gabriele Desidera' (DISI) [desidera@disi.unige.it], -use of variable "time_integ" activated for the output structure -added possibility to reduce boundary effect : for version 5.0, Gabriele Desidera' (DISI) [desidera@disi.unige.it], -eliminated variables concerning regularizations with alpha=0.5 and alpha=1. -image type (img_t) completed (tag "angle" added). : may 2011, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -routine debugged. : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : April 2012 (for version 6.0), Andrea La Camera (DISI) [lacamera@disi.unige.it]: -module rewritten: new method (OS-ISRA), new regularizations, new accelerations added. Debugging of existing algorithms. Old regularizations and old accelerations have been removed. : April 2013, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -added gain_ron parameter (gain of the detector, in order to convert RON from electrons/pixel to ADU/pixel); -added SGP algorithm. Also added the "deconvolve_sgp" sub-routine. : November 2013, Marcel Carbillet (Lagrange) [marcel.carbillet@unice.fr], -1D case debugged (NN=N before right definition of N). : December 2013, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -1D case added (debugged) for SGP method. : May 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -background is now an array (from previous modules) -two new regularizations added: HYPERSURFACE and TIKHONOV 1st ORDER -all the 8 regularizations are available for SGP now (i.e. they are available for ALL methods). -added optional output save: objective function -GUI debugged (small changes on text and displacement of the widgets) -stopping rules modified (same rules for RL,OSEM,SGP) -The header of the input/output image is kept up-to-date with deconvolution information : July 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -bug correction on the GUI (for regularization HS) : July 2017, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -if a stopping rule is satisfied, the variable "last_iter" is used for storing current iteration, next "this_iter" is set to the total iteration number, and then "tot_iter" is updated with the current iteration number (i.e the very last iteration).
(See dec/dec.pro)
FSM
[Previous Routine] [Next Routine] [List of Routines]NAME: fsm ROUTINE'S PURPOSE: FSM executes the simulation for the Find Stars Module (FSM) module. MODULE'S PURPOSE: FSM module find stars and perform the astrometric and photometric analysis, given a detection threshold expressed in RMS background (like in PRE module the MMM algorithm is used for background evaluation, unless it fails in which case the border of the frame is used to compute this value). A final display, in square-root scale, is given with the found stars encircled, as well as the listing of the stars location and aperture photometry. CATEGORY: main module's routine CALLING SEQUENCE: error = fsm(inp_img_t, $ par, $ INIT=init ) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_img_t: structure of type img_t (image type). par : parameters structure from fsm_gui. KEYWORD PARAMETERS: INIT: initialization data structure COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : total number of iteration during the simulation run. this_iter : current iteration number. SIDE EFFECTS: none. RESTRICTIONS: 1-In some cases, namely when the object is a double star of faint magnitude the MMM algorithm can return an incorrect value (0) for the background evaluation. For this kind of cases it is recommended to use an alternative method for background evaluation. 2- The background estimation done by PRE module can be contaminated by the object if the extension of the object is a large fraction of the image frame. The estimated mean value of the sky background and especially its rms value are then biased. A simple solution is to compute directly the mean background using the routine n_phot (found in .../caos/lib/, help at the IDL/CAOS prompt with the command <>). For example, with a 0.01 arcsec pixel size, a telescope collecting surface of 10 m^2, an integration time of 100 s and an overall efficiency of 0.3, the K band mean background (per pixel) is: 0.3*(n_phot(0.,BAND="K",DELTA_T=100.,SURF=10.))[1]*0.01^2 Then it is necessary to enter by hand the value found within the PRE module GUI (using the option "consider a user-defined background"). CALLED NON-IDL FUNCTIONS: amas_phot_m.pro astrolib_find.pro astrolib_find_module.pro ROUTINE MODIFICATION HISTORY: routine written: october 2000, Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : february 2003, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -use of variable "calibration" eliminited for version 4.0 of the whole system CAOS. : june 2003, Serge Correia (AIP) [scorreia@aip.de]: -status common variable eliminated. : december 2003, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed. : may 2011, Marcel Carbillet (Fizeau) [marcel.carbillet@unice.fr]: -help completed. MODULE MODIFICATION HISTORY: module written : Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : for version 2.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -no more use of the common variable "calibration" and the tag "calib" (structure "info") for version 4.0 of the whole Software System CAOS. : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack.
(See fsm/fsm.pro)
MCD
[Previous Routine] [Next Routine] [List of Routines]NAME: mcd ROUTINE'S PURPOSE: MCD manages the simulation for the image mcdonvolution (MCD) module, that is: 1-call the module's initialization routine mcd_init at the first iteration of the simulation project, 2-call the module's program routine mcd_prog. MODULE'S PURPOSE: MCD performs the deconvolution of high dynamic range images [1,2,3,4]. The module assumes that the unknown object $\mathbf{f}$ is the sum of two components: the point-like part f_P containing the bright sources of the object superimposed on the extended and smooth part f_E. Moreover MCD assumes to know the positions of the bright sources, i.e. the user must provide a mask M_P which is 1 in the pixels of the sources and 0 elsewhere. Alternatively, the user can set the mask to 1 in small regions around the known positions. References: [1] A. La Camera et al., SPIE Proc. 8455, 84553D (2012). [2] A. La Camera et al., PASP 126,(936), 180 (2014). [3] M. Prato et al., Inverse Problems (submitted), (2016) [4] A. La Camera et al., SPIE Proc. 9909-297 (2016) Please pay attention to the fact that the TOP BOX-INPUT of the module mcd is supposed to receive images, while the BOTTOM BOX-INPUT of the module mcd is supposed to receive PSFs. Concerning the output, the TOP BOX-OUTPUT is for the point-like component, while the BOTTOM BOX-OUTPUT is for the diffuse one. CATEGORY: main module's routine CALLING SEQUENCE: error = mcd(inp_img_t1, inp_img_t2, out_img_tE, out_img_tP, par, INIT=init) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_img_t1: structure of type img_t, corresponding to PSF's inp_img_t2: structure of type img_t, corresponding to images par : parameters structure. INCLUDED OUTPUTS: out_img_tE: structure of type "img_t" containing the characteristics of the deconvolved object (DIFFUSE COMPONENT), the following fields are contained in this structure: ; out_img_tE = $ ; { $ ; data_type : out_type[0] , $ ; data_status: !caos_data.valid , $ ; image : img , $ ; psf : 0B , $ ; This flag indicates that this is a IMAGE ; npixel : init.NN , $ ; Number of pixels (per subaperture) ; resolution : inp_img_t2.resolution , $ ; Pixel size [arcsec/pix] ; lambda : inp_img_t2.lambda , $ ; Mean detection wavelength [m] ; width : inp_img_t2.width , $ ; Wavelength band width [m] ; time_integ : inp_img_t2.time_integ , $ ; Integration time for each image [s] ; time_delay : inp_img_t2.time_delay , $ ; [NOT USED WITHIN AIRY] ; background : inp_img_t2.background , $ ; background ; snr : inp_img_t2.snr , $ ; snr ; header : PTR_NEW('') $ ; header of the output file ; } ; *out_img_tE.header = *inp_img_t2.header out_img_tP: structure of type "img_t" containing the characteristics of the deconvolved object (POINT-LIKE COMPONENT), the following fields are contained in this structure: ; out_img_tP = $ ; { $ ; data_type : out_type[0] , $ ; data_status: !caos_data.valid , $ ; image : img , $ ; psf : 0B , $ ; This flag indicates that this is a IMAGE ; npixel : init.NN , $ ; Number of pixels (per subaperture) ; resolution : inp_img_t2.resolution , $ ; Pixel size [arcsec/pix] ; lambda : inp_img_t2.lambda , $ ; Mean detection wavelength [m] ; width : inp_img_t2.width , $ ; Wavelength band width [m] ; time_integ : inp_img_t2.time_integ , $ ; Integration time for each image [s] ; time_delay : inp_img_t2.time_delay , $ ; [NOT USED WITHIN AIRY] ; background : inp_img_t2.background , $ ; background ; snr : inp_img_t2.snr , $ ; snr ; header : PTR_NEW('') $ ; header of the output file ; } ; *out_img_tP.header = *inp_img_t2.header KEYWORD PARAMETERS: INIT: initialization data structure. COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : int scalar. Total number of iteration during the simulation run. this_iter : int scalar. Number of the current iteration. It is defined only while status eq !caos_status.run. (this_iter >= 1). SIDE EFFECTS: none. RESTRICTIONS: none. CALLED NON-IDL FUNCTIONS: -other routine from the folder ./mcd_lib ROUTINE MODIFICATION HISTORY: routine written: June 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]. modifications : MODULE MODIFICATION HISTORY: module written : Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]. modifications : : July 2017, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -if a stopping rule is satisfied, the variable "last_iter" is used for storing current iteration, next "this_iter" is set to the total iteration number, and then "tot_iter" is updated with the current iteration number (i.e the very last iteration). -added common block (called parameters_mcd) to routines mcd_init and mcd_prog in order to correctly save the parameter "par.delta" (delta_ori) in header. (for future reference: this can be used for any other parameter)
(See mcd/mcd.pro)
OBJ
[Previous Routine] [Next Routine] [List of Routines]NAME: obj ROUTINE'S PURPOSE: OBJ manages the simulation for the OBJect (OBJ) module, that is: 1-call the module's initialization routine obj_init.pro at the first iteration of the project 2-call the module's program routine obj_prog.pro otherwise. MODULE'S PURPOSE: OBJ permits to define map of different types of astronomical objects as a target for observation and/or subsequent image reconstruction/deconvolution. Current object types are: single star, binary object, open cluster, planetary nebulae, supernovae remnant, spiral galaxy, Young Stellar Objects (YSOs), stellar surface and user-defined. For each object type the map is defined by its dimension [npixel] and pixel size. In particular, some remarks concerning the definition of some objects are the following : Single star : pixel located at [npixel/2,npixel/2] containing all the flux (i.e. unresolved star or point source). One may pay attention to the fact that such a definition will creates artifacts if one use PSFs (for both the convolution/ modelization and deconvolution) which are centered on [npixel-1/2,npixel-1/2]. A work around is to use a dirac map (pixel at [0,0] set to 1, 0 elsewhere) within the user-defined object type. Binary object : Formed by two point-source stars for which the barycenter (not photocenter) is located in [npixel/2,npixel/2]. In order to center each component on a pixel, the separation and position angle may vary slightly from the one set by user in the GUI. A warning appears if such a variation is more than 1%. CATEGORY: main module's routine CALLING SEQUENCE: error = obj(out_obj_t, par, INIT=init) OUTPUT: error: long scalar (error code). see !caos_error var in caos_init.pro. INPUTS: none. INCLUDED OUTPUTS: out_obj_t: structure of type "src_t" containing the characteristics of the selected source, the following fields are contained in this structure: out_obj_t = $ { $ data_type : info.out_type[0], $ data_status: !caos_data.valid, $ off_axis : init.off_axis, $ pos_ang : init.pos_ang, $ dist_z : init.dist_z, $ map : init.map, $ scale_xy : init.scale_xy, $ coord : init.coord, $ scale_z : init.scale_z, $ n_phot : init.n_phot, $ background : init.background, $ lambda : init.lambda, $ width : init.width, $ constant : init.constant, $ header : PTR_NEW('') $ } *out_obj_t.header = header ; update the pointer KEYWORD PARAMETERS: INIT: named variable undefined or containing a scalar when obj is called for the first time. As output the named variable will contain a structure of the initialization data. For the following calls of obj, the keyword INIT has to be set to the structure returned by the first call. COMMON BLOCKS: common caos_ao_block, tot_iter, this_iter tot_iter : total number of iteration during the simulation run. this_iter : current iteration number. SIDE EFFECTS: none. RESTRICTIONS: The "Object total magnitude" field within the sub-GUIs "YSOs" and "Spiral galaxy" remains to the original value although it has been changed and the whole set of parameters was saved before. This is just a display problem, since the change of this value is effectively taken into account (as it can be seen at the IDL/CAOS prompt line). PROCEDURE: none. CALLED NON-IDL FUNCTIONS: -n_phot : for number of photons calculus (see in .../lib). -spec2mag: to transform a V-magnitude into any other band magnitude (see in .../lib). -other routines from the astrolib/astron IDL library -other routines from the folder .../obj/obj_lib and the folder .../obj/obj_gui_lib ROUTINE MODIFICATION HISTORY: program written: may 2000, Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : july 2000, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed. : february 2003, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -use of variable "calibration" eliminited for version 4.0 of the whole system CAOS. -call to obj_prog eliminated (useless). : november 2003, Serge Correia (AIP) [scorreia@aip.de]: -help updated. MODULE MODIFICATION HISTORY: program written: version beta, Serge Correia (OAA) [correia@arcetri.astro.it]. : for version 2.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -no more use of the common variable "calibration" and the tag "calib" (structure "info") for version 4.0 of the whole Software System CAOS. -obj_prog eliminated since it was irrelevant. : for version 2.0 too, Serge Correia (AIP) [scorreia@aip.de]: -object type single star added. -help updated. : for version 5.0, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -flux constants are now "float" instead of "int", -object type (obj_t) completed (tag angle added), -modeling of elliptical disk, gaussian and stellar surface debugged. : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New sub-GUIs for Planetary Nebula, SNR, Spiral galaxy, YSO, and user-defined objects. -Bug fixed in parameter restoring procedure (esp. Planetary nebula and SNR). -Small changes in the text of the GUI. -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : May 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -keywords added to the header (that is now created whether the map is saved or not), most commons are: OBJECT, BAND, and PIX_SIZE. All the keywords are described in the FitsHeader_Keywords_definition.txt file.
(See obj/obj.pro)
PEX
[Previous Routine] [Next Routine] [List of Routines]NAME: pex ROUTINE'S PURPOSE: pex manages the simulation for the PEX module, that is to call the module's initialization routine pex_init at the first iteration of the simulation project. MODULE'S PURPOSE: PEX performs PSF extrapolation from a cube of images (or from a single image). The extraction can be done either when project is "set up" (when parameters of the modules are chosen and saved) or when project runs. This operation is divided between PEX_OPEN_GUI and PEX_INIT procedures. PEX_OPEN_GUI: users can load the image, set up scale, zoom, etc., then they can select one or more star with a simple point&click operation, and also select a suitable 'radius of extraction' (R) and the value of the beta parameter. Users have to complete the information about PSF (pixel-size, band, etc.). PEX_INIT: PSF is extracted by following steps: For each selected star, - centroid of the star is computed and its position is shifted to the center of the image with a sub-pixel precision; - a domain of size 2R x 2R is extracted from the central region (this image will be denoted by H); - Moffat extrapolation of H(n) (where n=[n1,n2] is the multi-index characterizing the pixels of the image) is executed by following sub-steps: -- a first estimation of background is performed with a bilinear function: B(n) = a0 + a1*n1 + a2*n2 -- the image H - a1*n1 - a2*n2 is fitted with a circular symmetric Moffat function: b1 M0(r) = b0 + ------------------- where r = sqrt(n1^2 + n2^2) (1 + r^2 / b2^2)^beta -- the estimated values of the parameters ai and bi are used as initial guesses for a least-squares best-fitting of H(n) with a rotated elliptical Moffat function superimposed with a linear varying background: c3 M(n) = c0 + c1*n1 + c2*n2 + ----------------------------------- (1 + (n1'/c4)^2 + (n2'/c5)^2)^beta where n1'=n1*cos(q) + n2*sin(q) and n2'=-n1*sin(q) + n2*cos(q). The value of b2 is the initial guess for both c4 and c5, while the initial guess of the rotation angle q in zero. -- the extracted image H(n) is merged into the sampled function M(n) defined on the full image and the linearly background is subtracted and the result is normalized to unit volume. If several stars are selected in the same image, the median of all the results of previous procedure is computed and this is normalized again to unit volume. CATEGORY: main module's routine CALLING SEQUENCE: error = pex(out_img_t, par) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INCLUDED OUTPUTS: out_img_t: structure of type "img_t" containing the extracted PSF array, the following fields are contained in this structure: out_img_t = $ { $ data_type : out_type[0], $ data_status: !caos_data.valid, $ image : image, $ ; image/psf data cube npixel : _N_out, $ ; number of pixels resolution : par.resolution, $ ; Pixel size [arcsec/px] lambda : par.lambda, $ ; Mean detection wavelength [m] width : par.width, $ ; Wavelength band width [m] time_integ : int_time, $ ; time is zero time_delay : 0., $ ; [NOT USED WITHIN AIRY] psf : par.psf, $ ; IT'S A PSF! background : background, $ ; the PSF's background is zero! snr : fltarr(360), $ ; [NOT YET EVALUATED] header : PTR_NEW('') $ ; header of the output } *out_img_t.header = header ; update the pointer OUTPUT IMAGE = PSF EXTRACTED COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : total number of iteration during the simulation run. this_iter : current iteration number. SIDE EFFECTS: none. RESTRICTIONS: none. CALLED NON-IDL FUNCTIONS: PEX_APPEND, PEX_REMOVE, PEX_CIRCLE (called by PEX_GUI, see PEX_GUI_LIB dir) PEX_PSF_EXTRAPOLATION (called by PEX_INIT, see PEX_LIB dir) MPFIT2DFUN, MPFIT, MPFIT2DPEAK (called by PSF_EXTRAPOLATION - routines written by Craig B. Markwardt, see each file *.pro in PEX_LIB directory for details) PEX_CIRCULAR_MASK (called by PEX_PSF_EXTRAPOLATION, see PEX_LIB directory) ROUTINE MODIFICATION HISTORY: routine written: January 2007, Andrea La Camera (DISI) [lacamera@disi.unige.it]. modifications : MODULE MODIFICATION HISTORY: module written : Andrea La Camera (DISI) [lacamera@disi.unige.it]. modifications : January 2007, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -PEX module is projected to be used in case of Space-Variant PSF extraction, by splitting the image into severals domains and extracting the PSF from each domain. This operation is NOT IMPLEMENTED YET, however data structures (esp. xsave, ysave and nb_click arrays) include a "domain" subdivision of the image. (In case of Space-Invariant PSF, the image coincides with the unique domain). PLEASE DON'T DELETE ANY COMMENTED (three ";") LINE. : October 2008, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -Added the possibility to extract the PSF when project runs, LPX_GUI now is a sort of "before-gui". A new procedure called LPX_OPEN_GUI has been created for managing the Graphical User Interface. : February 2011, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -routine debugged. Domains deleted (not really used) : December 2011, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -file "find_dim.pro" has been deleted [not really used] -files "circular_mask.pro", "psf_extrapolation.pro", "append.pro", "remove.pro", and "circle.pro" have been renamed by adding the prefix 'pex_' to each filename. Apt changes to the functions/procedures. : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : May 2012, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]: -Implemented an automatic search procedure for beta (exponent of the Moffat function). -Visualization options changed: scale, zoom and color (*NEW*) can be now set up by right-clicking on the draw areas. -Circular mask is computed more efficiently (pex_circular_mask.pro improvements). : January 2014, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]: -added the possibility for choosing whether the PSF is extrapolated with a Moffat function (already existing) of not (only PSF extraction is performed - just added) : May 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -The header of the input/output image is kept up-to-date with extrapolation information -the background is now an array. -keywords added to the header: SKY_TYPE, SKY_NB, SKY_BGn, SKY_FILE, BIAS_MAP, DARK_MAP, FLAT_MAP, BADP_MAP : May 2017, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -Routine MPFIT2DFUN, MPFIT, MPFIT2DPEAK have been removed from PEX_LIB and replaced with the whole package MPFIT by Craig B. Markwardt. See installation instructions for more details.
(See pex/pex.pro)
PRE
[Previous Routine] [Next Routine] [List of Routines]NAME: pre ROUTINE'S PURPOSE: pre manages the simulation for the pre-processing (pre) module, that is to call the module's initialization routine pre_init at the first iteration of the simulation project. MODULE'S PURPOSE: pre permits to pre-process a cube of images before a subsequent image restoration/deconvolution process. More precisely, the module permits: - data reduction (also called data calibration), - shift-and-add procedure for multi-frame images, - positivization of the calibrated images, - sky background evaluation, - SNR evaluation, - images re-centering. CATEGORY: main module's routine CALLING SEQUENCE: error = pre(inp_img_t, out_img_t, par, INIT=init ) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_img_t: structure of type img_t. par : parameters structure. INCLUDED OUTPUTS: out_img_t: structure of type "img_t" containing the characteristics of the pre-processed map, the following fields are contained in this structure: out_img_t = $ { $ data_type : out_type[0] , $ data_status: !caos_data.valid , $ image : pre_map , $ ; image map npixel : inp_img_t.npixel , $ ; number of pixels resolution : inp_img_t.resolution , $ ; pixel size [arcsec/pix] lambda : inp_img_t.lambda , $ ; mean detection wavelength [m] width : inp_img_t.width , $ ; wavelength band width [m] time_integ : inp_img_t.time_integ , $ ; Integration time for each image [s] time_delay : inp_img_t.time_delay , $ ; [NOT USED WITHIN AIRY] psf : inp_img_t.psf , $ ; image or PSF ? background : back , $ ; estimated sky background level of the ; pre-processed maps snr : snr , $ ; estimated peak SNR of the ; pre-processed maps header : PTR_NEW('') $ ; header of the FITS File (modified event.) } *out_img_t.header = header ; update the pointer KEYWORD PARAMETERS: INIT: initialization data structure. COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : total number of iteration during the simulation run. this_iter : current iteration number. SIDE EFFECTS: none. RESTRICTIONS: 1-In some cases, namely when the object is a double star of faint magnitude the MMM algorithm can return an incorrect value (0) for the background evaluation. For this kind of cases it is recommended to use an alternative method for background evaluation. 2- The background estimation done by PRE module can be contaminated by the object if the extension of the object is a large fraction of the image frame. The estimated mean value of the sky background and especially its rms value are then biased. A simple solution is to compute directly the mean background using the routine n_phot (found in .../caos/lib/, help at the IDL/CAOS prompt with the command <>). For example, with a 0.01 arcsec pixel size, a telescope collecting surface of 10 m^2, an integration time of 100 s and an overall efficiency of 0.3, the K band mean background (per pixel) is: 0.3*(n_phot(0.,BAND="K",DELTA_T=100.,SURF=10.))[1]*0.01^2 Then it is necessary to enter by hand the value found within the PRE module GUI (using the option "consider a user-defined background"). CALLED NON-IDL FUNCTIONS: phot_rec.pro : re-center the map wrt the photocenter location sky_back_sub : estimate the sky background level of a map using the astrolib routine SKY. ROUTINE MODIFICATION HISTORY: routine written: june 2000, Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : july 2000, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed. -call to routine pre_prog eliminated (useless). : february 2003, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -use of variable "calibration" eliminated for version 4.0 of the whole system CAOS. MODULE MODIFICATION HISTORY: module written : Serge Correia (OAA) [correia@arcetri.astro.it]. modifications : for version 1.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -help completed. -call to pre_prog eliminated (useless). : for version 2.0, Marcel Carbillet (OAA) [marcel@arcetri.astro.it]: -no more use of the common variable "calibration" and the tag "calib" (structure "info") for version 4.0 of the whole Software System CAOS. : for version 2.0 too, Barbara Anconelli (DISI) [anconelli@disi.unige.it] -added the possility for the user to subtract sky background from the images. : for version 4.0, Gabriele Desidera' (DISI) [desider@disi.unige.it]: -use of the variable "time_integ" activated. : for version 5.0, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -added possibility to simulate multi-frame images. Multi-frames images cannot be saved (by WFT), but only auto-reduced by PRE module (this module), -Added DATA REDUCTION for raw images (BAD-PIXEL MAP, FLAT-FIELD MAP, DARK CURRENT MAP and BIAS MAP), -Added SHIFT-AND-ADD method. The values of the shift can be either stored in a text file (x_shift, y_shift in every line) or calculated by correlation (with integer or sub-pixel accuracy), -Apodization has been removed (obsolete), -Changed Re-centering procedure, the new one is based on correlation among the images (with integer or sub-pixel accuracy), -New GUI's design with "TABs". : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : March 2013, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it]: -routine "find_boundary" renamed to "pre_find_boundary" for compatibility with other libraries (such as the well-known "Coyote" one); : May 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -background is now an array, which dimensions are the same of the input image. The user can now load the background contained in a FITS file (that must have the correct dimensions). -deleted procedure "sky_back_sub.pro" (useless!) and added the necessary steps directly in pre_init. -Moved here the definitions of the Read-Out Noise value and the Gain of the CCD, by default they are read from the header of the FITS file (be sure they are defined by "RON" and "GAIN" keywords) -keywords added to the header: RON, GAIN, SKY_TYPE, SKY_NB, SKY_BGn, SKY_FILE, BIAS_MAP, DARK_MAP, FLAT_MAP, BADP_MAP -bug corrections in the data-reduction procedure : December 2016-January 2017, Marcel Carbillet (Lagrange) [marcel.carbillet@oca.eu]: -Re-centering can now be done also for single images. -Back to correl_optimize from astrolib (instead of correl_optimize2 from CAOS lib., now eliminated), thanks to new keyword INIT_FACTOR, here chosen =4 instead of default 8 (which fails for images as small as 64x64).
(See pre/pre.pro)
RTI
[Previous Routine] [List of Routines]NAME: RTI ROUTINE'S PURPOSE: RTI manages the simulation for the RoTate Image (RTI) module, that is to call the module's initialization routine rti_init at the first iteration of the simulation project. MODULE'S PURPOSE: To rotate either images or objects in two different ways: - rotation in pixel space: by using the IDL routine "ROT"; - rotation in frequencies space: by rotating the Fourier transform of the input N.B. The rotation can generate artifacts, in particular in the case of point objects/stars. CATEGORY: main module's routine CALLING SEQUENCE: error = rti(inp_yyy_t, out_yyy_t, par) OUTPUT: error: long scalar (error code, see !caos_error var in caos_init.pro). INPUTS: inp_yyy_t: structure of type "gen_t". par : parameters structure. INCLUDED OUTPUTS: out_yyy_t: structure of type "gen_t" containing the rotated map/image(s). Depending on the type of data, the following fields are contained in this structure: 'img_t': out_yyy_t = { $ data_type : 'img_t' , $ data_status : !caos_data.valid , $ image : img_rot , $ psf : inp_yyy_t.psf , $ npixel : N*par.out , $ resolution : inp_yyy_t.resolution , $ lambda : inp_yyy_t.lambda , $ width : inp_yyy_t.width , $ time_integ : inp_yyy_t.time_integ , $ time_delay : inp_yyy_t.time_delay , $ background : background , $ snr : inp_yyy_t.snr , $ header : PTR_NEW('') $ } *out_yyy_t.header = header ; updated the pointer 'src_t': out_yyy_t = { $ data_type : 'src_t', $ data_status: !caos_data.valid, $ off_axis : inp_yyy_t.off_axis, $ pos_ang : inp_yyy_t.pos_ang, $ dist_z : inp_yyy_t.dist_z, $ map : img_rot, $ scale_xy : inp_yyy_t.scale_xy, $ coord : inp_yyy_t.coord, $ scale_z : inp_yyy_t.scale_z, $ n_phot : inp_yyy_t.n_phot, $ background : inp_yyy_t.background, $ lambda : inp_yyy_t.lambda, $ width : inp_yyy_t.width, $ constant : inp_yyy_t.constant, $ header : PTR_NEW('') $ } *out_yyy_t.header = header ; update the header KEYWORD PARAMETERS: COMMON BLOCKS: common caos_block, tot_iter, this_iter tot_iter : total number of iteration during the simulation run. this_iter : current iteration number. SIDE EFFECTS: none. RESTRICTIONS: none. CALLED NON-IDL FUNCTIONS: ROUTINE MODIFICATION HISTORY: program written: March 2007, Andrea La Camera (DISI) [lacamera@disi.unige.it] modifications : MODULE MODIFICATION HISTORY: program written: March 2007, Andrea La Camera (DISI) [lacamera@disi.unige.it] modifications : : february 2011, Andrea La Camera (DISI) [lacamera@disi.unige.it] -module debugged (in particular, for tags "angle" and "time_integ") : February 2012, Andrea La Camera (DISI) [lacamera@disi.unige.it]: -New way to call AIRY_HELP. By using the "online_help" routine, we resolved a known-issue of the Soft.Pack. : May 2016, Andrea La Camera (DIBRIS) [andrea.lacamera@unige.it], -background is now an array. -keywords added to the header: NB_ANGLES, ANGLEn, ROT_TYPE
(See rti/rti.pro)