aacgmv2.wrapper.convert_latlon()

Complexity

Conditions

16

Size

Total Lines	107
Code Lines	51

Duplication

Lines	0
Ratio	0 %

Importance

Changes

0

# -*- coding: utf-8 -*-
def convert_latlon(in_lat, in_lon, height, dtime, code="G2A"):
    """Converts between geomagnetic coordinates and AACGM coordinates

    Parameters
    ------------
    in_lat : (float)
        Input latitude in degrees N (code specifies type of latitude)
    in_lon : (float)
        Input longitude in degrees E (code specifies type of longitude)
    height : (float)
        Altitude above the surface of the earth in km
    dtime : (datetime)
        Datetime for magnetic field
    code : (str or int)
        Bit code or string denoting which type(s) of conversion to perform
        G2A        - geographic (geodetic) to AACGM-v2
        A2G        - AACGM-v2 to geographic (geodetic)
        TRACE      - use field-line tracing, not coefficients
        ALLOWTRACE - use trace only above 2000 km
        BADIDEA    - use coefficients above 2000 km
        GEOCENTRIC - assume inputs are geocentric w/ RE=6371.2
        (default is "G2A")

    Returns
    -------
    out_lat : (float)
        Output latitude in degrees N
    out_lon : (float)
        Output longitude in degrees E
    out_r : (float)
        Geocentric radial distance (R_Earth) or altitude above the surface of
        the Earth (km)
    """
    import aacgmv2._aacgmv2 as c_aacgmv2
    import aacgmv2

    # Test time
    if isinstance(dtime, dt.date):
        dtime = dt.datetime.combine(dtime, dt.time(0))

    if not isinstance(dtime, dt.datetime):
        raise ValueError('time must be specified as datetime object')

    # Test height
    if height < 0:
        aacgmv2.logger.warning('conversion not intended for altitudes < 0 km')

    # Initialise output
    lat_out = np.nan
    lon_out = np.nan
    r_out = np.nan

    # Test code
    try:
        code = code.upper()

        if(height > aacgmv2.high_alt_coeff and code.find("TRACE") < 0 and
           code.find("ALLOWTRACE") < 0 and code.find("BADIDEA") < 0):
            estr = ''.join(['coefficients are not valid for altitudes above ',
                            '{:.0f} km. You '.format(aacgmv2.high_alt_coeff),
                            'must either use field-line tracing (trace=True or',
                            ' allowtrace=True) or indicate you know this is a',
                            ' bad idea'])
            aacgmv2.logger.error(estr)
            return lat_out, lon_out, r_out

        if height > aacgmv2.high_alt_trace and code.find("BADIDEA") < 0:
            estr = ''.join(['these coordinates are not intended for the ',
                            'magnetosphere! You must indicate that you know ',
                            'this is a bad idea.  If you continue, it is ',
                            'possible that the code will hang.'])

            aacgmv2.logger.error(estr)
            return lat_out, lon_out, r_out

        # make flag
        bit_code = convert_str_to_bit(code)
    except AttributeError:
        bit_code = code

    if not isinstance(bit_code, int):
        raise ValueError("unknown code {:}".format(bit_code))

    # Test latitude range
    if abs(in_lat) > 90.0:
        if abs(in_lat) > 90.1:
            raise ValueError('unrealistic latitude')
        in_lat = np.sign(in_lat) * 90.0

    # Constrain longitudes between -180 and 180
    in_lon = ((in_lon + 180.0) % 360.0) - 180.0

    # Set current date and time
    try:
        c_aacgmv2.set_datetime(dtime.year, dtime.month, dtime.day, dtime.hour,
                               dtime.minute, dtime.second)
    except:
        raise ValueError("unable to set time for {:}".format(dtime))

    # convert location
    try:
        lat_out, lon_out, r_out = c_aacgmv2.convert(in_lat, in_lon, height,
                                                    bit_code)
    except:
        pass

    return lat_out, lon_out, r_out