VcstViirsGeo.h

Go to the documentation of this file.

/**************************************************************************
 *
 * NAME: VcstViirsGeo.h
 *
 * DESCRIPTION: VcstViirsGeo encapsulates the geolocation algorithm. It
 * contains function declarations for functions used in the geolocation
 * routines.
 *
 *
 **************************************************************************/
 
#ifndef VcstViirsGeo_h
#define VcstViirsGeo_h
 
#include <string>
#include <VcstGeoDataStructs.h>
#include <VcstGeoParameters.h>
#include <VcstCmnGeo.h>
#include <VcstParamsReader.h>
 
#include <VcstGeoRctnglStruct.h>
 
const unsigned char GEO_SCAN_QUALITY_HAMIMP_GOODDATA = 0x00; //00000000
const unsigned char GEO_SCAN_QUALITY_HAMIMP_BADDATA = 0x04; //00000x00
const unsigned char GEO_SCAN_QUALITY_HAMIMP_DEGRADDATA = 0x08; //0000x000
const unsigned char GEO_SCAN_QUALITY_HAMIMP_MISSINGDATA = 0x0c; //0000xx00
const unsigned char GEO_SCAN_QUALITY_NOT_ABOVE_SAA = 0x00; //00000000
const unsigned char GEO_SCAN_QUALITY_ABOVE_SAA = 0x10; //000x0000
const unsigned char GEO_SCAN_QUALITY_NO_SOLAR_ECLIPSE = 0x00; //00000000
const unsigned char GEO_SCAN_QUALITY_SOLAR_ECLIPSE = 0x20; //00x00000
//for DNB only
const unsigned char GEO_SCAN_QUALITY_NO_LUNAR_ECLIPSE = 0x00; //00000000
const unsigned char GEO_SCAN_QUALITY_LUNAR_ECLIPSE = 0x40; //0x000000
const unsigned char GEO_SCAN_QUALITY_HA_MIRROR_SIDE_SHIFT = 7; //x0000000
const unsigned char GEO_SCAN_QUALITY_HA_MIRROR_SIDE_MASK = 0x80; //x0000000
 
//DR4767, DR4759 new flags for SCE side, non nominal ham start
const unsigned char GEO_SCAN_QUALITY_SCESIDE_A_ON = 0x00; //0000000x
const unsigned char GEO_SCAN_QUALITY_SCESIDE_B_ON = 0x01; //000000x0
const unsigned char GEO_SCAN_QUALITY_SCESIDE_INVALID = 0x02; //000000xx
const unsigned char GEO_SCAN_QUALITY_HAM_START_IS_NOMINAL = 0x00; //00000000
const unsigned char GEO_SCAN_QUALITY_HAM_START_NOT_NOMINAL = 0x04; //00000x00
 
const unsigned char GEO_PIXEL_QUALITY_INPUT_VALID = 0x00; //00000000
const unsigned char GEO_PIXEL_QUALITY_INPUT_INVALID = 0x01; //0000000x
const unsigned char GEO_PIXEL_QUALITY_POINTING_GOOD = 0x00; //00000000
const unsigned char GEO_PIXEL_QUALITY_POINTING_BAD = 0x02; //000000x0
const unsigned char GEO_PIXEL_QUALITY_TERRAIN_GOOD = 0x00; //00000000
const unsigned char GEO_PIXEL_QUALITY_TERRAIN_BAD = 0x04; //00000x00
const unsigned char GEO_PIXEL_QUALITY_SOLARANGLE_VALID = 0x00; //00000000
const unsigned char GEO_PIXEL_QUALITY_SOLARANGLE_INVALID = 0x08; //0000x000
 
typedef enum {
    OFF, ON
} switch_t;
 
// macros needed to pass heap arrays to functions requiring double pointers
// TBD: combine into one overloaded function
#define ptrCastFloat(array,ny,ptrarr) {  \
        ptrarr = new float *[ny];  \
        for (size_t y = 0; y < ny; y++)  \
            ptrarr[y] = array[y];  \
    }
#define ptrCastUchar(array,ny,ptrarr) {  \
        ptrarr = new unsigned char *[ny]; \
        for (size_t y = 0; y < ny; y++)  \
            ptrarr[y] = array[y];  \
    }
 
