1 /* 2 * Copyright (c) 2016-2021, The OSKAR Developers. 3 * See the LICENSE file at the top-level directory of this distribution. 4 */ 5 6 #ifndef OSKAR_IMAGER_UPDATE_H_ 7 #define OSKAR_IMAGER_UPDATE_H_ 8 9 /** 10 * @file oskar_imager_update.h 11 */ 12 13 #include <oskar_global.h> 14 #include <mem/oskar_mem.h> 15 #include <vis/oskar_vis_block.h> 16 #include <vis/oskar_vis_header.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** 23 * @brief 24 * High-level function to run the imager and apply visibility selection. 25 * 26 * @details 27 * This function updates the internal imager state using the 28 * supplied visibility block. 29 * 30 * Visibility selection/filtering and phase rotation are performed 31 * if necessary. 32 * 33 * @param[in,out] h Handle to imager. 34 * @param[in] header Handle to visibility header. 35 * @param[in] block Handle to visibility block. 36 * @param[in,out] status Status return code. 37 */ 38 OSKAR_EXPORT 39 void oskar_imager_update_from_block(oskar_Imager* h, 40 const oskar_VisHeader* header, oskar_VisBlock* block, 41 int* status); 42 43 /** 44 * @brief 45 * Intermediate-level function to run the imager and apply visibility selection. 46 * 47 * @details 48 * This function updates the internal imager state using the 49 * supplied visibilities. 50 * 51 * Visibility selection/filtering and phase rotation are performed 52 * if necessary. The \p time_centroid parameter may be NULL if time 53 * filtering is not required. 54 * 55 * The visibility amplitude data dimension order must be 56 * (slowest) time/baseline, channel, polarisation (fastest). 57 * This order is the same as that stored in a Measurement Set. 58 * 59 * The visibility weight data dimension order must be: 60 * (slowest) time/baseline, polarisation (fastest). 61 * 62 * Call finalise() to finalise the images after calling this function. 63 * 64 * @param[in,out] h Handle to imager. 65 * @param[in] num_rows Number of times/baselines. 66 * @param[in] start_chan Start channel index of the visibility block. 67 * @param[in] end_chan End channel index of the visibility block. 68 * @param[in] num_pols Number of polarisations in the visibility block. 69 * @param[in] uu Visibility uu coordinates, in metres. 70 * @param[in] vv Visibility vv coordinates, in metres. 71 * @param[in] ww Visibility ww coordinates, in metres. 72 * @param[in] amps Visibility complex amplitudes. See note, above. 73 * @param[in] weight Visibility weights. See note, above. 74 * @param[in] time_centroid Visibility time centroids, at MJD(UTC) seconds 75 * (double precision). 76 * @param[in,out] status Status return code. 77 */ 78 OSKAR_EXPORT 79 void oskar_imager_update(oskar_Imager* h, size_t num_rows, int start_chan, 80 int end_chan, int num_pols, const oskar_Mem* uu, const oskar_Mem* vv, 81 const oskar_Mem* ww, const oskar_Mem* amps, const oskar_Mem* weight, 82 const oskar_Mem* time_centroid, int* status); 83 84 /** 85 * @brief 86 * Low-level function to run the imager only for the supplied visibilities. 87 * 88 * @details 89 * This low-level function runs one pass of the imager to update the 90 * supplied plane for the supplied visibilities only. 91 * 92 * Visibility selection/filtering and phase rotation are 93 * not available at this level. 94 * 95 * When using a DFT, \p plane refers to the image plane; 96 * otherwise, \p plane refers to the visibility grid. 97 * 98 * The supplied baseline coordinates must be in wavelengths. 99 * 100 * If this is called in "coordinate only" mode, then the visibility amplitudes 101 * are ignored, the plane is untouched and the weights grid is updated instead. 102 * 103 * @param[in,out] h Handle to imager. 104 * @param[in] num_vis Number of visibilities. 105 * @param[in] uu Visibility uu coordinates, in wavelengths. 106 * @param[in] vv Visibility vv coordinates, in wavelengths. 107 * @param[in] ww Visibility ww coordinates, in wavelengths. 108 * @param[in] amps Visibility complex amplitudes. 109 * @param[in] weight Visibility weights. 110 * @param[in] i_plane Internal plane index, used if \p plane is NULL. 111 * @param[in,out] plane Updated image or visibility plane. 112 * @param[in,out] plane_norm Updated required normalisation of plane. 113 * @param[in,out] weights_grid Grid of weights, updated if required. 114 * @param[in,out] status Status return code. 115 */ 116 OSKAR_EXPORT 117 void oskar_imager_update_plane(oskar_Imager* h, size_t num_vis, 118 const oskar_Mem* uu, const oskar_Mem* vv, const oskar_Mem* ww, 119 const oskar_Mem* amps, const oskar_Mem* weight, int i_plane, 120 oskar_Mem* plane, double* plane_norm, oskar_Mem* weights_grid, 121 int* status); 122 123 #ifdef __cplusplus 124 } 125 #endif 126 127 #endif /* include guard */ 128