/***************************************************************************
NOTE: geolocation data for every pixel.
 
NOTE: Moon phase is in degrees and done according to standard Astronomy
usage.  That is, Moon Phase ranges from 0 to +180. Phase=0.0 means that the
center of the Sun, the center of the Earth, and the center of the Moon
are all in a perfect straight line, with the Moon and the Sun on
opposite sides of the Earth (a lunar eclipse).  A "Full Moon" is the
point in each Moon cycle where the phase reaches minimum.  Phase=+180
would mean that the center of the Moon and the center of the Sun are in
the same apparent place as viewed from the center of the Earth (a Solar
eclipse on the Earth's Equator).  A "New Moon" is the point in each
Moon cycle where the phase reaches a maximum.  We also record the
fraction of the Moon illuminated (mifrac).  mifrac=0.0 is a dark Moon.
mifrac=1.00 means that all of the visible Moon disk is illuminated.
Since phase and mifrac have very small variation during a granule, we
provide only one value of phase and mifrac for the granule.
 
These structures are the baseline for input to EDRs and data delivery.
These will change as RDR to SDR algorithms are delivered from the
sensor vendors.
 **********************/
 
/* Quality Flags */
const unsigned char VIIRS_GEO_INVALID_SCAN_START_TIME = 0x01; /* 00000001 < lsb */
const unsigned char VIIRS_GEO_CMN_GEO_FAIL = 0x02; /* 00000010 < lsb */
const unsigned char VIIRS_GEO_INVALID_MIRROR_SIDE = 0x04; /* 00000100 < lsb */
const unsigned char VIIRS_GEO_TERRAIN_CORR_FAIL = 0x08; /* 00001000 < lsb */
const unsigned char VIIRS_GEO_INVALID_TEL_HAM_ENC_DATA = 0x10; /* 00010000 < lsb */
 
typedef enum {
    MISS, OUTOFBND, AUTO, MAX_NUM_GEO_QUAL
} GeoQual;
 
#define WriteNavData -1
#define WriteGeoAttributes -2
 
typedef enum {
    IMG_RGEO,
    MOD_RGEO,
    IMG_RGEO_TC,
    MOD_RGEO_TC,
    DNB_GEO,
    IMG_GEO,
    MOD_GEO,
    MOD_UNAGG_GEO,
    IMG_GEO_TC,
    MOD_GEO_TC,
    MAX_NUM_GEO_OUTPUTS
} GeoOutputs;
 
typedef struct {
    float imgLat[4];
    float imgLon[4];
    float imgLonRanges[4]; // minNeg, maxNeg, minPos, maxPos
    float imgNSEW[4];
    float modLat[4];
    float modLon[4];
    float modLonRanges[4];
    float modNSEW[4];
    float dnbLat[4];
    float dnbLon[4];
    float dnbLonRanges[4];
    float dnbNSEW[4];
} gRingArrays;
 
// Structure of pointers used by geolocation
 
typedef struct {
    // Pointer to VCST Navigation data
    VcstCmnGeo* pCmnGeo;
 
    // moonArray is generated for the calibration routine, and is local
    // to SDR processing
    ViirsMoonArrays moonArray;
 
    GEO_param_struct* geoParams;
 
    // global data used in processing of geolocation
    ViirsGeoProcType* procStruct;
 
    ViirsGeoOutputType* sdrGeo;
    //  ViirsGeoOutputType* sdrDGeo; // Radian form products pointer(s).
 
    //Array will keep track of the quality metadata values needed for
    //Geolocation products
    int geoMetadataInfo[MAX_NUM_GEO_OUTPUTS][MAX_NUM_GEO_QUAL];
 
    int autoQual;
 
    // QA LUT contains the SAA threshold
    proSdrViirsCalQALUT* QALUT;
 
    // Servo Control Checks
    set<string> geoChecks;
 
} viirsSdrGeoPtrs;
 
 
class VcstCmnGeo;
 
class VcstViirsGeo {
public:
    // Granule data
    string platform_;
    string startDirection_;
    string endDirection_;
    string day_night_flag_;
    string time_coverage_start_;
    string time_coverage_end_;
    string pge_start_time_;
    string pge_end_time_;
    string versionid_;
    string history_;
    string source_files_;
    int filled_scans_;
    int orbit_number_;
    int format_version_;
    int instrument_number_;
    int extract_pixel_start_;
    int extract_pixel_stop_;
    int leapseconds93;
 
    // scan line attributes:
    double scan_time_fill_;
    double scan_time_valid_min_;
    double scan_time_valid_max_;
 
    static string DISABLE_SERVO_CONTROL;
 
public:
    VcstViirsGeo();
 
    virtual ~VcstViirsGeo();
 
    void cleanupDataItems();
 
    int initialize();
 
 
    //    void setHistory(int argc, char* argv[]);
 
    int geolocate();
 
    int findNSEW(float** lat, float** lon,
            size_t ny, size_t x0, size_t nx, float NSEW[4], float lonRanges[4]);
 
    int findGring(float** lat, float** lon,
            size_t ny, size_t x0, size_t nx,
            float gringLat[4], float gringLon[4]);
 
    int updateBbox(GeoOutputs geotype, size_t x0, size_t nx);
 
    int write_img(int iscan, viirsSdrGeoPtrs* geoPtrs_);
 
    int write_mod(int iscan, viirsSdrGeoPtrs* geoPtrs_, bool modFromImg);
 
    int write_dnb(int iscan, viirsSdrGeoPtrs* geoPtrs_);
 
    void setHistory(string history) {
        history_ = history;
    }
 
    string getHistory() {
        return history_;
    }
 
    void setSource(string source) {
        source_files_ = source;
    }
 
    string getSource() {
        return source_files_;
    }
 
protected:
 
    int doProcessing();
 
 
    int initialize_L1A_data();
 
 
    int initialize_L1B_data();
 
    int getLandWaterMask(GeoOutputs geotype, size_t x0, size_t nx);
 
    int write_global_attributes(NcFile* nc_output, string type);
 
 
    int write_scan_data(NcFile* nc_output);
 
 
    int write_nav_data(NcFile* nc_output);
 
 
private:
 
    void cleanup();
 
    int geolocateGranule(int iscan,
            viirsSdrGeoPtrs* ptrs,
            VcstCmnGeo* geoPtr,
            ViirsGeoRctnglType* geoInterpRctngl,
            ViirsGeoDecimType* vInt,
            bool modFromImg);
 
    int storeGranule(int scan,
            const ViirsGeoFullType& inFull,
            const ViirsGeoRctnglType& inRect,
            viirsSdrGeoPtrs* ptrs);
 
    void calcModFromImg(int scan,
            viirsSdrGeoPtrs* ptrs,
            VcstCmnGeo *geoPtr,
            int extractPixelLimits[2]);
 
    int convertToDegrees(int iscan, char type);
 
    viirsSdrGeoPtrs* geoPtrs_;
 
    gRingArrays* gring;
};
 
 
int geolocatePixel(viirsSdrGeoPtrs* ptrs,
        const int inScan,
        const int inDet,
        const int inCol,
        VcstCmnGeo *geoPtr,
        ViirsGeoPixelType& outPix);
 
void setGeoPixelQuality(viirsSdrGeoPtrs* ptrs,
        const int inRow,
        const int inCol,
        const unsigned char pixeQuality);
 
int initGeoDataStructs(int iscan, viirsSdrGeoPtrs* ptrs);
 
int storeGranule(const ViirsGeoFullType& inFull,
        const ViirsGeoRctnglType& inRect,
        viirsSdrGeoPtrs* ptrs);
 
void geolocateAllRecPix(int scan,
        viirsSdrGeoPtrs* ptrs,
        ViirsGeoRctnglType* inRec,
        VcstCmnGeo* geoPtr,
        ViirsGeoFullType* ioFull,
        int extractPixelLimits[2]);
 
void correctFromPassThroughPI(float* ioValue);
 
void correctFromPassThroughPI(double* ioValue);
 
void adjustForPassThroughPI(float* io0,
        float* io1,
        float* io2);
 
void adjustForPassThroughPI(double* io0,
        double* io1,
        double* io2);
 
 
int calculateNadirData(const int inScan,
        viirsSdrGeoPtrs* ptrs,
        VcstCmnGeo* geoPtr,
        ViirsGeoFullType* outFull);
 
 
int GEO_validate_scan_encoder_data(viirsSdrGeoPtrs* ptrs);
 
int GEO_process_parameters(GEO_param_struct* geoParams,
        ViirsGeoProcType* procStruct);
 
 
int GEO_absolute_limit_check(double data_samples[],
        int const number_of_samples,
        double data_limits[2],
        int sample_flags[]);
 
int GEO_relative_limit_check(double data_samples[],
        int const number_of_samples,
        double const delta_limit,
        int sample_flags[]);
 
int GEO_find_next_flag(int sample_flags[],
        int const number_of_samples,
        int const start_sample);
 
void GEO_determine_DNB_sample_time_offsets(
        const focal_plane_geometry_struct& geometry_params,
        const int actScans,
        const double t_sync[MAX_SCAN_NUMBER],
        double sample_time[MAX_SCAN_NUMBER][MAX_SCAN_SAMPLE]);
 
void GEO_determine_sample_time_offsets(
        const focal_plane_geometry_struct& geometry_params,
        double sample_time[MAX_SCAN_SAMPLE]);
 
/******************************************************************
 * GEO_Upg_determine_sample_time_offsets
 *
 * @param *ptrs  Structure of pointers to VIIRS SDR geolocation structs
 *
 * @return void
 * *****************************************************************/
void GEO_Upg_determine_sample_time_offsets(
        const focal_plane_geometry_struct& geometry_params,
        const int actScans,
        const double t_sync[MAX_SCAN_NUMBER],
        double sample_time[MAX_SCAN_NUMBER][MAX_SCAN_SAMPLE]);
 
int GEO_determine_thermal_corrections(viirsSdrGeoPtrs* ptrs);
 
 
int GEO_determine_view_vectors(const int scan_number,
        const int sample_number,
        const int det,
        viirsSdrGeoPtrs* ptrs,
        unsigned char* flag,
        double u_inst[VEC_SIZE]);
 
int GEO_interpolate_telescope_encoder(int const scan_number,
        int const sample_number,
        double* const sample_enc,
        viirsSdrGeoPtrs* ptrs);
 
int GEO_interpolate_mirror_encoder(int const scan_number,
        int const sample_number,
        double* const sample_enc,
        viirsSdrGeoPtrs* ptrs);
 
int GEO_evaluate_polynomial(double coef[MAX_POLY_DEGREE + 1],
        double const in_x,
        int const degree,
        double* const out_fit);
 
 
int GEO_interp_mod_unagg(viirsSdrGeoPtrs* ptrs);
 
 
//-----------------------------------------------------------------------
 
inline void correctFromPassThroughPI(float* ioValue) {
    if (*ioValue > FLOAT32_FILL_TEST) {
        if (*ioValue > TWOPI) {
            *ioValue -= TWOPI;
        }
 
        if (*ioValue > PI) {
            *ioValue -= TWOPI;
        } else if (*ioValue < -PI) {
            *ioValue += TWOPI;
        }
    }
}
 
inline void correctFromPassThroughPI(double* ioValue) {
    if (*ioValue > FLOAT64_FILL_TEST) {
        if (*ioValue > TWOPI) {
            *ioValue -= TWOPI;
        }
 
        if (*ioValue > PI) {
            *ioValue -= TWOPI;
        } else if (*ioValue < -PI) {
            *ioValue += TWOPI;
        }
    }
}
 
//-----------------------------------------------------------------------
 
inline void adjustForPassThroughPI(float* io0,
        float* io1,
        float* io2) {
    float diff;
 
    if ((*io0 > FLOAT32_FILL_TEST) && (*io1 > FLOAT32_FILL_TEST) &&
            (*io2 > FLOAT32_FILL_TEST)) {
        diff = fabs(*io2 - *io0);
        if (diff > PI) {
            if (*io0 < 0.0) {
                *io0 += TWOPI;
            }
 
            if (*io1 < 0.0) {
                *io1 += TWOPI;
            }
 
            if (*io2 < 0.0) {
                *io2 += TWOPI;
            }
        }
    }
}
 
inline void adjustForPassThroughPI(double* io0,
        double* io1,
        double* io2) {
    double diff;
 
    if ((*io0 > FLOAT64_FILL_TEST) && (*io1 > FLOAT64_FILL_TEST) &&
            (*io2 > FLOAT64_FILL_TEST)) {
        diff = fabs(*io2 - *io0);
        if (diff > PI) {
            if (*io0 < 0.0) {
                *io0 += TWOPI;
            }
 
            if (*io1 < 0.0) {
                *io1 += TWOPI;
            }
 
            if (*io2 < 0.0) {
                *io2 += TWOPI;
            }
        }
    }
}
 
int eclipseAndSaaFlags(viirsSdrGeoPtrs *geoPtrs,
        VcstCmnGeo *cmnGeoPtr);
 
int getSaa(viirsSdrGeoPtrs* geoPtrs,
        float dLat,
        float dLon,
        VcstCmnGeo *cmnGeoPtr,
        unsigned char &inSAA);
 
template <int T_NUM_ROWS, int T_NUM_COLS>
int getSolarEclipse(float lat[T_NUM_ROWS][T_NUM_COLS],
        float lon[T_NUM_ROWS][T_NUM_COLS],
        long long startTime,
        long long endTime,
        int startRow,
        int endRow,
        VcstCmnGeo *cmnGeoPtr,
        unsigned char &solEclipse);
 
 
int getDnbLunarEclipse(viirsSdrGeoPtrs *geoPtrs,
        double startTime,
        double endTime,
        int endRow,
        int startRow,
        VcstCmnGeo *cmnGeoPtr,
        unsigned char &lunEclipse);
 
int Check_Tel_Start_Not_Nominal(viirsSdrGeoPtrs* ptrs);
 
 
int Check_Ham_Start_Not_Nominal(viirsSdrGeoPtrs* ptrs);
 
int Check_Scan_Sync_Failure(viirsSdrGeoPtrs* ptrs);
 
int calculateSCESide(viirsSdrGeoPtrs* ptrs);
 
 
int appendQualityFlag2(viirsSdrGeoPtrs* ptrs, int scan, unsigned char flag);
 
int VcstCreateInterpRectangles(const int bandType,
        int numZones,              //# of agg zones
        int *numPixPerZone,        //# of pixels in each agg zone
        ViirsGeoRctnglType* outRec);
 
 
#endif